Part III – How does Monorail Work?

Tonight I’m going to discuss Layouts and Rescues.


Layouts are another term that webform developers are going to relate to ‘master pages’ and asp developers will call an ‘include’ file.

There are several ways to approach a layout — you can span one layout over several controllers or you can assign a layout to each controller separately. Either way, it’s quite easy to do in Monorail.

Here is the example from the Monorail msi installer project:

public abstract class BaseController : SmartDispatcherController

It’s rather obvious here: the BaseController is going to use the layout ‘default’. In the Monorail folder structure, there is a ‘layout’ folder in the Views folder. All layouts can go in there.

When using NVelocity this file will be default.vm

The Layout makes for a great place to include any javascript libraries used by your controllers. For example:

    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
    <link rel="stylesheet" href="$siteRoot/Content/css/base.css" />
   <!-- We have added the common js files to the project. You can either bring them as static files: -->
        <script type="text/javascript" src="$siteroot/Content/js/prototype.js"></script>
        <script type="text/javascript" src="$siteroot/Content/js/scriptaculous.js"></script>
        <script type="text/javascript" src="$siteroot/Content/js/behaviour.js"></script>
        <script type="text/javascript" src="$siteroot/Content/js/formhelper.js"></script>


        <script type="text/javascript">

To dive into this a bit: you’ll notice the use of $siteRoot. This is a NVelocity way of referring to the virtual directory root path. There are a few ‘helper’ functions as well with the ‘InstallScripts’

I use the layouts to wrap up common UI elements to display from page to page. The directive to tell Monorail where to insert the current page is defined as:

<div id="content">$childContent</div>

Again, it’s rather easy to create separate layouts – if you have a controller that you want to take on a separate layout, you can simply define in the attribute and create the corresponding .vm file (assuming NVelocity).


Next is the concept of a ‘rescue’. I left this out of the above controller sample – but as with layouts, rescues can be defined on the controller by using the attribute as follows:

public abstract class BaseController : SmartDispatcherController

Similiar to a layout, the rescues go into the ‘rescues’ folder under Views. Rescues are similiar to the concept of the global application error handler. Basically you can define different views for handling unexpected application exceptions.

Again, the default install of Monorail includes a sample rescue called ‘generalerror’ – as you can see below, it uses an NVelocity ‘macro’

#macro(showexception $exc)



<b>Inner exception:</b>
#set($inner = $exc.InnerException)

<h2>Unexpected error happened</h3>

<p> This is the rescue page. See the exception details below </p>

#set($exception = $context.LastException)

As with layouts, you can define unique rescues per controller.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s