MIGX

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.

System > Actions

In the Actions panel on the left, right click on MIGX category and click on Create Action Here.

Create Action

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.

Create Action Pop Up

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

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.

Create Menu Pop Up

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.

Components > MIGX

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

MIGX Setup/Upgrade

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).

MIGX Template Variable

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.

MIGX Template Variable Input Options

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.

MIGX TV Template Access

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.

Template Variable Tab with MIGX Table

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 Table with Populated Data

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!

24 Oct
2012

Author Benjamin Marte Category Reviews Comments (8)

Comments (8)

  1. Bruno:
    Nov 01, 2012 at 03:26 AM

    Great Tutorial!
    Thanks for sharing this!

  2. Crssp:
    Nov 05, 2012 at 05:30 PM

    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!

  3. Keith Penton:
    Nov 12, 2012 at 06:40 AM

    Thanks for this straightforward and to-the-point tutorial. I'm just exploring Revo using a beta cloud account, and wanted to find out what MIGX is all about. This has been of great help to me.
    KP

  4. Csaba:
    Nov 14, 2012 at 04:23 PM

    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.

    Many thanks


    TypoZoo

    www.typozoo.com
    A website for TypoZoo blah blah...




    1 of 1




    Design
    CSS/(X)HTML
    Programming







  5. Benjamin Marte:
    Dec 13, 2012 at 08:20 AM

    @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.

    Good luck

  6. megasteve4:
    Feb 19, 2013 at 07:02 PM

    @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" ;-)

    Thanks.

  7. Benjamin Marte:
    Feb 19, 2013 at 08:08 PM

    @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.

    MIGX forum: http://forums.modx.com/board?board=271

  8. Oliver Haase-Lobinger / mindeffects:
    Mar 24, 2013 at 05:46 PM

    Nice tutorial! Thanks! You might want to add, that the setting up as a component it not mandatory if you just want to use MIGX. With MIGXdb this is different.


Leave a Comment

This thread has been closed from taking new comments.

Scroll to top