Elephant renders macros each time a page is requested. Macros start with {@ special characters and expand into text or HTML code. Macros can even include content from a file, HTML page or JSP page. In order to understand what macros are for see what current macros do:

• Core
• Navigational
• Modules
• Documentation
• Macro summary

Macros can be nested, but take in mind that macros are written inline, in order to allow content inclusions. Thus, only macros that resolve to a string could be nested. Ex.

{@equals:{@user:id}:admin:Administering:Browsing}

To escape the : character prepend a slash, like /:.

Next generation

The next generation of macros provide a great number of features, aiming to easy-of-use customization. The main goals are:

• Order agnostic parameters. Parameters can be specified by name, in any order.
• Significant decrement of macro names. Using the order agnostic parameters, a single macro can offer more options.
• Easy escaping characters. Escape values enclose it in brackets, ex. name=[values] or [values].
• Single parser, multiple processors. Relaxes complexity on macro processors, by parsing parameter tuples.
• Improved fail detection. Parser detects macro existence before fully interpreting the content.
• Better backward compatibility. While using named parameters, macro changes won't break previous code.
• Error feedback. None interpretable macros will be rendered in red and failure will be logged in the system.
• Empty result default. Empty results can show a value using the system-wide parameter void.
• Fully nested macros. Macros can be nested, in order to provide values, macro names or the empty default.

Next generation macros are expressed as @{macro_name}.

Macros with readers, how does it work?

The easiest way to read a file is store it in context's repository and access it with */file. The * will expand into rendering context repository. For example:

{@marker-xml:xml:doc:*/doc.xml}

Reads doc.xml in current repository and passes its data to [Template_root]/xml/docTemplate.html to be formatted.

Reading properties

Properties are stored in props list in the same order they are stored on disc. You can iterate props with #list.

<#list props?keys as key>
   <#assign value=props[key]/>
   // do something with key and value
   ...
< /#list>

Reading XML

XML documents are stored in doc model. You can iterate the elements using dot syntax and iterate collections as you would usually do for any other data. The XML model is the FreeMarker NodeModel.

Reading JSON

JSON files are stored in json model. To access a root, use json.read("$.root"). If the root is a list, use json.list("$.root"). Once retrieved the root, you can iterate the elements using dot syntax and iterate collections as you would usually do for any other data. The JSON model is a subset of the JsonPath DocumentContext, optimized for templates usage.

The JSON books example

The data:

{
  "book": [
    {
      "title": "...",
      "author": "...",
      "excerpt": "...",
      "availability": "...",
      "link": "...",
      "filelink": "...",
      "imagelink": "...",
      "pages": 0
    },
    {
      ...
    },
    ...
  ]
}

The template (Semantic-UI):

<div class="ui divided items">
  <#list json.list("$.book") as book>
    <div class="item">
      <a class="ui tiny image" href="${book.link}">
        <img src="${book.imagelink}"/>
      </a>
      <div class="content">
        <a class="header" href="${book.link}">${book.title}</a>
        <div class="meta">
          ${book.author}
        </div>
        <div class="description">
          ${book.excerpt}
        </div>
        <div class="extra">
          ${book.availability}
          <#if book.filelink?has_content>
            <a target="_new" href="${book.filelink}">${book.pages}</a>
          < /#if>
        </div>
      </div>
    </div>
  < /#list>
</div>

Understanding what behavioural keywords are

Behavioural keywords stand for keywords controlling how information displays. The way behaviours will extend in future versions might be controlled in this section.

Understanding what navigational keywords and selection keywords mean

Navigational keywords end up as a list, colon separated, of keywords pointing to existing contexts. As starting point, path_to_contexts initializes to current context, that is, the web page where macro displays.

Here comes a brief description of what each keyword does and after some clear examples:

Navigation keywords move current selection from context to context.

Selection keywords actually return contexts, one or several. A zero results it's considered an error an macro will displays with m_error class, which defaults to red color and a warning image. Otherwise, macro expands into m_list class.

Learning by example

Current list of modules exposing macros.

• Attachments
• Calendar
• Contacts
• DAO
• Dossier
• Elephant
• Financials
• Publications
• Students