Our First App

So we now have a basic file structure in place (in fact is you've downloaded the basic install from SourceForge then you should already have these files in place. So what happens when we browse a file through CFRhino. Well the first thing that happens is that the physical file we browse (usually index.cfm or rhino_root.cfm) calls a file rhino.cfm that lives in the frameworks core install location. This file ensures that the framework is instantiated for the root application we are using and sets up a number of request scope cfc's for us and the framework to use.

Rhino.cfm also checks that the framework knows how to respond to the request. This can actually occur via a number of routes, however, the most usual one is that the requested page has been defined in the /config/pages.xml file. The framework will try and match the requested page (usually defined as url.layout) to an entry of element <cfrhino:page> with a name attributes matching url.layout.

For this example we'll be requesting our example application's home page. Our url will be:

http://www.mysite.com/rhino_root.cfm?layout=example.home

Our pages.xml file will contain the following element

<cfrhino:page name="example.home">

    <cfrhino:construct>

        <cfrhino:layout name="lyt_main"/>

        <cfrhino:pagelet name="example.firstApp.dsp_head" space="head" order="0"/>

        <cfrhino:pagelet name="example.firstApp.dsp_home" space="content" order="0"/>

    </cfrhino:construct>

</cfrhino:page>

In this case, a match is found and control passes to the associated layout (lyt_main).

Layout, Spaces and Pagelets

The primary level of HTML contorl is the layout, this is where we start to take control of what is going to be output to the browser. You can think of the layout is an HTML document with holes in it. The concept is that the layout is a template, providing the rough structure of the rendered document, without any of the content. The holes in the template are where content will be inserted by CFRhino and are called 'spaces'.

Spaces, are simply containers that contain page content. The individual pieces of content that get inserted into these spaces are known as pagelets and are discrete units of output. The use of spaces and pagelets is a great benefit of using a framework like CFRhino as it allows you to do two things

You can extract common reusable elements, thus simplifying the process of updating them
You can modify the layout of the page very simply, by modifying a single layout file.

The space paradigm is essentially a <cfinclude..> but the target of the include is both dynamic and can include multiple pagelets.

To create a 'space' in a template, we use the code

<cfset request.space.getSpace("space_name")>

This forces the framework to search for any pagelets that should be displayed in the space named 'space_name'. The pages.xml file is where a pagelet is assigned to a space.

In our example, the layout has two spaces; 'head' and 'content'. CFRhino will include the file /firstApp/dsp_head.cfm in the head space and the file /firstApp/dsp_home.cfm in the content space.