While Warsteiner’s post is far the best example I’ve seen so far, in a) explaining what the three snippets do and b) in what order the logic might flow in a real-world non-blog example, it didn’t actually work for me. Nor did I understand what all the parameters seemed to be doing, or where they came from. or why they aren’t even mentioned in the documentation.
So here’s my take: I’d like to end up with an understanding sufficient to tackle the somewhat sketchy documentatio to take it to the level required of a novice.
My project is a real-estate listing website. Each house has its own resource page. House information is summarised, ditto-like, and tagging is used to present different sets of these summaries, so that one can filter out, for example, everything that does not have a swimming pool. When a houseof interest is identified through these summaries, full details of the house aare provided, together with tags, which when clicked take the user back to the summaries for that (possibly-new) tag.
In other words, like any real-estate website, but more intuitive because of the tagging. And I decided to do it in Revo, because it must be multilingual in due course, and YAMS can’t seem to stay in the alternative languages when tagging bocomes recursive - and YAMS’ author is now otherwise engaged.
So here goes:
Each Resource Page for each House has a TV called tags. It isn’t an Autotag. Tags are selected manually.
The content for each House includes the toLinks snippet. This snippet’s job is to take the list of tags stored in the TV "tags" and output it as a set of clickable links. You can control how these links are separated when displayed, and provide your own class for styling purposes.
[[!tolinks? &tagKey=`tags` &items=`[[*tags]]` &target=`7`]]
Resource ’7’ is the results-landing-page. I want every link in the list produced by toLinks to go there. Your choices are effectively "here" or "somewhere else". I chose the latter.
The default template chunk contains this:
<a href="[[+url]]" class="[[+cls]]">[[+item]]</a>
What you get looks like this:
<a href="tag-search-landing?tag=Pool&key=tags" class="tl-tag">Pool</a>
So: &key in the generated URL gets the value passed in parameter &tagKey.
This works fine: each House page has a list of tags across the top. Clicking took me to the landing page.
Which is where Warsteiner’s example stopped working: the landong page was blank, apart from thelist of "all" tags produced at the next stage.
The next snippet, tagLister, lists all the tags found for all the documents it is asked to process, and helpfully provides a count for each tag (How many houses have Swimming Pools?). Each list item is clickable. In other words it is a lisst of links, much as toLinks is a list of links. The essential difference is that toLinks only mentions the tags in the current document, while tagLister mentions all the tags for all the documents in the defined set.
The snippet tagLister, in my case looked like this:
[[!tagLister?
&tv=`tags`
&parents=`[[2]]`
&target=`[[*id]]`
&tpl=`tagsTpl`
&activeCls=`current`
&cls=``
&altCls=``
&weightCls=``
]]
And my chunk for tagsTpl looked like Warsteiner’s, but without the count.
<li class="[[+cls]]">
<a href="[[~[[+target]]? &key=`[[+tagKey]]` &tag=`[[+tag]]`]]">[[+tag]]</a>
</li>
&parents tells the snippet where to look for documents to process (my "defined set", above), and &target defines where you want the results displayed. This time I chose "here" - my results landing page. The various class parameters enable the kind of fancy styling that gets you tag clouds with BIGGER fonts for LOTS of results. I’ll do that later, as does Warsteiner...
That worked too - I got my list, and it looks like this:
<li class="">
<a href="tag-search-landing?key=tags&tag=Swimming+Pool">Swimming Pool</a>
</li>
<li class="">
<a href="tag-search-landing?key=tags&tag=Land">Land</a>
</li>
<li class="">
<a href="tag-search-landing?key=tags&tag=Lake">Lake</a>
</li>
The value passed as &tv is now shown as "key=tv".
I found the different ways to paramterise this tv, so far three different ways, a little confusing. We’ve had &tagKey. &items and &tv in our two snippets. The different ways to refer to it on output links is also a bit confusing. "&key=" and "key=". Only two - shouldn’t grumble.
Now to the bit that didn’t work. The Snippet: getResourcesTag., (I fully-concur with Warsteiner’s intelligent suggestion to think of it as "getResourcesByTag").
But it didn’t get any resources.
Warsteiner’s code, adjusted to fit my document ids, looked like this:
[[!getResourcesTag?
&elementClass=`modSnippet`
&element=`getResources`
&tpl=`propertySummaryTpl`
&limit=`0`
&includeTVs=`1`
&tagKey=`tags`
&showHidden=`0`
&hideContainers=`1`
&cache=`1`
]]
Here are some new ideas that distracted me while I tried to figure-out how this snippet was supposed to know what documents to get. I didn’t want it to get all the documents the way tagLister does, by defining &parents=`2`. I had getResources working elsewhere. and it provides for filtering by TV. I thought that &processTVs=`1` was missing. Nope. I thought that &limit=`0` was the problem: fetch zero. Nope. "0" might mean "all", because the default is 5, but this isn’t in the documentation. I had no idea where &cache came from. nor any idea what or why &elementClass and &element where doing - all undocumented. I traced the two element things down to getPage, and eventually arrived at the idea that these are to do with linking getReources to getResourcesTag. They certainly had a lot to do with getting the output to look correct when I called the same templating chunk I use for getReources elsewhere.
Eventually I cottoned-on - you have to put in &parents=`2`, when you do, it works. And it doesn’t get them all - just the resources for the tag you’ve just clicked. How? I have no idea.
[[!getResourcesTag?
&parents=`2`
&elementClass=`modSnippet`
&element=`getResources`
&tpl=`propertySummaryTpl`
&limit=`0`
&includeTVs=`1`
&tagKey=`tags`
&showHidden=`0`
&hideContainers=`1`
&cache=`1`
]]
This is what the code should be.
I suppose that getResourcesTag is also a wrapper-snippet like getPage. I don’t understand this yet in terms of the technicalities. I get the idea, just not the method. I’m going to try chopping-out some of these parameters to see what happens.
When it comes to the documentation, I got quite confused: There’s something called tagRequestParam mentioned in toLinks which does something to a REQUEST var key. In the example provided:
"Change the TV value of ’tags’ into links that point to the URL of Resource 123 with the GET param of ’tag’:
[[!tolinks? &items=`[[*tags]]` &key=`tag` &target=`123`]]
"
Now we have a GET parameter. &key isn’t mentioned as a parameter as such, and the *working* example provided by Warsteiner uses &tagKey, not &key.
I’m not whingeing here, just ignorant, and anxious to chip something back in by writing some better documentation, once I’ve got my head round it all.
My set-up:
CGI/FastCGI
MODx Revo 2.1.1 (trad)
PHP 5.3.6
MySQL 5.1.56
pdo-mysql installed
ImageMagick 6.4.8 2010-01-07
json version 1.2.1
I browse in Firefox, Safari, IE and Chrome - latest non-Betas of each.
I’m not opcode cacheing to my knowledge