Grid

Templating manual

Edit this chapter on Github Jump to...

3.2.5 Grid

The Grid is a structure much like an HTML table, with rows and columns that define a grid structure of cells. In Flux you can define grids inside templates by using the flux:grid ViewHelper and sub-ViewHelpers flux:grid.row and flux:grid.column. When a template contains a grid definition and the feature which uses the template supports grids the defined grid is used by TYPO3 (for example, fluidpages supports grids to define page content columns, and fluidcontent supports grids to define content container areas in other content elements).

Note: the Grid ViewHelpers do not render any output, they only define a structure that is stored internally in the template parser. Their only purpose is to define Grids which are rendered by other methods.

In the context of fluidpages and fluidcontent the flux:grid.column defines areas that can contain content elements. In fluidpages the Grid becomes a so-called backend layout in which each column is identified by a number, the colPos value. In fluidcontent this value is a string name that can contain machine-readable names like myContentArea or leftColumn etc., but can of course also be a number if you so desire.

Note: some Grid features will require the colPos attribute while others will require the name. The documentation of any feature using Grids will clearly state which is expected, but as a rule of thumb only page template features will use the colPos attribute and all others will use the name attribute.

The name or column position number of each column is then saved to records when they are placed into the column. Again in the context of fluidpages and fluidcontent these values are stored in fields which are defined in TCA as proper relations, enabling things like native translation of content elements inside other content elements and recursive copy/reference actions all handled by the TYPO3 core.

An example Grid definition

The following example defines a Grid which has two rows with each two columns. The template uses column numbering and is intended to be used in a page template. The code piece is placed inside an f:section with name Configuration and is a sibling of the flux:form tag:

<f:section name="Configuration">
    <flux:form id="myForm" />
    <flux:grid>
        <flux:grid.row>
            <flux:grid.column colPos="0" label="Top left" />
            <flux:grid.column colPos="1" label="Top right" />
        </flux:grid.row>
        <flux:grid.row>
            <flux:grid.column colPos="2" label="Bottom left" />
            <flux:grid.column colPos="3" label="Bottom right" />
        </flux:grid.row>
    </flux:grid>
</f:section>

The resulting structure of which looks like:

|¨¨¨|¨¨¨|
|   |   |
|---|---|
|   |   |
|___|___|

Controlling spans and widths

For advanced layouts with cells spanning multiple columns or rows the colspan and rowspan attributes can be used exactly like you would on an HTML table. In TYPO3, setting for example colspan="2" on one column and no colspan on the other, results in one column being twice as wide as the other. You can utilize this to control the structure's rendering:

<f:section name="Configuration">
    <flux:form id="myForm" />
    <flux:grid>
        <flux:grid.row>
            <flux:grid.column colPos="0" colspan="4" label="Top left" />
            <flux:grid.column colPos="1" rowspan="2" label="Top right" />
        </flux:grid.row>
        <flux:grid.row>
            <flux:grid.column colPos="2" colspan="4" label="Bottom left" />
        </flux:grid.row>
    </flux:grid>
</f:section>

Which results in this approximate rendering:

|¨¨¨¨¨¨¨¨¨¨¨|¨¨¨|
|           |   |
|-----------|   |
|           |   |
|___________|___|

Some implementations such as fluidcontent also support setting a style attribute on flux:grid.column - which then gets used as value of the style="" tag that represents the column when renderered.

Shorthand

When you only require a single row and a single column with no particular setup, you may use the flux:form.content shorthand. The following template example illustrates the behavior of this shorthand ViewHelper:

<flux:form.content />
<!-- ...is 100% identical to but must never be mixed with... -->
<flux:grid>
    <flux:grid.row>
        <flux:grid.column name="content" colPos="0" />
    </flux:grid.row>
</flux:grid>

The two variants should never be used in the same template since they both use the same internal variable - the result is that only the last occurrence of either ViewHelper is used since the old variable gets overwritten.

Variables allowedContentTypes and deniedContentTypes

It is possible to specify for a specific flux:grid.column what kind of child elements are allowed / denied to add when invoking the New Content Element Wizard. This could be useful, for example, if you are planning some workflow for editors.

        <flux:grid>
            <flux:grid.row>
                <flux:grid.column name="column1">
                    <flux:form.variable name="deniedContentTypes" value="text,textpic" />
                </flux:grid.column>
            </flux:grid.row>
        </flux:grid>

With the code above all the content elements except text and textpic will appear the New Content Element Wizard.

You also could do the opposite and just show text as only available Content.

        <flux:grid>
            <flux:grid.row>
                <flux:grid.column name="column1">
                    <flux:form.variable name="allowedContentTypes" value="text" />
                </flux:grid.column>
            </flux:grid.row>
        </flux:grid>
Note: if you are looking for allow only some fluidcontent you need to introduce other 'flux:form.variable' 
        <flux:grid>
            <flux:grid.row>
                <flux:grid.column name="column1">
                    <flux:form.variable name="allowedContentTypes" value="fluidcontent_content" />
                    <flux:form.variable name="Fluidcontent" value="{allowedContentTypes: 'my_own_extension:MyOwnContent.html'}" />
                </flux:grid.column>
            </flux:grid.row>
        </flux:grid>
Jump to...