Part of the process of porting our company web site over to Mura involved including some ajax functionality. I spent a few hours researching and experimenting, so thought I'd share what I learned in case it saves someone else some time later.
The Scenario
The site you're porting to Mura currently retrieves and outputs a list of scheduled events, and you need to have that same ajax call working within the Mura site as well.
How it Works In a Nutshell
In order to accomplish our goal, we need to:
Loading our Library and custom JS
The fact is, Mura already by default has JQuery loaded up and ready to go (if you'd like to change your default library to something else, such as Prototype, check out step 1 of this Mura article). As you know, however, the order that js files are loaded up is very important. For instance, loading up our custom JS file before our library gets loaded means that our custom js code will not execute and will likely error out. So, you have a couple of options here:
1. You can put your JS code directly within the page or component so that it will always be executed after JQuery is loaded (if this suits your needs, you can simplify your life and skip to the Simpler Method);
2. You can put your js code into an external file, then control the order that files are loaded up in the page using special Mura commands.
Keeping our code modular
The obvious answer to this one is to utilize a Mura Component to contain our Ajax. We'll call this component "Show Events". This component will contain the div that our ajax call will populate with content as well as the js code that does the populating.
Backend Code
My backend code for this exercise is a simple CFM page named registrationAjax.cfm that contains a cfswitch/cfcase statement that responds to ajax calls. I will be placing it in the following path:
[mura installation folder]\[site name]\includes\display_objects\custom\registrationAjax.cfm
THE DETAILS
Okay, let me show you how I put this all together, elaborating along the way as I feel the need.
Backend Code
As mentioned previously, I dropped my backend code into the [mura installation folder]\[site name]\includes\display_objects\custom folder. Your backend code may very well live in a galaxy far, far away; not a prob. It's ajax, man! If your backend code lives elsewhere, just forget about this step.
The Ajax Component
Okay, our component is going to include the target div where our retrieved event data will be output:
<div class="fancyheader" style="text-align: left; ">UPCOMING EVENTS</div>
<div id="eventTarg"></div>
We'll be adding a little something more to this component in the next step.
Loading the JS File
Just FYI, here is the content of my js file:
var params = new Object;
params.meth = "getEventLinks";
$('#eventTarg').load('includes/display_objects/custom/registrationAjax.cfm',params);
});
When the page this code lives in finishes loading, an ajax call will be made to my backend code, the result of the call being placed into the 'eventTarg' div.
Next we need to place our js file somewhere. I opted to create a "custom" folder under my site's "js" folder, like so:
[mura installation folder]\[site name]\js\custom
Bogus (yet necessary) Step
Here we come to a step that I feel is kinda bogus to have to do, but never the less it's required by Mura when you want your JS to live in an external file. Rather than us just being able to add a string like "<script src="[path stuff]/myjsfile.js"></script>" to the head of our page, Mura requires us to create a CFM template that itself contains that string, then we add that cfm page to the head. I know, sounds (and is) a bit overcomplicated, but this is how you have to do it if you want your JS in an external file. SO, I added a "custom" folder to my [mura install folder]\[site name]\includes\display_objects\htmlhead\ folder. In there I created "loadShowEventJS.cfm" which contains the following code:
<script src="#$.siteConfig('assetPath')#/js/custom/showEvents.js" type="text/javascript"></script>
</cfoutput>
Now that we have that file created and in place, we need to revisit our component and add two lines that will put our external js file into the page's head AND ensure that it is loaded AFTER the JQuery library. Add these two lines to your component:
[mura]$.addToHTMLHeadQueue('htmlHead/custom/loadShowEventJS.cfm')[/mura]
This is an excellent time to point out the use of Mura's addToHTMLHeadQueue function. It takes a path (relative to the display_objects folder in your site). Whatever the final rendered content of the targeted CFM file is, that is the string that will be included in the head of your page. Notice we're also using the loadJSLib method to ensure that our js library (JQuery in this case) is loaded before our custom js file. Even though by default Mura is ALREADY loading JQuery, if we don't use the loadJSLib() method here, JQuery would load AFTER our custom js file. For more information on the addToHTMLHeadQueue method (and every other Mura method), I highly recommend you bookmark the developer mura docs
That's It!
I know, it wasn't quite painless. But at this point you can go ahead and test it all by adding your component to a page and then viewing it. There are a lot of moving parts to this, like paths and your ajax code itself, so just bear that in mind if things don't work quite right the first time 'round.
Simpler Method
If having your JS live in an external file isn't a big deal to you, then there IS an easier way to get your ajax functionality into your page. Remember I told you that the JQuery library was already being included by default? Well, if we opted to put our JS code inline within our page body, then it would work just fine without us having to tell Mura where to load JQuery within the head. So in this scenario, we need only modify our component code to look like this:
<div class="fancyheader" style="text-align: left; ">UPCOMING EVENTS</div>
<div id="eventTarg"></div>
<script>
$(document).ready(function() {
var params = new Object;
params.meth = "getEventLinks";
$('#eventTarg').load('includes/display_objects/custom/registrationAjax.cfm',params);
});
</script>
Including that component on any page will now accomplish the same thing it took several additional steps to do the "proper" Mura way.
Hope this helps someone!
Doug out.
You are not logged in, so your subscription status for this entry is unknown. You can login or register here.
Also in 5.4 we added addTOHTMLFootQueue().