tagLister? Any examples?

I’ve spent some time trying to make sense of the tagLister docs. I’ve failed. I’m baffled by this... I have this feeling that it does what I need, but for the life of me, I can’t see how anyone got it to work given the current docs. Does anyone have an example of how to make the 3 inter-related snippets work?

* tagLister
* getResourcesTag
* tolinks

I’ll write it up on the official docs, but man, can somebody gotta help a brother out with a full example?

I’ll describe how they work for me. You can see working example here: http://osmynog.com.ua/portfolio/ (site is in Russian).
My content structure:
Portfolio page (folder, id=6)
- Category 1
- Work 1
- Work 2 etc.
- Category 2 etc.

Each Work page has a TV "serviceType" with input type set to Auto-tag.

Tags on Work page are displayed by toLinks snippet, which displays tags of the current document:

When someone clicks on a tag, he is directed to my portfolio page (&target=`6`), where getResourcesTag snippet displays all documents with the same tag.

Portfolio page contains tagLister and getResourcesTag calls.

tagLister displays all tags in specified TV’s from docs in specified folders:


tagLister template:


Then, getResourcesTag (actually better name for it could be getResourcesByTag):

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.


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:



What you get looks like this:



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:



And my chunk for tagsTpl looked like Warsteiner’s, but without the count.



&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:



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:



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.



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’:
"

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

I am posting here out of totally desperation. It seems like you all really understand taglister quite well and I'm hoping you can help me. I have set up a blog with tags using the methods above. My question is this:

Using nickboyds example: If a user is to click on a tag link for swimming pools and is brought to a page that has all the houses with swimming pools how do you get the word swimming pools to appear at the top of that page?

I feel like thats a pretty basic blog thing but I can not find an answer to it anywhere. I have tried posting myself but have not gotten any replies. Any help would be deeply appreciated.

@rrswans I don't know if you stumbled upon it yourself but you should take a look at this board posting. It's the solution you searched for. Just create this snippet proposed and use it where you want the name of the current tag to be displayed. It only depends on the parameter &tagKey named tags. If you have a different one you must change the code of the snippet.

http://forums.modx.com/thread/11108/dynamically-generated-list-of-documents-that-are-tagged-with-categories?page=2#dis-post-397237

I was looking for the same solution as you did and I found the above solution so I thought of letting you know.

Thanks gameship! I just needed the exact same solution and the link you posted too worked a treat

Glad I could help.

I updated the docs @ http://rtfm.modx.com/display/ADDON/tagLister trying to clarify this thing.

I just followed the link FROM the tagLister docs TO this thread, and read Everett's initial post and went "yeah, that's it exactly. I've got it working, but I can't really understand why and feel really baffled by the docs!" So then I was a bit disheartened when I got to the *last* post, wherein Everett says he updated the docs trying to clarify.

I'm having trouble with the flow from toLinks to getResourcesTag.

I'm using toLinks in my "tagged" resources, to provide a link to a "tag search results" page, which uses getResourcesTag. So far so good.

My toLinks call looks like this:


The result is a call to resource 4347 with the following query string:

(where grumble is the tag value).

Resource 4347 has this getResourcesTag call in it:


This whole setup works... IF you remove the "key=tags" from the query string.

I'm not sure what purpose that is supposed to be serving, but removing it makes the results page show the desired results.

The only problem is, I can't figure out how to stop it from showing up in the URL. 'tags' is the default value of 'tagKey' property in toLinks - so that's where it is coming from. But there doesn't seem to be a way to tell toLinks to NOT send that bit of the query string. The closest I've been able to come up with is

...which sends it with an empty value:


This works - my results page is showing results. But it feels like a frustrating hack. I want to understand what my code isn't doing that it should be, or what that value is supposed to be doing, or... something. Can anyone shed a light on this?

Perhaps it was the process of pain and suffering that brought me to enlightenment... sigh... if you have clarifications for the docs, I'll be happy to add them. Reading them now, I'm once again confused.