tutorials

Collections: Customizable Views for Content Types

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 Basics

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.

Collections Resource Type

The CMP

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

Collection Views menu item

There you will see a list of configured Views. If you haven't any customized views, it would only show the Default.

Collection Views menu item

Click on the "Add View" button to create a new view.

Collection Views menu item

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.

Collections View Options
Collections View Options in Action

In addition to the above grid settings, you can also set some defaults for when new child Resources are created:

Collection Views menu item

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:

Collection Views Edit Columns

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:

Example Collection Grid View

...and another one for a blog:

Example Collection Grid View

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.

Settings and your custom Javascript file
  1. In the Manager, go to the "System Settings" area, and filter on the namespace "Collections". In the setting 'collections.user.js', enter the url of a Javascript file that will contain the JS code for the renderer (see figure below.)
  2. You can optionally create a custom system setting here to specify the 'base_url' for your image TV (see figure below.)
  3. Create the JS file at the specified location on your server. When a Collections grid view is rendered, the JS file will be included.

Collections View Options
Collections System Settings

The contents of your JS file will be something like this, for an image renderer:

  1. First we define a function, with the name 'myimagerenderer' (the name can be whatever you want, obviously.)
  2. 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.
  3. 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'.
  4. 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.
  5. 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'.

Collection Views menu item

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

Hi. We’re MODX.

We’re here to help you fix, build and grow fantastic sites. How can we help?




How can we help?

Tell us the general reason for reaching out so we can connect you with the right team.

MODX Diagnostics

MODX’s Open Source software is 100% free for anyone to download and use. As the team behind it for more than a decade, we know it inside, out, and then some.

Like any software, sometimes things break; we can usually fix them very fast. But, we do have to charge for our time to support our families and fund its ongoing development. There are almost an unlimited variety of things that can cause problems, including server upgrades, corrupt files, accidental changes, outdated software, database hiccups and more. We will save you a lot of time and frustration, and get you back in action.

With our MODX Diagnostic service, we determine the source of issues, and often fix them on the spot. For more extensive problems needing more time, like hacked sites or overdue upgrades, we provide additional estimates and guidance. MODX Diagnostics cost $99 for standard business hours support (US Central Time), or $500 for priority, rush or after-hours emergencies.

If you don’t have budget for professional support from the source, you look for answers in the MODX Forums or Documentation, or seek help from MODXers in the Community Slack, or from MODX Professionals near you.

  I’m not ready to pay, let’s talk…

After submitting this form and completing payment, we will collect your access credentials in a secure support ticket. We look forward to helping restore your site back to full health.

Hi! We’d love to work together.

If you have a simple problem that needs our assistance, please request quick fix help here.

What should we keep in mind?

The project involves:
(select all that apply)
What are you planning?
(select all that apply)

Some other considerations

Specific project information

Commercial Support Customers

Customers with a current Commercial Support agreeement can get help using this form. Learn more about MODX Preferred Support.

Let’s get started

What seems to be the issue?

Contact MODX

We welcome conversations, ideas, inquiries and even the occassional cold sales call, but support and requests about how to use MODX software sent via this form cannot be guaranteed a response. That said, we try to respond to everyone that reaches out to us within two business days.

To report a security issue or file a bug for MODX software, please email security [at] modx.com to reach our security team. If you are looking for help with MODX, many times you can find an answer in the MODX Forums or MODX Documentation, from MODXers in realtime at the MODX Community Slack Channel, or from a MODX Professional near you.

How can we help?