Matrix Field

Enable dynamic composition of groups of fields

The matrix field is a very powerful feature of Enact. It allows the definition of fields organized into groups, which can then be used by content creators in any manner they wish, allowing them to add and remove fields to suite their current content and layout needs.

Options#

  • Max Blocks – The maximum number of blocks (field groups) that can be created in the matrix field. Leave blank if you don't care how many blocks are created.

  • Groups – Groups are the holders of any number of fields, and are how content is added and sorted within the matrix. Sort the groups in the matrix as you see fit. The order they appear in the options are only relevant for how they are displayed to be added within the actual use of the matrix field, not how they ultimately will be sorted when in use, as that is up to the content creator.

    Groups are defined by:

    • Name – The name as presented in the fields to the content creators.

    • Handle – The handle used to access the groups within templates.

    • Limit – The maximum number of times the group can be used in the matrix. Leave blank if you don't care.

  • Fields – The fields available for use in the group. All fields available in Enact are available for setup within the matrix groups, with the exception of the matrix field. Sort the fields within the group to set how they will be presented when shown to content creators when using the matrix group.

Use#

Use the controls at the bottom of the matrix fields to add groups to the matrix

Once you have added a group you can use the elevator icon button in the controls at the top of the group to add more groups before or after

You may also re-order/sort the the group using the move icon button in the controls at the top of the group, and delete the group using the x icon button.

If any of the groups have a limit set, once the limit is reached the group will longer be add-able to the matrix as shown below by the buttons turning gray

and as shown in the before and after controls with the buttons turning gray and the maxed out label being added

If the field is set to required, then the entry will not be update-able until at least one group has been added to the matrix.

Template Use#

Access your matrix fields via the handle you set for the field. Each matrix field provides an array accessed via matrixFieldHandle which contains the groups of fields stored in the matrix, in the order set by the content creators.

Lets say for example you have a matrix with three groups:

  • Group 1

    • Name : Image And Heading

    • Handle : imageAndHeading

    • Fields :

      • Image (a asset field)

      • Heading (a plaintext field)

  • Group 2

    • Name : Secondary Heading

    • Handle : secondaryHeading

    • Fields :

      • Heading (a plaintext field)

      • Position (a dropdown field)

  • Group 3

    • Name : Content

    • Handle : content

    • Fields :

      • Content (a richtext field)

      • Background Color (a color field)

To display a matrix field composed of these groups (remember there can be any number of the groups in the matrix, unless you set a max number of groups, or limit the number of times a particular group can be used in the matrix options, and the groups can be in any order) use a for loop. You can determine what kind of group your currently handling by calling the group directly, or using the groups handle property, and you access the fields in the group using the handle for the field as a property on the group.

{% for group in entry.yourMatrixFieldHandle %}


    {% if group == 'imageAndHeading' %}


        <div class='bg-heading'>

            <h1>{{ group.heading }}</h1>

            {{ group.image.assetFieldHandle[0].getImgHtml }}

        </div>


    {% elseif group.handle == 'secondaryHeading' %}


        <div class='secondary-heading' style='text-align:{{ group.position }};'>

            {{ group.heading}}

        </div>


    {% elseif group == 'content' %}


        <div class='content' style='background-color:{{ group.backgroundColor }};'>

           {{ group.content }}

        </div>


    {% endif %}


{% endfor %}