Adventures in Mura — Customizing a Site

Mura has a lot of interesting capabilities. However, the documentation is a little sparse.

Recently, I have been customizing a Mura site, so I thought I’d document some of the key things you need to know!

1 – Create a New Site to Customize

When initially installed, Mura automatically creates the  “Default” site. But, don’t customize this site. Make a new site and customize it. This way, you can still do Mura updates without overwriting your customizations.

  • Login to your admin area
  • Go to Site Settings -> Add New Site. (Site Settings is in the upper right of the admin screen.)
  • Name the site whatever you want. For example, you might call it MySite.
  • Now, when you go to customize things, don’t look in the Default folder. Instead find the MySite folder.
  • If you want MySite to come up automatically when you go to, click on Site Settings. Then, use the Order drop downs to set MySite to 1.

2 – Customize /MySite/includes/

Much of what you’ll want to customize is in the /MySite/Includes/ directory. Here are some things you might want to customize:

  • If you are using a theme like Merced, customize the style sheet at /MySite/includes/themes/merced/css/site.css. It’s a good idea not to change the other style sheets. Just override the style in site.css. More Info from Mura …
  • Again, if you’re using Merced or another theme, customize the templates at /MySite/includes/themes/merced/templates/.  Don’t forget to look in the /inc folder for the header and footer includes. More Info from Mura …

3 – Change the behavior of Display Objects

You can change how the Display Objects work! For many Display Objects, you can just copy the display object, put it in /MySite/includes/display_objects/custom/ and modify your copy. I wanted to add a download link to the images in the image gallery, so it was more complicated. Matt Levine of Mura advised me to:

  • Go get /MySite/includes/eventHandler.cfc and add a new onGalleryBodyRender function (See below).
  • Create a new directory named gallery at /MySite/includes/display_objects/custom/gallery. Into this new directory, copy index.cfm from /default/includes/display_objects/gallery/index.cfm. Now we have a copy of the gallery file to customize, so customize your heart out!
  • Stay in /gallery/index.cfm. Find the references to getSite() and queryPermFilter() method calls. Change these to renderer.getSite() and renderer.queryPermFilter().
  • Still in /gallery/index.cfm, change the template path in <cfinclude template=”../dsp_nextN.cfm”>. The new path should be ../../../dsp_nextN.cfm.
  • Reload the app either by clicking Reload Application in the admin, or adding ?appreload to the end of the url. A lot of the objects are loaded when the application starts, so I found it’s a good idea to reload after making changes.

Here’s the code for the updated eventHandler.cfc:

<cffunction name="onGalleryBodyRender" output="true" returntype="void">
<cfargument name="event">
<cfset var renderer=event.getContentRenderer()>
<cfset renderer.loadShadowBoxJS() />
<cfset renderer.addToHTMLHeadQueue("custom/gallery/htmlhead/gallery.cfm")>
<cfif not event.valueExists('galleryItemID')><cfset event.setValue('galleryItemID','')></cfif>

<!--- When you override default output you need to run content throught the renderer.setDynamicContent() method to process [mura] tag calls--->

<!--- Now include the customized display object --->
<cf_CacheOMatic key="portalBody#event.getValue('contentBean').getcontentID()##event.getValue('startRow')##event.getValue('galleryItemID')#" nocache="#event.getValue('r').restrict#">
<cfinclude template="display_objects/custom/gallery/index.cfm">


I hope this helps someone get started with Mura! If you have suggestions for improving this information or just have a question, please leave a comment.


  1. Michael Miller says

    Thanks Clarke. I keep telling people around here that the first person to write a book on Mura will make a lot of money. Have to bookmark this.

  2. White Castle Lover says

    Thanks for the post. I’m having fun learning about Mura. Won’t an upgrade to Mura overwrite your custom code in the eventHandler.cfc file and cause your system to revert to the use of your original gallery? Thanks.

    • Clarke Bishop says

      There’s a trick in Mura that will prevent Mura from overwriting your code during an upgrade. The trick is: Don’t customize the Default site. Instead, create a new site in the Mura admin and customize it. In the blog post, I mentioned creating a site called MySite for this very reason.

      Mura uses eventHandler.cfc in the MySite/Includes folder, so the file won’t get overwritten. Of course, if Mura fixes a bug, it also won’t get updated. But, normally, this isn’t a problem.

  3. White Castle Lover says

    Wait a second! I just saved a copy of dsp_mailing_list_master.cfm into the custom folder, and Mura (5.2) detected and rendered that one instead of the original. So it seems that any code in the custom folder is run instead of the original code? Huh. Do you know why that is? Thanks.

    • Clarke Bishop says

      Exactly — That’s the way Mura is designed! This way, you can use the custom folder to override the original version.

  4. Mura Newbie says

    So, all the modifications are done in the code, correct? If I install a new theme and want to change the banner image, then I modify the code to do that? Or, as in WordPress, can I just update my new banner image via the Mura framework without touching code?

  5. admin says

    @Mura Newbie

    It’s been several years since I worked with Mura. If you create a new site, then update the CSS, you should be able to change things like the banner image.

    The code I showed was to make some more advanced changes to and actual module (display object).

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>