Part 3 -- DRYML and Hobo Rapid

Without writing any view layer code at all, the POD application is already in a fairly usable state. The entire UI has been derived automatically using information from our models and controllers. Of course, if you're building an important app, one that is going to be used over and over again, there is never going to be a substitute for a carefully considered, hand-crafted UI. This is where DRYML comes in. DRYML keeps development moving forward very rapidly thanks to two key features:

• The DRY in DRYML (Don't Repeat Yourself) is there for a reason. DRYML makes it painless to keep your view layer extremely well factored. Well factored code is agile code, and in web development this matters as much in your views as anywhere else. Maybe more.

• DRYML has a unique and powerful paramaterisation mechanism. All those automatic pages that are almost but not quite what you want -- you won't have to throw away any of it. DRYML will allow you to make very specific changes, small or large. Mark-up that you don't want to change will remain.

• application.dryml

• Customizing the front page
• Customizing a show page
• Tweaking the theme

application.dryml

In app/views/taglibs/application.dryml you can define your own application-wide tags and re-define existing tags to suit your needs. The file is pre-generated by Hobo.

App-name

Initially you will see:

<def tag="app-name">Pod</def>

This defines a tag called <app-name> that is used to display the application's name in the page header.

Change the definition to the following:

<def tag="app-name">POD Classifieds</def>

You will see that the page header changes to reflect this.

Page

The <page> tag provides the basic structure of your pages and is used by the generic page tags in Rapid. It is possible to define your own version of <page> but typically you can customize the existing definition to suit your needs with less effort. This is described in more detail elsewhere but for now we will show a short example of customizing the <page> tag.

Add the following to app/views/taglibs/application.dryml:

<def tag="page" extend-with="my-app">
  <page-without-my-app merge>
    <footer:>Copyright 2008 Acme Ltd.</footer:>
  </page-without-my-app>
</def>

{: .dryml}

Here we are providing some content to the page footer. You should see "Copyright 2008 Acme Ltd." appear at the bottom of every page. footer: is a named parameter provided by the <page> tag. For a full list of the parameters see the Rapid Pages documentation.

Changing the page layout

Page layouts provide a number of named parameters within the body of a page in a given structure. Rapid uses "simple-layout" as the default page layout and provides "aside-layout" as an option.

To switch to an aside layout by default for all pages, change the line above that reads <page-without-my-app merge> to:

<page-without-my-app layout="aside" merge>

Your pages should now look like this:

Customizing the front page

It is now time to begin editing individual pages, we will begin with the application's front page.

The front page in app/views/front/index.dryml is one of the few pages automatically generated by Hobo.

You will initially a <page> tag with "body", "content-header" and "content-body" parameters. Start by removing everything inside the content-header and content-body parameters so that the file looks like this:

<page>
  <body: class="front-page"/>

  <content-header:>
  </content-header:>

  <content-body:>
  </content-body:>
</page>

{: .dryml}

We want to add an image to the top of the page. Change content-header to the following:

<content-header:>
  <img src="http://hobocentral.net/images/trolley.jpg" alt="List It! Sell It! Fast!"/>
</content-header:>

{: .dryml}

Next, we want to fill out the main part of the page with a summary of "recent adverts".

Change content-body to the following:

<content-body:>
  <section>
    <h2>Recent Adverts</h2>

    <collection with="&Advert.recent.all"/>
  </section>
  <a with="&Advert">Show all</a>
</content-body:>

{: .dryml}

This will display a list of recent adverts.

Now we want to populate our aside with lists of categories and users.

Our page layout provides a parameter called "aside", we can add this inside our <page> to add our content to the side part of the page.

<aside:>
  <section>
    <h2>Categories</h2>
    <ul with="&Category.all">
      <li:><a/> (<count:adverts/>)</li:>
    </ul>
  </section>

  <section>
    <h2>Users</h2>
    <ul with="&User.all">
      <li:><a/></li:>
    </ul>
  </section>
</aside:>

{: .dryml}

Your front page should now look like this:

Customizing a show page

Now we are going to edit an advert's "show page" which is the page that displays details on a single advert such as /adverts/1.

The page already looks quite good, but we decide that we would like a list of categories in the aside. We've already written the code to display the categories on the front page so the first thing to do is to refactor this code into a tag so that we can use it in both places.

Add the following to app/views/taglibs/application.dryml:

<def tag="list-categories">
  <section>
    <h2>Categories</h2>
    <ul with="&Category.all">
      <li:><a/> (<count:adverts/>)</li:>
    </ul>
  </section>
</def>

{: .dryml}

Now that we've defined a tag we can replace the code in app/views/front/index.dryml that displays the list of categories with <list-categories/>.

We would like to add the same list of categories to the aside on our advert show pages. To do this we will need to edit app/views/adverts/show.dryml. Initially you will see that this file doesn't even exist. When a view file isn't present, Hobo will automatically try to use a tag <"action-name"-page>, in this case <show-page>, to render the page instead. <show-page> is a tag defined in Rapid pages which on it's own renders a generic view of our advert.

Create the file app/views/adverts/show.dryml. Now that there's a file in place we'll need to call <show-page> ourselves by making the contents of the file:

<show-page/>

{: .dryml}

If you reload /adverts/1 you will see that nothing has changed yet, but now we are in a position to make changes to the page by providing parameters to <show-page>.

Change the contents of show.dryml to the following:

<show-page>
  <aside:>
    <list-categories/>
  </aside:>
</show-page>

{: .dryml}

The categories should now be listed in the side column.

Tweaking the theme

The default Hobo theme "clean" provides comprehensive but minimal styling for all of Hobo's generic pages and tags. When styling your app you have a choice between creating your own theme from scratch or tweaking an existing theme to suit your needs.

In many cases tweaking the existing theme is sufficient. By adding style rules to public/stylesheets/application.css we can override the theme's styling since our application stylesheet is loaded and applied last.

Here is a simple example of tweaking the "clean" theme. Add the following to public/stylesheets/application.css:

html {background: #0f2639;}
.page-header {padding: 0; margin-top: 25px; margin-bottom: 0;}
.page-header {
  width: 100%;
  background-color: #47718F;
}
.page-header h1 {padding: 30px 40px;}
.page-footer {background-color: #0f2639;} 
.aside-content {background: #DAEFF2;}

.page-header .nav {margin: 0; background: #101d27;}
.main-nav {padding-left: 20px;}
.main-nav a {padding: 7px 8px 8px; border: none; background: none;}
.main-nav a:hover {border:none; background: black;}
.account-nav {top: -20px;}

{: .css}

This will make the pages blue and apply a different styling to the main navigation bar.