Ditto Parameters
Last edited by Kari Söderholm on Feb 5, 2015.
This is a user-contributed Extra. If you find issues or would like more info or help, please contact the author.
Parameter description for Ditto version 2.1.1 (bundled with MODX 1.0.15)
Main parameters
Parameter | Description | Options | Default |
---|---|---|---|
config | Load a custom configuration |
"default" - default blank config file
CONFIG_NAME - Other configs installed in the configs folder or in any folder within the MODX base path via @FILE |
`default` |
dateFormat | Format the [+date+] placeholder in human readable form | Any valid format for PHP function strftime() | $_lang["dateFormat"] - From Ditto language file. Default for English language is `%d-%b-%y %H:%M` |
dateSource | Source of the [+date+] placeholder | Any UNIX timestamp from MODX fields or TVs such as createdon, pub_date, or editedon | `createdon` |
debug | Output debugging information | 0 (off), 1 (on) | `0` |
depth | Depth of document tree levels to fetch from | positive integer (0 for unlimited) | `1` |
display |
Number of documents to display
(per page if pagination is on) |
positive integer, `all` (all documents found) | `all` |
ditto_base | Location of Ditto files | Any valid folder location containing the Ditto source code with a trailing slash | [(base_path)]assets/snippets/ditto/ |
documents | IDs of documents for Ditto to retrieve. Overrides &parents property. | Comma-separated list of IDs of resources to list | none |
extenders | Load an extender which adds functionality to Ditto | Any extender in the extenders folder or in any folder within the MODX base path via @FILE. May be a comma separated list of extenders. | none |
format | Output format to use | html, json, xml, atom, rss | `html` |
hiddenFields | Allow Ditto to retrieve fields its template parser cannot handle such as nested placeholders and [*fields*] | Any valid MODX fieldnames or TVs comma separated | none |
hideFolders | Don't show folders in the returned results |
0 - show folders 1 - hide folders |
`0` |
hidePrivate | Don't show documents the guest or user does not have permission to see |
0 - show private documents 1 - hide private documents |
`1` |
id | Unique ID for this Ditto instance for connection with other scripts (like Reflect) and unique URL parameters | Any combination of characters a-z, underscores, and numbers 0-9 (This is case sensitive) | blank |
keywords | Enable fetching of associated keywords for each document. Can be used as [+keywords+] or as a tagData source | 0 (off), 1 (on) | `0` |
language | language for defaults, debug, and error messages | Any language name with a corresponding file in the &ditto_base/lang folder | `english` |
noResults | Text or chunk to display when there are no results | Any valid chunk name or text | $_lang['no_documents'] - From Ditto language file. Default for English language is `<p>No documents found.</p>` |
orderBy | Sort the result set | Any valid MySQL style orderBy statement | `createdon DESC` |
parents | IDs of containers for Ditto to retrieve their children to &depth depth | Comma-separated list of resource IDs | current resource |
phx | Use PHx formatting | 0 (off), 1 (on) | `1` |
queryLimit | Number of documents to retrieve from the database, same as MySQL LIMIT | positive integer, `0` (automatic) | `0` |
randomize | Randomize the order of the output | 0 (off), 1 (on), Any MODX field or TV name (for weighted random by that field) | `0` |
removeChunk | Name of chunks to be stripped from content separated by commas. Commonly used to remove comments. | Any valid chunkname that appears in the output | none |
save | Saves the ditto object and results set to placeholders for use by other snippets |
0 - off; returns output 1 - remaining; returns output 2 - all; 3 - all; returns ph only |
`0` |
seeThruUnpub | See through unpublished folders to retrive their children. Used when depth is greater than 1. | 0 (off), 1 (on) | `0` |
showInMenuOnly | Show only documents visible in the menu |
0 - show all documents
1 - show only documents with the "show in menu" flag checked |
`0` |
showPublishedOnly | Show only published documents |
0 - show only unpublished documents
1 - show both published and unpublished documents |
`1` |
start | Number of documents to skip in the results | positive integer, `0` (don't skip) | `0` |
total | Number of documents to retrieve | positive integer, `all` (all documents found) | `all` |
where | Custom MySQL WHERE statement | A valid MySQL WHERE statement using only document object items (no TVs) | blank |
Filtering
Parameter | Description | Options | Default |
---|---|---|---|
filter | Removes items not meeting a critera. Thus, if pagetitle == joe then it will be removed. |
Use in the format "field,criteria,mode" with the comma being the local delimiter. Mode - Meaning 1 - != (not equal) 2 - == (equals) 3 - < (lower than) 4 - > (greater than) 5 - <= (lower than or equal) 6 - >= (greater than or equal) 7 - Text not in field value 8 - Text in field value 9 - case insenstive version of #7 10 - case insenstive version of #8 11 - checks leading character of the field @EVAL: @EVAL in filters works the same as it does in MODX exect it can only be used with basic filtering, not custom filtering (tagging, etc). Make sure that you return the value you wish Ditto to filter by and that the code is valid PHP. |
none |
globalFilterDelimiter | Filter delimiter used to separate filters in the filter string | Any character not used in the filters | `|` |
localFilterDelimiter | Delimiter used to separate individual parameters within each filter string | Any character not used in the filter itself | `,` |
Pagination
Parameter | Description | Options | Default |
---|---|---|---|
paginate |
Paginate the results set into pages of &display length.
Use &total to limit the number of documents retrieved. |
0 (off), 1 (on) | `0` |
paginateAlwaysShowLinks | Determine whether or not to always show previous next links | 0 (off), 1 (on) | `0` |
paginateSplitterCharacter | Splitter to use if always show is disabled | Any valid character | $_lang['button_splitter'] - From Ditto language file. Default for English language is `|` |
tplPaginateCurrentPage | Template for the current page link |
- Any valid chunk name - Code via @CODE - File via @FILE |
`<span class='ditto_currentpage'>[+page+]</span>` |
tplPaginateNext | Template for the next link |
- Any valid chunk name - Code via @CODE - File via @FILE |
`<a href='[+url+]' class='ditto_next_link'>[+lang:next+]</a>` |
tplPaginateNextOff | Template for the next link when it is off |
- Any valid chunk name - Code via @CODE - File via @FILE |
`<span class='ditto_next_off ditto_off'>[+lang:next+]</span>` |
tplPaginatePage | Template for the page link |
- Any valid chunk name - Code via @CODE - File via @FILE |
`<a class='ditto_page' href='[+url+]'>[+page+]</a>` |
tplPaginatePrevious | Template for the previous link |
- Any valid chunk name - Code via @CODE - File via @FILE |
`<a href='[+url+]' class='ditto_previous_link'>[+lang:previous+]</a>` |
tplPaginatePreviousOff | Template for the previous link when it is off |
- Any valid chunk name - Code via @CODE - File via @FILE |
`<span class='ditto_previous_off ditto_off'>[+lang:previous+]</span>` |
Templates
Parameter | Description | Options | Default |
---|---|---|---|
tpl | User defined chunk to format the documents |
- Any valid chunk name - Code via @CODE - File via @FILE |
HTML code block $_lang['default_template'] from Ditto language file (using @CODE). |
tplAlt | User defined chunk to format every other document |
- Any valid chunk name - Code via @CODE - File via @FILE |
value of &tpl |
tplCurrentDocument | User defined chunk to format the current document |
- Any valid chunk name - Code via @CODE - File via @FILE |
value of &tpl |
tplFirst | User defined chunk to format the first document |
- Any valid chunk name - Code via @CODE - File via @FILE |
value of &tpl |
tplLast | User defined chunk to format the last document |
- Any valid chunk name - Code via @CODE - File via @FILE |
value of &tpl |
Suggest an edit to this page on GitHub (Requires GitHub account. Opens a new window/tab).