PageFactory (Kirby Plugin)

Macros()

A Macros is implemented as a PHP-function, which returns a string.

That string is injected into the page in place of the macro call, e.g. {{ my-macro() }}.

Note:
As described in chapt. Custom Macros, Macros can initiate side-effects, such as modifying the <head> element.

However, that only works within an .md file, not in a Twig template.

What Macros are Available?

To see the list of currently avialble macros, append ?macros to the URL.

Note: for this to work you need to be working on a localhost or need to be logged in as admin.

Where Can Macros Be Defined?

  • site/custom/macros/*.php
    (→ custom macros)
  • site/plugins/pagefactory/macros/*.php
    (→ built-in macros)
  • site/plugins/pagefactory-{XY}/macros/*.php
    (→ extension macros)
    (where XY is the name of a PageFactory extension package)

Handling of Unknown Macros

If a Macros is unknown, the string is rendered as is, e.g. X{{ unknown() }}X → X{{ unknown() }}X.

Insert a ^ to render an empty string instead, e.g. X{{^ unknown() }}X → XX.

Test

{{^ unknown-macro() }}

{{ Test() }}

{{ Test() }}

{{M Test() }}

{{m Test() }}

Macro Help

Every macro provides its own help text. Just write {{ macro(help) }} in an .md file to see it.

Example: 

{{ lorem(help) }}

Output:

lorem()

Renders filler text "Lorem ipsum…".

If you set min or max values, rendered words are selected at random.

Arguments

min
If set, defines the minimum number of random words to be rendered. (default: false)
max
If set, defines the maximum number of random words to be rendered (max: 99). (default: false)
dot
If true, a dot will be appended at the end of the output (default: false)
class
Class to be applied to the wrapper element (default: )
wrapperTag
Allows to define the tag of the wrapper element (default: div)

Syntax

To invoke a macro, write {{ macro-name( arguments ) }}.

Lowercase / uppercase is ignored.
E.g. LoRem() is treated like lorem().

Argument List

The argument syntax is "relaxed JSON":

  • Arguments are written as argName: 'value…',.
  • Multiple arguments can be written all on one line; or spread over several line.
    → In that case trailing comma may be omitted.
  • Arguments that accept/expect structured values are written as argName: { 'a':'A','b':'B' } (i.e. non-relaxed JSON)
  • Quotes around argName and arg-values may be omitted, if the resulting expression is still unambiguous.
  • Argument names may be omitted, in which case they are interpreted according to their position within the argument list
    (which you can be determine from the macro's help text).

Example of Acceptable Notations

{{ lorem() }}

{{ lorem(min: 3, max: '9') }}  // ← explicit arguments

{{ lorem(3, 9) }}              // ← implicit arguments

{{ lorem(                      // ← arguments spread over multiple lines
    min: 3
    max: 9
    )
}}

Note:
The filename of a macro must correspond exactly to the function name inside the file.

How to Develop a Custom Macro?

See chapter Custom Macros.

PageFactory