Rowboat
Last updated Mar 6th, 2021 | Page history | Improve this page | Report an issue
Support the team building MODX with a monthly donation.
The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.
Backers
Budget
$301 per month—let's make that $500!
Learn moreThe Rowboat Snippet¶
This snippet iterates across rows for any database table.
Usage¶
Display the first 10 Doodles in the modx_doodles table, sorted by name:
[[!Rowboat?
&table=`modx_doodles`
&tpl=`myDoodle`
&limit=`10`
&sortBy=`name`
]]
Using the following Chunk, "myDoodle":
<li id="doodle[[+id]]"><strong>[[+name]]</strong> - [[+description]]</li>
Available Properties¶
Name | Description | Default |
---|---|---|
tpl | The Chunk to use for each row. If empty, will output an array of placeholders that are available. | |
table | Required. The table to grab records from. | |
columns | A JSON object of columns and aliases for those columns to grab for the row. If not set, will grab all columns in the table. | * |
where | A JSON object for a where statement. | |
sortBy | If set, will sort by this field. | |
sortDir | The direction to sort by. | ASC |
limit | The number of rows to limit per call. Defaults to 10. Set to 0 to show all. | 10 |
offset | The start index to begin with when limiting. | 0 |
cacheResults | If set to 1, will cache the results of the specific query. | 1 |
cacheTime | If cacheResults is set to 1, the number of seconds to cache the query for. | 3600 |
placeholderPrefix | The prefix to use when setting global placeholders, such as total. | rowboat. |
outputSeparator | The separator between each user record. | |
toPlaceholder | Optional. If set, will set the output to this placeholder and return empty. | |
debug | Optional. If set to 1, will output a table of information about the generated query and results. Always leave at 0 for production sites. | 0 |
tpl Chunk Properties¶
In your &tpl Chunk, you will have all the columns that you selected as properties, as well as:
Name | Description |
---|---|
_idx | The index of this row. |
_alt | 1 if is an even row, 0 if odd. |
_first | If this row is the first of this paged result set, then this will be 1. |
_last | If this row is the last of this paged result set, then this will be 1. |
Examples¶
Grab top 10 Doodles, sorted by name, from modx_doodles that have "Test" in their name:
[[!Rowboat?
&table=`modx_doodles`
&tpl=`myDoodle`
&limit=`10`
&where=`{"name:LIKE":"%Test%"}`
&sortBy=`name`
]]
Grab only the id, name and description (with description aliased as "desc") columns from the above example: (note that non-aliased columns need a blank "" for the alias)
[[!Rowboat?
&table=`modx_doodles`
&tpl=`myDoodle`
&columns=`{"id":"","name":"","description":"desc"}`
&limit=`10`
&where=`{"name:LIKE":"%Test%"}`
&sortBy=`name`
]]
Grab 10 Doodles where description isn't empty or the name is "Test":
[[!Rowboat?
&table=`modx_doodles`
&tpl=`myDoodle`
&limit=`10`
&where=`{"description:!=":"","OR:name":"Test"}`
&sortBy=`name`
]]
More to come shortly.
Using getPage with Rowboat¶
It's pretty simple - just make sure to set the totalVar property in your getPage call as "rowboat.total", and have cache=0
in the getPage call. For example, this will grab all doodles where the name contains "Fun", paginate them to 10 per page, and add page navigation:
[[!getPage?
&element=`Rowboat`
&table=`modx_doodles`
&sortBy=`name`
&where=`{"name:LIKE":"%Fun%"}`
&totalVar=`rowboat.total`
&tpl=`myDoodle`
&cache=`0`
&limit=`10`
]]
<div class="paging">
<ul class="pageList">
[[!+page.nav]]
</ul>
</div>
Gotchas¶
Be careful about the &columns argument: if you list a column that does not exist, the RowBoat Snippet call will return no results.
See Also¶
Support the team building MODX with a monthly donation.
The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.
Backers
Budget
$301 per month—let's make that $500!
Learn more