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:
[cf]
<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>
[/cf]
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.
