Extenders

This is a user-contributed Extra. If you find issues or would like more info or help, please contact the author.

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:

  1. [+summary+]

    will contain the first "n" characters of the corresponding Evo document's content field.

  2. [+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
  • onlyAllTags - show documents that have all of the tags
  • onlyTags - show documents that have any of the tags
  • removeAllTags - remove documents that have all of the tags
  • removeTags - documents that have 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.