Backend-Usage

Backend-Usage¶

How the MIGX Custom Template Variable (TV) Works¶

The MIGX TV allows you to store complex data items as one TV. These data items are stored as JSON. This documentation page assumes that you have a working knowledge of JSON.

Each complex data item can have multiple fields associated with it. These fields can be (almost) any standard or custom MODX TV input type. These data items are defined in the "Form Tabs" field. Items can be sorted by tabs as defined by the JSON.

Creating your first MIGX TV¶

Sample MIGX configurations are stored under /core/components/migx/examples/. We will be referring to "tabs.txt" for this documentation page. This documentation page assumes that you have the add-on TinyMCE installed.

tabs.txt shows a sample implementation of a simple image gallery. The image gallery will consist of one complex data item that uses one richtext field (an image description), one image field (the image itself), and a short string (a caption). This short string will not be stored in a separate TV.

"Helper" TVs still work but are no longer needed; use inputTVtype: instead of inputTV:

Step 1: Create the MIGX aggregate TV¶

• fill in a name, caption, description, and category as you would for any other TV
• give the template access for which you would like to add data items. In this example, perhaps "Gallery"
• select MIGX as the input type

Step 2: Configure the MIGX input type¶

For your first MIGX TV, we are only concerned with two textarea fields: "Form Tabs" and "Grid Columns"

Step 2.1 Form Tabs¶

The Form Tabs define the structure that end users will use to input their data.

Content of tabs.txt:

[{
    "caption": "Info",
    "fields": [{
        "field": "title",
        "caption": "Title"
      },
      {
        "field": "description",
        "caption": "Description",
        "inputTVtype": "richtext"
      }
    ]
  },
  {
    "caption": "Image",
    "fields": [{
      "field": "image",
      "caption": "Image",
      "inputTVtype": "image"
    }]
  }
]

That's a lot of JSON -- let's break it down. The first key you see is entitled "Caption". This refers to the name of the first tab. The tab will be labeled "Info".

The second key you see is entitled "fields". This refers to each of the fields that will be accessible from that tab. The fields are stored as a nested JSON string. Let's break these down.

The first key within the nested JSON string is entitled "field". This refers to the placeholder that MIGX will generate that we will access later with getImageList. For the first item, we have labeled it "title". This refers to the short string mentioned above. The second key is labeled "caption". This refers to the label that the end user will see when they're filling in a data item. Let's label it "Title" so that our users know they're filling in the title of the image.

The second key within the nested JSON string is entitled "description". We have three keys this time: the first, "field", refers to the placeholder that we will access later. The second, "caption", is the label the user will see. The third, "inputTVtype", refers to the type of field that we want to use.

We're done with the first nested JSON string. We can now see that there is a second tab -- this one has a label of "Image" and specified an inputTVtype of "image". To specify a Media Source for the image, add another key "sourceFrom":"migx" and assign the MIGx TV to a media source using the TV's Media Sources tab.

We are now halfway done with our first MIGX TV. We have now created the form for each of the individual data items. The keys for each field are listed below in a table for your viewing convenience. Let's now define the summary view of the data items using Grid Columns in Step 3.2

Step 2.2 Grid Columns¶

In the grid columns, we're specifying the summary view that users will see to view their information.

Content of columns.txt:

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

Here is some more JSON for us to tackle! This JSON shows the caption of the image as well as a preview of it. Let's break it down.

The first key, "header", refers to the header label that will be used to categorize the fourth key, "dataIndex". The dataIndex refers to the placeholder that we've specified above in the form tabs. The first entry here uses the dataIndex we specified above of "title". We also have two more keys: width and sortable. The width defines the relative width of the column, and sortable defines whether the grid is sortable by that column.

The second entry has a fifth key: renderer. This key allows us to render a view of the image here.

We're now done specifying our first MIGX TV. Feels great, right? Make sure you click save.

Don't forget to save your Resource after adding or editing MIGX items!

We're now half done our MIGX experience. Next step: Data Entry

The keys for this grid are listed here:

Advanced MIGX Configuration¶

Multiple Forms¶

Content of switchFormTabs.txt

[
  [{
    "formname": "image_description",
    "formtabs": [{
        "caption": "Info",
        "fields": [{
            "field": "title",
            "caption": "Title"
          },
          {
            "field": "tpl",
            "caption": "Tpl",
            "inputTV": "tplDropdown"
          }, {
            "field": "description",
            "caption": "Description",
            "inputTV": "richtext"
          }
        ]
      },
      {
        "caption": "Image",
        "fields": [{
          "field": "image",
          "caption": "Image",
          "inputTV": "image"
        }]
      }
    ]
  }, {
    "formname": "textonly",
    "formtabs": [{
      "caption": "Info",
      "fields": [{
          "field": "title",
          "caption": "Title"
        },
        {
          "field": "tpl",
          "caption": "Tpl",
          "inputTV": "tplDropdown"
        }, {
          "field": "description",
          "caption": "Description",
          "inputTV": "richtext"
        }
      ]
    }]
  }]
]

here we have an additional outer array with two keys.

when using multiple forms this will produce an additional field with name 'MIGX_formname'. You can use the value of this field to switch tpls in the frontend by using &tpl=`@FIELD:MIGX_formname` and create chunks with the same names as your formnames or you can add an additional field (listbox-TV with name tpl for example) to choose the output-tpl for this item.

Preview Feature¶

MIGX has a preview featured that allows you to see rendered output of items in an iframe window. In order to use this preview feature, you need to create a preview resource. This resource should have content like:

[[!getImageList? &tpl=`@FIELD:MIGX_formname`&tvname=`multiitemsgridTv`]]
[[!getImageList? &tvname=`multiitemsgridTv2`]]

If you have multiple calls on the preview resource you will also need unique values for each TV in 'Preview JsonVarKey' - default is 'migx_outputvalue'

Once you have filled out the field 'Preview Url' you will have an additional button 'Preview' on your MIGX-TV, which shows the preview window with content of your preview resource.

Inline Editor¶

To edit fields directly within the MIGX grid, simply add "editor": "this.textEditor" or "editor": "this.listboxEditor" to the Grid Columns JSON of the field you wish to make editable:

{"header": "Title", "width": "160", "sortable": "true", "dataIndex": "title", "editor": "this.textEditor"}