MIGX

In this tutorial, I’m going to be writing about MIGX, a fantastic MODX extra developed by the talented Bruno Perner
(Bruno17 on the MODX forums). This extra can help you create a wide range of objects, from a table with each
row specifically defined, to a complex product catalog with images, prices and product descriptions. To see a
real-world MIGX example, simply look to the image sliders and images that I use on this and my other blog posts
on this site. The possibilities are really endless, and you can create some truly cool things using MIGX. Although
the learning curve is slightly steep, it’s worth it – you’ll thank me later.

What is MIGX?

MIGX is a custom Template Variable (TV) input type for aggregating multiple TVs into one TV. This aggregation greatly
simplifies the workflow for end users of the manager to add complex data items to the manager. A data item can
consist of any number of any other TVs, including text, images, files, check boxes, etc.

The package is highly customizable and allows the developer to define a custom input window for the MIGX TV. From
this input window, items can be added, modified, and reordered.

The package also ships with a snippet (getImageList) that facilitates the easy retrieval of the complex data items
from the custom MIGX TV input type. MIGX stands for MultiItemsGridtv for MODX.

Installation Instructions

Unlike other MODX extras MIGX, needs to be setup and configured after you install it via the Package Manager. Here’s
how we do it:

Go to System menu in the Manager and click on Actions.

In the Create Action popup, you have 3 fields: Controller, Namespace and Parent Controller. In Controller, type “index”;
in Namespace, select “MIGX”; and, in the Parent Controller, select “No Action” and then click Save.

In the Top Menu panel on the right, right click on Components and select Place Action Here.

This will open the Create Menu. In the Lexicon Key, type “migx”; in the Description field, type “Configurator and
Package Manager”; in Action, select “index”; in Parameters, type “&configs=packagemanager||migxconfigs||setup”;
and, finally, click Save. The remaining fields can remain empty.

Refresh the page and you will now have a Components menu option in the Managers top menu. Hover over it and you will
have a MIGX entry in the drop down. Click on it to go to the MIGX Management Page.

Now that we have MIGX set up, let’s have some fun with it.

How to use MIGX

In order to use MIGX in the MODX manager, we need to create a Template Variable. In the General Information tab,
put your Template Variables name, the caption you wish to use for it, and a description and put it in a category
(optional).

Next, click on the Input Options tab. For the Input Type, select migx. The input option values, default values, and
configurations options can be left empty (unless you want to specify any default values, etc.) What we’re primarily
interested in is the Form Tabs and Grid Columns.

The Form Tabs field lets us configure what our MIGX pop up window looks like when entering values. Let’s paste the
following code into the Forms Tab and see how it works:

Let’s explain what’s going on here. First, we’re creating a JSON array with an object whose key is Caption and whose
value is Image Properties. “Image Properties” will be the text displayed on our MIGX TV tab and can be whatever
you choose. Next, we’re telling it that this tab will have some fields inside of it by creating another JSON
array which contains two JSON objects.

The first key is “field” and it’s value is “name”. The next key is “caption” with a value of “Name”. Lastly, we have
a third key, “inputTVtype”, with a value of text. The last option is what lets MIGX know what type of Template
Variable we want to use for this specific field. In this case, we’re telling it to use a text Template Variable,
although this can be any of the
MODX Template Variable Input Types

The next JSON object has a key “field” with a value of “image”, “caption” key with “Image” as the text to be displayed
as the label for this TV, and, lastly, the third key “inputTVtype”, whose value is “image” to indicate to MIGX
that we are using an image TV.

The Grid Columns field is how we control how our MIGX TV displays in the manager. It lets us configure the labels
for our table that will display the values of our MIGX entries. Paste the following code and let’s explain what
it’s doing:

As you can see, we’re creating another JSON array with two objects and a few properties. The first key, “header”,
is what label our table’s first column will use. The next key lets us pass the width we want for this column.
The next key, “sortable”, tells MODX that we can sort by this field. The “dataIndex” key tells MODX which value
it will display from our Forms Tab. It’s very important that the dataIndex matches the field name you use for
each object in order for it to render the correct value.

The second JSON object follows the same structure with a few differences. Mainly, the “dataIndex” has now changed
to image and there’s an extra property, “renderer”, which lets the MODX manager know to render an image as a
thumbnail.

The last step before we can proceed is to click on the Template Access tab and select which template will have access
to the MIGX TV we just created.

Entering data in MIGX

Now that we configured what MIGX will render and how we want it to look in the Manager, let’s proceed to enter some
values to see how MIGX works in the MODX Manager. Create a New Resource with the template we gave access to use
our MIGX TV. Click on the Template Variables tab. You should see a Label with “Image Properties” with an Add
Item button and an empty table with the headers we used in our Grid Columns fields.

When you click on the Add Item button, the MIGX pop up window opens up with the Tab and the fields we configured
in our Forms Tabs. Proceed to enter a name for the image and then click on the image select field. This will
open the MODX browser which will let us select an existing image or upload a new one. Click on Done and watch
our table update with the text we just entered and the image we selected.

MIGX on the Front End

We already know how to use MIGX in the Manager. Now, let’s see how we can use it on our site. MIGX comes with a snippet
called getImageList which is used to format our MIGX TVs output. A helpful tip from the MODX documentation on
MIGX is to treat getImageList like the ever-popular snippet,
getResources

With that said, let’s learn how we can use getImageList. Lets output our MIGX TVs to an unordered list using getImageList.
We’re going to use the following code and discuss below what’s happening here.

As you can see, we are wrapping our getImageList call with a “ul” tag. From there, we have our getImageList which
is being called uncached with 2 parameters. The first parameter, &tvname, is where we tell getImageList the name
of our MIGX TV. The second parameter, &tpl, is an inline template which will wrap each MIGX TV with a “li” tag
and an image tag. This image tag uses our MIGX TV image as the source and the MIGX TV name as the alt text for
our image.

getImageList has many more parameters that will allow you to accomplish more amazing things. It’s possible to use
MIGX with getResources, use chunks as tpls, or even use phpthumbof to generate thumbnails on the fly. There are
many possibilities, so feel free to play with it and explore the many things you can do with MIGX. Remember,
if you get stuck, just head over to the
MIGX section of the
MODX Forums and a community member or Bruno himself will help you with your MIGX related questions.

I hope this review helps you understand what you can accomplish with MIGX or if you’ve never heard of it you will
give it a try it’s a fantastic MODX Extra. Thanks for reading!

Benjamin Marte

Benjamin Marte is a Front End Developer with more than 10 years of experience creating interactive multimedia
experiences both online and offline. He currently works as a Senior Front End Developer at
Wolters Kluwer. He’s the creator of CMSTricks where he blogs about the MODX Content Management System
and tweets with a focus on MODX and Web Development under the handle
@benmarte

Comments (8)

MIGX… so what does it stand for again… :)
This one looks very detailed, but me-being-me and I wonder right away, where did you get your setup
values, or would somebody else want to change those… controller, Namespace, and Parent controller
sort of make my head hurt right away, but also let’s me know this is one powerful programmer coding
tool, probably simpler than it starts out, but definitely a big boy tool of MODX.

Anyways thanks for the in-depth look at this add-on, that will help other designer/devs to knock
their next MODX project out-of-the-park!

I am a beginner to modx and after reading a bunch of tuts. I becam somewhat lost in them.
May I ask what method would be best for a small comany website, particularly for the portfolio section.
In that I would like to have sub categories like webdesign, print desing etc. Each would have the
completed projects in them (with some text and photos for each) one after another. But only one photo
displaying (shadowbox).
Now I have all this working already but with a pure php +html form and no cms.
What I would like is to be able to recreate this so that it would be easier to maintain with modx.

Is there a way I can manage for example the portfolio part with ease with modx? Would MIGX be good
for this?

Here is what I would like to generate, a portfolio item with multiple photos and text, and a photo
counter.

@Csaba There are many different ways to accomplish this in MODX you can use Articles or getResources
with MIGX, Template Variables or Gallery extras.

If you need to create some sort of gallery per page I would highly recommend you use MIGX as it
gives you more customization options than any other gallery extra out there and it would work perfectly
for your portfolio item with multiple images.

@Benjamin Marte - Brilliant tutorial!! (…and site by the way!) Been using Modx for a few years now
and been aware of Migx but all other tutorials I have seen have been a lot more complicated and I
have slacked off taking the time to learn how to implement Migx. I can already see the advantages
it can bring.

Note there is a typo in the code above though under the “MIGX on the Front End” section the line
of code that starts (the rest of the code was getting stripped by your comment sanitiser)

&tpl=`@CODE:

is missing the closing
` ‘back tick’ character I believe it is called and the result is the getImageList snippet
spits out a raw plain text array rather than the formatted
< li> row.

Out of curiosity is there a way you can insert dynamic options into the Migx manager table -
ie from an array of other resources. Real world example I have a conference with sessions. Session
is an document/resource and I would like to have a list of speakers (an existing group of other
resources) with tick boxes next to them so my manager users can select who will be speaking at
the session.

Any tips on achieving this (…or possibly another “Advanced Migx tutorial” ;-)

@Megasteve4 thanks for letting me know about the typo ill get it fixed ASAP as for your MIGX question
you can probably use getResources as part of your MIGX tpl to achieve what you need I suggest you
post in the MIGX forum so Bruno can answer your question.