Best Practices

The Default Site

One of the most frequently asked questions we get is, "Should I use the Default site or create a new one when deploying a site in Mura?" We recommend not using the Default site at all when developing in Mura. Here's why:

When you create a new site in Mura, Mura makes an exact copy of the entire Default directory for the new site. Because of this, we recommend that you do not develop using your Default site, but instead leave it empty, keep it updated, and always create a new site for any new deployments (even if you've only got one active site in your Mura install).

Alternatively, if you need an easy way to deploy sites that must have their own codebase, customizing the Default site and using it as a master site is a completely valid approach. That way, when you create a new site, it will have all the custom code changes you've made to the Default site files - this can be a big time-saver if your sites all need to share common custom features. 

Keep in mind that sites in Mura can share resources and operate off the same "includes" directory, making it possible to maintain code for multiple sites in a single place.

Auto-Updates

There are two types of auto-updates for Mura:

  1. Core files
  2. Site files

Updating Core Files: 

You update your core files by clicking on "Site Settings" in the Mura admin and the clicking the "Update Core File to Latest Version" link:

Updating Site Files: 

You can update your site files by clicking on "Update Site Files to Latest Version" when in Site Settings for a specific site:

Important: You can update your core files and not update your site files without issue. If you have customizations in a site and everything is working just fine, don't feel compelled to keep your site files up-to-date. There may be times when it makes sense to make sure site files are updated (such as wanting to make sure you can take advantage of updated functionality), but it's absolutely O.K. not to.

However, it is likely you will run into issues if you update your site files, but not your core files. We strongly recommended you keep your core files up to date.

Staying on the Upgrade Path

When updating your site's files with the built in Mura auto-updater, it is important to know what gets updated in order to avoid having your custom code overwritten.You can add custom files to other directories if you need to, but do not edit existing files, as they may be overwritten during an auto-update.

The following files and directories are update safe and any customizations you make will not be overwritten:  

  • {siteID}/includes/contentRenderer.cfc
  • {siteID}/includes/eventHandler.cfc
  • {siteID}/includes/servlet.cfc
  • {siteID}/includes/loginHandler.cfc
  • {siteID}/includes/themes
  • {siteID}/includes/email
  • {siteID}/includes/display_objects/custom
  • {siteID}/includes/plugins

Customizing Mura Functions

If you need different business logic or simply don't like the way we've done something, you can override default functions by creating your own in your site-specific .cfc's. For instance, if you need to change the markup or output of the primary navigation, you can copy the function from the global contentRenderer.cfc into your local (site-specific) one and customize it to meet your needs. Since this file doesn't get updated on auto-update, your modifications are safe. The same goes for eventHandler.cfc, servlet.cfc, and loginHandler.cfc.

Customizing Display Objects

Since the "{siteID}/includes/display_objects/custom" directory does not get updated when using the auto-update function in Mura, this is a great place to store any customizations to these files. By design, Mura will look in the "custom" directory first when rendering a display object. This makes it possible to copy any of the files you want to customize and place them in the "custom" directory. Once they've been copied to this directory, you can customize these files as much as necessary and stay on the upgrade path.

Note: Sometimes files have references to other files in the "display_objects" directory. These references will need to be updated and/or copy these files into the custom directory also.

Themes

Themes also do not get auto-updated so be sure to use themes for any visual customizations rather than using the templates and CSS files found at the root of the site. These files are deprecated and will be removed in a future version of Mura.