Extenders
Summary Extender
Purpose
The "Summary" extender provides legacy support for the Ditto v1.x era [+summary+]
placeholder and it's associated parameters.
NewsListing was originally designed with the thought that it would be used to display lists of blog entries, news articles, etc. where for each item you'd want to show it's title, author, date and the first fifty or so characters of the article as a "summary" thereof: hence the [+summary+]
placeholder.
As for version 2, Ditto will no-longer support the summary placeholder natively as it is resource intensive and superseded (introtext field)
Placeholders
This extender defines two placeholders:
[+summary+]
will contain the first "n" characters of the corresponding Evo document's content field.
[+link+]
will contain an HTML link to the corresponding Evo document (so that you can view the entired document that has been summarized in Ditto's output list.
This extender also defines parameters that deal with two basic issues: the rules for how much of the document's content field to place in the [+summary+]
placeholder, and how to format the HTML link that's placed in the [+link+]
placeholder.
The truncation function has a wandering ability so if you set it to 50 characters it will wander &truncOffset (30)
either way by default to find the nearest end tag or end of word.
Parameters
Parameter | Description | Options | Default |
---|---|---|---|
&trunc | Enable truncation of the text that goes into the [+summary+] placeholder | 0,1 | 1 |
&truncAt | Marker string to split the content at | Any unique text or code string that is contained in the content of each document. Notes: $_lang['splitter'] |
<!-- splitter --> |
&truncSplit | Should the document be summarized at the splitter? | 0,1 | 1 |
&truncLen | Number of characters to show of the content | Any number greater than &truncOffset | 200 |
&truncOffset | Number of characters to 'wander' either way of truncLen | Any number greater less than truncLen | 20 |
&truncText | Text to be displayed in [+link+] | Any valid text or html Notes: $_lang['more_text'] |
Read more… |
&tplTrunc | Template to be used for [+link+] | chunk name; code via @CODE:file via @FILE: | &truncText |
Request Extender
Purpose
Normally all the parameters you want Ditto to use are specified in the snippet call you embed into a Evo document's template. Thus each time the document is invoked the snippet will be called with exactly the same parameters.
However the "Request" extender makes Ditto look for Ditto parameters that have been appended to the URL that invokes the Evo document, and to change its behavior accordingly.Thus you can change Ditto's behavior each time you invoke a Evo document simply by adding Ditto parameters to the end of the URL that invokes the document.
How to Add Ditto Parameters to a URL
All Ditto parameters appended to a URL must begin with:
&ditto_
Follow this with the name of the parameter, then an equals sign, then the value of the parameter. For example:
&ditto_display=5 &ditto_start=3 &ditto_hideFolders=1
You can string together as many parameters as you wish (but be careful not to let any spaces creep into the string), e.g.:
&ditto_display=5&ditto_start=3&ditto_hideFolders=1
So given a base URL such as:
http://www.example.com/index.php?id=97
The same URL with Ditto parameters would look like this (and remember, no spaces):
http://www.example.com/index.php?id=97&ditto_display=5&ditto_start=3&ditto_hideFolders=1
Multiple Ditto Calls in a Document
You are allowed to have multiple Ditto calls in a single Evo document. And you are allowed to add parameters for these Ditto calls to the URL. But how does each Ditto call figure out which parameters to respond to? This is where the Ditto &id parameter comes in. In each Ditto call you must specify an unique ID, and in each parameter appended to the URL you must include the ID of the Ditto call for which it is intended. Here's how that works.
Let's say your Evo document contains two Ditto calls, one that generates a menu and another that generates a table of contents. Let's assign them IDs as follows:
[!Ditto? &id=`menu` … !] [!Ditto? &id=`toc` … !]
Then in the URL, the beginning of each Ditto parameter takes the form:
&ditto_id_
Or with our two example IDs above:
&ditto_menu_ &ditto_toc_
Then just the parameters you want to each of the above:
&ditto_menu_display=all &ditto_toc_hideFolders=1
And you can string them all together and add them to the base URL (and remember, no spaces):
http://www.example.com/index.php?id=97&ditto_menu_display=all&ditto_toc_hideFolders=1
If you specify some parameters with IDs and some parameters without IDs the ones without IDs will affect all Ditto calls without an id parameter set.
Handling Characters that are Illegal in URLs
Some characters (such as spaces) are meaningful and necessary within Ditto parameter values, but are illegal for inclusion in URLs. There's a web-standard way of handling these cases: you convert each "illegal" character into a "legal" format.
As I recall, this format is the percent sign followed by the numerical ASCII value of the character in decimal notation (i.e. normal human numbers rather than HEX or binary).
Thus anywhere you need to include a SPACE character just substitute it's legal equivalent, which is: %20
Based on documentation work by Bill Fernandez
Parameters
Parameter | Description | Options | Default |
---|---|---|---|
&stripTags | Remove HTML tags from supplied parameters | 0,1 | 1 |
&bad | Parameters not allowed to be set via extender | Ditto options separated by commas | seeThroughtUnpub, showInMenuOnly, showPublishedOnly, debug, start, config, extenders, dittoID |
&good | Parameters that may be set via extender | Ditto options separated by commas | Everything not in 'bad' list |
Tagging Extender
Parameters
Parameter | Description | Options | Default |
---|---|---|---|
&tagDocumentID | ID for tag links to point to | Any Evo document with a Ditto call setup to receive the tags | Current Document |
&tagData | Document field for template variable containing tags | Comma separated list of Evo fields or TVs | [NULL] |
&tags | Set tags for filtering | any valid tags separated by &tagDelimiter Notes: Alternative to supplying them in URL |
empty |
&tagMode | Select or hide documents with all or any of the tags |
|
onlyTags |
&tagDelimiter | Separator between tags | Any character not used within the tags | space |
&caseSensitive | Make tag matching and duplicate tag removal case sensitive | 0,1 | 0 |
&tagDisplayDelimiter | Separator between tags in display | Character string | &tagDelimiter |
&tagSort | Sort the tags alphanumerically | 0,1 | 1 |
&tagDisplayMode | Display format of tags in [+tagLinks+] | 1 (string of links &tagDisplayDelimiter separated), 2 (UL/LI list) | 1 |
&tplTagLinks | Output template for the [+tagLinks+] placeholder | chunk name; code via @CODE:file via @FILE: | |
&tagCallback | Set name of function to handle source and processing of tags | Any valid function name | empty |
DateFilter Extender
Parameters
Parameter | Description | Options | Default |
---|---|---|---|
&dateFilterSource | Source of filter data | get, params, name of $_REQUEST variable Notes: from URL (prefixed with any Ditto ID) |
get |
&dateFilterDefault | Set default filter to current year, month or day | 0,1,2,3 (off, this year, this month, today) | 0 (off) |
&month | Month to filter by | Numerical month value | empty |
&year | Year to filter by | Year (2 or 4-digit) | empty |
&day | Day to filter by | Numerical day of the month | empty |
Suggest an edit to this page.