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 Actions panel on the left, right click on MIGX category and click on Create Action Here.

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.

Once in the MIGX Management Page, click on Setup/Upgrade tab and the click on the Setup button to complete the MIGX installation.

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:

                  [
                      {"caption":"Image Properties", "fields": [
                      {"field":"name","caption":"Name","inputTVtype":"text"},
                      {"field":"image","caption":"Image","inputTVtype":"image"}
                      ]}
                  ]
              

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:

[
                      {"header": "Name", "width": "160", "sortable": "true", "dataIndex": "name"},
                      {"header": "Image", "width": "50", "sortable": "false", "dataIndex": "image","renderer":"this.renderImage"}
                  ]
              

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.

<ul>
      [[!getImageList?
      &tvname=`myMIGXtv`
      &tpl=`@CODE:<li><img src="[[+image]]" alt="[[+name]]"/></li>`]]
      </ul>
      

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.

Make sure to check out the official MIGX documentation and some of the tutorials that will help you get a better understanding of MIGX.

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!