So what is a MIGX TV?
One of the drawbacks of template variables is the inability to add more than one set. They are great for adding a calendar date or background header image, but can't build an image slider as the TV cannot be replicated. Here's where MIGX comes in, MIGX stands for MultiItemsGridtv and is a "custom Template Variable (TV) input type for aggregating multiple TVs into one TV". The only issue is the official documentation can be somewhat difficult to understand for new developers. This article will attempt to improve on the official MIGX documentation to show just how powerful and easy it is to use.
What will this article cover?
This article is a step-by-step guide on using MIGX to set up an image slider which can be easily updated.
Getting started
To get started you'll need to install MIGX using the package manager which can be found under Extras > Installer, search for MIGX and download the top item. Head back to your package manager and install the Extra by clicking the green Install button.
If you are following the official documentation, you can ignore step 2 as at the time of writing the current release version is 2.12.0.
Keep in mind that when you create a MIGX TV, you should plan out what the TV will do and the type of data you want to add. For our Slider TV we'll need the following:
- Image
- Title (alt-text)
- Description
- URL (to hyperlink the image)
Creating the TV
The first thing we'll need to do is create a new template variable (TV) in the Elements tab and name it something appropriate and lazy... 'Slider' will work. Next, under the Input Options Tab select 'migx' from the Input Type drop-down and give the TV access to the BaseTemplate (or whatever template you are using).
Steps:
- Create new TV named Slider
- Set Input Type to
migxusing the drop-down menu - Give the TV access to your template by clicking the checkbox beside the template under the Template Access tab
- Save the template by clicking the green Save button in the top right of your screen
Creating the MIGX TV Configuration
Once you've saved your Slider TV, you need to create the MIGX configuration. In the official documentation, it shows you how to hand code the JSON required for this step. Fortunately, you don't have to hand-code anything as MIGX comes with its very own Custom Manager Page which writes the JSON for us. Go to Extras > Migx and click on the second tab called MIGX.
In the Actions box there is a button called Add Item, click it, and you'll see a modal window, type 'Slider' into the Name input (very first input) then click on 'Formtabs'. Here, we'll add in the necessary inputs our slider requires.
Steps:
- Click Add Item button
- Write 'Slide' in the Caption input. You can ignore the Display Above Tabs filed for now as this is not relevant to this tutorial
- Click Add Item button under the Fields heading
Creating the configuration fields
You should now see a Pop-up, this is where things get slightly complicated, and you may find it helpful to write a few things down to help you keep track. You'll also need to open the documentation on Template Variables Input Types. Here we'll create the repeating template variables which we planned earlier on.
Repeatable Steps:
- fieldname: i.e. slider_image
- Caption: i.e. Image (human readable)
- Input TV: (for the sake of simplicity should match fieldname) slide_image
- Input TV Type: image (refer to Template Variables Input Types documentation) - lowercase
- Click Done
For the sake of this tutorial, we won't go into adding media sources or default values as there is already a lot of ground to cover. Once you've clicked done, you should return to the previous Pop-up, but this time you'll have your field appear in the table. Repeat the steps above to add the following fields:
| Fieldname | Caption | Input TV | Input TV Type |
|---|---|---|---|
| slider_image | Image | slider_image | image |
| slider_title | Title | slider_title | text |
| slider_desc | Desc | slider_desc | richtext |
| slider_link | Link | slider_link | url |
(Note: For richtext to work correctly you should have a WYSIWYG editor installed such as Redactor)
When you have finished, you should end up with a table showing your newly created fields, now click Done in the bottom right of the Pop-up. Next, we need to add columns so we can preview the slide in the resource. Click on the Columns Tab (Next to Formtabs at the top) and click Add Item.
Here is where it comes in handy to have written down (or at least use a memorable naming system) the fields you created in the previous step. Firstly, give the column an appropriate header such as Image, then enter the field to which this column relates, i.e. slide_image, give the column a width, i.e. 40 (width specifies the table column width in %), and finally set sortable to Yes (optional, but we always set the first column to Yes). Once you've completed this section, you can either click Done or open the Renderer tab. The renderer tab allows you to customise how the data is presented in the resource, so if you want your slide_image image to appear then select this.renderImage from the drop-down box otherwise, it will just output the path to your image.
Repeatable steps:
- Header: Give the column a header
- Field: Enter the field that this column relates to, i.e. slide_title
- Column width: A value between 1-100, try and stay between 20-80 in whole numbers
- Sortable: Optional, if the first item is sortable the rest can be no
- Renderer: Optional, only used to render the Field value on the resource, i.e. to show the slide image instead of the path to the image
When you have finished adding in your columns click Done to save and exit the TV.
Adding the MIGX configuration
Once we've completed the above steps, our MIGX config will be available in the MIGX Management table. Now we need to grab the configuration JSON so we can add it to the Slider TV we created at the start of this article. Right-click the configuration line to bring up the context menu, then click on Export/Import, this will open a Pop-up containing your JSON. Click inside the textarea, select all content cmd+a and copy cmd+c then click Done.
Sorting through the JSON
Now you have your JSON you'll need to copy and paste it into the correct boxes. The easiest way to handle this next part is to paste the JSON you just copied into a code editor.
Open the Slider TV in your elements tab, then click on Input Options, in the Form Tabs textarea copy and paste all JSON code between the "formtabs": square brackets []. Do the same thing for the Grid Columns textarea below, copy and paste all content between "columns":square brackets [].
Here is the full JSON code you need to paste:
[
{
"MIGX_id":4,
"caption":"Slide",
"print_before_tabs":"0",
"fields":[
{
"MIGX_id":7,
"field":"slider_image",
"caption":"Image",
"description":"",
"description_is_code":"0",
"inputTV":"slider_image",
"inputTVtype":"image",
"validation":"",
"configs":"",
"restrictive_condition":"",
"display":"",
"sourceFrom":"config",
"sources":"",
"inputOptionValues":"",
"default":"",
"useDefaultIfEmpty":"0",
"pos":1
},
{
"MIGX_id":8,
"field":"slider_title",
"caption":"Title",
"description":"",
"description_is_code":"0",
"inputTV":"slider_title",
"inputTVtype":"text",
"validation":"",
"configs":"",
"restrictive_condition":"",
"display":"",
"sourceFrom":"config",
"sources":"",
"inputOptionValues":"",
"default":"",
"useDefaultIfEmpty":"0",
"pos":2
},
{
"MIGX_id":9,
"field":"slider_desc",
"caption":"Description",
"description":"",
"description_is_code":"0",
"inputTV":"slider_desc",
"inputTVtype":"richtext",
"validation":"",
"configs":"",
"restrictive_condition":"",
"display":"",
"sourceFrom":"config",
"sources":"",
"inputOptionValues":"",
"default":"",
"useDefaultIfEmpty":"0",
"pos":3
},
{
"MIGX_id":10,
"field":"slider_link",
"caption":"Link",
"description":"",
"description_is_code":"0",
"inputTV":"slider_link",
"inputTVtype":"url",
"validation":"",
"configs":"",
"restrictive_condition":"",
"display":"",
"sourceFrom":"config",
"sources":"",
"inputOptionValues":"",
"default":"",
"useDefaultIfEmpty":"0",
"pos":4
}
],
"pos":1
}
][
{
"MIGX_id":1,
"header":"Image",
"dataIndex":"slider_image",
"width":40,
"sortable":"false",
"show_in_grid":1,
"customrenderer":"",
"renderer":"this.renderImage",
"clickaction":"",
"selectorconfig":"",
"renderchunktpl":"",
"renderoptions":"",
"editor":""
},
{
"MIGX_id":2,
"header":"Title",
"dataIndex":"slider_title",
"width":20,
"sortable":"false",
"show_in_grid":1,
"customrenderer":"",
"renderer":"",
"clickaction":"",
"selectorconfig":"",
"renderchunktpl":"",
"renderoptions":"",
"editor":""
},
{
"MIGX_id":3,
"header":"Description",
"dataIndex":"slider_desc",
"width":80,
"sortable":"false",
"show_in_grid":1,
"customrenderer":"",
"renderer":"",
"clickaction":"",
"selectorconfig":"",
"renderchunktpl":"",
"renderoptions":"",
"editor":""
},
{
"MIGX_id":4,
"header":"Link",
"dataIndex":"slider_link",
"width":30,
"sortable":"false",
"show_in_grid":1,
"customrenderer":"",
"renderer":"",
"clickaction":"",
"selectorconfig":"",
"renderchunktpl":"",
"renderoptions":"",
"editor":""
}
]One final addition we like to make is customising the Add item button, to do this enter a value into the "Add Item" Replacement: input, i.e. Add new slide.
Make sure you save your changes when you have finished. The above may seem challenging to follow, but if you are still with me you've already done 70% of the work!
ADDING SLIDES
The fiddly part is now over! It's a bit easier from here on. Now your next step is to open the resource that will contain your image slider. For us, that's our Home resource as it uses the baseTemplate template that uses our Slider TV. When you open your resource and navigate to the Template Variables tab, you will see your Slider TV ready to be filled with content. To add a new slide click the Add new slide button, this will bring up a window containing the fields we created above. Go ahead and fill out the form then click Done when you are finished. Do this as many times as you like to add more slides, for the sake of this tutorial we've added two more slides.
Repeatable steps:
- Click Add New Slide to open TV modal window
- Fill out form fields
- Click Done to save
- Rinse and repeat (TIP: You can right-click your newly created slide and duplicate it, this brings up a modal window with the data already filled in, can make life much easier.)
- ALWAYS SAVE - Press the green button in the top right to save the resource
Displaying your slides in your resource
Depending on how you set up your templates and resources there are many ways in which to present your slides. In this article, we'll be adding the code directly to the resource (I don't recommend doing this for production websites/ websites that someone else will be authoring. Always make it as easy as possible to update/ add new content to your resources).
We use a snippet called getImageList to display our slides on the frontend, add the following details to the snippet:
To quickly test if your slider is working, copy and paste the following into your resource content, save it then View:
Note that we used inline code instead of a chunk for our template, I highly recommend that you use a chunk instead of inline as you can use additional snippets and chunks to make complex systems.
You should see now see your slides on your webpage.
CONCLUSION
If you master this method then creating new MIGX TVs becomes an absolute breeze, you no longer need to worry about formatting your JSON code, using the right key names etc. This method also opens up other areas of the MIGX extra for you to explore, we only used a small percentage while creating our image slider, MIGX can handle so much more! Just take some time to make mistakes! Get frustrated at things not working and learn from your mistakes. I hope you enjoy using MODX as much as I do.