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

Show file "#template.php"

<?php
namespace PgFactory\PageFactory;

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

function NAME($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 .= '';

    //$str = markdown($str); // markdown-compile
    //$str = shieldStr($str, 'inline'); // shield from further processing if necessary

    //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;
}