Macros

The framework includes sets of macros that will help you create forms, modals, accordions, and icons so as to reduce the amount of typing that you need to do. Using these will also make it easier to update the layout if the HTML/CSS for layout changes, for example with a different CSS framework.

If you are logged in as an administrator, you can see how most of these macros render in your browser from the Test Page on the Testing menu.

Form creation macros

To use the form macros you need to import them:

{% import '@util/formmacro.twig' as f %}

Form set-up

Two wrapping macros handle setting up a form:

{{f.startform({…options…})}}
…form content…
{{f.endform()}}

The options availabe for start form are:

method Either get or post. Defaults to get if omitted
action The URL to send the form to. Defaults to '#' (the current page) if omitted
multi If TRUE then generate an enctype="multipart/form-data" attribute. You must use this if you are sending files!
id The value for the id attribute
class The value for the class attribute
data The value is an object containing field names and values that are expanded into data attributes, see example below

Example


    {{f.startform({method: 'post', action: '/handle', id: 'fform', class: 'fclass', data: {fcode: 55}, multi: TRUE})}}
    {{f.endform()}}

will generate


    
<form id="fform" class="fclass" action="#" method="post" data-fcode="55" enctype="multipart/form-data" role="form">

    </form>

text, email, password, textarea

To instantiate one of these use the appropriate macro, for example:

{{f.text({…options…})}}
{{f.email({…options…})}}
{{f.password({…options…})}}
{{f.textarea({…options…})}}

The options availabe are:

label The label that appears above the input
id The value for the id attribute
name The value for the name attribute
value The value for the value attribute
disabled A boolean value (TRUE or FALSE) indicating whether or not this attribute is enabled
readonly A boolean value (TRUE or FALSE) indicating whether or not this attribute is enabled
required A boolean value (TRUE or FALSE) indicating whether or not this attribute is enabled
class This will add the given value to the class field of the input or textarea
ph The placeholder text for the input
data The value is an object containing field names and values that are expanded into data attributes, see example below
parsley The value is an object contaniing field names and values that are expanded into data-parsley attributes, see example below
help Help text that will appear below the input.

Example


    {{f.text({label: 'Name', id: 'npname', name: 'pname', value: 'MyName',
        ph: 'Page name - alphanumeric characters only', required: TRUE,
        parsley: { type: 'alphanum'}, data: { dval: 56 } })}}

will generate


<div class="mb-3">
<label class="form-label" for="npname">Name</label>
<input type="text" id="npname" required name="pname" class="form-control" placeholder="Page name - alphanumeric characters only" data-dval="56"
 data-parsley-type="alphanum" //>
</div>

This renders as :

number and range

These have the same options as above with the following extras :

min The value for the min attribute
step The value for the step attribute
max The value for the max attribute
dvalue The value for the defaultValue attribute - range only

date, datetime, datetimelocal and time

These have the same options as text. Note that datetime will actually generate a dateime-local input as the original datetime has been removed from the HTML specification. Also note that not all browsers support these input types and will default to text.

checkbox

This generates checkboxes.

{{f.checkbox({…options…})}}

Options:

group If TRUE, wraps all the checkboxes in a Bootstrap form-group div.
label Only enabled when group is TRUE, a label that will appear above the line of checkboxes. It is not a label for an individual checkbox.
class A class added to each checkbox
labels An array of {labels}{v}}, one for each checkbox
ids An array of {labels}{v}}, one for each checkbox
names An array of {labels}{v}}, one for each checkbox
values An array of {labels}{v}}, one for each checkbox
check An array of boolean values for each checkbox - if TRUE then checkbox is checked
disabled An array of boolean values for each checkbox - if TRUE then checkbox is disabled

Example


    {{f.checkbox({group: TRUE, label: 'Rank', class: 'cbc', labels: ['First', 'Second', 'Third'],
        ids: ['id1', 'id2', 'id3'], names: ['c1', 'c2', 'c3'],
        values: ['v1', 'v2', 'v3'], check: [TRUE, FALSE, TRUE], disabled: [FALSE, FALSE, TRUE]})}}

will generate


<div class="mb-3">
<label class="form-label">Rank</label>
            <div class="form-check">
            <label class="form-check-label me-4">
                        <input type="checkbox" value="v1" name="c1" class="me-2 class="form-control class""
                 id="id1" checked />
            First</label>
        </div>

            <div class="form-check">
            <label class="form-check-label me-4">
                        <input type="checkbox" value="v2" name="c2" class="me-2 class="form-control class""
                 id="id2" />
            Second</label>
        </div>

            <div class="form-check">
            <label class="form-check-label me-4">
                        <input type="checkbox" value="v3" name="c3" class="me-2 class="form-control class""
                 id="id3" checked disabled />
            Third</label>
        </div>

        </div>

This renders as :

radio

This generates radio buttons.

{{f.radio({…options…})}}

Options:

group If TRUE, wraps all the checkboxes in a Bootstrap form-group div.
label Only enabled when group is TRUE, a label that will appear above the line of radio buttons. It is not a label for an individual radio button.
name If this is set then every radio button has the same name. Do not mix this with the names option (or if you do be careful)
class A class added to each radio button
labels An array of labels, one for each radio button
ids An array of ids, one for each radio button
names An array of names, one for each radio button
values An array of values, one for each radio button
check An array of boolean values for each radio button - if TRUE then radio button is checked
disabled An array of boolean values for each radio button- if TRUE then radio button is disabled

Example


    {{f.radio({group: TRUE, label: 'Pick', class: 'rbc', labels: ['Yes', 'No', 'Maybe'], name: 'pick',
        ids: ['id1', 'id2', 'id3'],
        values: [1, 2, 3], check: [FALSE, FALSE, TRUE], disabled: [FALSE, TRUE, FALSE]})}}

will generate


<div class="mb-3">
<label class="form-label">Pick</label>
            <div class="form-check">
                        <label class="form-check-label me-4">
                <input type="radio" value="1" name="pick" class="me-2 class="form-control class""
                 id="id1" />
            Yes</label>
        </div>

            <div class="form-check">
                        <label class="form-check-label me-4">
                <input type="radio" value="2" name="pick" class="me-2 class="form-control class""
                 id="id2" disabled />
            No</label>
        </div>

            <div class="form-check">
                        <label class="form-check-label me-4">
                <input type="radio" value="3" name="pick" class="me-2 class="form-control class""
                 id="id3" checked />
            Maybe</label>
        </div>

        </div>

This renders as :

select

This generates a select input.

{{f.select({…options…})}}

Options:

label The value for the label attribute
id The value for the id attribute
name The value for the name attribute
class The value for the class attribute
options An array of objects with fields value and text, see example
selected If this value is equal to one of the option values then that option is selected
multiple If TRUE then allow multiple selects
disabled If TRUE then select is disabled
help This generates a help text belwo the select box

Example


        {% set options = [
            {text: '&mdash;Select&mdash;', value: ''},
            {text: 'Value 1', value: 1},
            {text: 'Value 2', value: 2},
            {text: 'Value 3', value: 3},
            {text: 'Value 4', value: 4},
            {text: 'Value 5', value: 5},
        ] %}
        {{f.select({label: 'Select', id: 'slid21', name: 'sl21', selected: 1, options: options})}}

will generate


<div class="mb-3">
<label class="form-label">Select</label>

    <select  class="form-control" name="sl21" >
                    <option value="">&mdash;Select&mdash;</option>
                    <option value="1" selected="selected">Value 1</option>
                    <option value="2">Value 2</option>
                    <option value="3">Value 3</option>
                    <option value="4">Value 4</option>
                    <option value="5">Value 5</option>
            </select></div>

This renders as :

file

This generates a file input.

{{f.file({…options…})}}

Options:

id The value for the id attribute
name The value for the name attribute
accept Mimetypes that can be sent via this input
multiple Allow multiple files

hidden

This generates a hidden input.

{{f.hidden({…options…})}}

Options:

id The value for the id attribute
name The value for the name attribute
value The value for the value attribute
data The value is an object containing field names and values that are expanded into data attributes, see example below

submit

This generates a submit button and has only one option:

bstyle The button class used for styling - defaults to btn-primary for Bootstrap

Modal creation macros

Read the Bootstrap documentation to understand how modals work. To use the modal macros you need to import them:

{% import '@util/modalmacro.twig' as m %}

Currently there are only two main macros supporting modal creation:

{{m.open({…options…})}}

The options availabe are:

title The title for the modal
id The value for the id attribute
size One of xs, sm, md, lg, xl - deafults to lg
{{m.close({…options…})}}

The options availabe are:

nofooter If TRUE then no footer will be generated. The footer has an action button and a close button in it and is used when there is a form in the modal
action The label for the "submit" button
id The value for the id attribute

Accordion creation macros

Read the Bootstrap documentation to understand how accordions work. To use the the macros you need to import them:

{% import '@util/accmacro.twig' as a %}

The accordion macro expects the contents of each of accordion cards to be in a separate twig file. At the moment there is no way of simply including text. You can see an example that uses this macro on the installation page.

{{a.accordion(id, cards, carets)}}

where the parameters are:

id The id value for the whole accordion.
tabs an array of objects describing each of the accordion cards in the format:
[{id: 'the card id', file: 'The twig file to include',
title: 'The card title', with:'Optional with object for the include statement'}, …]
carets

An optional argument that defaults to FALSE. If it is set to TRUE then a right pointing caret will be added to the end of each title. You must then use the macro:

{{a.caretJS(id)}}

in your onload block as JavaScript is needed to toggle the caret between right and down as the card is opened and closed.

Icon inserting macros

The framework uses macros from Font Awesome which povides a comprehensive set of icons in a variety of styles. (Note some of the styles are only available if you have a license to use them). Include the macros using:

{% import '@content/iconmacro.twig' as fa %}

You are most likely to use the fa macro:

{{fa.fa(icon, class)}}

where the parameters are:

icon The name of the icon. All Font Awesome Icons are named using a class name in the form fa-name-of-icon. For this parameter you remove the fa- and pass in the rest of the name: {{fa.fa('pencil')}} produces using the distributed rendering.
class An optional parameter that lets you add more classes to the icon.

The key thing about this macro is that you can change the default style that is used by editing the macro definition, which is in twigs/content/iconmacro.twig.

There are also macros for each of the styles available that ake the same paramters: farfas, fad, and fab. Go to the Font Awesome website to learn more about the different styles and how to access them. Also included are some shortcut macros for icons that are used by the Framework itself — look in twigs/content/iconmacro.twig to see them.