In this article, we'll look at how to control the order in which Template variable (TVs) appear on the MODX Manager's Create/Edit Resource panel.
TV Sort Order
You may know about the rank field of a Template variable, but it doesn't always work as expected. The reason is this code in the resource/tv controller:
When editing a resource, TVs appear in categories. This is the first level of sorting for them. By default, the categories are sorted alphabetically by category name. You can change the order of the categories by editing their 'rank' field. The lower the rank number, the higher the category will appear in the list. You can set the category's rank when you create it, or by right-clicking on the category and selecting "Rename Category."
You might be tempted to try dragging the categories around in the tree, but dragging a category will make it a sub-category under another category. If you've already made that mistake, you can drag the category to the "Categories" folder to put it back and the top level.
The second sort (within categories) was a bit of a surprise to me. It's by the rank set for the
TemplateVarTemplate, not the rank set for the TV. You can't set this by changing the rank of the TV itself. You have to edit the *Template* the TV is attached to and set the "Rank" field on the "Template Variables" tab. TVs with a lower rank number will appear first. If all the TVs have the same rank there, and no ranks are set on the TV objects (see below)), the TVs will usually appear in the order they have in the database, which is normally the order in which you created them (though it's not guaranteed).
So, the rank of the TV per template has a higher sorting precedence than the rank of the TV itself. The reasoning for this is that you might want to have TVs attached to separate templates appear in different order. In other words, the TVs could be in one order when editing one document, but in a different order when editing a document that uses a different template.
If the ranks on the "Template Variables" tab when editing the template are all the same (or all empty), the third sorting criterion comes into play: the rank of the TV itself.
When editing the TV object itself in the Manager (under "Template Variables" in the Element tree), on the "General Information" tab you'll see a field called "Sort Order". This sets the
rank field of the TV. As usual, lower numbers have a higher priority and will appear first. As I mentioned above, this number will only apply if two or more TVs have the same rank on the panel you see when editing a page template.
Same Order Everywhere
For most use cases, you either don't care what order the TVs are in (in which case, do nothing), or want them in the same order everywhere they appear. If you want to order them and have the order apply everywhere, there are two ways to go.
One is leave the "Sort Order" field alone when editing the TV itself, and set the "rank" field for each TV on the "Template Variables" tab when editing the template. Double-click on the field and enter a number. (If you right-click on the field and select "Edit TV", you'll leave that page and find yourself editing the TV itself, which is probably not what you want.) You'll have to repeat this for every Template that uses the TVs you want to order.
The other method is the reverse. Set the "Sort Order" field when editing each TV and leave the settings on the template alone. Which method is easier depends on how many templates you have and how many TVs you want to order. If you have a small number of Templates, it's usually easier to do it on the "Template Variables" tab when editing each template. If you have lots of templates and not many TVs, it's often easier to edit the TV objects themselves and set the "Sort Order."
Sort Order by Template
If you want the TVs to have a different order depending on the template used, it's always easier to leave the "Sort Order" on the TV itself alone and set the "Rank" field when editing each template.
In the next article, we'll look at the case where you want to change the value of a placeholder, but don't know where the placeholder is set. This is a common problem when you inherit a site created by another developer.
Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)