Mura X: Managing Mura

Where to Start

In this section, you'll learn about Mura's directory structure, the differences between "core files" and "site files," as well as some basics on managing multiple sites, and using site bundles as a vehicle for distributing themes.

 

Where Mura is Installed

As a Mura theme developer, you're going to be working with the file system. So, it's important to have an understanding of where Mura is located, and how you can reference this information programmatically, via code. Because at some point, you're going to need this kind of information when generating links to, and from, your own template files.

{context}

The location on your file system of where Mura is actually installed, is referred to as the {context}.

While the vast majority of Mura installations occur at the webroot, some organizations may have Mura installed in a subdirectory of the webroot. It doesn't matter if it's only one level deep, or ten levels deep. Mura is able to ascertain its installation directory, and can help you obtain the information with a simple code snippet.

For example, on a typical Windows server, it might be installed in the following directory:

C:\inetpub\wwwroot\

We can easily reference this information with a simple code snippet in Mura:

m.globalConfig('context')

Listed below are examples of what the m.globalConfig('context') Mura code snippet would return, based on where Mura is installed on the file system.

Install Location Return Value
C:\inetpub\wwwroot\ Empty string
C:\inetpub\wwwroot\muraplatform\ /muraplatform
C:\inetpub\wwwroot\somedirectory\muraplatform\ /somedirectory/muraplatform

The usage of this Mura code snippet, and many others, will be covered much more in depth, as well as how to use them, in another section. At this point, it's important to just keep the {context} in mind, and that there's a way to find out what it is.

 

Mura Directory Structure

There are a few primary directories and files you'll want to be aware of in Mura. The image below displays the directory structure of Mura, highlighting its required directories and files. The directories and files highlighted in red may be updated when updating Mura.

Note: Unless explicitly stated to the contrary, none of the directories or files listed below should be modified.

Directory or File Editable Description
{context}/admin/ No These files should never be modified. The files located here comprise the view and much of the functionality used for the administrative features of Mura.
{context}/config/ Yes This directory contains configuration files. See The "config" Directory section for more information.
{context}/core/ No These file should never be modified. The files located here are essentially the beating heart of Mura. We'll discuss a few files specific to Theme Developers in other sections. That said, it's best to simply leave the files in this directory alone.
{context}/sites/ Yes* The directory itself is required, however the contents may be edited and will not be overwritten when updating Mura. This directory will be covered in the "Site Files" section.
{context}/themes/ Yes* The directory itself is required, however the contents may be edited and will not be overwritten when updating Mura. This directory will be covered in the "Theme Layout Templates" section.
{context}/modules/ Yes* The directory itself is required, however the contents may be edited and will not be overwritten when updating Mura.
{context}/resource_bundles/ Yes* The directory itself is required, however the contents may be edited and will not be overwritten when updating Mura.
{context}/plugins/ Yes* The directory itself is required, however the contents may be edited and will not be overwritten when updating Mura. This directory is used by experienced developers when creating Mura plugins.
{context}/Application.cfc No This file contains Mura's application-specific variables and settings.
{context}/box.json No This file is used by the Mura Team to run various tests using CommandBox and TestBox.
{context}/index.cfm No This is Mura's "start" file, and should not be modified.
{context}/README.md No A simple README file. When viewed on Github, a badge from Travis CI will display whether or not the current build is passing its required tests.

 

The "config" Directory

This directory contains Mura's configuration files. The files and their purpose are listed below.

Directory Editable Description
{context}/config/Application.cfc No This file prevents site visitors from navigating directly to any of the .CFM files contained within this directory.
{context}/config/cfapplication.cfm Yes Experienced developers may add custom Application.cfc variables and/or ColdFusion/CFML mappings here.
{context}/config/README.md No This file contains information about the files contained in this directory.
{context}/config/settings.ini.cfm Yes This is an extremely important file, and contains many of the default settings for Mura. A detailed reference is available in the Mura Developer Guide.

The "core" Directory

Once you've determined where Mura has been installed, you'll want to be able to identify Mura's "core" files. This is important to know, because the last thing you want to do is modify a file you shouldn't have touched to begin with.

As you'll see later, Mura offers an easy way to keep your installation of Mura up-to-date, and if you're modifying "core" files, there's a very good chance your changes would be overwritten. So, in this section, we'll cover where "core" files reside, and which ones you can safely modify, to stay on the upgrade path.

Mura Directory Structure

There are a few primary directories and files you'll want to be aware of in Mura. The image below displays the "core" directory structure.

Directory or File Editable Description
{context}/core/appcfc/ No The files contained in this directory are included in Mura's main Application.cfc file. See The "appcfc" Directory section for details
{context}/core/modules/ No The directories and files located here represent the default display objects and modules used by Mura. This is covered more extensively in the Mura Developer section.
{context}/core/mura/ No The files located here are essentially the beating heart of Mura. We'll take a deeper look at some of its directories and files later.
{context}/core/setup/ No This directory contains files required during the installation process.
{context}/core/templates/ No This directory contains "templates" used to create core files such as the settings.ini.cfm, robots.txt, and some site files such as the SitecontentRenderer.cfc, and Site eventHandler.cfc. These files are typically only used during the installation process.
{context}/core/tests/ No This directory contains files for conducting unit tests.
{context}/core/vendor/ No This directory contains third-party code which Mura relies on for various parts of its functionality such as CKEditor.
{context}/core/.gitignore No The Mura Team uses Git for distributed version control, and this is the site .gitignore file used to specify intentionally untracked files.
{context}/core/Application.cfc No This particular file merely prevents users from navigating to any of the .cfm or .cfc files directly via the browser.

 

The "sites" Directory

You can host multiple websites under one installation of Mura. Each website can have its own, unique domain, assets, groups, users, etc. That said, one important thing to keep in mind when working with theme development in Mura is to make sure you're working with the right directory.

{context}/sites/

Every Mura installation has a directory labeled "sites", located directly under the Mura root or context. This directory name should never be modified, under any circumstances. It contains one file, labeled the Application.cfc (see table below), and a minimum of one sub-directory.

Directory or File Editable Description
{context}/sites/Application.cfc Yes Required. This file is used by experienced ColdFusion/CFML developers, and is covered in the Mura Developer Guide.
{context}/sites/default/ Yes Required. Each Mura installation also has a minimum of one site, labeled the "default" directory. The "default" directory name itself should not be modified, nor should any other Mura-generated directory name located under the "sites" directory. Doing so will break functionality. See below for more information on the "default" directory.

{context}/sites/v10/

Every Mura installation has a directory labeled "default." This directory name should never be modified, under any circumstances. The directories and files located under the "default" directory comprise the "site" files for the "Default" site.

In addition to holding all of the "site" files for the "Default" site, the directory label is also the "Site ID," also referred to as the "SiteID" (no space). To verify a site's SiteID, follow the steps below.

  1. From the back-end administration area of Mura, select Site Settings, then click Edit Settings.
  2. On the Site Settings screen, the first field located under the Basic tab is labeled "Site ID."
  3. The "Site ID" field is a "read only" field, and cannot be modified. This is intentionally designed to work this way.
  4. When creating a new site in Mura, you specify the Site ID. This is important, because whatever you enter into that field will become the directory name. So, do not use any punctuation, special characters, etc. when doing so. See the "How to Add a New Site" section for more information on creating a new site.

The key to remember here is each site in Mura has a unique SiteID which also matches the directory name. So, the path to any particular site you desire to work with can be notated as {context}/sites/{SiteID}/.

Note: Whenever you create a new site in Mura, all of the files located under the "default" directory are copied over to the newly created site's directory.

{context}/sites/{SiteID}/

As a Mura theme developer, you'll be spending most of your time working with files located within your theme. The directory structure of a Mura site is detailed below.

Directory or File Editable Description
{context}/sites/{SiteID}/assets/ Yes* Required. The "assets" directory stores any files uploaded through Mura's web file manager, currently CKFinder, when editing content via the user interface. It's best to simply use the web file manager itself to manage these files. However, we understand you may want, or need, to perform a bulk upload of files to a specific directory. When doing so, please be sure not to alter the primary directory structure, as you could potentially break links to files referenced here.
{context}/sites/{SiteID}/cache/ No Required. You should not touch this directory. Any images, files, etc. uploaded as actual content or primary associated files are renamed and stored here. References to all files are also stored in Mura's database.
{context}/sites/{SiteID}/modules/ Yes Optional. This directory contains the files Mura uses to render display objects in the browser. See The "modules" Directory section for more information.
{context}/sites/{SiteID}/resource_bundles/ Yes Optional. This directory contains ".properties" files containing locale-specific data as a way of internationalising Mura. See The "resource_bundles" Directory section for more information.
{context}/sites/{SiteID}/themes/ Yes Optional. This directory contains a site's themes. Themes stored under this directory are not accessible to any other site, unless the sites are using the same "Display Object Pool" as defined under Site Settings > Edit Settings > Share Resources tab. See The "themes" Directory section for more information.
{context}/sites/{SiteID}/.gitignore No Optional. The Mura Team uses Git for distributed version control, and this is the site .gitignore file used to specify intentionally untracked files.
{context}/sites/{SiteID}/contentRenderer.cfc Yes Optional. This is the Site contentRenderer.cfc file. You can add site-specific methods here. This is covered in the Mura Developer Guide.
{context}/sites/{SiteID}/eventHandler.cfc Yes Optional. This is the Site eventHandler.cfc file. You can add site-specific event handlers/listeners here. This is covered in the Mura Developer Guide.
{context}/sites/{SiteID}/index.cfm No Required. This is the site's "start" file, and should not be modified.

 

The "themes" Directory

As a Mura Theme Developer, you will obviously be spending quite a bit of time working with themes. Themes may be located under one of the following locations:

  • Global Themes
    • {context}/themes/
    • Themes located under the "Global" themes directory will automatically be available as a theme option for all sites under the same Mura instance.
  • Site Themes
    • {context}/sites/{SiteID}/themes/
    • Themes located under a site's "themes" directory are available to the specified site, and/or any other sites sharing the same "Display Object Pool" as defined under Site Settings > Edit Settings > Shared Resources tab.

Mura automatically checks these "themes" directories for any subdirectories. If Mura discovers any subdirectories, it assumes it is a theme, and uses the name of each directory as the "Theme Name". The "Theme Name" will then be listed as an option for authorized administrators to apply as a theme to their site. You may have as many themes as you wish under a "themes" directory.

When Mura is first installed, if a theme does not exist under either of these directories, Mura will attempt to download a theme using the "defaultthemeurl" setting found in the {context}/config/settings.ini.cfm file.

We'll cover the files and directories that comprise a theme under the Creating Layout Templates section.

 

How to Select a Theme From the Admin UI

Only members of the "Admin" group, and "Super Admin Users" are able to select a theme from the Mura administrator. Follow the steps below to select a theme.

  1. From the back-end administrator of Mura, select Site Settings from the main navigation, and click Edit Settings.
  2. You should see the Site Settings screen, and make sure the Basic tab is selected.
  3. Scroll down the screen, and locate the select menu labeled Theme.
  4. Select your desired theme from the list of available Theme options, then click the Save Settings button.
  5. The selected theme should now be applied to your site.
  6. To apply a theme's layout templates to the various sections and pages of your site, please visit the Layout Templates section of the Content Manager's Guide.

The "modules" Directory

Mura "modules" can be used to either enhance your layout via the use of "display objects", and/or even add functionality to your site(s). Mura's modules allow you to quickly and easily add visual elements such as Collections, Components, Forms, navigational aids, and so much more.

Lookup Hierarchy

Mura uses the following lookup hierarchy when searching for modules, and aborts the lookup process once the target module has been located:

  • Registered Modules Directory
    • {RegisteredModulesDirectory}/
    • A pre-registered modules directory path. See Modifying Mura's Modules for more information.
  • Module
    • ../{module}/modules/
    • A nested "modules" directory nested within a known module.
  • Theme
    • ../{ThemeName}/modules/
    • Theme modules are only used when the specified theme is actively assigned to a site. Keep in mind themes may be located under either the global themes directory ({context}/themes/{ThemeName}), or under a site ({context}/sites/{SiteID}/themes/{ThemeName}).
  • Site
    • {context}/sites/{SiteID}/modules/
    • Site modules are shared across all themes within the specific site.
  • Global
    • {context}/modules/
    • Global modules are shared across all sites under a single Mura instance.
  • Core
    • {context}/core/modules/v1/
    • These are the "core" modules or display objects which may be copied and placed into any of the directories above to be safely modified.
       

Note: You should not edit the "core" modules directly. If you do, you run the risk of losing your edits or changes whenever you update Mura to the latest version.

Learn More

Developers may customize existing modules, or even create custom modules, unique to your organization's needs such as a stock ticker, and even create full-blown applications to be embedded within a single page or an entire section of your site. You can learn more about creating custom modules in the Mura Developer Guide.

The "resource_bundles" Directory

Mura utilizes resource bundles to internationalize various areas of the user interface, making the code locale-independent.

Resource bundles are .properties files, located under specified directories in Mura. These .properties files, or resource bundles, are named to indicate the language code, and country code. For example, the language code for English (en) and the country code for United States (US) would be represented as en_US.properties. If Mura cannot find a direct language and region match, it will search for a language match. If a locale's language cannot be found, Mura will fall back to its default of English, or en_US.properties.

The file itself is comprised of key-value pairs. The keys remain the same throughout each of the .properties files, and the value is translated into the file's designated language. If Mura is searching for a specific key-value pair within a translation, and cannot locate it, Mura will fall back to the English translation.

The image below illustrates the en_US.properties file side-by-side with the es_ES.properties file:

Lookup Hierarchy

Mura automatically searches for resource bundles under specific directories, and uses the key-value pair(s) found in the order outlined below. If a resource_bundles directory does not exist in the following locations, you may safely create one, and place your resource bundle files there.

  • Module
    • ../{module}/resource_bundles/
    • Module (aka "Display Object") resource bundles are used for the specific module itself.
  • Content Types
    • ../content_types/{type}_{subtype}/resource_bundles/
    • Content Types resource bundles are used for the specified content type.
  • Theme
    • ../{ThemeName}/resource_bundles/
    • Theme resource bundles are only used when the specified theme is actively assigned to a site.
  • Site
    • ../{SiteID}/resource_bundles/
    • Site resource bundles are shared across all themes within the specified site.
  • Global
    • {context}/resource_bundles/
    • Global resource bundles are shared across all sites under a single Mura instance.
  • Core
    • {context}/core/modules/v1/core_assets/resource_bundles/
    • If the requested key-value pair is not defined in any of the locations above, Mura will use the "core" resource bundles located here for Mura's modules.

Note: Admin-area resource bundles are located under {context}/core/mura/resourceBundle/resources/. However, as of v7.1, many key-value pairs are not able to be overwritten using the technique described above at this time. Allowing for this option is under consideration for a future version.

Contribute

If you would like to contribute to the translations project, please visit https://crowdin.com/project/muracms. Your help will be greatly appreciated!

More Info

More information on resource bundles, including how to customize and create your own key-value pairs, is covered in the Mura Developer Guide.

How to Update Mura

Mura offers a way to keep your installation up-to-date, with the click of a button. Please be sure to back up the database, and your filesystem before attempting to use this feature. We also recommend performing this in a development or testing environment before using this feature in a "live" or "production" environment.

Follow the steps below to update Mura.

  1. From the back-end administrator area of Mura, select Global Settings on the main navigation, then click Update Mura Core. Or, from the Global Settings area, you may also click the "Update Core Files" button, located near the top of the screen.
  2. You should see the Update Mura Core confirmation window, with a warning instructing you not to update the core files unless you've back up your current Mura install. If you wish to proceed, select the "OK" button, otherwise, click "Cancel" to abort the update process.
  3. If you selected the "OK" button, Mura will use the value of the autoupdateurl variable entered in the file located at {context}/config/settings.ini.cfm. No files are ever deleted during this process, files are only overwritten if they exist, or created if they don't. Once the process completes, Mura will display a message, along with the version you have been updated to as found in the {context}/box.json file.
  4. When you're finished, you may click the List Sites button to return to the Global SettingsSites view.

Managing Multiple Sites

Mura can host multiple websites under a single installation. Each website can be a subdomain, or even its own unique domain entirely. In addition, each site can have multiple aliases, allowing you to choose whether or not you want users who visit your site to have their URL redirect to your "primary" domain. Beyond that, Mura offers a number of other powerful features that makes managing multiple websites a breeze.

Only users granted "Super Admin User" privileges are able to access most of the areas and features described in this section. So, if you're trying to follow along, and you don't see the links or screens described here, you will most likely have to coordinate with another member of your team who has been granted the proper credentials.

Global Settings

In the back-end administrator area of Mura, there's a special area labeled Global Settings. Here you can perform various tasks such as creating and/or managing sites, installing and/or managing plugins, and keeping your "core" up-to-date.

  • Sites
    • This area lists all websites currently managed by Mura.
  • Add Site
    • See the How to Add a New Site section for more information.
  • Copy Site
    • This feature allows you to copy all site files, and its content from one site, to another.
  • Plugins
    • This area lists any installed plugins, and allows you to install new plugins and/or manage and/ore delete any existing plugins. This feature is covered in the Mura Developer Guide.
  • Update Mura Core
    • Mura offers a way to keep your "core" directories and files up-to-date, with the click of a button. See the Update the Mura "Core" section for more information.
  • Reload Application
    • This feature is used when a developer makes a change to any files that require the ColdFusion/CFML server to reload and start the application lifecycle again.

How to Add a New Site

Mura can host multiple websites under a single installation. This makes it easy to host both a public-facing website, and a company-facing intranet, and/or additional web properties owned and managed by your organization.

To add a new Mura site, follow the instructions below.

  1. From the back-end administration area of Mura, select Global Settings from the main navigation, and click Add New Site
  2. The only required form field is the "Site ID" field. Please keep in mind the text you enter here will become the directory name under Mura's {context}/sites/{SiteID}, and as such, you should not use any spaces, punctuation, dots, or file delimiters here
  3. At a minimum, you'll probably also want to enter a "Site Name" and "Primary Domain" in order to identify, and access the site
  4. Remember, when adding a new site, all directories and files located under {context}/sites/v10/ will be copied and placed into the new SiteID directory.
  5. Additional information about adding a new site can be found in the forthcoming Installation and Setup Guide.
  6. When you're finished, click the Add button, to create your new site
  7. You should now see your new site in the listing of sites on the Global Settings screen

Switching Between Sites

When you're working with multiple websites managed under the same instance of Mura, you'll need to know how to switch between each site, as well as easily identify which site you're currently working with.

The most simple way to identify the website you're currently working with from the back-end administrator area of Mura is to look at the top-left area of the administrator screen. You should see a button with a down arrow icon.

In the example above, you'll see we're working with the "Default" site. As you may already know, if you click the button itself, Mura will launch a new tab or browser window, and load the home page of the current site. 

If you wish to switch to another site, simply click the down arrow next to the button, and select your desired site from the list.

Once you've made your selection, you should be able to work with your selected site.

Another Way to Switch Between Sites

Super Admin Users can also switch between sites in the back-end administrator area of Mura by selecting Global Settings from the main navigation, and clicking Sites.

In the example above, you'll see we're currently working with the "Default" site. As soon as you select another site from the listing of sites under the Current Sites tab, Mura will automatically switch you to the selected site. For example, if we select My Awesome Site from the list, you'll be taken to the Site Settings screen, and the site name in the button at the top of your screen will be updated to reflect your selected site.

 

How to Delete a Site

Super Admin Users are able to delete sites from Mura, by following the steps outlined below.

  1. From the back-end administration area of Mura, select Global Settings, then click Sites
  2. On the Global Settings screen, the Current Sites tab contains a listing of all sites currently being managed by Mura
  3. Locate the desired site, and click the three-dot menu, then select Delete
  4. An Alert dialog window should open with a warning which informs you that a deleted site and all of its files and content cannot be recovered after performing this operation. If you wish to proceed, click the "OK" button. If you wish to abort this process, click the "Cancel" button
  5. If you click OK, the site files and all of its content will be deleted, and an updated listing of sites should appear.

Site Bundles

Site Bundles are a convenient way to create backups and migrate your site(s) from on instance of Mura to another. Mura gathers all of your site's assets, including uploaded files, themes, and content to create a "Site Bundle" exported as a .ZIP file. The file can then be stored on an offsite hard drive as a backup, or handed off to a client as a completed project that can then be imported into another instance of Mura.

As you can see, site bundles can also be a great way to distribute your theme. Imagine how awesome it would be to have your theme files done, as well as a fully functional website, with sample content, and everything else so that anyone who uses your theme, will be able to see it exactly the way you intended it to be.

 

How to Create/Export a Site Bundle

When you create a site bundle with Mura, a .ZIP file will be generated. There's no need to unzip it. The file will contain data that has been exported from the database, as well as all of the assets used for the site such as images, CSS, JavaScript, and of course, any layout templates used by the originating site.

Note: Depending on the size of your site, as well as the size of your assets, site bundle files can get quite large, rather quickly. If your bundles are in the 2Gb+ range, we highly encourage you to use more traditional backup and deployment strategies.

To create a site bundle, follow the steps below.

  1. From the back-end administration area of Mura, select Site Settings from the main navigation, then click Create Site Bundle.
  2. The Create Site Bundle screen should appear.
    • Include in Site Bundle
      • Items in Trash Bin
        • Select this option if you wish to include deleted items still remaining in the Trash Bin.
      • Content Version Histories
        • Select this option if you wish to include all available version histories.
      • Content Comments and Ratings
        • Select this option if you wish to include comments and ratings submitted by site visitors.
      • Form Response Data
        • Select this option to include any form submissions.
      • Site Members & Administrative Users
        • Select this option if you wish to include the current groups and users associated with your site.
    • Also include selected Plugins:
      • If any plugins are enabled for your site, a listing of those plugins will appear with a checkbox next to each of them. You may select any plugins you wish to be included in the bundle file.
    • Server Directory (Optional)
      • You can choose where you would like the bundled .ZIP file to be stored on the server. If you choose to leave it blank, Mura will package up the .ZIP file, and will prompt you to download the file when its finished.
      • If you wish to use the "Current Working Directory" as listed on the screen, you may simply click the Select Working Directory button, and Mura will auto-populate the text area with the information.
  3. After making your desired selections, click the Create Bundle button.
  4. An Alert dialog window will appear to confirm your decision to create a bundle file. Select Yes to continue, or No to abort the process.
  5. Depending on your choice for Server Directory, you will either be prompted to download the file (if you left it blank), or you will be redirected to the Bundle Created screen, when the file is saved on the server and ready to be retrieved.

How to Deploy/Install a Site Bundle

Mura site bundles are essentially pre-packaged Mura websites. The bundle file includes content, along with the site's assets and theme files. A bundle file is typically named as MuraBundle_{SiteName}_YYYY_MM_DD_HH.zip. As you can probably already decipher, the date and time the bundle was exported is usually attached to the bundle name. This makes it helpful when you're working with bundles that have been created as backups for a particular site.

While you can upload a bundle via the user interface, as you'll see below, when deploying/installing a site bundle, we highly recommend uploading the bundled .zip file to the server. One of the primary reasons for this is because the process will go much smoother and easier for you in the long run since you can eliminate the need to upload a large file via your browser.

Note: Depending on the size of your site, as well as the size of your assets, site bundle files can get quite large, rather quickly. If your bundles are in the 2Gb+ range, we highly encourage you to use more traditional backup and deployment strategies.

Follow the steps below to deploy/install a Mura site bundle.

  1. From the back-end administration area of Mura, select Site Settings from the main navigation, then click Deploy Site Bundle
  2. You should see the Site Settings screen, and the Deploy Bundle tab should be pre-selected for you.
  3. Review the form options below to assist you in making your desired selections.
    • Are you restoring a site from a backup bundle?
      • No - Assign New Keys to Imported Items
        • This is the default option. Unless you are actually restoring a site from a backup bundle, you should use this option.
      • Yes - Maintain All Keys from Imported Items
        • If, and only if, you are restoring a site from a backup bundle, select this option. However, you MUST be deploying the bundle to the same site. Do NOT attempt to deploy the bundle file with this option to a new site under the same instance of Mura. The main reason is because you would be attempting to overwrite existing records in the database which exist for another site, causing serious issues to occur.
    • Include
      • Site Architecture & Content
        • Select this option to include the content. This is a very common selection, unless you're only attempting to install the theme files. Also be aware that if you select this option, all existing content for the site will be deleted, and replaced with the new content from the bundle.
      • Site Members & Administrative Users
        • Select this option to import groups and users included in the bundle.
      • Form Response Data
        • Select this option to import any form submissions and content ratings from site visitors.
      • All Plugins
        • If the bundle is dependent upon plugins to function properly, you may wish to select this option.
    • Which rendering files would you like to import?
      • All
        • Selecting this option would include all "site" files, as saved in the bundle.
      • Theme Only
        • Selecting this option would leave your "site" files alone, and only import the theme files. This is independent of any selection you made for importing content. If you select this option, the theme will be imported, and the site's theme assignment will be updated as well.
      • None
        • Select this option if you don't wish to import any "site" files, or theme files.
    • Select Bundle File From Server (Preferred)
      • This is the recommended option. First, you must FTP the bundle file to a location under the Mura webroot. For example, ../wwwroot/temp/. Then, click the Browse Server button, and navigate to the location where the file resides, and select it.
    • Upload Bundle File
      • For very small bundle files, this option may work without any issues. However, many browsers and web servers have filesize limitations when submitting a form. Many bundle files exceed the filesize restriction, so it is recommended to use the first option whenever possible.
  4. After you've made your desired selections, and you're ready to deploy/import the bundle, click the Save Settings button.
  5. After your bundle has been imported, you will be taken back to the Global Settings screen.

Theme-Based Sites

As a Mura theme developer, this will be the section you are most interested in. In this section, you'll learn how to create theme layout templates and component layout templates. You'll also learn some Mura template variables, as well as some commonly used code snippets to make your life easier when integrating your own custom theme.

 

Theme Layout Templates

As covered in The "themes" Directory section, themes may be located under one of the following directories:

  • Global Themes
    • {context}/themes/
    • Themes located under the "Global" themes directory will automatically be available as a theme option for all sites under the same Mura instance.
  • Site Themes
    • {context}/sites/{SiteName}/themes/
    • Themes located under a site's "themes" directory are available to the specified site, and/or any other sites sharing the same "Display Object Pool" as defined under Site Settings > Edit Settings > Shared Resources tab.

Mura automatically checks these "themes" directories for any subdirectories. If Mura discovers any subdirectories, it assumes it is a theme, and uses the name of each directory as the "Theme Name". The "Theme Name" will then be listed as an option for authorized administrators to apply as a theme to their site. You may have as many themes as you wish under a "themes" directory.

When Mura is first installed, if a theme does not exist under either of these directories, Mura will attempt to download a theme using the "defaultthemeurl" setting found in the {context}/config/settings.ini.cfm file, and will create a "Global" theme using "default" as the directory name, as well as the "Theme Name". As of version 10, the default setting for the "defaultthemeurl" is "https://github.com/murasoftware/mura-bootstrap4/archive/master.zip".

../{ThemeName}/templates/

The only "required" directory under a theme is the "templates" directory. This is also the directory where you will create and manage your theme-specific layout templates.

Visit the "How Do I Create Layout Templates?" section to learn more.

How Do I Create Layout Templates?

The great thing about working with Mura is, you can start off by creating layout templates just like you always have. Many theme developers begin by creating custom layouts using vanilla HTML, CSS, and JavaScript. Or, some theme developers begin by purchasing and/or downloading free templates from the web. The end result is typically a directory of HTML files, and subdirectories of the assets, images, and other related files.

If we were to open one of the files from the example listed above, you would see that it's straight vanilla HTML.

So, there's no reason to change anything about the initial part of your theme development process.

1. Move Your Theme to a "themes" Directory

Place your theme under a "themes" directory. For example, {context}/themes/{ThemeName} if you wish to create a "global" theme, or {context}/sites/{SiteID}/themes/{ThemeName}, if you only want the theme to be available for a specific site.

2. Create a "templates" Directory

The only required directory of a Mura theme is a "templates" directory. So, we'll need to create it, and then move our layout templates into it.

3. Rename ".html" Files to ".cfm"

Rename all of your layout templates from the ".html" file extension, to the ".cfm" file extension. As indicated by the ".cfm" file extensions, Mura uses ColdFusion Markup Language (CFML) as its server-side scripting language. Like many other web scripting languages, CFML augments standard HTML files with database commands, conditional operators, high-level formatting functions, and other elements to produce web applications. If you're interested in learning more about CFML, checkout https://helpx.adobe.com/support/coldfusion.html or http://learncfinaweek.com.

So, using our existing example files, our directory structure might look like the following illustration.

4. Create a "default.cfm" Layout Template

Remember, if Mura is unable to locate a currently assigned layout template, it will "fall back" to using the "default.cfm" layout template. So, it's good practice to simply have one created.

5. Use Commonly Used Layout Template Names

Listed below are the most commonly used layout templates in Mura. If you plan on distributing your theme, you might consider using this naming convention. This way, if an administrator swaps a theme, they won't necessarily have to go back through their entire website, and reapply new layouts to all of the pages and sections of their site.

  • default.cfm
    • This is the "default" layout template. If Mura is unable to locate a layout that has been assigned to a content item (e.g., the layout has been renamed, or removed), Mura will "fall back" to this layout. Using a simple line of code, you can easily "include" one of your other layouts to be used. For example, <cfinclude template="two_column_SL.cfm">
  • home.cfm
    • The "home" layout is traditionally applied only to the "Home" page of the website.
  • one_column.cfm
    • This layout is used when you don't need any "sidebars" or other columns other than the main "body/content" area.
  • three_column.cfm
    • This layout accommodates a centered main "body/content" region, as well as a left sidebar, and a right sidebar.
  • two_column_SL.cfm
    • This layout has a main "body/content" region, and its sidebar to the left.
  • two_column_SR.cfm
    • This layout has a main "body/content" region, and its sidebar to the right.

So, reviewing our example files, we should be able to rename example templates as follows:

Original Name New Name
index.cfm home.cfm
left-sidebar.cfm two_column_SL.cfm
no-sidebar.cfm one_column.cfm
right-sidebar.cfm two_column_SR.cfm

Since we have a "default.cfm" layout template, if the prior theme assignment was using a layout template that our new theme doesn't include, we could either make a new one, or just allow the "fall back" to occur, and rely on "default.cfm" to be used instead.

A common method used with the default.cfm layout template is to "include" your desired "default" layout template. For example, maybe you want the two_column_SL.cfm layout to be your default. The following illustration shows how you could do that.

Visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-i/cfinclude.html for more information about the <cfinclude> tag.

6. Replace # With ##

Hashtag/number sign (#) characters have special meaning in CFML. So, if your layout template has any hashtag characters, you will need to escape single hashtags with double hashtags. In short, you need to use ## to represent a single # character. Using a simple "find and replace" feature of most code editors tends to work well.

7. Wrap All Output With <cfoutput></cfoutput> Tags

In CFML, <cfoutput> tags displays output that can contain the results of processing CFML variables and functions. You're going to need these tags in your layout templates, because soon, you're going to be adding some template variables and code snippets, to replace your static text.

To learn more about <cfoutput> tags, visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-m-o/cfoutput.html.

Summary

Here's a quick overview of the process we've covered for creating theme layout templates so far:

  1. Move your theme to the "themes" directory
  2. Create a "templates" directory (and move your layout templates inside of it)
  3. Rename ".html" files to ".cfm"
  4. Create a "default.cfm" layout template
  5. Use commonly used layout template names
  6. Replace # with ##
  7. Wrap all output with <cfoutput></cfoutput> tags

Soon, we'll go through and replace static text with dynamic template variables and code snippets.

Example Theme Directory Structure

As previously mentioned, when you first install Mura, if a theme does not exist, Mura will attempt to download one for you based on the "defaultthemeurl" setting found in the {context}/config/settings.ini.cfm file. As of version 7.1, this setting defaults to "https://github.com/blueriver/MuraBootstrap4".

Using the MuraBootstrap4 theme as an example, the table below details the directories and files Mura automatically scans for, and those are identified with an asterisk (*) within the "Required" column. As you'll see below, the "templates" directory is the only one that's truly required.

Directory or File Required Description
../{ThemeName}/assets/ No Typically, various front-end framework and library files, are stored here. For example, "bootstrap" and "font-awesome" directories can be found in the MuraBootstrap4 theme.
../{ThemeName}/content_types/ No* This directory, and its purpose is beyond the scope of this guide. Please visit the Mura Developer Guide for details.
../{ThemeName}/css/ No* If an "editor.css" file is located, its styles will be included with CKEditor's styles for any HTML Editor type regions when editing content via Mura's user interface.
../{ThemeName}/modules/ No* This directory, and its purpose is beyond the scope of this guide. Please visit the Mura Developer Guide for details.
../{ThemeName}/images/ No Theme-specific images are typically stored here.
../{ThemeName}/js/ No* This directory is used for storing theme-specific JavaScript files. In addition, Mura checks for an "editor" directory. If found, Mura then scans for some additional directories and files for customizing the web editor. Additional information can be found under the Customizing the Web Editor section.
../{ThemeName}/resource_bundles/ No* As discuss in The "resource_bundles" Directory section, Mura offers a way to internationalize both the user interface, as well as parts of your theme. More information resource bundles, including how to customize and create your own key-value pairs, is covered in the Mura Developer Guide.
../{ThemeName}/templates/ Yes This is technically, the only "required" directory. This is where you create and manage your theme-specific layout templates. See Theme Layout Templates for more information.
../{ThemeName}/.gitignore No The Mura Team uses Git for distributed version control, and this is the site .gitignore file used to specify intentionally untracked files.
../{ThemeName}/config.xml.cfm No* This file contains some theme-specific configuration settings. Visit The Mura Developer Guide to learn more.
../{ThemeName}/contentRenderer.cfc No* This is the theme-specific contentRenderer.cfc. You can add any theme-specific methods here. Visit The Mura Developer Guide to learn more.
../{ThemeName}/eventHandler.cfc No* This is the theme-specific eventHandler.cfc. You can add any theme-specific event handlers/listeners here. Visit The Mura Developer Guide to learn more.
../{ThemeName}/README.md No General information about the theme itself is stored in this file. It is not used by Mura.

Note: The primary focus of this guide is to help theme developers integrate their existing designs into Mura. The Mura Developer Guide will cover many of the more complex scenarios when it comes to building dynamic display areas, as well as extending the functionality of Mura.

Mobile Layouts

As a Mura theme developer, you'll want the ability to assist your content writers and content managers in engaging visitors using mobile devices. You'll learn Mura doesn't get in the way of whether or not you should use "responsive" design, or create a mobile-specific version of your entire site. Mura will simply deliver your desired content to whichever path you choose to pursue.

Throughout this section, you'll discover the various methods you can utilize to leverage both your design and development knowledge as well as Mura's baked-in features. From creating a mobile-specific layout template to displaying mobile-specific content, Mura can assist you in both the usability needs of mobile users, as well as delivering content mobile readers will love.

Note: You may also want to review the Mobile Navigation section of the Content Manager's Guide.

Using Responsive Layouts

The use of responsive web designs has grown exponentially, along with the explosion of people using their mobile devices to surf the web. Responsive design is a development approach where the page layout dynamically adjusts to the size of a user's screen, and often includes checking which type of device or browser is being used to access the site. Hence, content displayed on a "desktop" browser in a three-column layout, may re-flow to a two-column format for tablet devices, and a one-column layout for smaller, mobile devices.

Most modern front-end frameworks such as Bootstrap, Foundation, Semantic UI, and others, accommodate responsive layouts. For example, Mura's readily available MuraBootstrap4 theme utilizes the responsive web design features of Bootstrap.

As you'll see in the "What Can I Use?" section, you can use pretty much any front-end framework you want. Mura also includes a useful tool when previewing the front-end of your site. The front-end toolbar includes a "Multi-Device Preview" button.

Clicking the Multi-Device Preview button will launch the Preview Mode window.

At the top of the window, you should be able to see five different button icons, each representing a different "view". Selecting a different icon, the screen will resize to give you an idea of how your content might display on a device with similar viewport dimensions. Options cover Desktop, Tablet Portrait, Tablet Landscape, Phone Portrait, and Phone Landscape.

For example, selecting Phone Portrait, the home page of the MuraBootstrap3 site might look like the following illustration.

Responsive layouts has become the most common approach to use in Mura to deliver content to both desktop and mobile users of your sites.

Component Layout Templates

As covered in the Content Manager Guide, Mura components are reusable content objects that can be shared across multiple pages or sections within your site. Theme developers will often want a way to control the look, feel, and even the functionality, of some of these components. For this reason, Mura offers a way to create special layouts, designed specifically and exclusively for components themselves.

How to Create a Component Layout Template

Mura automatically checks your theme's "templates" directory for a "components" directory. If the "components" directory is discovered, Mura will inventory all ".cfm" files within it, and include them as Layout Template options when editing a component. So, you would place your component layout templates under ../themes/{ThemeName}/templates/components/.

If you reference the MuraBootstrap4 theme, and look under the "templates" directory, you should see a subdirectory labeled "components" with a couple of files in it.

If you view the example.cfm layout template, you'll notice a few lines of code. We'll cover template variables in another section, so for now, focus on the HTML included.

Notice the <div class="your-component-class"> tag. You could change that to be anything you want, and use it as a hook to target the display of anything within it. Think of all of the other things you could include here, such as JavaScript, HTML, CSS, CFML, and more. The possibilities are endless. The main thing to keep in mind at this point is Mura offers an easy way for you to style components with your own layout templates.

How to Apply a Layout Template to a Component

Follow the steps below to apply a layout template to a component.

  1. From the back-end administration area, go to the Content section, select the Tree View tab, then select the Components button.
  2. Either select an existing component you wish to edit, or create a new component.
  3. From the Create/Edit Component screen, select the Advanced tab.
  4. Locate the Layout Template field, and choose your desired layout from the select menu.
  5. After completing the form, select your desired publishing option to save your component.
  6. If you've created a new component, and wish to add it to a page or section of your site, please visit the Component Display Object Type section of the Content Manager Guide.

The Mura [m] Tag

Mura uses ColdFusion Markup Language (CFML) as its server-side scripting language. CFML treats text surrounded by hashtag/number sign characters (#) as a variable or function call.

For example, the following code would output the current time:

<cfoutput>#TimeFormat(Now(), 'hh:mm:ss tt')#</cfoutput>

However, the code would have to be contained in a .CFM file, and parsed by a CFML server. If you attempt to use the same method with text entered into one of Mura's form fields, or HTML Editor areas, the data is simply stored as text, and rendered back to the browser. In other words, if you added the same line of code, minus the <cfoutput> tags into the content/body area in Mura ...

You would simply see the exact same text rendered back to you.

Usage

If you want to output dynamic code with text entered into one of Mura's standard form fields, or HTML Editor, you can simply use Mura Tags in lieu of the hashtag/number sign characters.

[mura]...[/mura]

<!--- OR --->

[m]...[/m]

Using the previous example, the illustration below shows the same code with Mura Tags instead of hashtag/number sign characters.

Now, the text is evaluated as CFML, and the returned to the browser.

For information on how to render Mura [m] tags in your layout templates, see setDynamicContent in the Template Variables & Helper Methods section.

The Mura Scope

Similar to how CFML includes various scope types, Mura also includes its very own "Mura Scope" for accessing, and manipulating, Mura CMS variables, data, and objects. In a nutshell, the Mura Scope allows you to "talk" with Mura.

The Mura Scope is available via mura, $, or m.

Examples

We're covering template variables shortly, however, a couple of examples demonstrating use of the Mura Scope are noted below.

<!--- Example from within .cfm templates --->
#m.content('title')#

<!--- Example when using the [m] or [mura] tag --->
[m]m.content('title')[/m]

Note: For theme developers, the Mura Scope will be available to you most of the time you need it. In the Mura Theme Developer Guide, we'll explore the rare situations when it's not immediately available to you, and how to obtain an instance of it, when needed (e.g., when you're running code outside of the normal Mura event model).

Template Variables & Helper Methods

As a Mura theme developer, your layout templates are initially filled with static text. However, the primary reason for using a content management system (CMS) such as Mura, is so non-technical end users can create new content, and maintain existing content, quickly and easily.

Using the Mura Scope, theme developers are given the power to replace static text, with code that can dynamically display text and data entered into Mura by content managers. In addition to displaying text and data, the Mura Scope provides a number of useful helper methods to assist theme developers by dynamically generating navigational elements, display objects, as well as a special method to dynamically output the main content/body region, but only if the user accessing the content is allowed to do so.

Throughout this section, you'll find references to some of the most commonly used helper methods and template variables to help you get your theme integrated into Mura as quickly and efficiently as possible.

While reviewing the template variables and helper methods, you may find <cfdump>, a CFML tag, quite useful for inspecting them further than the documentation provides. For more information on <cfdump>, visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-d-e/cfdump.html

This section primarily covers template variables and helper methods frequently used by theme developers. Many of the helper methods covered in this section are found in Mura's contentRenderer. If you wish to learn more, visit the Mura Developer Guide, and/or the Mura Component API.

Note: Unlike JavaScript, and many other programming languages, CFML is case-insensitive. In other words, CFML does not distinguish between uppercase and lowercase variables, functions, or arguments/parameters. So, you don't have to strictly follow the casing found within the documentation when using CFML.

 

esapiEncode

Scattered throughout this section, and throughout the default theme that ships with Mura, you'll find references to a special method called esapiEncode. This method is used to encode a given string for safe output to stop Cross Site Scripting attacks. You can safely use this method in Mura, even though it has not been fully implemented in all available CFML engines yet.

Function Syntax

esapiEncode( encodeFor, string )

Parameters

Parameter Type Req/Opt Default Description
encodeFor string Required  

encode for what, valid values are:

  • css: for output inside Cascading Style Sheets (CSS)
  • dn: for output in LDAP Distinguished Names
  • html: for output inside HTML
  • html_attr: for output inside HTML Attributes
  • javascript: for output inside Javascript
  • ldap: for output in LDAP queries
  • url: for output in URL
  • vbscript: for output inside vbscript
  • xml: for output inside XML
  • xml_attr: for output inside XML Attributes
  • xpath: for output in XPath
string string Required  

string to encode

Usage

We highly recommend to use this function whenever outputting user-entered text. For example, content managers enter text into Mura fields such as the Title, Credits, Meta Description, Meta Keywords, etc. Wherever you output these fields in your layout templates, be sure to pass the field in as the string to encode.

Example

The following example encodes a content item's "Title" for output inside of standard HTML heading tags.

<cfoutput>
	<h2>#esapiEncode('html', m.content('title'))#</h2>
</cfoutput>

setDynamicContent

A Mura Scope helper method to render Mura [m] tags. This function checks a string for Mura [m] tags, and if found, will pass the variable or function call the the CFML server for processing before final rendering of the page.

Function Syntax

m.setDynamicContent( string )

Parameters

Parameter Type Req/Opt Default Description
string string Opt empty string

This is the string to parse for Mura [m] tags.

Usage

Use this function to search through a string for Mura [m] tags. Most use cases revolve around user-entered text that may, or may not, contain Mura [m] tags, such as the "Summary" field of a content item.

Examples

You can wrap this method around any string, or anticipated string, to render Mura [m] tags.

Basic Example

The following is a very basic example to illustrate how to output an explicit string containing Mura [m] tags.

<cfset exampleString = "Today is [m]DateFormat(Now(), 'yyyy-mm-dd')[/m]" />
<cfoutput>
    <div>
        #m.setDynamicContent(exampleString)#
    </div>
</cfoutput>

Content Summary

The following example illustrates how to output a content item's "Summary" field, if you expect it may contain Mura [m] tags. You could apply this method to nearly any text field of a content item.

<cfoutput>
    <article>
        #m.setDynamicContent(m.content('summary'))#
    </article>
</cfoutput>

dspPrimaryNav

A Mura Scope helper method to dynamically output primary navigation. Mura also checks a user's permissions, and will only display links to content the user has access to. If a section of a site is restricted, a link will be generated to the topmost content item only. If a user visits that link, they will be presented with a login screen, if they're not currently logged in, or if they are logged in and don't have access, a message will inform the user they do not have the proper authorization.

Function Syntax

m.dspPrimaryNav(
    viewDepth
    , id
    , class
    , displayHome
    , closeFolders
    , openFolders
    , showCurrentChildrenOnly
    , liClass
    , liHasKidsClass
    , liHasKidsAttributes
    , liCurrentClass
    , liCurrentAttributes
    , liHasKidsNestedClass
    , aHasKidsClass
    , aHasKidsAttributes
    , aCurrentClass
    , aCurrentAttributes
    , ulNestedClass
    , ulNestedAttributes
    , aNotCurrentClass
    , siteid
    , complete
)

Parameters

Parameter Type Req/Opt Default Description
viewDepth Numeric Opt 1

Expects a numeric value to indicate how 'deep' each top level nav should go when listing its children. It is not recommended to set this greater than 1 or 2 due to the overhead required to parse a node's 'current' location and permissions. Setting it to a '0' results in no dropdowns or more specifically, no output of links to child nodes.

id String Opt navPrimary

This is the id attribute of the opening <ul> element used to output primary navigation.

class String Opt

This is the class attribute of the opening <ul> element used to output primary navigation.

displayHome String Opt conditional

This controls whether or not a 'Home' link appears in the primary navigation. Valid options are:

  • conditional - does not display a link to 'Home' when viewing the Home page itself, but will display at all other times
  • always - a link to 'Home' will appear at all times
  • never - a link to 'Home' will never appear
closeFolders string Opt

This controls the visibility of a Folder's child links. Valid options are:

  • true
  • false
  • A comma-delimited list of ContentID's (found on the 'advanced' tab of any content item).
openFolders string Opt

This controls the visibility of a Folder's child links. Valid options are:

  • true
  • false
  • A comma-delimited list of ContentID's (found on the 'advanced' tab of any content item).
showCurrentChildrenOnly boolean Opt false

This controls the visibility of a content item's child links. If true, then child links will only appear for the section currently being viewed on the front end of the site. This can be useful when creating a vertical oriented navigation. Valid options are:

  • true
  • false
liClass string Opt

Controls the class attribute of <li> elements.

liHasKidsClass string Opt

Controls the class attribute of <li> elements that have children.

liHasKidsAttributes string Opt

Optionally pass in any additional attributes to output with <li> elements that have children.

liCurrentClass string Opt

Control the class attribute of the current <li> element.

Also configurable via the Site or Theme contentRenderer.cfc's this.liCurrentClass setting.

liCurrentAttributes string Opt

Optionally pass in any additional attributes to output with the current <li> element.

liHasKidsNestedClass string Opt

Control the class attribute of any <li> element that has children. Useful for adding markup that will include icons such as arrows, etc.

Also configurable via the Site or Theme contentRenderer.cfc's this.liHasKidsNestedClass setting.

aHasKidsClass string Opt

Control the class attribute of <a> elements that have children.

aHasKidsAttributes string Opt

Optionally pass in any additional attributes to output with <a> elements that have children.

aCurrentClass string Opt current

Control the class attribute of the current <a> element.

Also configurable via the Site or Theme contentRenderer.cfc's this.aCurrentClass setting.

aCurrentAttributes string Opt

Optionally pass in any additional attributes to output with the current <a> element.

Also configurable via the Site or Theme contentRenderer.cfc's this.aCurrentAttributes setting.

ulNestedClass string Opt

Control the class attribute of <ul> elements that are nested within other <ul> elements.

ulNestedAttributes string Opt

Optionally pass in any additional attributes to output with <ul> elements that are nested within other <ul> elements.

aNotCurrentClass string Opt

Control the class attribute of all <a> elements that are not currently active or currently being viewed.

Also configurable via the Site or Theme contentRenderer.cfc's this.aNotCurrentClass setting.

siteID string Opt $.event('siteid')

You can optionally pass in a SiteID from another site managed under the same installation. It default's to the SiteID of the site currently being visited.

complete boolean Opt false

If true, links are output with the full URL, including the domain. Valid options are:

  • true
  • false

Usage

Use this function to output primary navigation.

Example

The following example outputs the primary nav up to two-levels deep.

<cfoutput>
    <nav>
       #m.dspPrimaryNav(
           viewDepth=2
           , id='navPrimary'
           , class='nav navbar-nav'
           , displayHome='always'
           , closeFolders=false
           , showCurrentChildrenOnly=false
           , ulNestedClass='dropdown-menu'
           , liHasKidsNestedClass='dropdown-submenu'
           , aHasKidsClass='dropdown-toggle'
           , aHasKidsAttributes='role="button" data-toggle="dropdown" data-target="##"'
        )#
   </nav>
</cfoutput>

dspBody

A Mura Scope helper method to dynamically output the body/content of a content item. This function automatically checks the content type, and displays output accordingly (e.g., if a Mura "Folder" or "Calendar", will output the children). Additionally, Mura checks to see if the content is restricted/protected, and if so, checks to see if the current user is logged in. If not logged in, will display a login screen. If user is logged in and does not have the required permissions, Mura will display a message to the user in lieu of the content.

Function Syntax

m.dspBody(
    body
    , pageTitle
    , crumbList
    , crumbSeparator
    , showMetaImage
    , metaImageSizeArgs
    , metaImageClass
    , includeMetaHREF
)

Parameters

Parameter Type Req/Opt Default Description
body string Opt m.content('body')

This is the primary content/body of a content item. If you omit this parameter, Mura will automatically use the content/body of the current content item.

pageTitle string Opt empty string

If you wish to display a title above the body/content, you may optionally pass in a title. For example: m.content('title')

crumbList boolean Opt true

If true, will display breadcrumb links above the body/content. Valid options are:

  • true
  • false
crumbSeparater string Opt &raquo;&nbsp;

If crumbList=true, the string passed in here will be used as a delimiter between the links.

showMetaImage boolean Opt true

If true, will display the content item's associated image. Valid options are:

  • true
  • false
metaImageSizeArgs struct Opt {size='medium'}

An object/struct (list of key-value pairs) to be passed to the m.content().getImageURL(args) function. Commonly used keys are:

  • size (string, req). Valid values are:
    • small
    • medium
    • large
    • custom
    • Or, any pre-defined image size
  • height (opt). If size='custom', pass in desired height in pixels.
  • width (opt). If size='custom', pass in desired width in pixels.
metaImageClass string Opt empty string

This is the class attribute of the <img> tag for the associated image.

includeMetaHREF boolean Opt true

If true, will wrap the content item's associated image with <a> tags and a link to the content item. Valid options are:

  • true
  • false

Usage

Use this function to output the main content/body of a content item.

Example

The following example outputs the content/body, without a page title or breadcrumbs, while outputting the associated image (if one exists) using the 'medium' image size.

<cfoutput>
    <article>
        #m.dspBody(
            body=m.content('body')
            , pageTitle=''
            , crumbList=false
            , showMetaImage=true
            , metaImageSizeArgs={size='medium'}
        )#
   </article>
</cfoutput>

dspObjects

A Mura Scope helper method to dynamically output the display objects assigned to display regions.

Function Syntax

m.dspObjects( columnID )

Parameters

Parameter Type Req/Opt Default Description
columnID numeric Req

Enter the desired display region number as defined under Site Settings > Edit Settings, Display Regions tab. The region number is determined by "^" delimited list position of Display Region Names, starting with "1" (not zero). For example, if the Display Region Names were "Left Column^Main Content^Right Column" and you wanted to output display objects assigned to the "Main Content" region, you would pass the number "2" for the columnID parameter.

Usage

Use this function to output display objects assigned to specific display regions.

Examples

The following example outputs display objects assigned to the second display region as defined under Site Settings > Edit Settings, Display Regions tab, Display Region Names list position.

<cfoutput>
    <article class="display-objects-wrapper">
        #m.dspObjects(2)#
    </article>
</cfoutput>

Default Settings Example

The following is merely a simple reference to output the display regions as initially set up in Mura. However, you will want to verify your settings defined under Site Settings > Edit Settings, Display Regions tab, and adjust accordingly.

<cfoutput>
    <!--- Left Sidebar/Column Display Objects --->
    <aside class="left-sidebar display-objects-wrapper">
        #m.dspObjects(1)#
    </aside>

    <!--- Main Content Display Objects --->
    <article class="main-content display-objects-wrapper">
        #m.dspObjects(2)#
    </article>

     <!--- Right Sidebar/Column Display Objects --->
    <aside class="right-sidebar display-objects-wrapper">
        #m.dspObjects(3)#
    </aside>
</cfoutput>

dspObject

A Mura Scope helper method to dynamically output specific types Mura display objects such as components, forms, and more.

Function Syntax

m.dspObject(
    object
    , objectid
    , siteid
)

Parameters

Parameter Type Req/Opt Default Description
object string Req

The type of object you wish to display. Valid options are:

  • plugin
  • feed
  • feed_no_summary
  • category_summary
  • category_summary_rss
  • tag_cloud
  • site_map
  • related_content
  • component
  • form
objectID string Req*

The Object ID or Title/Name of the object. *The following objects do not require an objectID:

  • category_summary
  • category_summary_rss
  • tag_cloud
  • site_map
  • related_content
siteID string Opt empty string

Optionally pass a different SiteID, if you wish to display an object from another site under the same instance of Mura.

Usage

Use this function to output specific types of Mura display objects.

Examples

Listed below are some examples of how to render specific types of Mura display objects.

Component

The following example outputs a "Component" named "Footer".

<cfoutput>
    <footer>
        #m.dspObject(object='component', objectid='Footer')#
    </footer>
</cfoutput>

Form

The following example outputs a "Form" named "Contact Us".

<cfoutput>
    <aside class="contact-us-wrapper">
        #m.dspObject(object='form', objectid='Contact Us')#
    </aside>
</cfoutput>

Category Summary

The following example outputs a "Category Summary" display object. Keep in mind, this will only output something if the section of the site you're currently viewing actually has categorized content.

<cfoutput>
    #m.dspObject(object='category_summary')#
</cfoutput>

outputMuraCSS

A Mura Scope helper method to dynamically output links to Mura's stylesheets to account for basic styling of Mura-generated output. Just to clarify, including Mura's CSS is completely optional. However, using it can save you loads of time in the long run.

Function Syntax

m.outputMuraCSS(
    version
    , includeskin
    , complete
    , useprotocol
)

Parameters

Parameter Type Req/Opt Default Description
version string Opt 7.1 A string to allow for backward-compatibility. For example, if your theme was originally created for 7.0, you may pass "7.0" as the value. However, keep in mind that prior versions of Mura's CSS may not account for newer Mura-generated markup.
includeskin boolean Opt true

If true, Mura will include a separate stylesheet to account for some very basic

complete boolean Opt false If true, Mura will include the domain for the "href" attribute(s) of the auto-generated <link> elements. If false, Mura will omit the domain, and include the absolute path to Mura's CSS.
useprotocol boolean Opt true If true, and complete=true, Mura will include the "protocol" for the "href" attribute(s) of the auto-generated <link> elements. For example, <link rel="stylesheet" href="https://yourdomain/...">.

Usage

Use this function to include Mura's own CSS for basic styling of Mura-generated output.

Example

The following example outputs Mura's CSS

<cfoutput>
  <!--- Always include this _before_ any custom CSS --->
  #m.outputMuraCSS(version='7.1', includeskin=true)#

  <!--- Custom CSS should go here --->
</cfoutput>

Illustrated below is an example of a theme without Mura-generated CSS.

Below is an illustration of the same example as above, using Mura-generated CSS.

The differences are even more noticeable when you are creating a custom theme from scratch.

createCssHook

A Mura Scope helper method to dynamically create CSS-friendly hooks for use within your layout templates. Pass in any string of text, and Mura will strip out CSS-unfriendly characters (e.g., script tags, HTML tags, etc.), and create a CSS-friendly string. Spaces, underscores, and bad characters (such as entity-encoded characters, etc.) are replaced with hyphens. Any capital letters are converted to lowercase. If the first character is numeric or begins with a hyphen, the character will be stripped from the resulting string.

Function Syntax

m.createCssHook( text )

Parameters

Parameter Type Req/Opt Default Description
text string Req

A string to use to create a CSS-friendly hook with.

Usage

Use this function to create CSS-friendly hooks.

Example

The following example outputs a class of "body-" and is appended with a CSS-friendly hook based on a content item's "Title".

<cfoutput>
    <body class="body-#m.createCssHook(m.content('title'))#">
        ...
    </body>
</cfoutput>

In the example above, if the "Title" was "About Us", the output would result in the the following.

<body class="body-about-us">
    ...
</body>

getURLForImage

A Mura Scope helper method to output the URL for an image based on a fileID. The result can then be used to populate the src attribute of a HTML image tag (<img>) to display the image via a browser.

Function Syntax

m.getURLForImage(
    fileID
    , size
    , complete
    , height
    , width
    , siteID
)

Parameters

Parameter Type Req/Opt Default Description
fileID string Req

The fileID as stored in Mura's database to use as the source image file.

size string Opt large

The image size to use. Valid options are:

  • small
  • medium
  • large
  • custom
  • Or, any pre-defined image size
complete boolean Opt false If true, will output the entire path to the image, including the domain. If false, will output the absolute path to the image, from the webroot.
height numeric* Opt AUTO If size parameter is set to custom, you may pass in your desired height in pixels. Or, if passing in the width parameter, you may use AUTO, and Mura will maintain the aspect ratio of the original source image.
width numeric* Opt AUTO If size parameter is set to custom, you may pass in your desired width in pixels. Or, if passing in the height parameter, you may use AUTO, and Mura will maintain the aspect ratio of the original source image.
siteID string Opt SiteID of the current request context If you wish to obtain an image from another site hosted under the same instance of Mura, you may optionally pass the desired siteID.

Usage

Use this function to output the path to a Mura image. If an invalid fileID is used, the result will be an empty string.

Examples

There are several ways you can use this method. Using Class Extensions (covered in the Mura Developer Guide), there could be any number of associated images to a content item. Using the fileID of any image, you can use the following examples to output an image.

The examples use a simple bit of CFML logic first, to make sure the image actually exists. For more information on the CFML tag cfif, please visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-i/cfif.html.

Large Image

The following example outputs a Large image of the current content item. This is very similar to the Get Associated Image example found under the content object section.

<cfoutput>
    <cfif Len(m.getURLForImage(fileid=m.content('fileid')))>
        <img src="#m.getURLForImage(fileid=m.content('fileid'))#">
    </cfif>
</cfoutput>

Medium Image

The following example outputs a Medium image of the current content item.

<cfoutput>
    <cfif Len(m.getURLForImage(fileid=m.content('fileid')))>
        <img src="#m.getURLForImage(fileid=m.content('fileid'), size='medium')#">
    </cfif>
</cfoutput>

Medium Image with Alt Attribute

The following example outputs a Medium image of the current content item, and populates the alt attribute of the <img> tag with the content item's Title.

<cfoutput>
    <cfif Len(m.getURLForImage(fileid=m.content('fileid')))>
        <img  src="#m.getURLForImage(fileid=m.content('fileid'), size='medium')#"
              alt="#esapiEncode('html_attr', m.content('title'))#">
    </cfif>
</cfoutput>

Site Placeholder Image

As covered under How to Manage Image Sizes, each site can have a Placeholder Image. This example demonstrates how to output a placeholder image.

<cfoutput>
    <cfif Len(m.getURLForImage(fileid=m.siteConfig('placeholderImgID')))>
        <img  src="#m.getURLForImage(fileid=m.siteConfig('placeholderImgID'))#">
    </cfif>
</cfoutput>

Display Site Placeholder Image if Associated Image Doesn't Exist

The example below is useful for when you want to output the placeholder image for content that doesn't have an associated image.

<cfoutput>
    <cfif Len(m.getURLForImage(fileid=m.content('fileid')))>
        <img  src="#m.getURLForImage(fileid=m.content('fileid'))#">
    <cfelseif Len(m.getURLForImage(fileid=m.siteConfig('placeholderImgID')))>
        <img src="#m.getURLForImage(fileid=m.siteConfig('placeholderImgID'))#">
    </cfif>
</cfoutput>

content

A Mura Scope object, (also referred to as a "subscope" of the Mura Scope), that provides access to several helper methods for the Content Item in the current request context, as well as easy access to its attributes.

Function Syntax

m.content( property, propertyValue )

Parameters

Parameter Type Req/Opt Default Description
property string Opt  

Optionally pass in an attribute name, and Mura will return its value (unless a propertyValue is also provided). If the property parameter is omitted, Mura will return a content object, which has several helper methods associated to it.

propertyValue any Opt  

If you pass in a property, you may optionally "set" the value of the property by passing in a value to this parameter. If you leave this parameter empty, Mura will return the actual value stored in the database for the requested property.

Usage

Use this function to "get" and/or "set" values of the content item. The content object also has a number of helper methods, very useful for theme developers, and are noted below under the Examples.

Examples

Note: Some of the examples below make use of esapiEncode to encode a given string for safe output to stop Cross Site Scripting attacks.

Content Title

The following example outputs the "Title" of the content item in the current request context.

<cfoutput>
    <h2>
        #esapiEncode('html', m.content('title'))#
   </h2>
</cfoutput>

HTML (Browser) Title

The following example outputs the "HTML (Browser) Title" of the content item in the current request context.

<cfoutput>
    <title>
        #esapiEncode('html', m.content('HTMLTitle'))#
    </title>
</cfoutput>

You could also combine this with the siteConfig's "Site Name" attribute, to have a full <title> for your theme's layout template.

<cfoutput>
    <title>
        #esapiEncode('html', m.content('HTMLTitle'))# - 
        #esapiEncode('html', m.siteConfig('site'))#
   </title>
</cfoutput>

Content Summary

The following example outputs the "Summary" of the content item in the current request context.

<cfoutput>
    <article>
        #m.content('summary')#
   </article>
</cfoutput>

If you want Mura [m] Tags to render, you will want to wrap the output with m.setDynamicContent().

<cfoutput>
    <article>
        #m.setDynamicContent(m.content('summary'))#
   </article>
</cfoutput>

Date Created

This example outputs the date the content item was originally created on. For more information on the CFML tag DateFormat, please visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-c-d/DateFormat.html

<cfoutput>
    <p>
        Date Created: #DateFormat(m.content('created'), 'YYYY-MM-DD')#
   </p>
</cfoutput>

Date Last Updated

This example outputs the date the content item was last updated.

<cfoutput>
    <p>
        Date Last Updated: #DateFormat(m.content('lastUpdate'), 'YYYY-MM-DD')#
   </p>
</cfoutput>

Last Updated By

This example outputs the first and last name of the content manager who last updated the content item.

<cfoutput>
    <h2>
        Last Updated By: #esapiEncode('html', m.content('lastUpdateBy'))#
   </h2>
</cfoutput>

Credits (Author)

This example outputs the "Credits" attribute (from the Publishing tab).

<cfoutput>
    <h2>
        Author/Credits: #esapiEncode('html', m.content('credits'))#
   </h2>
</cfoutput>

Meta Description

This example shows how to output text entered into the Meta Description field.

<cfoutput>
    <meta name="description" content="#esapiEncode('html_attr', m.content('metaDesc'))#">
</cfoutput>

Meta Keywords

This example shows how to output text entered into the Meta Keywords field.

<cfoutput>
    <meta name="keywords" content="#esapiEncode('html_attr', m.content('metaKeywords'))#">
</cfoutput>

Get Associated Image

This example shows how to output the primary associated image of a content item. It uses a simple bit of CFML logic first, to make sure an image actually exists. For more information on the CFML tag cfif, please visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-i/cfif.html

<cfoutput>
    <cfif Len(m.content().getImageURL('medium'))>
        <img src="#m.content().getImageURL('medium')#">
    </cfif>
</cfoutput>

Inspecting Available Attributes

This example demonstrates how to inspect the available attributes of a content item. For more information the CFML tag cfdump, please visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-d-e/cfdump.html.

<cfdump var="#m.content().getAllValues()#">

component

A Mura Scope object, (also referred to as a "subscope" of the Mura Scope), that provides access to several helper methods for a Component Item in the current request context, as well as easy access to its attributes.

Function Syntax

m.component( property, propertyValue )

Parameters

Parameter Type Req/Opt Default Description
property string Opt

Optionally pass in an attribute name, and Mura will return its value (unless a propertyValue is also provided). If the property parameter is omitted, Mura will return a content object, which has several helper methods associated to it. Mura "components" are really just "content objects" which is why it returns a "content object" and not a "component object."

propertyValue any Opt

If you pass in a property, you may optionally "set" the value of the property by passing in a value to this parameter. If you leave this parameter empty, Mura will return the actual value stored in the database for the requested property.

Usage

Use this function to "get" and/or "set" values of the component item. The content/component object also has a number of helper methods, very useful for theme developers, and are noted below under the Examples.

Examples

Note: Some of the examples below make use of esapiEncode to encode a given string for safe output to stop Cross Site Scripting attacks.

Component Body

The following example outputs the "Body/Content" of the component item in the current request context.

<cfoutput>
    <article>
        #m.component('body')#
   </article>
</cfoutput>

If you want Mura [m] Tags to render, you will want to wrap the output with m.setDynamicContent().

<cfoutput>
    <article>
        #m.setDynamicContent(m.component('body'))#
   </article>
</cfoutput>

Component Title

The following example outputs the "Title" of the component item in the current request context.

<cfoutput>
    <h2>
        #esapiEncode('html', m.component('title'))#
   </h2>
</cfoutput>

Date Created

This example outputs the date the content item was originally created on. For more information on the CFML tag DateFormat, please visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-c-d/DateFormat.html

<cfoutput>
    <p>
        Date Created: #DateFormat(m.component('created'), 'YYYY-MM-DD')#
   </p>
</cfoutput>

Date Last Updated

This example outputs the date the component item was last updated.

<cfoutput>
    <p>
        Date Last Updated: #DateFormat(m.component('lastUpdate'), 'YYYY-MM-DD')#
   </p>
</cfoutput>

Last Updated By

This example outputs the first and last name of the content manager who last updated the component item.

<cfoutput>
    <h2>
        Last Updated By: #esapiEncode('html', m.component('lastUpdateBy'))#
   </h2>
</cfoutput>

Inspecting Available Attributes

This example demonstrates how to inspect the available attributes of a component item. For more information the CFML tag cfdump, please visit https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-d-e/cfdump.html.

<cfdump var="#m.component().getAllValues()#">

siteConfig

A Mura Scope object, (also referred to as a "subscope" of the Mura Scope), that provides access to several helper methods for the Site Settings in the current request context, as well as easy access to its attributes.

Function Syntax

m.siteConfig( property, propertyValue )

Parameters

Parameter Type Req/Opt Default Description
property string Opt  

Optionally pass in an attribute name, and Mura will return its value (unless a propertyValue is also provided). If the property parameter is omitted, Mura will return a site settings object, which has several helper methods associated to it.

propertyValue any Opt  

If you pass in a property, you may optionally "set" the value of the property by passing in a value to this parameter. If you leave this parameter empty, Mura will return the actual value stored in the database for the requested property.

Usage

Use this function to "get" and/or "set" values of the Site Settings. The siteConfig object also has a number of helper methods, very useful for theme developers, and are noted below under the Examples.

Examples

Note: Some of the examples below make use of esapiEncode to encode a given string for safe output to stop Cross Site Scripting attacks.

Theme Asset Path

The following example outputs the a relative path to where your site's theme files reside on the server.

<cfoutput>
    <p>
        #m.siteConfig('themeAssetPath')#
    </p>
</cfoutput>

This is useful for when you may want to create dynamic links to your theme's CSS files. Otherwise, you would have to hard-code the path yourself, which makes it difficult for long-term maintenance since your theme could be hosted in different environments, and the paths could be completely different. For example, if you want to include your theme's CSS, you could use the following code example.

<cfoutput>
    <!--- Your Theme's Styles --->
    <link rel="stylesheet" href="#$.siteConfig('themAssetPath')#/css/your-styles.css">
</cfoutput>

Site Name

The following example outputs the "Site Name" of the site being accessed in the current request context.

<cfoutput>
    <header>
        <a class="navbar-brand" href="/">
            #esapiEncode('html', m.siteConfig('site'))#
        </a>
    </header
</cfoutput>

Site Tagline

The following example outputs the "Site Tagline" of the site being accessed in the current request context.

<cfoutput>
    <header>
        <p>
            #esapiEncode('html', m.siteConfig('tagline'))#
        </p>
    </header
</cfoutput>

Site ID

The following example outputs the "Site ID" of the site being accessed in the current request context.

<cfoutput>
    #esapiEncode('html', m.siteConfig('siteID'))#
</cfoutput>

Domain

The following example outputs the "Domain" of the site being accessed in the current request context.

<cfoutput>
    #esapiEncode('html', m.siteConfig('domain'))#
</cfoutput>

Inspecting Available Attributes

This example demonstrates how to inspect the available attributes of the Site Settings using the CFML tag cfdump.

<cfdump var="#m.siteConfig().getAllValues()#">

What Can I Use?

Theme developers often come to the table with their custom toolbox of frameworks, libraries, and development methodologies. A (formerly) frequently asked question from theme developers was, "What can I use with Mura?" In other words, they wanted to know which, if any, of the tools in their toolbox they could pull out and apply to their Mura theme development process.

Use any front-end framework you want.

Most theme developers know that using a front-end framework makes theme development faster and easier. However, there are so many options to pick from. It doesn't matter to Mura whether you're using Bootstrap, Semantic UI, Foundation, or any other front-end framework. Use the one that best suits the needs of your project or personal taste.

Use any JavaScript library or framework you want.

Because Mura's front end uses Mura JS as its internal library for DOM manipulation and client-side interaction, you can consider Mura as a Vanilla environment into which you can integrate your own choice of libraries and frameworks. This includes everything from jQuery up to advanced frameworks like Vue JS, React and Angular. As we've previously mentioned throughout the documentation, you can even replace the Theme-based, server-rendered version of Mura's front end with a Decoupled or Headless front end.

In other words ...

Use pretty much anything you want. Period.

Customizing Default Output

Throughout this section, you'll learn how to customize some of Mura's default display output. For example, you'll learn how to customize your own "404: Page Not Found" screen, and how to instruct Mura to use your own "Error" page. In addition, you'll learn how to customize Mura's web editor (CKEditor), as well as how to create and use custom image sizes for your website(s).

 

Custom 404 Page

When a visitor stumbles upon content that doesn't exist on your Mura website, they are presented with a "404" page. This simply means the server could not find the requested URL. For example, you may see something similar to the following illustration when visiting a Mura site that's using the default text.

By follow the steps outlined below, you can customize the default "404" page however you wish.

  1. From the back-end administrator of Mura, select Content from the main navigation.
  2. On the Tree View tab, locate the three-dot menu next to the top-most content item, usually labeled Home.
  3. Click the three-dot menu of the Home page, and select Add Content.
  4. From the Select Content Type dialog window, select Page.
  5. Enter your desired Title. For example, "Page Not Found".
  6. Click the Show Additional Content Titles button.
  7. Locate the URL Title (Optional) field, and enter 404.

    Note: This is the crucial part of this process! If you skip this step, Mura will not use this content item as your custom 404 page.

  8. In the Content area, enter your desired text and/or images.
  9. Select the Publishing tab.
  10. On the Publishing tab, deselect Include in Site Navigation, and enable Exclude from Site Search to prevent it from appearing in search results.
  11. Select the Layout tab.
  12. On the Layout tab, select your desired Layout Template, and set the Inheritance Rules to Start New Cascade so that any display objects assigned to the Home page don't display on the 404 page.
  13. Select Publish to save your new 404 page.
  14. Now, whenever anyone visits a page that doesn't exist in Mura, they should be presented with your custom 404 page.

Custom Error Page

If your website has any CFML errors, Mura will display information about that error by default. However, in a production environment, you probably don't want visitors to your website, or the general public, to see these errors. In most cases, you probably want to display a special "Site Error" message, and possibly log information about the error.

Mura offers a few settings to control whether or not you want these errors to display. If you don't want the errors to display, you can then supply a path to a specific file for Mura to use instead of its default.

Before proceeding, you may want to purposefully create an error, so you can see what happens by default. For example, if you edit a content item, and use some Mura [m] tags to output an undefined variable, you will generate an error.

In the example above, we're attempting to output variable "x" which is not defined anywhere. So, because it's undefined, and Mura displays errors by default, the following image illustrates the generated error message.

How To Enable/Disable Error Messages

You can choose to enable or disable error messages, or debugging information, to appear for site visitors by following the steps below.

  1. Open the file located at {context}/config/settings.ini.cfm
  2. Locate the setting labeled debuggingenabled
    • true
      • If set to true, error messages will appear to site visitors.
    • false
      • If set to false, error messages will not appear to site visitors, and a special "Error" screen will be displayed instead.
  3. Save the file.
  4. Reload Mura for the settings to take effect.

How To Create A Custom Error Screen

Mura will only display a custom error screen when error messages are disabled. So, before proceeding, you will need to follow the steps under How to Enable/Disable Error Messages, and set debuggingenabled to false.

Once you've disabled error messages, follow the steps below to use your custom error screen.

  1. Open the file located at {context}/config/settings.ini.cfm.
  2. Locate the setting labeled errortemplate. By default, the errortemplate setting is set to /muraWRM/core/templates/error.html.
  3. The default error template points to the file located under {context}/core/templates/error.html.
  4. The error.html file simply generates the following screen by default.
  5. Do not modify the error.html file directly. If you do, you run the risk of the file being overwritten after performing a "core" update.
  6. Instead, create a new file with whatever you want to appear, and save it under your desired directory (e.g., {context}/config/custom-error-file.html). Technically, you could save it wherever you want under Mura, but you'll have to be aware of the file path for the next step. The illustration below shows a new file labeled "custom-error-file.html" and the file contains some simple HTML. You could create and use a custom CFML file as well, if desired.
  7. Next, we need to update the errortemplate setting to point to the newly created file.
  8. Save the file.
  9. Reload Mura for the new settings to take effect.

Image Sizes

Most content types in Mura have a field labeled Assign Associated Image located on the Basic tab of the Edit Content screen. Your Mura Developers may also have created additional image fields, which all function the same way as Associated Images.

When you upload an Image, Mura automatically creates three (3) different sizes of the image. You can see these images on the Image Details screen by clicking the crop marks button.

The three (3) primary image sizes are labeled Small, Medium, and Large, and you can see a preview of each image, as well as have the ability to select a different crop region.

To modify image sizes in Mura, visit How to Manage Image Sizes. Also, if you're interested in how to display associated images and/or site placeholder images, visit the getURLForImage page under the Template Variables & Helper Methods section.

How to Manage Image Sizes

Mura allows you the ability to modify default image sizes (Small, Medium, and Large), as well as the option to create additional, pre-defined image sizes. Having pre-defined image sizes allows your content managers the ability to upload an image, and then select their desired crop region. This is quite useful to avoid issues where a person's head, or some other desired feature of the photo may be removed during the automatic cropping process.

Follow the steps below to manage image sizes in Mura.

  1. From the back-end administration area of Mura, select Site Settings on the main navigation, and click Edit Settings.
  2. Select the Images tab.
  3. The Images tab contains the dimensions of the default images sizes (Small, Medium, Large), as well as any Custom Images.
    • Small
      • This is the default image size used on Folder content types for any listed child content.
    • Medium
      • This is the default image size used by Mura when using the dspBody template helper method, and setting showMetaImage to true.
    • Large
      • This is the default image size used to display when clicking the Medium image, if being output by dspBody and setting includeMetaHref to true.
  4. To modify the dimensions of any default image sizes, simply enter your desired Height and/or Width settings.
  5. To add a new custom image, click the Add Custom Image Size button.
    1. The Add Custom Image Size window should appear.
    2. Enter a Name for the image. The Name should not have any spaces or special characters in it (other than hyphens). Be aware that invalid characters and spaces will be removed upon saving anyway. Also note that any capital letters will be converted to lowercase.
    3. You may also enter your desired Height and/or Width in pixels. You may optionally specific only one of these attributes, and leave the other as "AUTO" for Mura to make crops proportionately to the original image size.
    4. Click the Save button to save your new custom image size.
    5. Your new custom image size should appear in the listing of custom images.
  6. To edit the dimensions of any Custom Images, click the pencil icon next to the custom image name.
    • If you click the pencil icon, the Edit Custom Image Size window should appear.
    • Enter your desired Height and/or Width in pixels, and click the Save button to save your changes.

  7. You can also upload a Placeholder Image that can be used for content items that haven't had an Associated Image uploaded.
  8. When you've finished making your edits, click the Save Settings button, to save your changes.

Summary

Throughout this section, you learned how to customize some of Mura's default display output. We covered customizing your very own "404: Page Not Found" page, and how to create your own "Error" screen. You also learned how to make some significant changes to Mura's web editor (CKEditor), as well as how to create and use your own image sizes for your site.

Your journey doesn't have to end here for customizing Mura. Be sure to check out the Extending Mura guide.