Using Custom Objects and Custom Display Objects for Data Sources in Mura Form Builder

That title is a mouthful. And many might not be familiar with what it means. Check out this video to learn more about Mura's Form Builder, or you can go to this link which goes directly to the section of the video that I had an issue with.

In the video, Sean demonstrates the basics of creating a dropdown where you can manually enter the options for the dropdown. He does gloss over the fact that you can also get the data for the dropdown from other sources. Unfortunately, this is the extent of the currently existing documentation for this feature. So when I wanted to use this feature of the form builder to feed in data from another part of the site, I had to figure it out on my own. Here is what I came up with. Hopefully it is right(ish). Oh, you can also use this stuff to populate checkbox and radio button sets.

Populating a dropdown from a Mura Feed

Mura allows you to create feeds from data on the website. These are called Local Content Indexes. You can find instructions for that here.

I needed to populate a dropdown using a feed of content nodes from a set of Mura pages. So first I set up a Local Content Index that contained all of the content that I needed. This was simple and I posted the instructions above, so I am not going to cover it. The Content Index was named "Programs".

Next I needed to set up a means of getting the data from that feed into form builder. We can do that using a Custom Object, or a Custom Display Object.

Using a Custom Object

I opted to use a custom object for this, but I will also demonstrate how to do it using a custom display object, in the next section.

Custom objects for form builder datasources require a specific API. They are a component that contains the method getData(). The getData() method needs to return a struct that contains properties called datarecords and datarecordorder. datarecords needs to contain a struct with datarecordid, label, value, and isSelected. datarecordorder will contain an array that contains the datarecordids from the dataset in the order we want them to appear.

First, I created a new folder to hold my custom object. Since I plan to be able to do this more in the future, I created a folder under my site directory called datasets/. This is where I will keep all dataset objects that will be used to convert feeds into datasets for mura. I then created a programs.cfc file in there.

Now that we have the dataset available to Mura we can add it as a datasource to the form builder for the dropdown. Remember, it is called Program.cfc and it is in datasets/ in my site folder.

And that's it. Now, when we place the dropdown in a form, we should see it populated with the data from the feed.

Using a Custom Display Object

Using a custom display object works generally the same way. If you prefer, you can put the objects in with your other display objects instead of in a folder under your site directory as I did.

For example, here is an example of retrieving the same feed using a display object instead of a custom object (with the getFeed() method).

Then in my form builder, I would use a custom display object instead of a custom object and enter the path to the display object.

The path above is "/includes/themes/dctcTheme/display_objects/datasets/programs.cfm"

Remote Feeds

It is also possible to populate the data in a field in form builder using a remote feed. But i have not explored this yet. I suspect the feed itself must use a similar data structure, so this seems less useful. If I was going to use a remote feed, I would probably bring it in through a custom object and manipulate it from there.

Conclusion

The documentation for this feature of form builder is woefully inadequate. My contribution here is only marginally better. I know I am missing stuff (like using remote feeds) and i suspect I have some things wrong (like using a custom display object), but it is still better than what is out there and it may get some conversation started on how to do this stuff better.

In my experience so far with this, I see the Custom Object as a better solution than the custom display object. Which is why I think I have something wrong in the custom display object section. I mean, really, this is not a custom *display* object at all. It is not really displaying anything, it is just making a struct for something else to display. I don't really have any control over how things are rendered, unless I am doing something wrong.

Anyway, for now, i will keep using Custom Objects with the getData() method. It is clean, does not clutter my display_objects, and is easy enough.

Your comments, correction, improvements are welcome.

Comments
Grant Shepert's Gravatar Hey Jason, good job on this!

Unfortunate-timing wise, there is actually documentation forthcoming with the Mura CMS 6.1 release. It's never been a priority before as it is very niche and almost never comes up (I think once in the last two years).

As to how you did it, this is essentially correct. You are right that the custom display object doesn't let you control anything; it is there only as a 'simpler' method of allowing dynamic lists to be built for non-CF ninja types.

As to the data format, you can also use the dataRecordBean (/requirements/mura/formBuilder/dataRecordBean.cfc) instead of building it out manually.

In the documentation I'll be sure the Remote methodology is covered as well. This is essentially accomplished by returning a JSON object.
# Posted By Grant Shepert | 12/2/13 2:29 PM
Jason Dean's Gravatar @Grant,

Sweet! Glad to hear that docs are improving.

I like the DataRecordBean support. I will probably go update my production code and this blog post to reflect that method. I really display using structs as DTOs.
# Posted By Jason Dean | 12/2/13 3:14 PM
BlogCFC was created by Raymond Camden. This blog is running version 5.9.1. Contact Blog Owner