The "config" Directory

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

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.

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.

{context}/sites/default/

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.

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.

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 display object 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 Settings > Sites view.
   

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/default/ 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.
   

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.