In the Swiss army knife that is MODX, TV’s still play a major role in creating and managing your content. There’s a few different input types available, and I’m sure you’re also using the checkbox, listbox and radio types every now and then. The options for those TV’s are defined in the Input Option Values field, using the double-equals and double-pipes formatting you're familiar with, like this:
Man||Bear||Pig
Option 1==value1||Option 2==value2
This works fine in a lot of cases, but there is a problem with this. If you want to change the value of the option (typo’s, different chunk name, etc), all the TV’s with the old value(s) selected, will loose these selections. Very inconvenient, if your client just filled 80 resources with their content and set the TV’s accordingly.
Especially for larger, more complex projects, this is unacceptable behaviour. The selected values of TV’s should be referenced in the database by a unique ID. This way, you can change whatever you want in the value, without harming the existing selections. To do this, we created a little extra called Set Input Options.
How to use Set Input Options to manage your TV’s
Set Input Options is a very basic CMP that allows you to create groups with their own input options. These options can then be used in TV's, for checkboxes / listboxes etc. Unlike the default Man||Bear||Pig input options, the CMP is easy enough for clients to understand, in case you want them to be able of managing the values.
To set it up, you have to go through the following steps:
- Install SetInputOptions through the package manager (or download from MODX.com)
- Go to Extras > Set Input Options and create a group with some options
- Create a TV with an @SELECT binding in the Input Options Value field, that points to the options created in step 2 (see example below)
- Fetch the input option values in your content with the getInputOptions or Rowboat snippets
Connect your TV to your custom input options
An example of an @SELECT binding for checkboxes and radios:
@SELECT `name` AS `name`,`id` FROM `[[+PREFIX]]setinputoptions_inputoptions` WHERE `group` = 2 AND `softDelete` = 0 ORDER BY `position`
An example @SELECT binding for listboxes and multiselects. Note the first part up till UNION ALL. This adds an empty first item to your TV, so by default, nothing will be selected.
@SELECT '' AS name, '' AS id UNION ALL ( SELECT `name` AS `name`,`id` FROM `[[+PREFIX]]setinputoptions_inputoptions` WHERE `group` = 1 AND `softDelete` = 0 ORDER BY `position` )
Important Don’t forget to use a `,` as output delimiter, in order for the getInputOptions snippet to work!
Display input option values using the getInputOptions snippet
To reconnect the unique ID of the input option to the name that needs to be displayed, you can use the getInputOptions snippet. This snippet needs a comma separated list of ID’s as input, which it will get from the TV. By default, only the name of the value is being displayed, but you can use your own tpl chunk to override this.
[[getInputOptions? &tv=`[[*your_template_variable]]` &tpl=`yourTplChunk`]]
Available Properties:
- tpl
- delimiter
- outputDelimiter
Available Placeholders in the row tpl:
- name
- alias
Display input option values using the Rowboat snippet
You can also use Rowboat to list all the options in a group. Useful for example, for creating filter buttons. Don't forget to download and install Rowboat separately through the package manager!
[[Rowboat?
&table=`modx_setinputoptions_inputoptions`
&tpl=`filterButtonsRow`
&limit=`10`
&sortBy=`position`
&where=`{"group":"1"}`
]]
It’s not spacecraft technology or anything, but we’re finding it very useful for maintaining TV’s in all of our projects. It makes things more solid and flexible. So if you ever find yourself fiddling with missing TV values again, this might just save your day...
All credits go out to my colleague Robin Rijkeboer, for writing the actual code, and to Git Package Management, for making the process of creating extra’s such a breeze.
If you have any questions or issues, please let us know!