Resultant Systems

For most websites it’s usually a good idea to have error pages that have user-friendly error messages that are styled to look like the rest of the site.  Also, you may want to send yourself an eMail when an error happens. Read on to see how to make this work.

For the DonorUp website, I used CFWheels and the Splash CMS. Once I knew the tricks, it turned out to be really easy to make this work. So, I decided to write a post to explain what you need to know.

Typically, in ColdFusion, you add an onError() method to your Application.cfc file. Wheels gives you various hooks into Application.cfc, but Wheels already has an onError() method. So, you can’t add another one! Fortunately, Wheels has an easy way to handle most errors.

How to send error messages from CFWheels

All you have to do to get Wheels to send error message emails  is add the following into your /config/settings.cfm file:

<cfset set(sendEmailOnError = true)>
<cfset set(errorEmailAddress = “you@yourServer.com”)>

Now, whenever there’s an error, you’ll get a really nice email with all the troubleshooting info you’ll need. Easy!

How to setup a custom error page in CFWheels or Splash

As part of its built-in error handling, Wheels runs the file at /events/onerror.cfm. Just put a redirect to your error page at the top of onerror.cfm and you’re done:

<cfset redirectTo(route=”viewer”, slug=”error-page”)>

In my case, I went into the Splash CMS admin and added a page called Error Page. This way, the page is automatically styled to match the rest of the site. The error page apologizes to the user for the error, and let’s them know I am going to fix it!

When Wheels does its error handling, it will run /events/onerror.cfm, and the redirectTo() will send them to my error page! If you aren’t running Splash, you could just use the other arguments of redirectTo() to send them to any controller and action.

You can also put your own HTML or CFML code in onerror.cfm, but I like doing it this way better as it uses all the layouts and styling of my site!

Please leave me a comment if you like this approach or have other ideas!

Clarke Bishop CFWheels, ColdFusion, Splash CMS CFWheels, Splash CMS

Mura has a lot of interesting capabilities. However, the documentation is a little sparse.

Recently, I have been customizing a Mura site, so I thought I’d document some of the key things you need to know!

1 - Create a New Site to Customize

When initially installed, Mura automatically creates the  “Default” site. But, don’t customize this site. Make a new site and customize it. This way, you can still do Mura updates without overwriting your customizations.

• Login to your admin area
• Go to Site Settings -> Add New Site. (Site Settings is in the upper right of the admin screen.)
• Name the site whatever you want. For example, you might call it MySite.
• Now, when you go to customize things, don’t look in the Default folder. Instead find the MySite folder.
• If you want MySite to come up automatically when you go to www.YourDomain.com, click on Site Settings. Then, use the Order drop downs to set MySite to 1.

2 - Customize /MySite/includes/

Much of what you’ll want to customize is in the /MySite/Includes/ directory. Here are some things you might want to customize:

• If you are using a theme like Merced, customize the style sheet at /MySite/includes/themes/merced/css/site.css. It’s a good idea not to change the other style sheets. Just override the style in site.css. More Info from Mura …
• Again, if you’re using Merced or another theme, customize the templates at /MySite/includes/themes/merced/templates/.  Don’t forget to look in the /inc folder for the header and footer includes. More Info from Mura …

3 - Change the behavior of Display Objects

You can change how the Display Objects work! For many Display Objects, you can just copy the display object, put it in /MySite/includes/display_objects/custom/ and modify your copy. I wanted to add a download link to the images in the image gallery, so it was more complicated. Matt Levine of Mura advised me to:

• Go get /MySite/includes/eventHandler.cfc and add a new onGalleryBodyRender function (See below).
• Create a new directory named gallery at /MySite/includes/display_objects/custom/gallery. Into this new directory, copy index.cfm from /default/includes/display_objects/gallery/index.cfm. Now we have a copy of the gallery file to customize, so customize your heart out!
• Stay in /gallery/index.cfm. Find the references to getSite() and queryPermFilter() method calls. Change these to renderer.getSite() and renderer.queryPermFilter().
• Still in /gallery/index.cfm, change the template path in <cfinclude template=”../dsp_nextN.cfm”>. The new path should be ../../../dsp_nextN.cfm.
• Reload the app either by clicking Reload Application in the admin, or adding ?appreload to the end of the url. A lot of the objects are loaded when the application starts, so I found it’s a good idea to reload after making changes.

Here’s the code for the updated eventHandler.cfc:

[cf]

<cffunction name="onGalleryBodyRender" output="true" returntype="void">
<cfargument name="event">
<cfset var renderer=event.getContentRenderer()>
<cfsilent>
<cfset renderer.loadShadowBoxJS() />
<cfset renderer.addToHTMLHeadQueue("custom/gallery/htmlhead/gallery.cfm")>
<cfif not event.valueExists(’galleryItemID’)><cfset event.setValue(’galleryItemID’,”)></cfif>
</cfsilent>

<!— When you override default output you need to run content throught the renderer.setDynamicContent() method to process [mura] tag calls—>
<cfoutput>#renderer.setDynamicContent(event.getValue(’contentBean’).getBody())#</cfoutput>

<!— Now include the customized display object —>
<cf_CacheOMatic key="portalBody#event.getValue(’contentBean’).getcontentID()##event.getValue(’startRow’)##event.getValue(’galleryItemID’)#" nocache="#event.getValue(’r').restrict#">
<cfinclude template="display_objects/custom/gallery/index.cfm">
</cf_CacheOMatic>

</cffunction>
[/cf]

I hope this helps someone get started with Mura! If you have suggestions for improving this information or just have a question, please leave a comment.

Clarke Bishop ColdFusion, Mura ColdFusion, Mura

On Page 73 of Head First Rails, we need to add a design for the meBay site.

Just like Rails, CFWheels supports layouts to create a master template and to avoid repeating yourself.

For our simple app, we could just work with the default layout located at /views/layout.cfm. But, to follow the book, let’s create a controller-specific layout at: /views/ads/layout.cfm. So, this layout.cfm in the /view/ads/ subdirectory will only be used for views associated with the ads controller.

[cf]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<cfoutput>
<title>Ads: #params.action#</title>
#stylesheetLinkTag("default")#
</cfoutput>
</head>
<body>
<cfoutput>
<div id="wrapper">
<div id="header">
<div>
<h1>MeBay</h1>
<ul id="nav">
<li>#linkTo(text="All Ads", route="adsNoKey")#</li>
</ul>
</div>
</div>

<div id="content">
#contentForLayout()#
</div>
<div id="clearfooter"></div>
</div>
<div id="footer"></div>
</cfoutput>
</body>
</html>
[/cf]

Most of this code is HTML boilerplate. #params.action# inserts the name of the current action in the Title tag. The params structure is always passed from the controller to the view. It includes the name of the action, variables, etc. You can always cfdump it out if you want to see what all is in there.

#stylesheetLinkTag(”default”)# uses another CFWheels helper function. By convention, stylesheets are located in the /stylesheets directory. So this function builds the link to our stylesheet named default.css. Download the code for Chapter 2 from the Head First Rails website, and get default.css from the /public/stylesheets/ folder. In CFWheels, put default.css in your /stylesheets folder. If you have trouble with the stylesheet, make sure all the images references are correct. If your web server configuration is different, you might need to adjust the paths.

On line 16, we’ve setup a link to our index action.

On line 22, you see #contentForLayout()#. This is where CFWheels puts the content from the other view pages — show.cfm and index.cfm. It’s the equivalent of <%= yield %> in Rails.

That’s it! Now we have a pretty, styled meBay application. Visit http://localhost/index.cfm/ads/ and see how pretty things look.

Next, it’s on to Chapter 3. In software development, things always change. And, now meBay wants to let people post ads online!

Clarke Bishop CFWheels, ColdFusion CFWheels

Starting on Page 73 of Head First Rails, we need to add an index page so that people can find the pages they want!

First, let’s add a new route so that http://localhost/index.cfm/ads/ goes to the new index action we’ll add in a minute.

Open up /config/routes.cfm, and change it to:

[cf]
<cfset addRoute(name="ads", pattern="/ads/[key]", controller="ads", action="show")>
<cfset addRoute(name="adsNoKey", pattern="/ads/", controller="ads", action="index")>
<cfset addRoute(name="catchall", pattern="[path]", controller="redirect", action="index")>
<cfset addRoute(name="home", pattern="", controller="redirect", action="index")>
[/cf]

Notice the new route on line 2: <cfset addRoute(name=”adsNoKey”, pattern=”/ads/”, controller=”ads”, action=”index”)>. CFWheels checks the routes in order. So, if the URL pattern matches /ads/[key], it will go to the show action. But, if the key isn’t there, it matches the /ads/ pattern and goes to the new index action.

Now, we need to add an index action to the controller and then an index.cfm view. Open up /controllers/Ads.cfc and add the new index function. Leave the show function alone.

[cf]
<!— ads/index —>
<cffunction name="index">
<cfset ads = model("Ad").findAll()>
<cfdump var="#ads#"><cfabort>
</cffunction>
[/cf]

Notice the that we set ads = model(”Ad”).findAll().  This tells Wheels, to go get the Ad model, and findAll the data — Pretty Powerful! The data comes back as a ColdFusion query object.

For testing, put the <cfdump>line  in your controller, and send your browser to:  http://localhost/index.cfm/ads/. You’ll see the query dumped out in all its glory! This is a pretty good debugging trick. Add a <cfdump> to your controller to see what variables and data the controller is passing to the view. Remove the <cfdump> line, and let’s go create the view.

Go create /views/ads/index.cfm:

[cf]
<h1>All Ads</h1>
<ul>
<cfoutput query="ads">
<li>#linkTo(text="#ads.name#", route="ads", key="#ads.id#")#</li>
</cfoutput>
</ul>
[/cf]

Pretty simple! Specifying the query attribute in <cfoutput> makes this just like a <cfloop>. You end up with a bunch of List Items (<li>) — One for each record in the query we got from the controller.

linkTo() is another cool Wheels helper function. You could just use an <a> tag. However, using the linkTo() function is a best practice because it makes your application more portable. We specified the “ads” route in the function. If, later on, we changed our subfolders or URL rewriting, everything would still work.

That’s it. Send your browser to: http://localhost/index.cfm/ads/ and you should see a list of ads. Each ad will have a link that takes you to the show action and displays the ad.

Clarke Bishop CFWheels, ColdFusion CFWheels