It’s no secret that Arketi loves MODX. It’s a content management system (CMS) that gives you a clean slate to build a site your way. There is no predefined structure that you have to build your sites within and no tweaking of your design to fit another developer’s vision of how a site should be structured. As the MODX site says, “Creative. Freedom.”
There is always a tradeoff with that kind of freedom. With no one telling you how to structure your site, you have to decide how to do it yourself! It’s intimidating at first, but once you start getting into the power that MODX offers with template variables, input/output filters, snippets and chunks, it gets addictive. The hard part is learning what tools you have available and how to utilize them to do what you want.
We’re going to look at MIGX, a type of custom template variable that has quickly become one of my favorites. Using MIGX, which stands for MultiItemsGridtv for MODX, Arketi was able to create a scrolling homepage banner for our client, ARA.
Whoa, whoa, what’s a template variable? Well, let’s explain that first. In MODX, a template variable is a custom field for a MODX Resource. Resources in MODX can be many things, but the most common are representations of your website’s pages. Template variables allow you to store or use custom fields in your pages. They can be simple things such as text or a block of rich text with code. Or, they can be more complex such as date and time for recurring events, drop down lists built from other resources, or check boxes used to turn on or off page features. Basically, it’s one of the more powerful tools in MODX.
Setting up MIGX
I would highly recommend also reading the excellent tutorial for MIGX created by Mark Hamstra here and reading the MIGX documentation here. Both are excellent guides.
The hardest part of the whole process is setting up the initial template variable. To begin, MIGX is installed through the MODX package management page. Once installed, you have access to a new type of template variable. Set your name, caption and description as you would for any other, and assign it to which template can use this variable under template access.
The input option is where it gets different. Set your input type to MIGX and you’ll see a whole host of new options. The most important are the form tabs and grid columns and both fields require JSON statements. The form tabs are how your data is stored and presented while the grid column is how that data is presented to a user in the MODX manager.
The ARA form tabs
1
2
3
4
5
6
7
8
9
10
| [{"caption":"Homepage Slider Content", "fields": [
{"field":"placeholder","caption":"ID","inputTV":"placeholderTV-MIGX"},
{"field":"title","caption":"Title","description":"Intro Title","inputTV":"textTV-MIGX"},
{"field":"location","caption":"Location","description":"Name of location","inputTV":"textTV-MIGX"},
{"field":"address1","caption":"Address","description":"First Address line","inputTV":"textTV-MIGX"},
{"field":"address2","caption":"Address 2","description":"Second Address line","inputTV":"textTV-MIGX"},
{"field":"copy","caption":"Description","description":"Short descriptive text","inputTV":"textareaTV-MIGX"},
{"field":"image","caption":"Image","description":"LocationImage","inputTV":"imageTV-MIGX"},
{"field":"panelcolor","caption":"Color","description":"Panel Callout Color","inputTV":"homeagepanelcolorTV-MIGX"}]}
] |
The caption line defines what the header will say when you’ve opened a new item in your grid.
Using the title as an example, let’s look at each piece:
- “field”:”title” is the name used for the field
- “caption”:”Title” is the display name of this field
- “description”:”Intro Title” is a short bit of descriptive text shown to the user
- “inputTV”:”textTV-MIGX” (this one is key) this defines the TYPE of the field. This is a bit confusing at first but this entry looks for the textTV-MIGX template variable. It’s a special template variable, not assigned to a template that is set up with the textTV-MIGX name and the type is set to text.
As you can see above, there are 5 types of input TVs we use:
- placeholderTV-MIGX is a hidden field so it does not show up when editing a line
- textTV-MIGX is a simple text field
- textareaTV-MIGX is a simple text area
- imageTV-MIGX is an image template variable, allowing processing of a thumbnail.
- homeagepanelcolorTV-MIGX is a special template variable made for this panel. It is a series of radio buttons allowing a user to select a color
The ARA grid columns look like this
1
2
3
4
5
6
7
8
9
10
| [
{"header": "ID", "width": "10", "sortable": "true", "dataIndex": "placeholder", "renderer": "this.renderPlaceholder"},
{"header": "Title", "width": "100", "sortable": "true", "dataIndex": "title"},
{"header": "Location", "width": "120", "sortable": "true", "dataIndex": "location"},
{"header": "Address 1", "width": "120", "sortable": "true", "dataIndex": "address1"},
{"header": "Address 2", "width": "120", "sortable": "true", "dataIndex": "address2"},
{"header": "Copy", "width": "160", "sortable": "true", "dataIndex": "copy"},
{"header": "Image", "width": "150", "sortable": "false", "dataIndex": "image","renderer": "this.renderImage"},
{"header": "Color", "width": "120", "sortable": "false", "dataIndex": "panelcolor"}
] |
Let’s look at the title again:
- “header”: “Title” is the title for this column
- “width”: “100″ sets this column to 100 pixels wide
- “sortable”: “true” gives you the ability to sort it
- “dataIndex”: “title” links this column with the field name used in our Form Tabs.
There are a few special cases here such as the placeholder and image “renderer”: “this.renderPlaceholder” helps create a sequential id for each row. “renderer”: “this.renderImage” helps to create a thumbnail image in the row.
Once you are all done, go to any resource that uses this new template variable and you will see something like this:
You get a very nice, easy to update grid of items. Clicking add item opens up a pop up window with the ability to create a new row with all the necessary information.
Placing this template variable on a page gives us this:
1
| [{"MIGX_id":"3","placeholder":"","title":"RECENT TRANSACTIONS","location":"The Vistas at Saddle Rock","address1":"22959 East Smoky Hill Road","address2":"Aurora, CO","copy":"320-Units","image":"assets/homepage/denver.jpg","panelcolor":"blue"},{"MIGX_id":"1","placeholder":"","title":"RECENT TRANSACTIONS ","location":"Autumn Park Apartments","address1":"1801 Interface Lane","address2":"Charlotte, NC","copy":"586-Units","image":"assets/homepage/charloette-autumnpark.jpg","panelcolor":"green"},{"MIGX_id":"2","placeholder":"","title":"RECENT TRANSACTIONS ","location":"Belmont Apartments & Townhomes","address1":"2500 Bennett Avenue","address2":"Dallas, TX","copy":"477-Units","image":"assets/homepage/DallasUDR.jpg","panelcolor":"red"}] |
Not very helpful, but that is where two other MODX tools come in—the snippet and the chunk.
Snippets are the way MODX can run pieces of dynamic PHP code on a page. Chunks are pieces of static text or other elements on a page. Chunks don’t process PHP, but they can be used to call snippets. The template variable, a snippet called “HomepageSlider”, and a pair of chunks is all we need to turn the output above into HTML code we can use.
On the homepage template is this line:
[[HomepageSlider? &input=`[[*HomepageFeatures]]` ]]
[[*HomepageFeatures]] is the name we gave our Template Variable
“HomepageSlider” is the name of the Snippet we are going to use. You can see that the Template Variable has been assigned to a paramater named input. This will be passed to the Snippet and used as a PHP variable.
So here’s the snippet’s code:
HomepageSlider
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
| <?php
$input = $modx->fromJSON($input);
$slideOrder = 1;
$output = '';
$output.= '<div class="slideshow"><div class="txt"><div class="holder">';
foreach($input as $row)
{
$row['MIGX_id'] = $slideOrder;
$section1[] = $modx->getChunk('HomepageSliderTpl', $row);
$slideOrder++;
}
$output.= implode("\n", $section1);
$output.= '</div></div><div class="gmask"><ul id="slider">';
foreach($input as $row2)
{
$section2[] = $modx->getChunk('HomepageSliderTpl2', $row2);
}
$output.= implode("\n", $section2);
$output.= '</ul></div></div>';
return $output; |
Let’s walk through this.
- First, turn that template variable into something usable. If you remember from before, we assigned a parameter to the snippet call named input. We are now using one of the MODX functions to turn that JSON string into a PHP array.
- Since the site editor might want to change the order of the slides in the manager, make a new variable that starts at the number 1 called slideorder.
- Create the output variable and make sure nothing is in it. Next, we can start to add some HTML code.
- We then start to step through this big array. First, set the MIGX_id to whatever number the slideorder variable is. In this case, it is the first one, so we number it one.
- Now, make a call with one of the MODX functions called getChunk. It does exactly as it sounds. It gets a chunk called ‘HomepageSliderTpl’ and uses the row array (more on this later).
- We then bump up the slide order by one.
- We run through this loop filling up a new array called section1.
- Once this loop is done, we implode the array into a nice new bit of HTML code.
- In most cases you would now be ready to return your output variable to the page. In the case of the ARA homepage area, the content is split from the images. Therefore, we have a bit more HTML code as well as another for each loop and implode.
This snippet has two getChunk statements. Here is what the getChunks look like
HompageSliderTpl
1
2
3
4
5
6
| <b>[[+title]] </b>
<i>[[+location]][[+address1]]
[[+address2]] </i>
[[+copy]] |
HompageSliderTpl2
1
2
3
4
| <ul>
<li>[[+image:imageProcess]] </li>
</ul>
|
When this chunk is called in or for each loop, it is given an array that has key pairs. The key value associated with ‘title’ will be placed in your chunk where you see the placeholder [[+title]]. You may notice that these placeholders share the same names as our field names way back in the Template Variable setup.
And there we have it! Once this snippet is executed on the page, it drops in a bit of HTML code that our Javascript based slider can then use.
