Advertisement
  1. Web Design
  2. CMS
Webdesign

Mura CMS: Custom Methods

by
Difficulty:AdvancedLength:LongLanguages:
This post is part of a series called Theme development with Mura CMS.
Mura CMS: Class Extensions
Mura CMS: Mura Scope
Sponsored Content

This sponsored post features a product relevant to our readers while meeting our editorial guidelines for being objective and educational.

Mura CMS gives you the ability to create your own custom functionality, directly from the theme level. This article will show you how you can enhance your themes by creating reusable custom methods that can be used in both layout templates and admin users.

Recap

When developing themes, you may have a series of 'objects' that you would like to display over and over again, such as slideshows, detail blocks, etc.

In the Class Extensions tutorial, we went over how to create custom attributes for a Book, and display them onto the page using a component. Here is the final component we created:

This worked well for our example, but there are a few drawbacks:

  1. The markup is open to admin editors who could potentially alter the markup, affecting its display.
  2. There is no logic around each item; if ISBN doesn't exist, for example, the label would still show with a blank value next to it. This would also happen if the user added this component to a page that isn't even a Book, in which case none of the extended attributes would show up.

One way we can solve these issues is to create a custom method in our theme that will display the book details whenever it's used. 

Creating a Custom Display Method

Display methods in Mura are located in a file called contentRenderer.cfc. Now, this file exists in two locations within your site:

  1. Site Level: {siteID}/includes/contentRenderer.cfc
  2. Theme Level: {siteID}includes/themes/{ThemeName}/contentRenderer.cfc

It's important to understand that both files will render methods in your site, however, theme level contentRenderer.cfc will append any methods that don't exist at the site level, and override any methods that already exist at the site level.

Another important thing to consider is that when doing theme development, any work done above the theme directory will not be distributed with your theme. If you're planning on creating themes for distribution, I recommend keeping all of your custom code at the theme level.

Adding to Your Theme’s contentRenderer.cfc

In your theme directory, open the contentRenderer.cfc file

Note: if you are building your theme from scratch and do not have the file already, go ahead and add the contentRenderer.cfc from the MuraBootstrap3 theme attached to this article. 

In this file, we’re going to create a new function called dspBookDetails

Now, whenever we call this function, Mura will execute anything inside of it. At the moment, there is nothing for Mura to do or display, until we specify that we want the function to return something. Let's add a variable to store our content for this function to return:

You can see now that we are creating a variable to store all of our content and logic (<cfsavecontent>), then telling the function to return that variable to the page (<cfreturn>).

Now we are ready to add the actual book content, similar to how we had in the component:

Note: we replaced the [m] tags with hashtags (#) because we're in a code file. [m] tags are only able to be used in the admin area editors. 

Calling the Function From a Component

Now that we have the function created in contentRenderer.cfc, we can call it using the Mura Scope. Go back to the component and replace the contents with the following line:

Note: We are wrapping the function in a <div> to prevent CKEditor from adding additional <p> tags around the output. Also, don't forget the parenthesis after calling the function ()

When you publish the component and reload the book page, you should see the book details identical to how you had it before:

Calling the Function From a Layout Template

In addition to calling the function from a component, you can also use your custom methods directly within your layout templates. For example, you can duplicate the twoCol_SR.cfm template, call it book.cfm, and add this to the right sidebar:

Adding Some Dynamic Logic

Now that we have the book details contained in a custom method, we can add some additional logic to make our output a bit more robust. First, let's wrap the entire contents of the function to detect whether or not the page in question is actually a book. If not, then it will return nothing.

The next thing we want to do is detect whether a value actually exists for each item we're displaying (Author, ISBN, etc). If the value does not exist, we want to skip the item and move on to the next line.

We can accomplish this by wrapping an if statement around each line, seeing if there is a length of the value greater than 0:

Wrap each book detail item in the code above, replacing the $.content() values with the appropriate values for each item:

Conclusion

Creating custom methods is a great way to add versatility to your themes, as well as maintaining the integrity of your code.

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.