Content macros May 15, 2013 / Updated: June 12, 2022

Note: The example macros in this text contain a space after the first and before the last bracket. This is to avoid them being executed. On real usages there should be none.

General

Zenphoto 1.4.5 introduced the content macros. The overall concept follows the shortcodes Wordpress features. A simple content macro looks like this (spaces to avoid execution only!):

[ ZENPHOTO_VERSION ]

This is one of the default ones (later more) and will print the Zenphoto version number.

Content macros are added directly as text to fields. They work in the following places:

• Codeblock content
• Gallery description
• Image description
• Album description
• Zenpage article content
• Zenpage page content

If you need them to work on other places you can use the function applyMacros($text).

Standard macros

Zenphoto has five predefined example macros that are available via the exampleMacros plugin (again, spaces to avoid execution only!):

• [ CODEBLOCK %1 ] – Places codeblock number %1  in the content where the macro exists.
• [ PAGE ] –  Prints the current page number.
• [ VAR_DUMP ] – Dump the contents of the parameter list.
• [ ZENPHOTO_VERSION ] – Prints the version of the Zenphoto installation.
• [ PAGELINK %1 ] – Provides text for a link to a "custom" script page indicated by %1.

If you enable the macroList plugin you will find such info for all available macros on a separate "macros" tab on the backend. 

Four types of macros

Zenphoto has four built in  default macros that act as examples for those:

• procedure
• function
• constant
• expression

The default ones are defined like this (within getMacros() in /zp-core/functions.php):

array(
        'CODEBLOCK' => array(
                'class'=>'procedure',
                'params'=>array('int'),
                'value'=>'printCodeblock', 
                'desc'=>gettext('Places codeblock number %1 in the content where the macro exists.') ), 'PAGE' => array( 'class'=>'function', 'params'=>array(), 'value'=>'getCurrentPage', 'desc'=>gettext('Prints the current page number.') ), 'ZENPHOTO_VERSION' => array( 'class'=>'constant', 'params'=>array(), 'value'=>ZENPHOTO_VERSION, 'desc'=>gettext('Prints the version of the Zenphoto installation.') ), 'VAR_DUMP' => array('class' => 'procedure', 'params' => array('array'), 'value' => 'var_dump', 'owner' => 'Zenphoto core', 'desc' => gettext('Dump the contents of the parameter list.')), 'PAGELINK' => array( 'class'=>'expression', 'params'=>array('string'), 'value'=>'getCustomPageURL($1);', 'desc'=>gettext('Provides text for a link to a "custom" script page indicated by %1.') ) );

Custom content macros

You can define your own macros either theme or plugin based. We will here explain it with an simple hello world example. You should probably read the plugin tutorial first before proceeding.

Basic macro setup

First setup the plugin to be available on the backend as well:

$plugin_is_filter = 5|THEME_PLUGIN|ADMIN_PLUGIN;

Then register your macro with the filter:

zp_register_filter('content_macro','mymacro');

The function mymacro() does contain the definition of the macro type:

function mymacro($macros) {
        $macros['HELLOWORLD'] = array(
                'class'=>'expression',
                'params'=>array('string'),
                'value'=>'getHelloWorld($1);',
                'owner'=>'your plugin or theme name';
                'desc'=>gettext('%1 = Text before')
        );
        return $macros;
}

Then you need to define the function attached to the marco. It must match the parameters defined above and this function must only return a value and NOT print anything!:

function getHelloWorld($beforetext) {
        return $beforetext.'Hello World';
}

If you now put [ HELLOWORLD My ] (Never quotes around the values!) into a supported text field you will get on the front end: My Hello World

More than one parameter

As you noticed parameters are defined as an array. So you can have as many parameters as you like. Just add fields to the array:

'params' => array('string', 'bool*'),

So the first parameter is a string, the second a bool one. The * behind the second means it is optional and does not need to be set as it uses a default value then.

Note: If a macro has more than one parameter you cannot leave those inbetween out if you for example only want to set the third one. An optional parameter must be the last one.

Available parameter types

• 'string' -> String
• 'int' -> Integer
• 'bool' -> Bool
• 'array' -> array()

Assuming we have a marco [ MACRO ] with four parameters in the order above the usage would be:

[ MACRO string 1 true u=w x=y ]

Note: There can be only one array parameter and it must be the last.

If you don't want your macro to have any parameters just pass an empty array:

'params' => array(),

Official plugins with macro support

Currently these have support for macros:

• The jPlayer plugin: [ MEDIAPLAYER ]. This macro is also available and output by tinyZenpage if embeding multimedia items. 
• The Slideshow plugin: [ SLIDESHOW ].

See each plugins' documentation for more detailed info.