Tagged blogging with Ditto
From MODx Wiki
Contents |
Introduction
Requirements
- ditto 1.0.2 or newer
Optional Items (recommended)
Creating the TV
Log into your MODx Manager and create a new template variable. In this example we will name our tv "tags". The input type for this tv will be a "Check Box". The input option values will be our tag names separated by double pipes "||". Select "Delimited List from the Widget dropdown and our delimiter will be a comma ",". Place a check next to the template(s) that will be using this tv, then click "Save".
Now when you edit or create a document with a template associated with this tv, you will see a check box for each item you entered in the input option values. You can select as many or as few of these tags as you want.
Category Pages
Category pages are like folders for your tagged items. These differ from folders, however, because a document can have multiple tags and exist in multiple category pages at the same time.
We are going to create a Category Page for each of our tag items. In our example, we are going to create a page for Personal (alias = personal), MODx (alias = modx), Web Design (alias = webdesign), and of course Pirate (alias = pirate). In this tutorial I have MODx configured to use Friendly Alias Paths, so First I created a document Titled "Categories" with an alias of "categories" and on the "Page Settings" tab, I checked "Container". I will create each of my category pages in this container (or folder if you will). so for the category page for Web Design, the url will be mysite.url/categories/webdesign.
The index page on my site is id "1". On this page I have a Ditto call to gather all the documents in my blog folder which is id "2" with this Ditto call:
[!Ditto? &startID=`2` &tpl=`dittoTpl` &summarize=`5`!]
On each of the category pages I am going to place a Ditto call and use ditto to filter the results to return only items tagged as "Web Design" like this:
[!Ditto? &startID=`2` &tpl=`dittoTpl` &tagData=`tvtags` &tagDelimiter=`,` &tagMode=`onlyTags` &tags=`Web Design`!]
The important parameters to note here are:
- &tagData : This tells ditto which tv to look in for tag data. it is the name of our tv (tags) prefixed by the letters "tv".
- &tagDelimiter : In our tv we set our widget to Delimited List and the delimiter to a comma (,).
- &tagMode : Setting this to "onlyTags" will return only the items that have this tag checked. it will return All items checked with "Web Design" regardless of which other tags are also checked.
- &tags : tells ditto which tag to search for. Spelled and spaced exactly as we set it when we made the tv.
The Ditto &tpl parameter
In the example we are working with we are going to be using the templating function of Ditto to tell Ditto how we want our blog Items to be displayed. In this example of a ditto template, I will be using the snippet [[tagLinks]] to output a list of the tags associated with each document which are links to the respective category pages we made earlier that will aggregate only blog entries with that tag. I will also be using Jot to display the number of comments on each blog entry and it will also be a link to the page anchor #pageComments which I have placed at the beginning of the comments section on each page.
<p><div class="ditto_summary">
<div class="ditto_head">
<h3><a href="[~[+id+]~]">[+date+] </a> : [+title+]</h3>
<div class="commentCount"><a href="[~[+id+]~]#pageComments">[[Jot? &docid=`[+id+]` &action=`count-comments`]] comments. </a></div>
[[tagLinks? &id=`[+id+]` &tv=`tags` &separator=`, ` &fap=`1` &path=`categories` &label=`Tags: ` &style=`dittoTags`]]
</div>
<div class="ditto_content">
<p>[+summary+] [+link+]</p>
</div>
<div class="ditto_author"></div>
</div></p>
In this template, I am using the [+date+] as the link to the full article, followed by the [+title+] for more info. The next line holds the comments count. I used Jot with the action of count-comments and the id of Ditto's placeholder for the id of the summarized document. If we used [*id*] it would return the comments for the page we are on (id "1" at the moment).
The next line is our tagLinks call. Full documentation for the tagLinks snippet is next. for now, we are telling the tagLinks snippet to get the tags for the page [+id+] (Ditto's reference to the summarized article again), that the tv holding our tags is called "tags", that we want a comma followed by a space (, ) to separate each tag, that we are using Friendly alias paths (fap = boolean affirmative), that the friendly path to our category pages is mysite.url/categories/, that before we render the links we want it to say "Tags: " (Tags: Web Design, Pirate,), and finally that the element (div) that this is wrapped in should have be rendered as <div class="dittoTags"> for styling purposes.
The tagLinks Snippet
Using the tagLinks snippet, we will output a list of links of the tags that are attached to the document. These links will bring the visitor to the associated "Category Page" where they can view other items with the same tag.
The tag links snippet has many parameters. it can get tags from any document by declaring which id to use, it can output a bunch of plain <a href=""> html tags. It can output ordered lists or unordered lists of your links. it supports Friendly Alias Paths.
For this snippet to work properly, the Category page you are linking to must have an alias that is the same name as the tag, only lower case and without spaces. For example, If the tag is "Personal", the category page must have an alias of "personal". If the Tag is "Web Design", the category page must have an alias of "webdesign".
Parameters
- &id = document id to get tags for. default is the current document. When using this in a ditto tpl, use &id=`[+id+] to get the tags for the document being summarized.
- &tv = name of the template variable used for declaring categories.
- &delimiter = delimiter used in the tv's Delimited List widget. Defaults to a comma ","
- &label = Label displayed before the list of links. Defaults to "Categories: ".
- &separator = character to separate tag links. comma (,) or pipe (|) for example. Defaults to (blank).
- &element = Element to wrap this in [div/span/p]. Defaults to "div".
- &style = CSS class to apply to the &element. Defualts to "taglinks".
- &format = format of the output for links. can be an anchor `a`, unordered list `ul`, or an ordered list `ol`. Defaults to `a`.
- &newline = add new line after each element. Defaults to '1' (yes, add new lines). Set to `0` and new lines will not be added.
- &fap = output for Friendly Alias Paths. If you use FAPs, set this to `1` and set the path to your category pages in &path
- &path = path to your category page under FAPs. if your category pages are under "yoursite.url/blog/categories/", you would set &path=`blog/categories`. If you are not using Friendly Alias Paths, this variable is ignored and the link created is to "yoursite.url/tagname". From version 1.0.4, you can specify a ModX Doc ID - just provide the number and the correct URL will be used.
Examples
Call as an unordered list, in a <span></span>element separated by a space, using Friendly Alias Paths.
[[tagLinks? &tv=`tags` &separator=` ` &format=`ul` &element=`span` &fap=`1` &path=`furl/path`]]
Call as <a href=""> tags in a paragraph block (<p></p>) inside a Ditto tpl with a pipe as the separator and a CSS class of "myTags".
[[tagLinks? &id=`[+id+]` &tv=`tags` &separator=` | ` &element=`p` style=`myTags`]]
