Mura 10: Extending Mura

Lifecycle Events vs. Contextual Events

Before you continue through this section, you'll need to understand the differences between Mura's lifecycle events and Mura's contextual events.

• "Lifecycle" events generally get triggered on every page request, and represent the execution of Mura's normal request flow. Mura consists of two unique lifecycles: the Front-end Lifecycle, and the Admin Lifecycle.
• "Contextual" events aren't triggered on every page request, because they occur in response to the specific event(s) or action(s) that preceded them.

For example, Mura-related events that occur when editing a "User" are only triggered when a user is being created or updated, and would not necessarily be triggered in the course of a normal front-end request.

Note: Contextual events only contain data that is directly supplied to it by the Mura core. If you need to access to the full event scope itself (i.e., during a front-end or admin rendering event), it can be accessed via m.getGlobalEvent().

Mura "event" Scope

When working with events, keep CFML's scopes in mind. As noted in the Mura Scope section, in addition to the CFML scopes, Mura has its own scope called the Mura Scope.

The Mura Scope has a special subscope called the "event" scope, and it is created on every request. It can be referenced via m.event(). If you need to access the global event scope from within a contextual event, you may use m.getGlobalEvent().

Mura's event scope wraps CFML's request, form, and URL scopes. Mura also injects additional data and helper methods into the event scope, and the availability of the data is dependent upon the context in which you may be accessing it. As covered in the Mura Objects section, you may also store your own data in Mura's event scope for use within your own application logic.

Syntax

You can use the following examples to "get" and/or "set" various attributes of Mura's event scope. Use whichever syntax feels best to you.

Getters

m.event('attributeName')
m.event().get('attributeName')
m.event().get{AttributeName}()
m.event().getValue('attributeName')

Setters

m.event('attributeName', 'someValue')
m.event().set('attributeName', 'someValue')
m.event().set{AttributeName}('someValue')
m.event().setValue('attributeName', 'someValue')

Event Hooks

In this section, we'll cover Mura's various event hooks/methods, or trigger points, you can use to either add to, or even replace Mura's business logic and functionality.

One thing you'll want to think of when using this section is determining the point(s) in which you wish to add your logic. For example, are you trying to do something that occurs while the Mura application is loading up? Or, are you attempting to do something during a normal, front-end request? Are you trying to do something when a content item is being updated? Maybe you're attempting to do something when a session begins. These are all good questions that can point you in the right direction. Once you've determined the answers to these types of questions, you can dig into the available event hooks, register your event handlers, and implement your custom application logic.

Also, when working with Mura events, keep in mind that all events are automatically passed in the Mura (m) scope as an argument. The example below illustrates a sample method with the argument being passed in.

public any function onSomeEvent(m) {
  // do something here
}

To can obtain the event scope via the Mura scope, follow the example below.

public any function onSomeEvent(m) {
  // obtain the `event` scope via the Mura Scope
  var e = arguments.m.event();
}

Keep in mind when working with some contextual events, you may need to access the "global" event scope itself. The example below demonstrates accessing the global event, if necessary.

public any function onSomeEvent(m) {
  // access the global event scope
  var globalEvent = arguments.m.getGlobalEvent();
}

Finally, you may add any of these events to a registered event handler, in order for Mura to execute them. See the Event Handlers section for more information.

Event Prefixes

As you review the available events, you'll notice a common naming convention. Mura's events all start with a prefix, which informs you whether you're replacing Mura's business logic, or adding to Mura's business logic. Keep the following information in mind as you dive into the rest of this section.

• standard{Event}
  • All "standard" events are points where you can replace Mura's business logic and functionality. These events are all defined within the file located at {context}/core/mura/Handler/standardEventsHandler.cfc
• on{Event}
  • All "on" events are points where you can add to Mura's business logic and functionality. The important thing to understand about "on" events is that these are not necessarily "defined" anywhere. These types of events are merely "announced" during the normal execution of a request.

Global vs. Site

In addition to the "standard" vs. "on" prefixes, you'll notice many events also have additional common names after the prefix:

• onGlobal{Event}
  • All "global" events are those that occur throughout the entire instance of Mura, and are not bound to any specific site.
• onSite{Event}
  • All "site" events occur site-wide, and are bound to the specific site they have been registered to.

Before vs. After

Another common naming convention includes using the words "before" and "after" to indicate whether something is happening immediately before Mura is about to do something, or after Mura has finished doing something.

• onBefore{Event}
  • All "before" events are announced immediately before Mura is about to execute its normal functionality.
• onAfter{Event}
  • All "after" events are announced immediately after Mura has executed its normal functionality.

on{YourEvent}

m.announceEvent('YourEvent', m);
// OR
m.announceEvent('onYourEvent', m);

<form method="post">
  <input type="text" name="myField" value="[m]esapiEncode('html_attr', m.event('myField'))[/m]">
  <input type="hidden" name="myFormIsSubmitted" value="true">
  <input type="submit">
</form>

// check form submission via `onRenderStart`, and if found, announce your custom event.
public any function onRenderStart(m) {
  if ( arguments.m.event('myFormIsSubmitted') == 'true' ) {
    // announcing the event
    arguments.m.announceEvent('CustomFormSubmitted', arguments.m);
  }
}

public any function onCustomFormSubmitted(m) {
  // you could do whatever you want here
  // including dumping out the entire event itself to inspect it
  // or simply dumping out the value of a specific form filed
  // and then halt the rest of the process (for example only)
  WriteDump(var=arguments.m.event('myField'), abort=true);
}

m.renderEvent('YourEvent');

<cfoutput>
  #esapiEncode('html', m.renderEvent('YourEvent'))#
</cfoutput>

eventOutput = esapiEncode('html', m.renderEvent('YourEvent'));

if ( Len(eventOutput) ) {
  WriteOutput(eventOutput);
} else {
  // render something else / default output
}

Event Lifecycles

Lifecycle events are generally triggered on every page request, and represent the execution of Mura's normal request flow. Mura consists of primarily two unique lifecycles: the Front-end Request Lifecycle, and the Admin Request Lifecycle. During the flow of these lifecycles, other contextual events are triggered, and are dependent upon the requested action that precedes it.

onGlobalRequestStart
  onAdminRequestStart

    onAdminHTMLHeadRender         // renders just before the closing </head> tag

      onAdminMFAChallengeRender   // Multi-factor Auth area of login screen

      onDashboardReplacement      // render a completely new dashboard

      onDashboardPrimaryTop       // renders in the top of the dashboard
      onDashboardPrimaryBottom    // renders in the bottom of the dashboard
      onDashboardSidebarTop       // renders in the top of the dashboard sidebar
      onDashboardSidebarBottom    // renders in the bottom of the dashboard sidebar

      onAdminNavMainRender        // render additional main nav menu items
      onFEToolbarExtensionRender  // render additional front-end toolbar menu items
      
      on{Type}SecondaryNavRender
      on{Type}{Subtype}SecondaryNavRender

      on{Type}{Subtype}NewContentMenuRender
      onNewContentMenuRender

    onAdminHTMLFootRender         // renders just before the closing </body> tag

  onAdminRequestEnd
onGlobalRequestEnd

onGlobalRequestStart
  onSiteRequestInit
  onSiteRequestStart

    standardEnableLockdownValidator
      standardEnableLockdownHandler // if lockdown enabled

    standardSetContentHandler
      // if `previewid` exists
      standardSetPreviewHandler 
      // else
      standardSetAdTrackingHandler

      standardWrongFilenameValidator
        standardWrongFilenameHandler // if wrong filename

      standard404Validator
        standard404Handler // contextual: if content item not found
          onSite404 
    
    standardWrongDomainValidator
      standardWrongDomainHandler // if invalid domain

    standardTrackSessionValidator
      standardTrackSessionHandler // if session tracking enabled

    standardSetIsOnDisplayHandler
    standardDoActionsHandler // checks `doaction` (e.g., login, logout, etc.)

    standardSetPermissionsHandler
    standardRequireLoginValidator
      standardRequireLoginHandler // if login required

    standardSetLocaleHandler
    standardMobileValidator
      standardMobileHandler // if `request.muraMobileRequest` and no `altTheme`

    standardSetCommentPermissions

    standardDoResponseHandler
      standardForceSSLValidator
        standardForceSSLHandler // if necessary

      // This is a great place to put your logic
      // Mura begins compiling the code that will be returned to the browser
      onRenderStart

        // if content type is link
        standardLinkTranslationHandler
        // else if content type is file
        standardFileTranslationHandler
          standardFileTranslator
            onBeforeFileRender
            onAfterFileRender
        // else
        standardTranslationHandler  // sets m.event('__MuraResponse__')
          // if `returnformat` is JSON
          standardJSONTranslator
            onAPIResponse
            on{Type}APIResponse
            on{Type}{Subtype}APIResponse
            onAPIError  // if an error occurs

          // else
          standardHTMLTranslator // parses layout template and renders queues
            // other events could be announced, based on template code
            // `m.dspBody()` invokes several events (and is included in most templates)
            // if event('display') is `search`
            onSiteSearchRender

            // else if event('display') is `editprofile`
            onSiteEditProfileRender

            // else if event('display') is `login`
            onSiteLoginPromptRender

            // else if content is restricted and user not allowed
            onContentDenialRender

            // else if content is not on display
            onContentOfflineRender

            // else if `m.event('display')` is not an empty string
            onDisplayRender  // allows you to have custom displays

            // else
              // default body rendering

              on{Type}{Subtype}BodyRender  // e.g., onPageDefaultBodyRender
              // if a string isn't returned, then
              on{Type}BodyRender  // e.g., onPageBodyRender

              // if a string still isn't returned, then
              // Mura will look for files by content type
              // `../{ThemeName}/content_types/{Type}_{Subtype}/index.cfm`
              // Then, `../{ThemeName}/content_types/{Type}/index.cfm`
              // and so forth.
              // See the "Mura Rendering" section for more information

      // Mura has finished compiling the code to return to the browser
      // In other words, the train is about to leave the station ...
      onRenderEnd  // m.event('__MuraResponse__') is ready

  onSiteRequestEnd
onGlobalRequestEnd

Event Handlers

Mura event handlers are simply ColdFusion components (CFCs), or files saved with the extension .cfc. They contain methods/functions, and may contain other variables and/or data. Most event handlers will contain one or more of Mura's event hooks, and/or custom event hooks.

The event hooks are merely "announced" during specific points of a request. Registered event handlers will be parsed when the event they're registered for occurs, and if any event hooks are found, they will be executed. For example, if you have two registered even handlers, and both of them contain a method listening for the same event hook, both methods will execute, whenever the event is announced.

As described in the Standard Events section, Mura's standard events handler is located under {context}/core/mura/Handler/standardEventsHandler.cfc.
A list of the available methods and properties is available at via Mura's Component API at https://www.murasoftware.com/component-api/10.0/index.html?mura/Handler/standardEventsHandler.html.

Developers may have several Mura event handlers throughout your sites, themes, content types, modules, and plugins.You may also register your event handler(s) for specific entities. In addition, you can choose to register your event handlers by convention, or explicitly register them via a known event handler. Examples and options are described below.

Example Event Handler

With the exception of the "Site" event handler, or the "Theme" event handler, you can name your event handler anything you want, as long as it has the .cfc file extension. All event handlers should extend mura.cfobject. By doing so, you allow yourself the ability to leverage many of Mura's baked-in methods and functionality for working with Mura objects.

CFScript-based .CFC Example

component extends="mura.cfobject" {

  public any function onSomeEvent(m) {
    // arguments.m is "The Mura Scope"
    // Do something
  }

}

Tag-based .CFC Example

<cfcomponent extends="mura.cfobject" output="false">

  <cffunction name="onSomeEvent" access="public" returntype="any">
    <cfargument name="m" hint="Mura Scope">
    <!--- Do something --->
  </cffunction>

</cfcomponent>

Plugin Event Handlers

Plugin event handlers should extend mura.plugin.pluginGenericEventHandler, instead of using the typical mura.cfobject. Doing so allows you access to the plugin's own configuration information via variables.pluginConfig, as well as Mura's configuration data via variables.configBean.

Registering event handlers in plugins is covered in the Plugins section.

{context}/sites/{SiteID}/eventHandler.cfc

{context}/sites/{SiteID}/themes/{ThemeName}/eventHandler.cfc
// OR
{context}/themes/{ThemeName}/eventHandler.cfc

../model/handlers/{anyFilename}.cfc

// Sites
{context}/sites/{SiteID}/content_types/{Type}_{Subtype}/model/handlers/
{context}/sites/{SiteID}/modules/{module}/model/handlers/

// Themes
../themes/{ThemeName}/content_types/{Type}_{Subtype}/model/handlers/
../themes/{ThemeName}/modules/{module}/model/handlers/

m.getBean('pluginManager').addEventHandler( 
  {handlerObject or path}
  , {SiteID} 
);

public any function onApplicationLoad(m) {
  // Assuming the customHandler.cfc file exists in the same directory as this file
  var myHandler = new customHandler();

  // Register the custom handler
  arguments.m.getBean('pluginManager').addEventHandler(
    myHandler
    , arguments.event.get('siteid')
  );
}

public any function onApplicationLoad(m} {
  // This is where our code will be
}

m.getBean('someBean').on( eventName, fn )

public any function onApplicationLoad(m) {

  m.getBean('content')
    .loadBy(title='Contact Us')
    .on('renderStart', function(m) {
      // do something
    });

}

public any function onApplicationLoad(m) {

  m.getBean('user')
    .loadBy(useranme='steve')
    .on('userDelete', function(m) {
      // do something
    });

}

public any function onApplicationLoad(m) {

  m.getBean('configBean')
    .on('onRenderEnd', function(m) {
      // do something
    });

  // OR

  m.globalConfig()
    .on('onRenderEnd', function(m) { 
      // do something   
     }); 

}

public any function onApplicationLoad(m) {

  m.getBean('content')
    .loadBy(title='Information Request Form')
    .on('submitSave', function(m) {
      // do something
    })
    .on('submitResponseRender', function(m) { 
      // do something   
    });

}

public any function onApplicationLoad(m) {

  m.getBean('configBean')
    .on('beforeWidgetSave', function(m) {
      // do something
    })
    .on('widgetSave', function(m) { 
      // do something   
    })
    .on('widgetSave', function(m) {   
      // do something   
    });

}

m.getBean('someBean').addEventHandler( component )

public any function onApplicationLoad(m) {

  m.getBean('configBean')
    .addEventHandler({
      beforeWidgetSave = function(m) {
        // do something
      }
      , widgetSave = function(m) {
        // do something
      }
      , afterWidgetSave = function(m) {
        // do something
      }
    });

}

public any function onApplicationLoad(m) {

  m.getBean('widget')
    .loadBy(id='someID')
    .addEventHandler({
      beforeSave = function(m) {
        // do something
      }
      , save = function(m) {
        // do something
      }
      , afterSave = function(m) {
        // do something
      }
    });

}

Mura's Event Log

Mura has the capability to output an event log as a stack trace, including the time it took to execute, in milliseconds, directly to the browser. This feature is quite useful for troubleshooting and debugging, as well as discovering which areas of your code may benefit from applying performance optimization techniques.

<!--- Place this either at the top of your file, or at the beginning of a block of code you wish to trace --->
<cfset myTracePoint = $.initTracePoint('your filename, method name, or other description to identify this trace point goes here ... this is what will output in the Stack Trace') />

<!--- file content or block of code goes here --->

<!--- Place this either at the bottom of your file, or at the end of a block of code you wish to trace --->
<cfset m.commitTracePoint(myTracePoint) />

Summary

Throughout this section, we covered the differences between lifecycle events and contextual events, the Mura "event" scope, and the wide variety of possible events that may occur during any given request, as well as how to register your own event handlers targeting the specific event(s) related to the task(s) you wish to accomplish. Finally, you learned how to create your own custom events, and how to use Mura's event log for debugging and performance optimization purposes.

We hope that as you completed this section, you have a much better understanding on how you, as a Mura developer, can add to, or in some cases, even replace, Mura's own business logic and functionality.

The "config" Directory

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

[production]
adminemail=steve@blueriver.com
dbtype=mysql
yourCustomKey=Your Value

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

The "themes" Directory

As a Mura Developer, you may spend some 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.

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 Module Directory
  • {RegisteredModuleDirectory}/
  • A pre-registered module directory path.
• 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/core_assets/modules/
  • 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 will learn more about creating custom modules in the Mura Modules & Display Objects section.

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
  • {context}/sites/{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 Internationalization & Localization section.

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

Introduction

Modules are content integrations that come in a variety of types: some are designed for laying out content, such as Headers and Containers, while others provide sophisticated dynamic functionality like Forms and Navigation. Some are placed onto a page via the Layout Manager, while others function in the background and have no visual component at all.

Mura's baked-in modules are managed via the front-end user interface. Modules were formally referred to as "display objects" because often times, that's how the module itself is used. However, a Mura module does not have to contain a "display" of any kind. Modules can be complete applications, or simply contain some custom logic that is triggered based on a desired event.

Note: If you aren't familiar with Mura's default modules (display objects), you should review the Modules of the Using Mura guide, before continuing in this section.

Mura includes a variety of baked-in modules (display objects) by default while offering content managers the ability to quickly and easily add modules such as Collections, Components, Containers, Forms, Navigation, and many more.

Each of Mura's modules contain some server-side logic, basic markup, styling, and sometimes include JavaScript. In this section, you'll learn how to safely modify this logic, markup, styling, and/or JavaScript, and do so without worrying about your changes getting overwritten whenever Mura's files are updated. In addition, you'll learn how to create your own, custom modules too.

Custom Modules

First, create a directory under a known or registered "modules" directory. For example, ../modules/mymodule/. Within the {module} directory, you may have the following files and/or directories:

Example "index.cfm" File

The example below illustrates what an "index.cfm" file could contain. However, you may include your own custom markup, code, and more.

<cfparam name="objectparams.mytext" default="" />

<cfoutput>
  <h2>My Object</h2>

  <cfif Len(objectparams.mytext)>
    <p>
      This object has a configurator, and the value of "objectparams.mytext" is:<br>
      <strong>#esapiEncode('html', objectparams.mytext)#</strong>
    </p>
  <cfelse>
    <!--- No value entered for "objectparams.mytext" --->
  </cfif>
</cfoutput>

If you wish to add any CSS or JavaScript to the browser for your module, you'll need to use MuraJS to help you. The example below leverages the loader() method to load both CSS and JavaScript. Simply add this code to your "index.cfm" file. You may have to change the path(s) to match your specific directory structure, and needs.

<!--- Add the following to your "index.cfm" file --->
<script>
  Mura(function(m) {
    m.loader()
      .loadcss(m.themepath + '/modules/myobject/my.css')
      .loadjs(
        m.themepath + '/modules/myobject/my.js',
        m.themepath + '/modules/myobject/other.js',
        function() {
          // Do something with the loaded JS, if desired
        }
      );
  });
</script>

Visit the MuraJS section to learn more about Mura.loader() capabilities.

Rendering Via JavaScript

If your module will be rendered using only JavaScript, your index.cfm file should only contain the following code:

<cfscript>
    objectparams.render="client";
    objectparams.async="false";
</cfscript>

Choosing this option means you'll have to load your JavaScript by using a custom event handler method, as shown below.

// ../yourmodule/model/handlers/yourhandler.cfc

component extends='mura.cfobject' {

  function onRenderStart(m) {
    // if script should be included in the <head>
   if(len(m.event('amp')) || !(isBoolean(m.event('amp')) && !m.event('amp'))){
      m.addToHTMLFootQueue('<script src="#m.siteConfig().getRootPath(complete=true,useProtocol=false)#/modules/yourmodule/assets/yourjs.js" #m.getMuraJSDeferredString()#></script>');
    }

    // OR

    // if script should be included before closing </body> tag
    if(len(m.event('amp')) || !(isBoolean(m.event('amp')) && !m.event('amp'))){
      m.addToHTMLFootQueue('<script src="#m.siteConfig().getRootPath(complete=true,useProtocol=false)#/modules/yourmodule/assets/yourjs.js" #m.getMuraJSDeferredString()#></script>');
    }
  }

}

Please also see the Modules and Display Objects With Mura.js section, for more information on rendering modules via JavaScript.

Example "config.xml.cfm" File

The example below illustrates a simple example of the "config.xml.cfm" file. Visit the Elements Of The "config.xml.cfm" File section for more details on available elements and attributes.

<?xml version="1.0" encoding="UTF-8"?>
  <mura name="My Module" contenttypes="*" iconclass="mi-rebel">
    <!-- May also include other elements here -->
  </mura>

In this example, the module will be available to all content types contenttypes="*". If you want to limit the module to specific content types, include them as a comma-delimited list contenttypes="page,folder,calendar". Also, when the module appears in the Layout Manager menu, the icon associated to the module is identified in the iconclass attribute iconclass="mi-rebel". You can use any of the available base Font Awesome icons, prefixed with mi- instead of fa- as per Mura conventions.

Configurators

Mura's code conventions for custom modules also include a markup standard for consistency and ease of development.

Configurator Usage

The configurator manages any special settings, values or controls for that particular usage of the display object, and is displayed in the sidebar in the front end editing view.

When coding the "./configurator.cfm" rendering template for any custom display object, these conventions should be used to provide optimal results.

Basic Input / Label Grouping

Mura's front-end editor automatically provides the outer markup for any configurator forms rendered in the sidebar, including the html <form> wrapper. The contents of a configurator.cfm file consist of a few basic form elements to create the specific controls for the relevant display object.

Within the <cf_objectconfigurator>  tag (see overview example below), each form input is paired with its corresponding <label> element, inside a wrapper with the "mura-control-group" class.

For example, a standard text input:

<!--- Text --->
<div class="mura-control-group">
  <label>Text</label>
  <input type="text" name="exampletext" class="objectParam" value="#esapiEncode('html_attr',objectParams.exampletext)#"/>
</div>

Note the use of the objectParam class on the input itself, which is required for editing functionality, along with the dynamic value for the input. These conventions are used universally when creating custom display object configurators.

Standard Input Types

In addition to basic text inputs, other standard form elements can be used, with a similar syntax.
For example, a textarea:

<!--- TextArea --->
<div class="mura-control-group">
  <label>Text Area</label>
  <textarea name="exampletextarea" class="objectParam">#objectParams.exampletextarea#</textarea>
</div>

A select box:

<!--- Select --->
<div class="mura-control-group">
  <label>Select</label>
  <select class="objectParam" name="exampleselect">
     <option value="red"<cfif objectParams.exampleselect is 'red'> selected</cfif>>Red</option>
     <option value="green"<cfif objectParams.exampleselect is 'green'> selected</cfif>>Green</option>
     <option value="blue"<cfif objectParams.exampleselect is 'blue'> selected</cfif>>Blue</option>     
  </select>
</div>

Configurator elements with variables or automated values may also be used. For example, a select box with dynamic options via cfloop:

<!--- Select --->
<div class="mura-control-group">
  <label>Select</label>
  <select class="objectParam" name="exampleselect">
    <option value="">Choose a Value</option>
    <cfloop list="1,2,3" item="i">
      <option <cfif objectParams.exampleselect eq i>selected </cfif>value="#i#">#i#</option>
    </cfloop>
  </select>
</div>

Checkbox and Radio Inputs

One or more checkbox inputs can be grouped inside the same "mura-control-group" wrapper.
A standard <label> element can be used to describe the group, followed by any number of checkbox inputs, grouped in a "checkbox-group" container. Each input is wrapped with a label element using the "checkbox" class.

<!--- Checkboxes --->
<div class="mura-control-group">
  <label>Checkboxes</label>
  <div class="checkbox-group">
  <cfloop list="Red,Green,Blue" item="i">
    <label class="checkbox"><input type="checkbox" class="objectParam" name="examplecheckbox" value="#lcase(i)#"<cfif listFindNoCase(objectParams.examplecheckbox,i)> checked</cfif>>#i#</label>
  </cfloop>
  </div>
</div>

Radio buttons use a similar syntax, nested inside a "radio-group" container, and labels with the "radio" class. 

<!--- Radio Group --->
<div class="mura-control-group">
  <label>Radio Buttons</label>
  <div class="radio-group">
    <label class="radio"><input type="radio" class="objectParam" name="exampleradio" value="true" <cfif objectParams.exampleradio> checked</cfif>/>Yes</label>
    <label class="radio"><input type="radio" class="objectParam" name="exampleradio" value="false" <cfif not objectParams.exampleradio> checked</cfif>/>No</label>
  </div>
</div>

Configurator Overview

When utilizing these options in a single configurator.cfm file, your markup will look something like this:

<!--- set defaults for form values --->
<cfsilent>
  <cfparam name="objectParams.exampletext" default="">
  <cfparam name="objectParams.exampletextarea" default="">
  <cfparam name="objectParams.exampleselect" default="">
  <cfparam name="objectParams.exampleradio" default="false">
  <cfparam name="objectParams.examplecheckbox" default="">
  <cfparam name="objectParams.examplefile" default="">
</cfsilent>

<!--- cf_objectconfigurator tag adds default inputs --->
<cf_objectconfigurator>
  <cfoutput>

    <!--- Text --->
    <div class="mura-control-group">
      <label>Text</label>
      <input type="text" name="exampletext" class="objectParam" value="#esapiEncode('html_attr',objectParams.exampletext)#"/>
    </div>

    <!--- TextArea --->
    <div class="mura-control-group">
      <label>Text Area</label>
      <textarea name="exampletextarea" class="objectParam">#objectParams.exampletextarea#</textarea>
    </div>

        <!--- Select --->
        <div class="mura-control-group">
         <label>Select</label>
         <select class="objectParam" name="exampleselect">
          <option value="">Choose a Value</option>
          <cfloop list="1,2,3" item="i">
           <option <cfif objectParams.exampleselect eq i>selected </cfif>value="#i#">#i#</option>
          </cfloop>
         </select>
        </div>

    <!--- Checkboxes --->
    <div class="mura-control-group">
      <label>Checkboxes</label>
      <div class="checkbox-group">
      <cfloop list="Red,Green,Blue" item="i">
      <label class="checkbox"><input type="checkbox" class="objectParam" name="examplecheckbox" value="#lcase(i)#"<cfif listFindNoCase(objectParams.examplecheckbox,i)> checked</cfif>>#i#</label>
      </cfloop>
      </div>
    </div>

    <!--- Radio Group --->
    <div class="mura-control-group">
      <label>Radio Buttons</label>
      <div class="radio-group">
        <label class="radio"><input type="radio" class="objectParam" name="exampleradio" value="true" <cfif objectParams.exampleradio> checked</cfif>/>Yes</label>
        <label class="radio"><input type="radio" class="objectParam" name="exampleradio" value="false" <cfif not objectParams.exampleradio> checked</cfif>/>No</label>
      </div>
    </div>

        <!--- Custom file selector --->    
        <div class="mura-control-group">
            <label>Select File</label>
            <input name="myfile" class="objectParam" value="#esapiEncode('html_attr',objectparams.examplefile)#"><br/>
            <button type="button" class="btn mura-finder" data-target="myfile" data-completepath=false>Select File</button><br/>
        </div>

        <!--- Custom modal window w/ control button --->
        <div class="mura-control-group">
            <button type="button" class="btn" id="open-custom-modal">Open Modal</button>
        </div>
        <input name="trim-params" class="objectParam" type="hidden" value="true"/>
        <script>
            $(function(){
                $('##open-custom-modal').click(function(){
                    siteManager.openDisplayObjectModal('examples/modal.cfm');
                });
            });
        </script>

    </cfoutput>
</cf_objectconfigurator>

Note the additional "custom css classes" input. This is added automatically by Mura, with the supplied class names applied to the display object container. 

Available Custom Tags

In order make it so you don't really need to worry about the configurator markup in most cases the following custom tags are available.

<cfimport prefix="ui" taglib="/core/mura/customtags/configurator/ui"/>
<cfscript>
    param name='objectparams.myhtml' default='';
    param name="objectparams.myselect" default="test2";
    param name="objectparams.mytext" default="";
    param name="objectparams.mytextarea" default="";
    param name="objectparams.mycolor" default="";
    param name="objectparams.myimage" default="";
    param name="objectparams.myfile" default="";
    param name="objectparams.myradio" default="";
    param name="objectparams.mycheckbox" default="";
    param name="objectparams.mydispenser" default="";


    selectoptions=["test1","test2"];

    radiooptions=["test1","test2"];

    checkboxoptions=["test1","test2"];

    /*option attribute can be of objects to have different value and names*/
    dispenseroptions=[
        {
            name="label 1",
            value="value 1"
        },
        {
            name="label 2",
            value="value 2"
        }
    ];
</cfscript>
<cf_objectconfigurator>
    <ui:text 
        label="My Text"
        name="mytext"
        value="#objectparams.mytext#"/>
     <ui:textarea
        label="My Text Area"
        name="mytextarea"
        value="#objectparams.mytextarea#"/>
    <ui:color
        label="My Color"
        name="mycolor"
        value="#objectparams.mycolor#"/>
    <ui:image
        label="My image"
        name="myimage"
        value="#objectparams.myimage#"/>
    <ui:file
        label="My File"
        name="myfile"
        value="#objectparams.myfile#">
    <ui:html
        label="My HTML"
        name="myhtml"
        value="#objectparams.myhtml#"/>
    <ui:select
        label="My Select"
        name="myselect"
        options="#selectoptions#"
        value="#objectparams.myselect#"/>
    <ui:radio 
        label="My Radio Group"
        name="myradio"
        options="#radiooptions#"
        value="#objectparams.myradio#"/>
    <ui:checkbox 
        label="My Checkbox Group"
        name="mycheckbox"
        options="#checkboxoptions#"
        value="#objectparams.mycheckbox#"/>
    <ui:modal 
        label="My Modal"
        modalpath="mymodules/mymodal.cfm"/>
    <ui:dispenser 
        label="My Dispenser"
        name="mydispenser"
        options="#dispenseroptions#"
        value="#objectparams.mydispenser#"/>
</cf_objectconfigurator>

Defining Configurators in a mura.config.json File

When creating decoupled frontends to Mura you can use the mura.config.json to define modules. Since you don't have access to created the Mura container you can set a configurator attribute of the module object. They can be defined in multiple ways.

An important distinction in configurators defined and used in decoupled code is that you don't need to explicitly send a value attribute. The framework retrieves values from the the current module's configuration for you.

Array of Objects

The array of obects simply matches the attributes that you would set in a a custom tag invocation plus a "type" attribute that tells Mura what ui type to be used

{
	"global":{
		"modules":{
			"Examplejs":{
				"name":"Examplejs",
				"contenttypes":"*",
				"configurator":[
					{"type":"text","name":"mytitle","label":"My Label"}
				]
			}
        }
    }
}

URL to Static HTML or JS Object

The return value of the http request will be rendered as the configurator. It can be static html or a valid JSON object

{
	"global":{
		"modules":{
			"Examplejs":{
				"name":"Examplejs",
				"contenttypes":"*",
				"configurator":"https://localhost/app/configurator.html"
			}
        }
    }
}

Static HTML

{
	"global":{
		"modules":{
			"Examplejs":{
				"name":"Examplejs",
				"contenttypes":"*",
				"configurator":"escaped configurator markup"
			}
        }
    }
}

Model

The Model directory is where you will place any custom Mura ORM Objects or event handlers. These objects are instantiated by convention, meaning that any objects you place in here will be collected by Mura at start-up and integrated into the standard rendering Lifecycle.

As always, you should practice thoughtful naming conventions when integrating custom Mura ORM Objects. Using a module-name prefix is good practice.

Available Plugins

At this time, there is not an "official" repository for Mura plugins. So, in the mean time, if developing open source plugins, we suggest developers post them to Github, and include "Mura plugin" in the description so that it's easy to discover via searching Github's repositories.

You may also find some of the more popular Mura plugins at http://www.getmura.com/downloads/mura-cms-plugins/. If you would like to have your plugin considered for addition to the list, please don't hesitate to ask.

Plugin Anatomy

Mura plugins are distributed as ".zip" files. However, the .zip archive itself contains the underlying files which comprise the plugin. In this section, we'll cover the anatomy of a Mura plugin, and the directories and files Mura requires in order to function properly.

When you begin creating a plugin, all of your plugin's directories and files must be packaged together under a common directory, and will ultimately be deployed under Mura as:

{context}/plugins/{YourPluginDirectoryName}/

Be careful when naming your plugin's containing directory, as some operating systems will not accept special characters in the name. This is also important, because Mura will automatically create a CFML Application variable using "this.mappings" to your plugin using the value of your directory name.

A basic directory structure of a Mura plugin is detailed below, and assumes all listed directories/files are located under {context}/plugins/{YourPluginDirectoryName}/

Note: By default, Mura does not automatically scan for a "model" directory within plugins. This is intentional to avoid any collisions, as your plugin may have its own bean factory which scans for this directory as well.

The files outlined above represent a very basic plugin. Your plugin may contain many more directories and files than those listed here. Be sure to review the links for each file noted above for more details on their importance, and why may wish to include them in your own plugin.

Outside of the required and recommended directories and files, your plugin can be a completely separate, and independent application. If your application will merely be a portal of some kind, then maybe all you'll need is the "index.cfm" file and "config.xml.cfm" file.

However, in most cases, you're going to want to include some functionality to either add to, or even replace, Mura's business logic. As such, you'll want to do things such as register a custom event handler, so you can also register a custom "model" directory, and more. Be sure to review The Plugin's "config.xml.cfm" File section for more details.

<eventHandlers>

  <eventHandler event="onApplicationLoad" 
                component="model.handlers.eventHandler" />

</eventHandlers>

<settings>

    <setting>
        <name>country</name>
        <label>Country</label>
        <hint>The country where you live</hint>
        <type>select</type>
        <required>true</required>
        <validation>none</validation>
        <regex></regex>
        <message>Please select a Country</message>
        <defaultvalue>US</defaultvalue>
        <optionlist>US^UK^FR</optionlist>
        <optionlabellist>United States^United Kingdom^France</optionlabellist>
    </setting>

</settings>

<mappings>
  <mapping name="yourmapping" directory="somedir/anotherdir" />
</mappings>

<?xml version="1.0" encoding="UTF-8"?>
    <plugin>
        <name>Your Plugin</name>
        <package>yourplugin</package>
        <directoryFormat>packageOnly</directoryFormat>
        <loadPriority>5</loadPriority>
        <version>0.0.1</version>
        <provider>Blue River</provider>
        <providerURL>http://blueriver.com</providerURL>
        <category>Application</category>

        <!-- Event Handlers -->
        <eventHandlers>
            <eventHandler event="onApplicationLoad"
                          component="model.handlers.muraplugin" />
        </eventHandlers>

        <!-- CFML Mappings -->
        <mappings>
          <mapping name="yourmapping" directory="somedir/anotherdir" />
        </mappings>

        <!-- Settings -->
        <settings>

            <setting>
                <name>country</name>
                <label>Country</label>
                <hint>The country where you live</hint>
                <type>select</type>
                <required>true</required>
                <validation>none</validation>
                <regex></regex>
                <message>Please select a Country</message>
                <defaultvalue>US</defaultvalue>
                <optionlist>US^UK^FR</optionlist>
                <optionlabellist>United States^United Kingdom^France</optionlabellist>
            </setting>

        </settings>

        <!-- Image Sizes -->
        <imagesizes>
          <imagesize name="myimage"
                     width="600"
                     height="400" />
        </imagesizes>

        <!-- Class Extensions -->
        <extensions>
            <!-- <extension> elements -->
        </extensions>
    </plugin>

component extends='mura.plugin.pluginGenericEventHandler' output=false {

    public any function onApplicationLoad(required struct m) {
        // Register all event handlers/listeners of this .cfc with Mura CMS
        variables.pluginConfig.addEventHandler(this);
    }

    // Add any event handlers here

}

component extends='mura.plugin.pluginGenericEventHandler' output=false {

    public any function onApplicationLoad(required struct m) {
        // Register all event handlers/listeners of this .cfc with Mura CMS
        variables.pluginConfig.addEventHandler(this);

        // Register another event handler
        // Assumes you have a customHandler.cfc located under the same directory.
        var anotherEventHandler = new customHandler();
        variables.pluginConfig.addEventHandler(anotherEventHandler);
    }

    // Add any event handlers here

}

component extends='mura.plugin.pluginGenericEventHandler' output=false {

    public any function onApplicationLoad(required struct m) {
        // Register all event handlers/listeners of this .cfc with Mura CMS
        variables.pluginConfig.addEventHandler(this);

        // Register a custom 'model' directory
        variables.pluginConfig.registerModelDir(
          dir='path/from/plugin/to/model/dir'
        );
    }

    // Add any event handlers here

}

component extends='mura.plugin.pluginGenericEventHandler' output=false {

    public any function onApplicationLoad(required struct m) {
        // Register all event handlers/listeners of this .cfc with Mura CMS
        variables.pluginConfig.addEventHandler(this);

        // Register a custom 'module' directory
        variables.pluginConfig.registerModuleDir(
          dir='path/from/plugin/to/modules/'
        );
    }

    // Add any event handlers here

}

component extends='mura.plugin.pluginGenericEventHandler' output=false {

    public any function onApplicationLoad(required struct m) {
        // Register all event handlers/listeners of this .cfc with Mura CMS
        variables.pluginConfig.addEventHandler(this);

        // Register a custom 'content_types' directory
        variables.pluginConfig.registerContentTypeDir(
          dir='path/from/plugin/to/content_types/'
        );
    }

    // Add any event handlers here

}

component extends='mura.plugin.plugincfc' output=false {

    // pluginConfig is automatically available as variables.pluginConfig

    public void function install() {
        // Do custom installation stuff
    }

    public void function update() {
        // Do custom update stuff
    }

    public void function delete() {
        // Do custom delete stuff
    }

    public void function toBundle(pluginConfig, bundle, siteid) output=false {
        // Do custom toBundle stuff
    }

    public void function fromBundle(bundle, keyFactory, siteid) output=false {
        // Do custom fromBundle stuff
    }

}

// ./plugin/config.cfm

    // Mura Scope
    if ( !IsDefined('m') ) {
        siteid = session.keyExists('siteid') ? session.siteid : 'default';
        m = application.serviceFactory.getBean('m').init(siteid);
    }

myPluginApplication = pluginConfig.getApplication();
myPluginAppication.set('colors', ['Red','White','Blue']);
pluginColors = myPluginApplication.get('colors');

// 'true' = purge the plugin's application variables
myPluginApplication = pluginConfig.getApplication(true);

myPluginSession = pluginConfig.getSession();
myPluginSession.set('fruit', ['Grapes','Oranges']);
pluginFruit = myPluginSession.get('fruit');

// 'true' = purge the plugin's session variables
myPluginSession = pluginConfig.getSession(true);

<cfset rsSites = pluginConfig.getAssignedSites()>

<ul>
  <cfloop query="rsSites">
    <li>#siteid#</li>
  </cfloop>
</ul>

// ./plugin/config.cfm

    // Mura Scope
    if ( !IsDefined('m') ) {
        siteid = session.keyExists('siteid') ? session.siteid : 'default';
        m = application.serviceFactory.getBean('m').init(siteid);
    }

    // Plugin Config
    if ( !IsDefined('pluginConfig') ) {
        pluginConfig = m.getBean('pluginManager').getConfig('{YourPluginPackagNameGoesHere}');
    }

// ./plugin/config.cfm

    // Mura Scope
    if ( !IsDefined('m') ) {
        siteid = session.keyExists('siteid') ? session.siteid : 'default';
        m = application.serviceFactory.getBean('m').init(siteid);
    }

    // Plugin Config
    if ( !IsDefined('pluginConfig') ) {
        pluginConfig = m.getBean('pluginManager').getConfig('{YourPluginPackagNameGoesHere}');
    }

    // Check User Access ~ Redirect if Not Authorized
    if ( !pluginconfig.currentUserAccess() ) {
        location(
          url=m.globalConfig('context') & '/admin/index.cfm?muraAction=clogin.main'
          , addtoken=false
        );
    }

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>YourPlugin</title>
    </head>
    <body>
        <h1>Hello from YourPlugin!</h1>
    </body>
</html>

<cfinclude template="plugin/config.cfm" />

<cfsavecontent variable="pluginBody">
    <cfoutput>
        <h1>#esapiEncode('html', pluginConfig.getName())#</h1>
        <p>Hello from YourPlugin!</p>
    </cfoutput>
</cfsavecontent>

<cfoutput>
    #m.getBean('pluginManager').renderAdminTemplate(pluginBody)#
</cfoutput>

Installing Plugins

Mura plugins are distributed as ".zip" files. Plugins are managed in the back-end administrator area of Mura. Administrators may install plugins via the back-end user interface (UI). There are a few different methods for installing/deploying plugins. The method you select will often depend on whether you are a developer or not.

That said, here's some important tips before you install any plugins:

• Never install a plugin in a production environment without testing it elsewhere first.
• Plugins have access to all areas of Mura, and as such, be wary of plugins from sources you are unfamiliar with.
• Review the code of any plugin you intend to install first, if you are not the author of it.
• You may want to make a backup of your filesystem and database before deploying a plugin, in case something goes wrong during the deployment process.
• Finally, be sure the plugin you are deploying is compatible with your version of Mura.

Setting Permissions For Plugins

Plugins may be restricted to specific groups, allowing administrators the ability to control which groups may access each plugin. Permissions may be set only for plugins enabled for the specific site you are currently working on. To set permissions, follow the steps outlined below.

1. From the back-end administration area, select Plugins, and click Site Plugins
2. You will then be directed to the Site Plugins screen
3. At a minimum, there are two (2) tabs: Application and Utility. However, there may be additional tabs, depending on the plugins enabled for your site. Locate the plugin you wish to manage permissions on, then click the three-dot menu to the left of the plugin name.From the menu of options, click Permissions
4. The Permissions screen should appear.
5. Select the group(s) you wish to enable access for
6. When finished, click Update to save the new permissions

Deleting Plugins

To delete a Mura CMS plugin, follow the steps outlined below.

1. From the back-end administration area, select Global Settings, then click Plugins
2. Select the three-dot menu to the left of the plugin's name.
3. Then, click "Delete" from the options menu
4. An Alert dialog window should appear
5. Select "OK" to continue the delete process, or select "Cancel" to abort and close the dialog window.

Advanced Options

When it comes to plugins, the possibilities are truly endless. Throughout the documentation, we've shown you a plethora of ways to interact with Mura. In other words, we've given you all of the tools you'll need to do pretty much anything you want. Just in case you've forgotten, here's a quick reminder of some of the most powerful tools Mura has to offer:

• Mura Scope
  • When you need to communicate with Mura, use the Mura Scope.
• Mura Events
  • When you need to replace, or add to Mura's default functionality, use Mura's Events. You may also create your own, custom events too.
• Mura Beans & Objects
  • When you need to work with Mura beans or objects, or create your own custom objects using class extensions and/or Mura ORM, don't hesitate to do so directly from your plugin.
• Mura Rendering
  • When you need to alter Mura's rendering, remember you have access to tools such as Mura's modules, custom content types, Mura.js, and localization features.

In addition to all of Mura's baked-in developer tools, feel free to use any CFML framework you wish. For example, are you a fan of Framework One? Great! We have a starter plugin using FW/1 as its application framework called MuraFW1. Using a different one? Go ahead. Remember, your plugin can be completely isolated from Mura, if you want it to be. You, as the plugin developer, choose which pieces of Mura you wish to include in your application.

Plugins vs. Modules

As you've seen in the Mura Modules section, modules are a powerful tool, allowing Mura developers to integrate not only custom displays and applications, but also a new world of possibilities for injecting custom processing logic and more. 

The decision to use a Plugin instead of a Module comes down one question:

• Do you need a custom administration area?
  • Yes
    • Use a plugin. Each plugin can be restricted to specific sites, and the plugin's administrator area can be restricted to specific user groups.
  • No
    • Use a module.

The Mura contentRenderer.cfc

The majority of Mura's rendering behavior occurs in a special file labeled the "contentRenderer.cfc". Mura's primary, or "Core" contentRenderer is located under:

 {context}/core/mura/content/contentRenderer.cfc

As covered in the Theme Developer's Guide, the "Core" contentRenderer also contains a plethora of helper methods, as well as settings used by Mura's display objects, all of which are frequently used by Mura developers.

Since the "Core" contentRenderer is a "core" file, it shouldn't be modified directly. Instead, if you wish you to override any of the default settings or methods found in the "core" contentRenderer, Mura will first check the theme, and then the site for a contentRenderer.cfc. If the matching setting or method is found, it will use the custom setting or method in lieu of Mura's default "core" setting or method. You only need to define the setting(s) or method(s) you wish to override in your "Site" or "Theme" contentRenderer.

Custom Rendering Methods

In addition to overriding any of the default settings and methods found in the "Core" contentRenderer, any custom rendering methods defined in the "Site" or "Theme" contentRenderer are available via the Mura Scope. For example, if you have the following method defined in your "Site" or "Theme" contentRenderer:

public string function dspHello() {
  return "<p>Hello from dspHello!</p>";
}

You may invoke the method by simply using the following syntax:

<cfoutput>
  #m.dspHello()#
</cfoutput>

The above code would output:

<p>Hello from dspHello!</p>

Lookup Hierarchy

Mura uses the following lookup hierarchy for settings or methods found in a contentRenderer.cfc. If the setting or method is defined in the first file, Mura will use it and ignore any other identically named methods found in the remaining files.

1. "Theme" contentRenderer
   • ../themes/{ThemeName}/contentRenderer.cfc
2. "Site" contentRenderer
   • {context}/sites/{SiteID}/includes/contentRenderer.cfc
3. "Core" contentRenderer
   • {context}/core/mura/content/contentRenderer.cfc

this.validateCSRFTokens = true;
this.navOffset = 0;
this.navDepthLimit = 1000;
this.navWrapperClass = 'sidebar-nav well';

{context}/core/modules/v1/nav/

{context}/core/modules/v1/form/

{context}/core/modules/v1/formbuilder/

{context}/core/modules/v1/calendar/

{context}/core/modules/v1/comments/

{context}/core/modules/v1/collection/

{context}/core/modules/v1/editprofile/