Docs Developer Site
Enonic XPCMSMacros

Macros

Contents

Macros

Macros are instructions that allow adding extra functionality or include dynamic content in the Html Editor.

The Html Editor is used when editing HtmlArea input fields, or while editing a Text component in Page Editor.

There are two built-in macros included in XP. But its real power comes from macros provided by applications. When an application that contains macros is added to a site, they will be available for any HtmlArea or Text component inside the site.

Macro instruction

A macro instruction is similar to an HTML or XML tag but using square brackets instead of angle brackets.

[macroname attrib1="value1" attrib2="value2"] body [/macroname]

A macro has a name, a set of attributes, and optionally a body (anything that is too long to be passed via parameters).

[macroname attrib1="value1" attrib2="value2"/]

Macro instructions can be added anywhere in an HTML page, usually inside a content’s HtmlArea field.

During the rendering of the page the macros are resolved and executed. Then the result from executing the macro replaces the instruction text. In addition, a macro can also add styles or scripts to the page, by setting Page Contributions in its response.

A user can add macro instructions by typing the square bracket tags, as the examples above. But more frequently it will click on the Insert macro button and select one of the macros available.

Descriptor

A macro descriptor is an xml file that allows assigning a user-friendly name, and a description to the macro. It also has a configuration to define the types and names of the macro parameters.

display-name

A simple human readable display name.

[email protected]

The key to look up the display-name text in the localization bundles. Optional. (See also Localization of Schemas)

description

A description to show in the Insert macro dialog in Content Studio.

[email protected]

The key to look up the description text in the localization bundles. Optional. (See also Localization of Schemas)

config

The config element is a form where each input element corresponds to a macro parameter. The macro body is represented with an input named "body".

The config form does not support nested elements, so Item Sets are not allowed in the macro config form. Also the HtmlArea input type is not allowed in the config form, since it may contain macros itself.
If you don’t have a input with the name="body", the generated macro tag will be self closing [macro attr="" /]

Its path follows the pattern site/macros/<macroName>/<macroName>.xml

<macro>
  <display-name i18n="a-macro.display-name">Current user</display-name>
  <description i18n="a-macro.description">Shows currently logged user</description>

  <form>
    <input name="body" type="TextLine">
      <label>Macro body</label>
    </input>
    <input name="defaultText" type="TextLine">
      <label>Text to show if no user logged in</label>
    </input>
  </form>
</macro>
The macro texts (display-name, description, label and help-text from config input types) can be provided in multiple languages. See Localization of Schemas for details.

Although not strictly required, it is recommended to create a descriptor, as it provides the required details for adding macros through the UI in Content Studio.

Controller

The functionality of a macro is implemented in a JavaScript controller, inside an application.

Its path follows the pattern site/macros/<macroName>/<macroName>.js

A macro controller must export a single macro function that takes a context parameter and returns a response object (see HTTP Response).

The context parameter is a Javascript object with the following properties:

name

a string containing the macro name.

body

a string containing the body of the macro instruction.

params

an object with key-value pairs containing the macro parameters. The values are the strings from the macro instruction attributes.

document

a string with the HTML document that contains the current macro. The document contains the raw source HTML, before any macro instructions have been executed, and before image or content URLs have been resolved. The document is only an input parameter to the macro, it cannot be modified.

request

the request object.

// Example usage: [currentUser _document="__macroDocument4" defaultText="Anonymous"/]
var authLib = require('/lib/xp/auth');
var portalLib = require('/lib/xp/portal');

exports.macro = function (context) {
    var defaultText = context.params.defaultText;
    var macroBody = context.body;

    var user = authLib.getUser();
    var body = '<span>' + macroBody || (user ? user.displayName : defaultText) + '</span>';

    var doc = context.document; // HTML document containing the current macro
    var lineCount = doc.split(/\r\n|\r|\n/).length;
    if (lineCount <= 1) {
        return {
            body: ''
        }
    }

    return {
        body: body,
        pageContributions: {
            headEnd: [
                '<link rel="stylesheet" href="' + portalLib.assetUrl({path: 'css/current-user.css'}) + '"/>'
            ]
        }
    }
};

Note that only the body and pageContributions fields of the response are relevant for macro controllers.

A macro controller can also use libraries, like any other JavaScript controller.

Built-in macros

There are currently 2 built-in macros that are included in XP and available for any site:

disable

The contents (body) of this macro will not be evaluated as macros. That allows rendering another macro instruction as text without executing it. It is useful for documenting macros, for example. This macro has no parameters.

embed

It allows embedding an <iframe> element in an HTML area. This is a generic way for embedding content from an external source (e.g. YouTube videos). This macro has no parameters.

Examples:

Example of macro instruction: [myMacro param1="value1"/]
A macro may optionally have its own specific icon. The icon can be assigned to the macro by adding a PNG or SVG file with the same name, in the macro folder, e.g. site/macros/myMacro/myMacro.svg

Contents