Transform template variables into a sortable multi item list for the MODX Evolution content management framework

One example for multiTV usage could be found in EXAMPLES.md. Feel free to add your own examples there and create a pull request with them.

Events example:

Images example:

Links example (with editing layer):

With this code a MODX Evo template variable could be transformed into a sortable multi item list

1. Upload the folder assets/tvs/multitv in the corresponding folder in your installation.
2. Create a new template variable with imput type custom input (if you name this template variable multidemo it will use the multidemo config file)
3. Insert the following code into the input option values

@INCLUDE/assets/tvs/multitv/multitv.customtv.php

4. If you want to modify the multiTV with ManagerManager before MODX version 1.0.9 you have to patch the file mm.inc.php and insert

case 'custom_tv':

in line 136 just before the line

$t = 'textarea';

(Note 4) 5. If you want to use multiTV with YAMS you have to patch yams.plugin.inc.php according to the instructions on https://github.com/Jako/multiTV/issues/9#issuecomment-6992127 6. If you are updating from 1.4.10 and below you could install the updateTV snippet (see part 4) and modify the data in your multiTVs to the new format. Since the custom tv and the snippet code supports the old and new format, this is only nessesary, if you want to add/remove columns in your multiTVs or if you want to sort the output by a column. 7. If you want to use PHx with multiTV you have to modify the PHx plugin code a bit:

if (!class_exists('PHxParser')) {
    include MODX_BASE_PATH . "assets/plugins/phx/phx.parser.class.inc.php";
}

$e = &$modx->Event;
switch($e->name) {
	case 'OnParseDocument':
		$PHx = new PHxParser($phxdebug,$phxmaxpass);
		$PHx->OnParseDocument();
		break;
}

All options for a custom template variable are set in a config file in the folder configs with the same name as the template variable (otherwise the default config is used) and .config.inc.php as extension

The display of the input fields in the multi field list could be set in $settings['display'] to horizontal (events example), vertical (images example), datatable (links or multicontent example) or single. A multiTV with single display configuration contains only one list element.

The input fields of one list element could be defined in $settings['fields']. This variable contains an array of fieldnames and each fieldname contains an array of field properties.

• Supported MODX input types: text, rawtext, email, number, textareamini, textarea, rawtextarea, htmlarea, date, dropdown, listbox, listbox-multiple, checkbox, option, image, file

In datatable mode the columns for the datatable could be defined in $settings['columns']. This variable contains an array of column settings. Each column setting contains an array of properties. If a property is not set, the field property in $settings['fields'] is used.

In datatable mode the content of the editing layer could be defined in $settings['form']. This variable contains an array of form tab settings. Each form tab setting contains an array of field properties in the value of the content key. If a field property is not set, the field property in $settings['fields'] is used.

• In the editing layer the MODX input type richtext is possible.

The default output templates for the snippet could be defined in $settings['templates'].

The other configurations for one multiTV could be defined in $settings['configuration']

See the multidemo config for all usable vertical settings and the multicontent config for all usable datatable settings.

Create a new snippet called multiTV with the following snippet code

<?php
return include(MODX_BASE_PATH.'assets/tvs/multitv/multitv.snippet.php');
?>

Call the snippet like this (most expample parameters are using the default values in this example call and could be removed from the call – parameter tvName is required)

[!multiTV?
&tvName=`yourMultiTVname`
&docid=`[*id*]`
&tplConfig=``
&outerTpl=`@CODE:<ul>((wrapper))</ul>`
&rowTpl=`@CODE:<li>((event)), ((location)), ((price))</li>`
&display=`5`
&offset=`0`
&rows=`all`
&randomize=`0`
&reverse=`0`
&orderBy=``
&toPlaceholder=``
&toJson=`0`
&published=`1`
&emptyOutput=`1`
&outputSeparator=``
&firstClass=`first`
&lastClass=`last`
&evenClass=``
&oddClass=``
!]

The default templates for outer template and row template could be defined in the config file for the custom template variable. These custom definitions could be overwritten by rowTpl and outerTpl in snippet call. Both template chunks are parsed by PHx (chunkie class).

Since the JSON string in multiTV starts with [[ and ends with ]] (Note 1), you can't check if the multiTV is empty by i.e. [*multittvname:ne=``:then=`not empty`*].

But you could to use the PHx modifier in the folder phx-modifier in that case. Move the two files to assets/plugins/phx/modifiers and call it like this [+phx:multitvisempty=`tvname|docid`:then=`xxx`:else=`yyy`+] or like this [+phx:multitvisnotempty=`tvname|docid`:then=`xxx`:else=`yyy`+]. If the docid is not set it defaults to current document.

Create a new snippet called updateTV with the following snippet code

<?php
return include(MODX_BASE_PATH.'assets/tvs/multitv/updatetv.snippet.php');
?>

Version 1.4.11 of multiTV uses a new data format (the column names are saved as key with each value). The custom tv and the snippet code supports the old and new format, so you don't have to update your multiTVs. It is only nessesary, if you want to add/remove columns in your multiTVs. Call the snippet on one (temporary) MODX document like this:

[!updateTV?
&tvNames=`yourMultiTVname1,yourMultiTVname2`
!]

multiTV is totally free and comes with no warranty or support. I give basic support on github tracker and like to receive suggestions for enhancements there.

I work on new features and bug fixes in my spare time (and if one of my clients needs a special feature). So maybe a bugfix or an answer could take some time and unfortunately some enhancement wishes won't get addressed.

If multiTV is useful for you, I’d like to hear about that as well. Donations for multiTV are appreciated. Please feel free to donate any amount that that you like to give for your multiTV usage.

multiTV is free because I have fun working on it and because I don't have the resources to properly support it. If you decide to make a donation, I thank you very much. But please remember that I'm not able to extend my support for multiTV beyond the level I have done in the past.

If you urgently need an addition to multiTV code, you could hire me for that work for sure. My email address could be found on my github page

1. The JSON string the multitv is converted to starts with [[ and ends with ]] so the MODX parser thinks it contains a snippet and you can't place the template variable directly in the template.
2. If the snippet output is assigned to placeholder and PHx is installed, the page should be set to uncached and the Snippet should be called cached. Otherwise PHx will 'steal' the placeholders before the Snippet could fill them.
3. MODX does not like =, ? and & in snippet parameters. If the template code has to use those signs, put the template code in a chunk or change the default templates in the config file.
4. ManagerManager expects a custom tv field to be an input tag. Because of single and double quote issues the field containing the multiTV value is a textarea.