Published on September 30, 2014
Product listings, blog posts, news releases, white papers – these are just some of the custom "content types" that a typical site owner needs to manage. With Collections, MODX lets you easily customize admin views, with powerful options and all the flexibility you expect from MODX Revolution.
In this post, we'll take a deep dive into how to use Collections, how to quickly and easily set up customized views, and how to configure your own custom renderer for an image field (TV).
What is "Collections"?
For the uninitiated, Collections is an "Extra" (a piece of software that extends core functionality) for the MODX Revolution CMS. You can download and install it via the "Extras » Installer" main menu item in the Manager (MODX's admin interface.) Note: the screenshots and instructions in this post will be based on the latest version of MODX 2.3.1. Previous versions differ slightly.
You can also download Collections directly from the MODX Extras Repo. The official documentation for Collections can be found here. Collections is open source. Feedback, issues, bug reports, and contributions are welcome and encouraged: Collections Github repo.
Collections started out with a simple goal: to provide an alternate UI for managing Resources (versus the traditional MODX Tree view) and to improve performance in the Manager. With the release of version 2.2.0 however, Collections is maturing into one of the most useful and powerful Extras available.
How do I use it?
The documentation will help new users get started, but to summarize: all you need to do, in order to turn a standard MODX document into a Collection, is to change the Resource Type in the Settings tab of any Resource.
The fun really begins when you go to the Custom Manager Page (CMP). In the Manager, under the main menu item "Extras", select "Collection views".
There you will see a list of configured Views. If you haven't any customized views, it would only show the Default.
Click on the "Add View" button to create a new view.
Let's review each setting:
- Page size: default number of items to show per page in the grid. Can still be modified by the user.
- Sort field: the field by which to sort the grid. Can be a TV, using the TV name prefixed by 'tv_', or Tagger group prefixed by 'tagger_'.
- Sort direction: ascending or descending. Can still be modified by the user.
- Allow bulk actions: enabled, this provides the "Bulk Actions" button (see figure below.)
- Allow drag & drop: enabled, this allows drag n drop positioning of Resources listed in the grid.
- Resource type selection: enabled, this shows a dropdown next to the "Add Child" button to select Resource type (see figure below.)
- Tab's label: custom text for the "Children" tab (see figure below.)
- New child's button label: custom text for the "Add Child" button (see figure below.)
- Content's place: place the content field for the Collection Resource. You most likely don't want the content field visible beneath the grid, and you may want to remove it entirely, seeing as the child Resources are generally the ones with user-editable content.
In addition to the above grid settings, you can also set some defaults for when new child Resources are created:
Once you've saved the View (the "Save" button is at the top right) you'll see an area below where you can add columns to your grid view:
We'll go over adding columns below in the section on custom renderers.
Examples of Custom Collection Views
Here's an example of what the final, customized grid view may look like for a list of products:
...and another one for a blog:
Image and other Custom Renderers
Collections is bundled with a handful of the most-used renderers, with which to display values in the grid. As of Collections version 2.2.0, an image renderer has been added. By default, it prefixes the MODX 'base_url' system setting to the raw TV value. This may not be what you need. Fortunately, Collections author John Peca has built-in an easy way for you to add custom renderers.
The documentation has links to resources on how to build your own custom renderers, but we'll summarize it below.
- You can optionally create a custom system setting here to specify the 'base_url' for your image TV (see figure below.)
- Create the JS file at the specified location on your server. When a Collections grid view is rendered, the JS file will be included.
The contents of your JS file will be something like this, for an image renderer:
- First we define a function, with the name 'myimagerenderer' (the name can be whatever you want, obviously.)
- Collections will pass, as the first argument to this function, the raw value of the TV. We'll check to see if there's anything there.
- We set the 'baseUrl' variable with the value from our custom System Setting (shown above.) As you can see, all the System Settings in this MODX install are available as child object of the 'MODx.config' object. You could just as easily use 'MODx.config.whatever_system_setting'.
- We check the value to see if it starts with 'http://', and if it does, we won't prefix the 'baseUrl'. Note: if you expect your TV values to contain image links with 'https://', you should test for that as well.
- Finally, on line '7', we return a bit of HTML, with the 'baseUrl' prepended to the TV value.
In the Collections CMP
Previously we skipped over the process for adding columns to your grid view. Let's look at that now. By default, some of the standard MODX Resource fields are included, but you may want to check the documentation on how to add renderers and editors for specific fields like TVs and Tagger tags.
In the CMP, when you're updating a Collection view, click on the "Add column" button. This is where you specify the display/behaviour of grid columns. To add the custom image renderer, enter the name of the JS function in the 'renderer' field. In this case, it was 'myimagerenderer'.
- Label: this is what users will see in the grid view.
- Name: this is the name of the field. If it's a TV, prefix with 'tv_'.
- Renderer: this is where your function name goes.
- Width: specify a default width for the column. This and other fields are optional.
Other custom renderers
Image renderers aren't the only kinds of custom renderers – you can define JS functions to render almost anything you want. Here's an example of one that renders Unix timestamps:
Putting it all together...
With all these configurable options – what fields to show in the grid, which to sort by, how to render the values in those fields, and customizable text labels – the possibilities are endless. You can make a Collection view that does exactly what you or your clients need. We've had great feedback on Collections so far – but what about you? Have you had a chance to use it? What do your clients say about Collections and the new MODX UI? Please comment and let us know.