MIGX
Fun with MIGX
MIGX is a custom TV management system that adds a whole new dimension to building MODx sites.
Official documentation here. Another tutorial here.
Many years ago I worked with a web designer who was designing sites for a number of small businesses, hotels, wineries and restaurants in his area. He needed a basic system for managing restaurant menus, wine lists, and other lists of images with titles and descriptions, often with links to pages with more detail. While using resources and Ditto (this was in the Evolution days) would work, it was very awkward for the client, as well as more difficult to set up in the first place. We ended up using a modified version of Evo's commenting system, Jot, which I called Notes. It was used on a dedicated page for the client to manage his lists, such as menus. It was a little clunky, but it worked well.
Then the designer switched to Revo, while I stayed with Evo for some years more, and things got a lot more complicated for him. The results was a consultation with Bruno Perner (bruno17) to develop a custom TV for managing an arbitrary number of images along with title and description and other meta-data. And MIGX was born. But it's grown a lot since then, and is definitely not just for simple image lists any more!
The MIGX package provides:
- Included snippets - listing snippets and useful utility snippets
- MIGXdb - using custom tables in the database for TVs and CMPs
- Galleries - different ways to use MIGX and MIGXdb to manage galleries
- Calendars - using MIGXdb to handle event calendars
- Custom Manager Pages - take the pain out of CMPs using MIGX
- MIGXMultiLang - manage multiple languages from a single resource
Image Galleries
In our demo site development, using the It Fits free template, the Home page template has a row of three images. These images in the demo were taken at random from the pageThumb TV images of all of the resources. Let us suppose that that row of images is for displaying images from a single page, for example a Portfolio page. Instead of getting three images at random from all pages, we need to be able to get images from just that one Portfolio page. So we need a gallery to hold the images for that page, as well as a title and some text that goes with each image. MIGX was designed to do exactly that; in fact the MIGX documentation provides a perfect example of this very common requirement.
We'll create a new TV and call it HomeBlocks. From the Input Options tab, we use the Input Type drop-down to select "migx". MIGX automatically added this type during its installation. Now several new fields will appear.
MIGX TVs consist of two visible parts, the Form Tabs and the Grid Columns. The Form Tabs section supplies the forms for the TV's data, and the Grid Columns configures the grid display in the resource's TVs tab.
For the Form Tabs field, we'll simply copy and paste the JSON from the MIGX documentation. The documentation has an extensive explanation of what each line means.
[{ "caption": "Info", "fields": [{ "field": "title", "caption": "Title" }, <br>{ "field": "description", "caption": "Description", "inputTVtype": "richtext" } ] }, <br>{ "caption": "Image", "fields": [{ "field": "image", "caption": "Image", "inputTVtype": "image" }] } ]
If you create a Media Source to limit the location of images for this TV, you need to add that to the field specification...
{"field":"image","caption":"Image","inputTVtype":"image","sourceFrom":"sourcename"}
Next, we need to copy and paste the JSON contents of the Grid Columns from the documentation.
[ { "header": "Title", "width": "160", "sortable": "true", "dataIndex": "title" }, <br>{ "header": "Image", "width": "50", "sortable": "false", "dataIndex": "image", "renderer": "this.renderImage" }]
We can leave the rest of the new fields alone, although it adds a nice touch to customize the "Add Item" button, so let's put "Add Block" in that field.
That takes care of the Input Optons tab. Now open the Template Access tab, and check the template you want this TV to be attached to for editing purposes. Only resources using that TV will get the homeBlocks TV. Since these blocks are part of the Home page, it makes sense to only assign it to the Home template.
And if youre using a Media Source, assign the TV to your Media Source in the Media Sources tab. Our new MIGX TV will now use that source for its image field.
Adding Blocks
Now when you edit the Home page, you'll find this TV in its Template Variables tab. You'll see the grid, with the Add Block button. When you click that button, the MIGX forms will pop up. As you add images and their titles and descriptions, they'll appear in the grid. Right-click on them to edit or remove them. Drag them up and down to put them in the order you want them to appear on the page.
The Output
MIGX supplies a snippet to output this list of items. In spite of its name, an artifact of its earliest purpose, the items can be anything, links to files for download, images, text, it will all get listed from this snippet. It needs to be told what TV to use, and a tpl for formatting each item. If you call the snippet without a tpl, it will list all of the fields in the TV's output for each and every item. Seeing that listing when you don't expect it is a good way to know that you need to check the name of your tpl chunk!
[[getImageList?<br> &tvname=`homeBlocks`<br> &tpl=`homeBlocksTpl`<br>]]
The homeBlocksTpl chunk will contain the HTML layout that It Fits expects for each image block in the row. MIGX, as do most lising snippets, provides placeholders with the content of each item in its list of objects returned from the database. So our tpl chunk needs to look like this to make It Fits happy:
<article><br> <figure><br> <img src="[[+tv.homeBlocks:pthumb=`w=300&h=200&zc=1`]]" alt="[[+pagetitle]]"><br> <figcaption><br> <h3>[[+pagetitle]]</h3><br> <p>[[+longtitle]]</p><br> </figcaption><br> </figure><br></article>
This output tpl can easily be modified to fit any template or script requirement. For example, to animate and scroll the row of images, you only need to add the structural elements, classnames, and other attributes the script needs to style and activate the blocks.
A standard MIGX TV, like this one, stores everything in one JSON string in the same database tables as all ordinary TVs with one field for its resource's ID and one field for its content, in this case entire JSON string. This can get quite large and unwieldy, if, for example, you have a lot of images along with their titles and descriptions for a given page. That is where MIGXdb comes into play. It can create custom tables to hold the information, with a row in the table for each item with fields for its resource's ID, image path, title and description. So whether to use a simple MIGX TV with everything crammed into one JSON string for that resource's TV, or use a custom table and MIGXdb all depends on what you want to do, and how many items you're likely to end up with. There are several excellent tutorials in the MIGXdb documentation for using MIGXdb.