LUTECE Site Support - Wiki - Implementation and Use of Freemarker Macros in Back Office Templates

Mar 25, 2025 10:36:04 AM Elysa Jouve

Implementation and Use of Freemarker Macros in Templates

The rendering of macros by the framework is visible on the Style Guide BO.

The Macros

Macros aim to replace HTML code in order to reduce maintenance and facilitate migrations to other CSS frameworks. They provide a consistent and cohesive design intended for the entire back-office pages, and as such, their use is reserved for the back office.

Macros look like HTML to remain readable but also resemble HTML with Bootstrap classes since they were originally written to work with this CSS framework. Some macro names thus refer to Bootstrap components. For more information on these components, please consult the documentation.

Many macro parameters correspond simply to HTML attributes with the same name (name, id, title, type, href, class, action...).

Other parameters invoke functions and allow adding classes to meet presentation needs:

hide=['all'|'xs', 'sm', 'md', 'lg', 'xl']: This parameter specifies the visibility of an element. You can either hide it for all breakpoints ('all') or for certain breakpoints (xs, sm, md, lg, or xl).
align='left|right|center': This manages the alignment of an element on the page.

Finally, this parameter allows adding additional attributes:

params: This allows adding elements not included in the macro parameters for greater flexibility.

These parameters are commonly found in most macros.

Page Structure

Without Tabs

<@pageContainer>
    <@pageColumn>
        <@pageHeader title=''>
                Action Buttons
            </@pageHeader>
           Page content
    </@pageColumn>
</@pageContainer>

The `columns` macro includes the possibility to use the CSS framework grid system with parameters xs, sm, md, lg, and xl. The parameters of type ["offset"] allow shifting columns on the grid.

With Tabs

<@pageContainer>
    <@pageColumn>
        <@pageHeader title=''>
                Action Buttons
        </@pageHeader>
        <@tabs>
            <@tabList>
                <@tabLink href='panel1' active=true title='' />
                <@tabLink href='panel2'  title='' />
        </@tabList>
        <@tabContent>
                <@tabPanel id='panel1' active=true>
                    ...
                </@tabPanel>
                <@tabPanel id='panel2'>
                    ...
                </@tabPanel>
            </@tabContent>
        </@tabs>
    </@pageColumn>
</@pageContainer>

Rows and Columns

The grid system can be used with the macros as follows:

row for a new row
columns for columns with values corresponding to the breakpoints (from 1 to 12 columns) with parameters xs, sm, md, lg, and xl taking values from 1 to 12, as well as offset parameters to shift the columns.

<@row>
    <@columns>
        ...
    <@columns>
</@row>

Forms

The Form

The `tform` macro is used to display form-type elements.

Parameters:

type: horizontal or inline

The `fieldSet` macro is used to group fields and incorporates the legend of each group.

<@tform method='post' action=''>
   <@fieldSet legend=''>...</@fieldSet>
    ....
</@tform>

Form Elements

All form elements must be included within `formGroup` containers:

<@formGroup labelFor='' labelKey='' helpKey=''>
    Here is the form element
</@formGroup>

`labelFor` refers to the `name` attribute of the field type included in the formGroup (essential for clicking on a radio button or checkbox via the label, for example), `labelKey` corresponds to the content of the field label, and `helpKey` contains the help text for the field.

The `mandatory` parameter is inherited by the child field, which will automatically have the `required` attribute added. An asterisk will also be added to the label to visually indicate the mandatory nature of the field.

The `groupStyle` attribute of the `formGroup` macro allows dynamically adding a class to the field after form submission to represent its error or success state, for example.

Input Text, Search, Password, Email, File, Number, Hidden

<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='text' name='' id='' value='' />
</@formGroup>
<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='search' name='' id='' value='' />
</@formGroup>
<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='password' name='' id='' value='' />
</@formGroup>
<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='email' name='' id='' value='' />
</@formGroup>
<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='file' name='' id='' value='' />
</@formGroup>
<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='number' name='' id='' value='' />
</@formGroup>
<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='hidden' name='' id='' value='' />
</@formGroup>

Input Date, Datetime, Daterange, Time

Input Date

<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='date' name='' id='' value='' />
</@formGroup>

Input Datetime

<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='datetime' name='' id='' value='' />
</@formGroup>

Input Time

<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='time' name='' id='' value='' />
</@formGroup>

Time input with limits:

<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='time' name='' id='' value='' minTime='16:00' maxTime='22:30' />
</@formGroup>

Time input with a default value:

<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='time' name='' id='' value='' defaultDate='13:45' />
</@formGroup>

Ranges

This functionality is provided by the FlatPickr plugin (js/admin/bootstrap-flatpickr-rangePlugin.js).

Input Daterange

<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='daterange' dateRangeEndId='' name='' id='' value='' />
</@formGroup>}

The `dateRangeEndId` parameter must be specified on the first date field, but nothing for the second (which can even be of type text).

Input Datetimerange

<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='datetimerange' name='' id='' value='' />
</@formGroup>

Textarea

<@formGroup labelFor='' labelKey='' helpKey=''>
    <@input type='textarea' name='' id='' value='' />
</@formGroup>

Select

All "combo" macros should be replaced by the "select" macro, which covers the various use cases of the old combo macros.

Select with a list of values

<@select name='page_template_code' id='page_template_code'>
    <#list pages_list as key, value>
        <option value="${key}">${value}</option>
    </#list>
</@select>

<@select name='order_id' id='order_id-${group.id?html}' default_value=group.order?string items=order_list sort=true size='sm' />

Select with HTML content only

<@select id='status' name='status'>
    <#if default_user_status = 1>
         <option value="0">Enabled</option>
         <option value="1" selected="selected" >Disabled</option>
    <#else>
         <option value="0" selected="selected" >Enabled</option>
         <option value="1">Disabled</option>
    </#if>
</@select>

Checkbox

<@checkBox labelFor='status1' labelKey='Status' name='status' id='status1' value='1' />

The `labelFor` parameter must match the ID of the checkbox.

Radio Button

<@radioButton labelFor='form_id' labelKey='Form' name='form' id='form_id' value='2' />

The `labelFor` parameter must match the ID of the radio button.

Buttons

Button

Example of a simple submit button for a form:

<@button type='submit' title='Edit' buttonIcon='check'  />

Example of a "Cancel" button:

<@button type='submit' name='cancel' value='cancel' buttonIcon='times' title='Cancel' cancel=true size='' />

Parameters:

The `cancel` parameter adds the `formnovalidate` attribute to the button and changes its color from a submit button.

aButton

This macro represents a simple link styled as a button, with the associated class.

<@aButton href='jsp/admin/AdminLogin.jsp' title='Cancel' buttonIcon='close' color='default' />

<@aButton href='jsp/admin/features/RemoveExternalFeature.jsp?external_feature_id=${external_feature.id}' title='Delete' hideTitle=['all'] buttonIcon='trash' color='danger' size='sm' />

Element or Button Groups

inputGroup

This macro and its sub-macro `inputGroupItem` allow grouping a field and a button (either as a button or text). The button can be placed to the left or right, depending on whether the `inputGroupItem` is placed before or after the field.

<@inputGroup>
    <@input type='text' />
    <@inputGroupItem>
        <@button type='submit' />
    </@inputGroupItem>
</@inputGroup>

btnGroup

This macro groups buttons together.

<@btnGroup>
    <@button type='button' />
    <@button type='submit' />
    <@aButton href='' />
</@btnGroup>

Dynamic Components

Accordion

<@accordionContainer id='PARENT_ID'>
    <@accordionPanel collapsed=true childId='CHILD_ID'>
        <@accordionHeader title='Header Title' id='HEADER_ID' parentId='PARENT_ID' />
        <@accordionBody>
            Content
        </@accordionBody>
    </@accordionPanel>
</@accordionContainer>

Example of an accordion with a list:

<@accordionContainer id='accordion'>
    <#list groups_list as group>
        <@accordionPanel collapsed=true childId='${group.id}_child'>
            <@accordionHeader title='${group.name}' id='${group.id}_header' />
            <@accordionBody>
                <p>${group.description}</p>
            </@accordionBody>
        </@accordionPanel>
    </#list>
</@accordionContainer>

Notes:

The `childId` parameter of the `accordionPanel` macro corresponds to the ID of the collapsible `accordionBody` element. The ID is automatically added by the macro.

Collapse/Expand Buttons

Possible styles are `card-control collapse` and `card-control remove`.

Collapse Button

<@button type='button' title='Button' style='card-control collapse' buttonTargetId='#example' buttonIcon='minus' size='sm' />