Skip to content

Improvements and fixes to Grid / Fluid Fieldtypes and to No_Results #1160

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nep wants to merge 5 commits into
base: 7.dev
Choose a base branch
from
+100 −62
Open

Improvements and fixes to Grid / Fluid Fieldtypes and to No_Results #1160

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5c05741
Enhance `{if no_results}` documentation clarity
nep Jul 8, 2026
c66f89e
Update Fluid Field Notes for clarity
nep Jul 8, 2026
1c2babc
Revise Grid field documentation for clarity
nep Jul 9, 2026
af42a51
Merge pull request #6 from nep/patch-12
nep Jul 9, 2026
50fe31d
Merge pull request #7 from nep/patch-11
nep Jul 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 30 additions & 13 deletions docs/channels/entries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1261,33 +1261,50 @@ Handy conditional for displaying markup or content based on whether or not the e

### `{if no_results}`

{if no_results} content {/if}
{if no_results} There are no entries available {/if}

You may use this conditional for displaying a message in the case when no entries are returned. The contents inside of the conditional will be displayed in cases where there are no results returned for the tag.
You will use this conditional frequently to display alternative content when no entries are returned. The content inside the conditional will be displayed when no results are returned for the tag with the given parameters.

{if no_results} <p>There are no entries available.</p> {/if}

Further, you may specify that another Template be shown in a case when there are no results. In order to do that, you must use the redirect=variable
Further, you may specify that another page should be shown when there are no results. In order to do that, you use the [redirect= variable](templates/globals/single-variables.md#redirect).

{if no_results} {redirect="channel/noresult"} {/if}

Lastly, if you want to simply display your 404 page (with 404 headers) when no entries are returned, simply use "404" as the template name.
Lastly, if you want to simply display your [custom Not Found page](general/404pages.md#404-pages) (with proper 404 headers) when no entries are returned, simply use "404" as the template name.

{if no_results} {redirect="404"} {/if}

NOTE: **Note:** If you have several nested tags, each one would need to include a `{if no_results}` pair to be parsed correctly.
NOTE: **Note:** If you have nested tag loops that each check for no results, the outer one will "claim" and process the first (and only the first) `{if no_results}` block before the inner tag loop has a chance, unless the conditional is prefixed (which not every tag provides).

For instance, if you have a Grid field with an `{if no_results}` block, the parent `{exp:channel:entries}` tag pair would need to include an `{if no_results}` block as well:
For instance, if you have a Relationship field with an `{if no_results}` block, and the parent `{exp:channel:entries}` tag pair needs to include an `{if no_results}` block as well, you should use this format:
```
{exp:channel:entries channel="blog"}
{my_relationship_field}
{if my_relationship_field:no_results} Relationship is empty {/if}
{my_relationship_field:title}
{/my_relationship_field}
{if no_results} No entries {/if}
{/exp:channel:entries}
```

NOTE: **Note:** Grid, File Grid, and Member fields do not have a `{if no_results}` conditional. Use [:total_rows](/fieldtypes/grid.md#total_rows-1).
Fluid fields do not have a `{if no_results}` conditional. Use [:total_fields](/fieldtypes/fluid.md#total_fields)
```
{exp:channel:entries channel="blog"}
{if my_grid_field:total_rows == 0} Grid is empty {/if}
{my_grid_field}
{if no_results} Grid is empty {/if}
{my_grid_field:text}
{/my_grid_field}
{if my_fluid_field:total_fields == 0} Fluid field is empty {/if}
{my_fluid_field}
{my_grid_field:text}
{/my_fluid_field}
{if no_results} No entries {/if}
{/exp:channel:entries}
```

NOTE: **Note:** It is invalid syntax to use `{if:else}` with the `{if no_results}` conditional. Results (no pun intended) may be unpredictable.


### `{if not_category_request}`

{if not_category_request} content {/if}
Expand Down Expand Up @@ -1326,15 +1343,15 @@ You may test whether an entry is set to be "sticky". You may also test whether i

Variable pairs contain an opening and closing tag as well as content in between. Example:

{date_heading} <h1>{entry_date format="%Y %m %d"}</h1> {/date_heading}
{date_heading} <h1>{entry_date format="%Y %m %d"}</h1> {/date_heading}

The reason variable pairs have an opening and closing pair is because the information between the pairs can be shown or not shown if the criteria for each tag is met.

In the case of the "date_heading" pair, for example, it only appears at a certain interval that you set (hourly, daily, weekly, monthly, etc.). By using a pair of variables, you can put HTML formatting between them that only gets shown when the interval is met. Otherwise, the chunk is not displayed.

### `{date_footer}`

{date_footer display="daily"} <p>That's all from today!</p> {/date_footer}
{date_footer display="daily"} <p>That's all from today!</p> {/date_footer}

The date footer can be used to show a footer at certain intervals. The interval can be set to show hourly, daily, weekly, monthly, or yearly. An optional "display" parameter can be used to set the display interval:

Expand All @@ -1354,7 +1371,7 @@ NOTE: **Note:** You can use as many date_footers as you want in the same tag. Th

### `{date_heading}`

{date_heading} <h1>{entry_date format="%Y %m %d"}</h1> {/date_heading}
{date_heading} <h1>{entry_date format="%Y %m %d"}</h1> {/date_heading}

The date heading can be used to show a heading at certain intervals. The interval can be set to show hourly, daily, weekly, monthly, or yearly.

Expand Down Expand Up @@ -1493,7 +1510,7 @@ This variable will be replaced by a URL to the specified Template Group/Template

If you want the category links to point to your site index instead of a particular template group/template, you can use SITE_INDEX instead:

{categories} <a href="{path='SITE_INDEX'}">{category_name}</a> {/categories}
{categories} <a href="{path='SITE_INDEX'}">{category_name}</a> {/categories}

#### Custom Category Fields

Expand Down
6 changes: 4 additions & 2 deletions docs/fieldtypes/fluid.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -341,10 +341,12 @@ A fluid field can handle the output of all of those fields, as many as they add,

## Fluid Field Notes

- The `{if no_results}` tag is not valid within the prefixed variable pairs.
- Count variables available in some variable pairs (grid and relationship) restart at 1 each loop. So the total_results for a relationship tag pair would refer to the total number of relationships for that specific instance of the relationship field.
- All native fields aside from a Fluid field can be included in a Fluid field.

- The `{if no_results}` conditional tag is not valid for use in controlling the display of fluid fields. To test if the overall field has any content, use [:total_fields](/fieldtypes/fluid.md#total_fields) outside of the fluid field loop: `{if my_fluid_field:total_fields == 0} Fluid field is empty {/if}`

- Count variables available in some variable pairs (grid and relationship) restart at 1 each loop. So the total_results for a relationship tag pair would refer to the total number of relationships for that specific instance of the relationship field.

## Field Examples

### Checkbox and Multi Select Fields
Expand Down
113 changes: 66 additions & 47 deletions docs/fieldtypes/grid.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,29 +15,29 @@ lang: ee

[TOC]

The Grid field in ExpressionEngine provides a way to group fieldtypes in repeatable rows. This is useful for when you need to group a subset of data in your channel entry form that may or may not have a varying number of rows. You can select a minimum and a maximum amount of rows to allow data entry for, or it can be virtually infinite.
The Grid field in ExpressionEngine provides a way to enter and organize content in repeatable rows using many of the other fieldtypes. This is useful when you need to group a subset of information in your channel entry form in a logical manner, especially when that infomation may have varying numbers of rows. You can set a minimum and/or a maximum number of rows, or it can be virtually infinite.

![grid field](_images/field_grid.png)

## Field Settings

#### Minimum Rows

Specifies the minimum number of rows this Grid will have. For example, if you enter `3`, the publish form will load with three rows ready to be populated and will not allow the publisher to have less than three rows in this Grid field.
Specifies the minimum number of rows this grid will have. For example, if you enter `3`, the publish form will load with three empty rows ready to be populated and will not allow the publisher to delete any rows if there are only three.

#### Maximum Rows

Specifies the maximum number of rows this Grid can have. For example, if you enter `10`, the publish form will not allow the publisher to add any more than ten rows to this Grid field.
Specifies the maximum number of rows this grid can have. For example, if you enter `10`, the publish form will not allow the publisher to add any more than ten rows to this grid field.

#### Allow reordering
#### Allow Reordering

Enables moving the Grid rows with drag & drop to change the order
Enables moving the grid rows with drag & drop to change the order.

#### Show Row Numbers

Enables the display of row count alongside each row in the data grid.

#### Grid layout
#### Grid Layout

Tip: Grid Field Layout
<div class="video-wrapper">
Expand All @@ -52,24 +52,41 @@ Tip: Grid Field Layout

### Grid Fields

Here, you specify the columns you want in your Grid field. All [native fieldtypes](fieldtypes/overview.md) are available to add and have many of the [same configuration options](control-panel/field-manager/field-manager-settings.md#createedit-field) as full fields do.
Here, you specify the columns (a.k.a. Grid Fields) you want in your main grid field. All [native fieldtypes](fieldtypes/overview.md) are available to be part of a Grid field -- with the exception of Grid itself, [File Grid](fieldtypes/file-grid.md) and [Fluid](fieldtypes/fluid.md). Grid Fields within a grid may have [slightly different configuration options available](control-panel/field-manager/field-manager-settings.md#createedit-field) than they do as full fields.

#### Creating and Editing Grid Fields

To add a new Grid Field (column) click the "plus" icon. You must always have one field in your grid.

You can collapse or show the settings for each field by clicking on the triangle in the box.

Re-order the fields by grabbing the drag handle (three horizontal lines).

Make a copy of the field by clicking the "copy" icon -- two superimposed squares.

#### Grid Field General Options

Just as with other field types, you can specify whether a grid field is required or not. This applies to every row in the grid.

For some fieldtypes, you can choose whether its content should be included in search. The overall grid field must also be set to Include in Search, or else this setting will not have any effect. If you change the search inclusion status of an existing grid Field -- or make other changes to the field settings -- you will need to [re-index your content](control-panel/utilities/data-operations.md#search-reindex)

You may set a minimum width for each grid field. When the grid is set to display horizontally, any grid field with a minimum width will have that width applied to it; fields without any minimum width will be given the remaining space.


## Template Tags

Contents of a Grid field are accessed via a variable pair surrounding prefixed variables representing each column. For example, if you have a field `gallery` with an `image` and `credit` fields, your template code may look like this:
Contents of a Grid Field are accessed via prefixed variables representing each column, surrounded by a variable pair. For example, if you have a grid field called `awards` with `name`, `details`, and `year_awarded` fields, your template code may look like this:

{gallery}
<figure>
<img src="{gallery:image}">
<figcaption>Photo by {gallery:credit}</figcaption>
</figure>
{gallery:description}
{/gallery}
{awards}
<h3>{awards:name} - {awards:year_awarded}<h3>
{awards:details}
{/awards}

Grid has a number of parameters and other variables available in order to get the information you need out of it.

## Parameters

Grid has a number of parameters and other variables available in order to get the information you need out of it.

[TOC=3]

### `backspace=`
Expand All @@ -82,7 +99,7 @@ Just like the backspace parameter on the [Channel Entries](channels/entries.md)

dynamic_parameters="orderby|limit|sort"

The [Dynamic Parameters](channels/dynamic-parameters.md) feature permits a Grid field tag's parameters to be set "on the fly" using POST data data submitted via a form. A practical use for this is to create some display options in a form on your page that your visitors can use to select their preferred page view.
The [Dynamic Parameters](channels/dynamic-parameters.md) feature permits a grid field tag's parameters to be set "on the fly" using POST data submitted via a form. A practical use for this is to offer display options in a form on your page that your visitors can then use to select their preferred page view.

NOTE: **Note:** This feature will only work if page caching is turned OFF for the template in which it is being used.

Expand All @@ -98,21 +115,21 @@ Allows the output of the tag pair to order rows in a fixed order of row IDs.

limit="5"

Limits the number of rows output by the tag pair to the number specified here. The limit will default to 100 rows if a value is not specified.
Limits the number of rows output by the tag pair to the number specified. The limit will default to 100 rows if a value is not specified.

### `offset=`

offset="1"

Offsets the number of rows output by the tag pair to the number specified here.
Offsets the number of rows output by the tag pair by the number specified.

### `orderby=`

orderby="column_name"

Allows the output of the tag pair to be ordered by a specific column, defaults to row order as set on the channel entry publish form. Entering `random` will return the rows in a random order.

NOTE: **Note:** Unlike `exp:channel:entries`, you can only use one column at a time for sorting.
NOTE: **Note:** Unlike `exp:channel:entries`, you can only use one column at a time for sorting -- though this limitation was removed in 7.5.23.

### `row_id=`

Expand Down Expand Up @@ -144,71 +161,71 @@ Specifies the direction of the sorting of the tag output. Defaults to ascending.

### `count`

{gallery:count}
{grid_field:count}

The "count" out of the current rows being displayed. If five rows are being displayed, then for the fourth entry the `count` variable would have a value of "4".
The "count" of the current row being displayed. If five rows are being displayed, then for the fourth entry the `count` variable would have a value of "4".

### `field_row_count`

{gallery:field_row_count}
{grid_field:field_row_count}

The count of the row inside the field regardless of tag output.

### `field_row_index`

{gallery:field_row_index}
{grid_field:field_row_index}

The index of the row inside the field regardless of tag output.

### `field_total_rows`

{gallery:field_total_rows}
{grid_field:field_total_rows}

The total number of rows in the field regardless of tag output criteria.
The total number of rows in the field regardless of tag output.

### `index`

{gallery:index}
{grid_field:index}

The count of the rows but starting at zero.
The count of the row being displayed but starting at zero.

### `prev_row`

{gallery:prev_row}
<a href="/gallery/lumenhaus/{gallery:row_id}">Previous photo</a>
{/gallery:prev_row}
{grid_field:prev_row}
<a href="{title_permalink}/{grid_field:row_id}">Previous Award</a>
{/grid_field:prev_row}

Used as a tag pair within the parent Grid field tag pair, provides access to data in the previous row in the dataset.
When used as a tag pair within the parent grid field tag pair, provides access to data in the previous row in the dataset.

### `next_row`

{gallery:next_row}
<a href="/gallery/lumenhaus/{gallery:row_id}">Next photo</a>
{/gallery:next_row}
{grid_field:next_row}
<a href="/awards/{url_title}/{grid_field:row_id}">Next Award</a>
{/grid_field:next_row}

Used as a tag pair within the parent Grid field tag pair, provides access to data in the next row in the dataset.
When used as a tag pair within the parent grid field tag pair, provides access to data in the next row in the dataset.

### `row_id`

{gallery:row_id}
{grid_field:row_id}

The database ID of the current row.

### `switch=`

{gallery:switch="odd|even"}
{grid_field:switch="odd|even"}

Identical to the [switch variable](channels/entries.md#switch) available in the [Channel Entries](channels/entries.md) tag pair, but prefixed for your Grid field.
Identical to the [switch variable](channels/entries.md#switch) available in the [Channel Entries](channels/entries.md) tag pair, but prefixed for your grid field.

### `total_rows`

{gallery:total_rows}
{grid_field:total_rows}

The total number of rows being returned by the current display criteria.

## Modifiers

All modifiers have access to the tag parameters available to the primary tag which are listed above.
All these modifiers can be used with the tag parameters available to the primary tag, which are listed above.

### `:average`

Expand Down Expand Up @@ -236,37 +253,39 @@ Given a column name containing numeric data, returns the sum of the column value

### `:table`

{grid_field:table cellspacing="0" cellpadding="0"}
{grid_field:table cellspacing="0" cellpadding="0" set_classes="y"}

Outputs the data in the Grid field as a table. All parameters available to the primary tag are available in addition to these:
Outputs the data in the grid field as a table. All parameters available to the primary tag are available in addition to these:

- **border=** Sets border attribute on the table's HTML element
- **cellspacing=** Sets cellspacing attribute on the table's HTML element
- **cellpadding=** Sets cellpadding attribute on the table's HTML element
- **class=** Sets class attribute on the table's HTML element
- **id=** Sets ID attribute on the table's HTML element
- **set_classes=** If set to 'y', adds column name to the class attribute of each cell.
- **set_widths=** If set to 'y', sets the same column widths configured for each column in the Grid field's settings.
- **set_widths=** If set to 'y', sets the same column widths configured for each column in the grid field's settings.
- **width=** Sets width attribute on the table's HTML element

### `:total_rows`

{grid_field:total_rows search:height=">55"}

When outside of a Grid field tag pair, this modifier can be used to get the total number of rows in a field given a specific criteria.
When outside of a grid field tag pair, this modifier can be used to get the total number of rows in a field given a specific criteria. Useful for determining if there are any grid rows at all: `{if grid_field:total_rows == 0} Grid is empty {/if}`. Note that `no_results` is not a valid conditional for the Grid field. Also note that you need to wrap the tag in quotes and curly braces if you are using any parameters:

{if "{grid_field:total_rows search:height='>55'}" == 0} No rows with tall things {/if}

### `:next_row`

{grid_field:next_row row_id="{segment_3}"}
Next up: <a href="/gallery/photo/{grid_field:row_id}">{grid_field:title}</a>
Next up: <a href="/awards/{url_title}/{grid_field:row_id}">{grid_field:title}</a>
{/grid_field:next_row}

Given a row ID, this tag pair will provide access to the next row in the field criteria. The `row_id` may be populated via a segment variable.

### `:prev_row`

{grid_field:prev_row row_id="5"}
Previous: <a href="/gallery/photo/{grid_field:row_id}">{grid_field:title}</a>
Previous: <a href="/awards/{url_title}/{grid_field:row_id}">{grid_field:title}</a>
{/grid_field:prev_row}

Given a row ID, this tag pair will provide access to the previous row in the field criteria. The `row_id` may be populated via a segment variable.
Expand Down