Primary Tag Pair

To fully customize your Matrix field’s output, use its primary tag pair.

{speakers}
  <h2>{speaker_name}</h2>
  <img src="{speaker_photo}" alt="{speaker_name}"/>
  <p>{speaker_description}</p>
{/speakers}

Tag Parameters

The following parameters can be added to each of Matrix’s tags:

search

Only loop through rows that match a certain criteria. Mimics the parameter for {exp:channel:entries}, and supports comparison operators <, >, <=, and >= as well.

{speakers search:age=">=16"}

row_id

Only show a specific row(s)

{speakers row_id="1|2|3"}

Or prefix with “not” to exclude rows

{speakers row_id="not 4|5|6"}

fixed_order

Only show specific rows, in a specific order

{speakers fixed_order="3|2|1"}

orderby

Order the rows by their column values.

sort="asc|desc"

Sort the rows in ascending or descending order

{speakers orderby="session_time|session_track" sort="asc|desc"}

sort="random"

Sort the rows in random order

offset

Skip the first X rows

limit

Limit the number of rows to be returned

{speakers offset="5" limit="1"}

backspace

Strip the last X characters from the tag output

{speakers backspace="2"}{speaker_name}, {/speakers}

dynamic_parameters

Set specific tag parameters “on the fly” using POST data submitted via a form. Mimics the parameter for {exp:channel:entries}.

Single Variable Tags

The following single variables are available within your tag pair:

{row_id}

The current row’s unique ID

{row_count}

The current row’s count

{row_index}

The current row’s index (same as {row_count}, except it starts counting at 0)

{total_rows}

The total number of rows

{field_row_count}

The current row’s count, regardless of any declared filter params

{field_row_index}

The current row’s index, regardless of any declared filter params (same as {field_row_count}, except it starts counting at 0)

{field_total_rows}

The total number of rows in the field, regardless of any declared filter params

{switch}

Switch between multiple values based on the current row index

{speakers}
  <li class="{switch='odd|even'}">
    {row_count} of {total_rows}: {speaker_name}
  </li>
{/speakers}

Variable Tag Pairs

The following variable pairs are available within your tag pair:

{prev_row} … {/prev_row}

Access the previous row in the field

{next_row} … {/next_row}

Access the next row in the field

{gallery row_id="{segment_3}"}
  <h1>{photo_title}</h1>
  <img src="{photo}" alt="{photo_title}" />
  <p>{photo_description}</p>

  {prev_row}<a href="/galleries/{segment_2}/{row_id}">← {photo_title}</a>{/prev_row}
  {if prev_row && next_row} | {/if}
  {next_row}<a href="/galleries/{segment_2}/{row_id}">{photo_title} →</a>{/next_row}
{/gallery}

:table Tag

Alternatively, you can use Matrix’s :table tag to quickly create an HTML table filled with your field’s data.

{speakers:table cellspacing="0" cellpadding="0"}

Tag Parameters

The :table tag accepts all of the primary tag pair’s parameters, as well as a couple of its own:

set_row_ids="yes"

Adds id attributes to all <tr>s within the <tbody>, set to “row_id_” followed by the row’s unique ID

set_classes="yes"

Adds class attributes to all <th>s and <td>s, set to the column names

set_widths="yes"

Adds width attributes to all <th>s and <td>s, set to the column widths

cellspacing

The table’s cellspacing attribute

cellpadding

The table’s cellpadding attribute

border

The table’s border attribute

width

The table’s width attribute

class

The table’s class attribute

:prev_row and :next_row

Access the previous or next row in your field, from a given starting point. The starting point is whatever the first row would be with your declared field parameters.

{gallery:next_row row_id="{segment_3}"}
  Up next: <a href="/galleries/{segment_2}/{row_id}">{photo_title}</a>
{/gallery:next_row}

:total_rows

The :total_rows tag returns the total number of rows within your Matrix field.

{if "{speakers:total_rows}" >= 5}
  We’ve got a great lineup of {speakers:total_rows} speakers!
{/if}

Tag Parameters

The :total_rows tag accepts all of the primary tag pair’s parameters.

:average, :lowest, :highest, and :sum

These tags return the average, lowest, highest, or sum value of a given (numeric) column in your Matrix field.

The speakers’ average age is {speakers:average col="age"}.

Tag Parameters

These tags accept all of the primary tag pair’s parameters, as well as the following:

col

The name of the column you wish to get info about (required)

decimals

The number of decimal points the number should have (default is 0)

dec_point

The character that will be used for the decimal (default is a period)

thousands_sep

The character that will be used as the thousands separator (default is a comma)