The Ditto Manual, just might be crappy.

Am I the only one that thinks the Ditto manual is practically useless for anyone that doesn’t already know how to use Ditto?

For example I was wanting to setup a Ditto call to display a folder of weblink documents. I figured Ditto would be good for that, so I go to the Ditto Manual and learn that the original call just to get things going is... well I can’t actually figure that out from the manual. But luckily I know a little bit about basic MODx calls so I figure out a call like this, which works...



I figured it would be good to modify the template to only show a title, description, and the URL. So I try to modify the place holders to show that but the weblink doesn’t seem to do anything. Is that not a place holder? The other ones like [+title+] seem to work so maybe I’m just typing something wrong. I try to look up place holders in the Ditto manual and find this description.

placeholders

Initialize custom placeholders array for configs or extenders to add to

Well that’s not very helpful. No list and not links to any sort of other information. So I scan up and down thinking that maybe placeholders is an extender or something. No luck, that’s all the info on place holders.

So I remember that I wanted to categorize these links with tags and later have maybe a tag cloud. So I find the tutorial on Tagging and follow the steps (which by the way don’t mention anything about activating the extender). But I figured that out somehow and when I initialized the snippet it comes back with an error saying

Tagging Extender does not exist. Please check it.

I figured maybe the extender is a separate install, and go to the manual to find a place to download it. No luck with that. Nothing but the list of parameters.

While I’m there I wonder how the extender tag would work with more than one extender so I go to the extender section to see how the items should be separated (with a space, comma, multiple &extender tags, etc.) No luck again. All it says is that an extender is to load extra functionality into Ditto and the options are any extender in the extender folder or in the MODx base path via @file.

I could go on with a couple more problems but maybe I’m just missing a key piece of logic in how to use the manual. Or maybe I’m just stupid, but I haven’t had a problem like this with any of the other MODx snippets. Leading me to believe it’s not actually me that is stupid.

The Ditto docs are a great effort, or a work in progress, but by far is the best documented snippet (well wayfinder is a good contender) but are a bit geared towards the slightly more experienced users. There is plenty to read between the lines or with a decoder ring. Maybe a beginners guide to Ditto would help bridge the gap. (now to add to your frustration there is so much more to Ditto than is in the documentation with the new releases). I have come to depend greatly on the Ditto docs, I refer to them regularly since it is common that I will be using it in a new unorthodox way. There are some good tips in the Ditto forum that help put things together, and there are a few stickies that clear some things up. Also it is a good idea to check the release notes of the new releases since there are some bug fixes that have been implemented but not yet documented.

As to your issue with Weblinks. By nature the weblink URL is stored in the [+content+] placeholder, this is a MODx thing. A weblink is actually a document like any other but with type=reference.

You can use PHx in the Ditto chunk to identify if it is a weblink and do other stuff to the formating if needed, here is an example from the forums:
[+type:is=`reference`:then=`[+description+]`:else=`[+introtext+]`+]

I feel your frustration, however I think that "crappy" may be a bit harsh, they are complicated and could be better, but IMO are not crappy

Holy cow I think I just stepped into the world of programming. Ok. Maybe the manual isn’t crappy. I’ll try to keep an open mind.



I have no idea how to follow the logic behind what that is doing (to modify it or make my own).

But on a different line, any idea where I can find the tagging extender or why Ditto can’t find it on it’s own?

I don’t think that it is an actual extender like the other extenders (ie you don’t need to load it). When you use the tagData parameter it loads the extender (or something like that).

Check out all the tagging related parameters here:
http://ditto.modxcms.com/files/assets/snippets/ditto/extenders/tagging-extender-inc-php.html

Tags rule! One thing to consider is that you can use any document variable as a tag. I have used pagetitle, id and template as tagData and they all worked great.

BTW, this:

[+type:is=`reference`:then=`[+description+]`:else=`[+introtext+]`+]

Would be used in your Ditto tpl chunk and it’s function is to identify if a document is a weblink, if it is then post the description field if not then post the introtext field. This is because a weblink has no introtext (don’t ask me why, to me weblinks really need the introtext since the content field is being used for the URL).

Or watch the tagging screencast:
http://ditto.modxcms.com/screencast/tagging.html

Quote from: dev_cw at Feb 16, 2008, 06:17 PM

This is because a weblink has no introtext (don’t ask me why, to me weblinks really need the introtext since the content field is being used for the URL).

I rather imagine that’s because it was never expected that a weblink would ever have any function other than being a placeholder to make menu entries out of. Quite a number of the original functions have been expanded on as it occurs to people to use them for things that weren’t envisioned. If you ever used the original Etomite, it would seem terribly limited, which of course is why the original MODx mods were written to begin with. I mean, really, no web user management, only manager users? (I had almost decided Etomite wasn’t going to fulfill my needs until I saw the MODx extensions)

Couldnt you use Wayfinder for this? It’s made for link lists.

Quote from: ProWebscape at Feb 17, 2008, 02:39 AM

Couldnt you use Wayfinder for this? It’s made for link lists.

Good point

Regarding the introtext for the weblinks, since the database field is available I imagine it would not be to difficult to add this feature. I really need to get my hands under the hood more. Initially it is a bit intimidating but after taking a few peeks it is really not as difficult to follow as imagined. Just a matter of taking a deep breath and going for it

Like I always say, if I can do it, certainly you can do it