New online documentation

When reporting an error in the documentation, would you please include a link to the offending page? Many things are documented in several places by several different people, and it is hard to figure out where exactly the error is!

http://modxcms.com/NewsListing.html
In the CSS section--



should instead read:


Semicolon erroneously doubled.

Thanks! Fixed.

Hello,
I have been using the Joomla CMS and I’m checking out MODx because from what I’ve seen it allows for a lot more flexibility with regards to site design (I’m a designer, not a coder).

I’m going through the documentation and it seems to me that an explanation of the implementation of template variables is left out of the Designer’s Guide in the Documentation. At the end of the "Adding MODx Tags" page it states "In the following documents, we will discuss snippets, Template Variables (TVs) and chunks, and how to use them to add functionality and ease of maintenance to your site." However, the the following sections in the Designer’s Guide talks about adding snippets and chunks, but an explanation of TV’s is left out.

I read the TV section in the Developer’s Guide and some posts on TV implementation in the Forum and I’m still not quite grasping it because either 1) it seems like these explanations assume some basic understanding of TV’s that I don’t have or 2) examples given include PHP code, which is not helpful to me.

What I DO understand is that TVs can somehow control what content (documents, chunks, snippets) appear depending on what page you’re on. (The Joomla analogy would be assigning specific modules to positions on your template depending on what which link you’re on). But beyond that, I still don’t have a basic understanding of how TV’s work and can’t find practical examples of how I, as a designer (with no coding knowledge) can use TV’s on a template that I design.
Also, aside from chunks, TVs, and snippets, the Developer Guide talks about widgets, modules, and plugins. But again, these are explained in ’developer-ese’ and, again, I feel like I won’t be able to take full advantage of this CMS without coding knowlege (even though I’ve read in testimonials from other designers that coding knowlege isn’t necessary to use MODx).
In the end, I figure that either 1) I’m so locked into the Joomla mindset that I’m missing something that’s really obvious about TV’s and I’ll later feel stupid about writing this post, or 2) using MODx really does require a bit more of a PHP background that I currently have.

Can anyone help or point me in the right direction?
Thanks.

Blitz, the template I released for the community uses TVs, maybe dissecting it might help you.

http://modxcms.com/forums/index.php/topic,4941.0.html

Also, this post was my "lightbulb moment" with TVs.

http://modxcms.com/forums/index.php/topic,4618.0.html

Quote from: blitz at Aug 02, 2006, 12:16 PM

What I DO understand is that TVs can somehow control what content (documents, chunks, snippets) appear depending on what page you’re on. (The Joomla analogy would be assigning specific modules to positions on your template depending on what which link you’re on). But beyond that, I still don’t have a basic understanding of how TV’s work and can’t find practical examples of how I, as a designer (with no coding knowledge) can use TV’s on a template that I design.

A TV *is* a document content field. It is a specific element of content. In addition to built-in fields like content and title, you can add your own fields. It is feasible to have a document that does not use the main content area - instead you might have TV fields for "Film Name", "Film Poster", "Film Review", "Film Rating" and your template would just reference the TVs in the right places. However, most often they are in addition to the content area.

A Template Variable is defined in your MODx manager - it may be plain text, a picture, a link. You can have a default value. You can make it available to templates. When editing a document, you can set the value of the TV.

Because of the way the TV is saved with the document, you can use it in the template - and also it in other ways. You could reference it within content. You could have a snippet that referenced it. You can also have snippets on other pages that reference it - for example a list of film names with ratings can be generated from a set of documents with TVs.

By separating out the content into definable elements like this, design can be fully separated from content.

MODx will let you create a document with a content field where you’ve made the film name bigger, included a picture and the review and had the rating at the end. But that’s not really a good idea - someone’s bound to use the wrong font setting on one film and your reviews section will look messy.

A widget basically formats your TV for display - your content may be saved as "mypicture.gif", but the widget will turn this into an image link.

A data binding lets you select the choice of field content from a list or database. This is more advanced stuff, but it’s actually pretty easy once you get the hang of it.

Plugins generally change the way MODx handles document processing. Modules are again generally add-ins that don’t affect the basic "design sites" stuff, other than giving you new ways to edit things. Don’t worry about them.

While the main content area is obviously useful, it seems as though it is mainly a default container. What I take from this is that one’s mindset might better be to define and aggregate a set of TVs that will manage project content as part of the upfront (data) design of a project. As a corollary, a widget(s) displays a TV in various ways (image link) depending on its type (picture).

The (same) TV can be assigned to a template, content area(s) of pages, snippets. Is it possible to override the default association of a TV with a widget and assign another widget to that TV for a specific purpose in a specific template, content area or snippet?

Also, could you share one specific example of a useful data binding relative to TVs? For example, you suggested some TV fields (Film Name, Film Poster, etc). Why might one want to bind these (or similar fields) to a list of database? I can guess but I have not experimented with them yet.

Please help me understand where I have missed or overshot your explanation. This has been helpful.

Incredibly useful @BINDING trick I use on almost every site:

Create a folder for docs. Create a [*CategoryImage*] TV to hold an image that is representative of that Category. In the default value of that TV, put @INHERIT. What this does is to make that TV look up the document tree until it finds a parent that has a non-default value for [*CategoryImage*]

Now, ever doc you create under that folder, will automatically have the correct image assigned. Change the parent folder image and all docs are updated automagically.

Quote from: RussLipton at Aug 02, 2006, 03:11 PM

I assume (I haven’t tried it in my early experimentation) that different widgets can be assigned to a TV when used in a different content (diff pages or snippets ...) or no?

I believe that the simple answer is that they can’t. *However* the value of one TV can be "loaded" by another TV which has a different widget, so you could achieve the same goal.

Quote from: RussLipton at Aug 02, 2006, 03:11 PM

Also, could you share one specific example of a useful data binding relative to TVs? For example, you suggested some TV fields (Film Name, Film Poster, etc). Why might one want to bind these (or similar fields) to a list of database? I can guess but I have not experimented with them yet.

Possibly you are running an ecommerce site alongside MODx, and you want to link to the DVD in the shop catalogue.
Possibly you want to have a "If you liked this, you’ll like this" feature. The data binding could link to another film title (and thus another review).
In essence, any time you want to select something by name that you have a list of somewhere with ID numbers that you’d want to use. Or any time you already have a list of the possible values and you can’t be mithered typing them in each time.

It’s also possible to just hardwire a selection list in.

The important thing to remember is that for most actions in MODx there is a simple way (enter text/paste in url) and a fancy way (select text/id from another db). It’s worth being aware of the fancy ways but it is not essential.

Ryan - that is very cool indeed. That capability has not occurred to me. It would be so helpful if there were a thread (don’t think there is?) that just listed mini-examples of how users leverage bindings. Even more than TVs, I find it hard to ’imagine’ how to apply them in practice.

Paul - OK, are you saying I could define the default value of TV1 to be another TV2 (that used a different widget)? I assume I would simply leave the widget value for the TV1 blank.

Your binding example would reduce the chance of coding errors and simplify maintenance of data in one location that may be referred to in many places. Taking Ryan’s example of data inheritance and yours of data abstraction, would you say those are the two primary uses for bindings? I know, there are an infinite number, this is MODx etc.

As for simple/complex, if installing MODx and getting a basic website up weren’t simple, I wouldn’t still be here.