Custom Instance of the Mura Scope

As a Mura developer, you are going to run into situations from time-to-time where the Mura Scope is not accessible to you. This most often occurs when you're processing logic falls outside of the normal Mura event model (e.g., Ajax requests, accessing your application directly under a non-Mura directory, etc.).

As long as you're working within the realm of the Mura application itself, you can easily create a custom instance of the Mura Scope. One important thing to keep in mind is that you'll most likely want to initialize the Mura Scope with a SiteID.  The reason for this is that most often, you're probably going to to be working with site-specific information, and unless the Mura Scope has been initialized with a SiteID, you won't have access to any site-specific data.

Also, unless a user is accessing your logic directly, and outside of the normal Mura event model, the session scope typically contains a SiteID key. However, there may be rare instances when this does not occur, and when it does, you can always fall back to using the one site that each and every Mura installation includes, which is the "default" site, and its SiteID is always default. 

Using this knowledge, the examples highlighted below should hopefully make a bit more sense.

Examples

Below is an example of how to create a custom instance of the Mura Scope, checking for an instance of session.siteid, and using that to initialize the Mura Scope, or using the default SiteID, if, for whatever reason, it has not been defined yet.

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

While the most common method for initializing the Mura Scope is with a SiteID string, it can also be initialized with an event object or a struct that contains a siteid key. 

if ( !IsDefined('m') ) {

  // Assumes you have a pre-defined event object named `yourEventObject`
  m = application.serviceFactory.getBean('m').init(yourEventObject);

  // OR

  yourStruct = {
    siteID = 'SomeSiteID'
    , someKey = 'Some Value'
  };

  m = application.serviceFactory.getBean('m').init(yourStruct);
}

 

setCustomMuraScopeKey

As you can see, the Mura Scope is a great way to access Mura CMS variables, data, and objects. There may be times when you want to add your own variables, data, and/or objects to the Mura Scope as well, and as you'll see, it's very easy to do just that.

In the Mura Events section, the various event/request lifecycles and contextual events that occur within Mura are covered. At any point within the lifecycle, or contextual event, you can choose to register your own custom Mura Scope key. Once it has been registered, the key will continue to be available for the remainder of the subsequent lifecycle and/or contextual event.

Function Syntax

m.setCustomMuraScopeKey(
  name
  , value
)

Parameters

Parameter Type Req/Opt Default Description
name string Req   This is the name of the custom Mura Scope key.
value any Req   This is the "value" returned when referencing the Mura Scope key.

Examples

To register your custom Mura Scope key, you first select the point in the lifecycle, or contextual event, you wish to create your custom key, and then choose your desired event handler to place your custom logic (e.g., the Site eventHandler.cfc, Theme eventHandler.cfc, or any other registered event handler).

Setting a Custom Key to a Simple String

The example below is using the onSiteRequestStart event to register a simple string to be stored in the Mura Scope.

public function onSiteRequestStart(m) {
  m.setCustomMuraScopeKey('myCustomKey', 'This is my custom Mura Scope Key value!');
}

Accessing the Custom Key

<cfoutput>
  <p>#m.myCustomKey#</p>
</cfoutput>

The above example should output the following:

<p>This is my custom Mura Scope Key value!</p>

Setting a Custom Key to an Object

First, we'll need an example object. Let's assume you have the following code in a file labeled exampleObject.cfc.

component {

  public function sayHello() {
    return 'Hello from exampleObject.cfc!';
  }

}

Next, we'll select an event to add our logic to, and set a custom key that references the example object.

public function onBeforeUserSave(m) {
  var myObject = new exampleObject();

  m.setCustomMuraScopeKey('myObject', myObject);
}

Because we've specified the onBeforeUserSave event in the example above, our new Mura Scope Key will be available in the onAfterUserSave event, if needed.

Accessing the Custom Key's Object

<cfoutput>
  #m.myObject.sayHello()#
</cfoutput>

The above example should output the following:

Hello from exampleObject.cfc!

Summary

Throughout this section, you've learned that the Mura Scope is a special scope, created specifically for Mura developers to access, and manipulate Mura CMS variables, data, and objects. In other words, you've learned a simple syntax for "talking" with Mura.

You've also learned how to create a custom instance of the Mura Scope, for those rare times it isn't defined for you, as well as how to set your own, custom Mura Scope key.

You'll learn more about the power of the Mura Scope as you proceed through the rest of this guide.