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 www.YourDomain.com, 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
</pre>

<cffunction name="onGalleryBodyRender" output="true" returntype="void">

<cfargument name="event">

<cfset var renderer=event.getContentRenderer()>

<cfsilent>

<cfset renderer.loadShadowBoxJS() />

<cfset renderer.addToHTMLHeadQueue("custom/gallery/htmlhead/gallery.cfm")>

<cfif not event.valueExists('galleryItemID')><cfset event.setValue('galleryItemID','')></cfif>

</cfsilent>



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

<cfoutput>#renderer.setDynamicContent(event.getValue('contentBean').getBody())#</cfoutput>



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

</cf_CacheOMatic>



</cffunction>

<pre>

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.