PageFactory (Kirby Plugin)

Custom Macros

Custom Macros are just like built-in Macros. But they are placed in a folder outside the plugin: site/custom/macros/.

 

To build your own macro:

  • go to folder site/custom/macros/
  • duplicate the macro-template #template.php
  • rename the file to the name of your new macro
  • open the file in an editor
  • change the function name to the name of your new macro *)
  • write your PHP code that eventually returns a string to be injected into the web-page
<?php
namespace PgFactory\PageFactory;

/*
 * PageFactory Macro (and Twig Function)
 */

return function ($args = '')
{
    $funcName = basename(__FILE__, '.php');
    // Definition of arguments and help-text:
    $config =  [
        'options' => [
//            '' => ['', false],
        ],
        'summary' => <<<EOT

# $funcName()

ToDo: describe purpose of function
EOT,
    ];

    // parse arguments, handle help and showSource:
    if (is_string($res = TransVars::initMacro(__FILE__, $config, $args))) {
        return $res;
    } else {
        list($options, $sourceCode, $inx) = $res;
        $str = $sourceCode;
    }

    // assemble output:
    $str .= '';

    //PageFactory::$pg->requireFramework();
    //PageFactory::$pg->addAssets('XY');

    return $str;
};

*) Macro Name

The name of your Macro must be a legal function name in PHP. Thus, it can consist of letters, digits and underscores, but not dashes, dots etc.
Lower- and uppercase letters are allowed.

The name of the Macro file must be identical to the function name.

Configuration Section

Look at section $config = [ ... ];. Here you can declare:

'options':

define for each parameter:
'parameter-name' => ['help text…', 'default value'],

'summary':

text describing the Macro's function in markdown notation

PHP Code

Do not modify the first few lines of your Macro function:

if (is_string($res = TransVars::initMacro(FILE, $config, $args))) {
    return $res;
} else {
    list($options, $sourceCode, $inx) = $res;
    $str = $sourceCode;
}

Inside the function you have access to

  • $argStr
    → the original argument string as stated in the call
  • $options[]
    → $argStr parsed and checked and returned as an array
  • PageFactory::$xy
    → static properties, e.g. PageFactory::$config or PageFactory::$pg etc.

Side Effects

A macro can produce side effects, such as injecting HTML-code into the page, e.g. the <head> element.

Most useful are methods of the Page object, accessible via PageFactory::$pg:

  • PageFactory::$pg->addAssets()
    → assets to load (CSS and JS files)
  • PageFactory::$pg->addHead()
    → string to be injected in <head> as is
  • PageFactory::$pg->addScss()
    → styles to be injected in <head> (wrapped in <style> tag)
  • PageFactory::$pg->addJs()
    → javascript snippet to be injected at end of <body> (before js-file loading segment)
  • PageFactory::$pg->addJsReady()
    → javascript snippet to be injected at end of <body> wrapped in a "when page loaded" clause.
  • PageFactory::$pg->addBodyTagClass()
    → class-name(s) to be injected into the <head> tag
  • PageFactory::$pg->addBodyEndInjections()
    → string to be injected at end of <body> as is

Example:

{{ sample_macro() }}

Renders output (including styling):

[ This is the output of 'sample_macro()' ]

 

→ The macro code, for instance, contains the line below, which injects a robots tag in the head section (check source code of this page to see the effect):

PageFactory::$pg->addHead("<meta name='robots' content='noindex,nofollow,noarchive'>");

(Note that you could have achieved the same by adding Robots: true in Frontmatter of a page.)

Sample Code:

File site/custom/macros/sample_macro.php:

<?php
namespace PgFactory\PageFactory;

/*
 * PageFactory Macro (and Twig Function)
 */

function sample_macro($args = '')
{
    $funcName = basename(__FILE__, '.php');
    // Definition of arguments and help-text:
    $config =  [
        'options' => [
            'optName' => ['Help text describing purpose and format of option', false],
        ],
        'summary' => <<<EOT

# $funcName()

Sample Macro
EOT,
    ];
//======================
    // parse arguments, handle help and showSource:
    if (is_string($res = TransVars::initMacro(__FILE__, $config, $args))) {
        return $res;
    } else {
        list($options, $sourceCode, $inx) = $res;
        $str = $sourceCode;
    }

//======================
    // cause side-effect: inject robots meta element in head:
    PageFactory::$pg->addHead("<meta name='robots' content='noindex,nofollow,noarchive'>\n");

//======================
    // assemble output:
    $str .= <<<EOT

@@@ .test background:cornsilk; padding:1em
[ This is the output of '$funcName()'  ]
@@@

EOT;

    $str = markdown($str); // markdown-compile because $str is in markdown
    $str = shieldStr($str); // shield from further processing because output contains HTML

    return $str;
}

PageFactory