Making an HTML Template

To follow along with this section, start with tag v2.0.8.

All of the work which will be done in this section could have been done in parallel with work in previous sections. This section will show you how to make an HTML template which can be used to render with the DOM.

One of the key ideas of pedestal-app is that it separates rendering from application logic. You don't have to think about one while working on the other. When these two things are mixed together it can lead to a lot of unnecessary complexity.

Organizing design work

The pedestal-app tools provide a way to organize your design work which is simple and flexible. Click on the Design link in the Tools Menu or go to http://localhost:3000/design.html to see the generated design page.

The purpose of this page is to provide links to all of the HTML templates for this project. Templates can be arranged in many different ways. You may want to have everything that you need for the application in one page or you may want to make templates to more closely reflect the pages of your application.

The file behind this page is

tutorial-client/tools/public/design.html

You may add anything, or nothing, to this file. The only purpose of the file is to make it easy for you find and load the template files you are working on. Nothing in pedestal-app requires that you use this.

The changes shown below will make the page a bit more informative.

<div class="section panel">
  <h2>Tutorial Templates</h2>
  <ul>
    <li><a href="/design/tutorial-client.html">Plain Counter Page</a></li>
  </ul>
</div>

Looking at the source for this page, you are introduced to the first of two special tags which are used for combining HTML files.

<_within file="tooling.html">
   <div>...</div>
</_within>

As shown above, from the development tool, you can refer to this page with the URL: http://localhost:3000/design.html.

When the design.html file is loaded it will see the _within tag and will load the page tooling.html and put the content of design.html within tooling.html.

How does it know where to put the content? design.html has a top-level div with id content. tooling.html also has div with id content. The div#content in tooling.html is simply replaced with the div#content of design.html. Only the top-level elements in the _within section are inserted into the parent file.

There is also an _include tag which allows you to include the contents of one file into another.

It is very important to realize that _within and _include are only used at development time. They are not part of pedestal-app's templating system. These tags are only recognized by the development server while templates are under development. As such, they are only meant to provide designers with a very simple way to not repeat themselves.

Creating a template

The generated "Hello World" application includes a generated template which is located in the file

tutorial-client/app/templates/tutorial-client.html

You may view this file by clicking on the link on the Design page or by loading the URL: http://localhost:3000/design/tutorial-client.html

A template which can be used for the counter application is shown below. You may use this or write your own.

<_within file="application.html">

  <div id="content">

    <div class="row-fluid" template="tutorial" field="id:id">

      <div class="span6">

        <div>
          <button class="btn btn-success" id="inc-button">Increment Counter</button>
        </div>

        <div class="counter-row">
          <span class="counter-label">Counter:</span>
          <span class="counter" field="content:my-counter">40</span>
        </div>

        <div id="other-counters">
          <div template="other-counter" class="counter-row" field="id:id">
            <span class="counter-label">Counter for <span field="content:counter-id">ahbnytnh</span>:</span>
            <span class="counter" field="content:count">10</span>
          </div>
        </div>

      </div>

      <div class="span2">

        <div class="stat-label">
          Max Count
        </div>
        <div class="stat" field="content:max-count">40</div>

        <div class="stat-label">
          Avg Count
        </div>
        <div class="stat" field="content:average-count">25</div>

        <div class="stat-label">
          Total Count
        </div>
        <div class="stat" field="content:total-count">50</div>

      </div>
      <div class="span3">

        <div class="stat-label">
          Max Dataflow Time
        </div>
        <div class="stat" field="content:dataflow-time-max">35</div>

        <div class="stat-label">
          Avg Dataflow Time
        </div>
        <div class="stat" field="content:dataflow-time-avg">9</div>

        <div class="stat-label">
          Current Dataflow time
        </div>
        <div class="stat" field="content:dataflow-time">6</div>

      </div>

    </div>

  </div>

</_within>

Most of this template is standard HTML. All the special stuff that makes this a pedestal-app template can be explained by focusing on two lines in this files.

Pedestal-app uses two special attributes to define a template: template and field. An HTML element with a template attribute is a distinct template which can be referred to by name. The field attribute is used to describe how data is mapped from a Clojure map to this template.

<div class="row-fluid" template="tutorial" field="id:id">

The example above begins to define a template named tutorial. This div and its contents are a single template. The field attribute indicates that the value under the key :id in the provided map should be set as the id attribute of this div.

You can define a mapping to several attributes by creating a comma delimited list.

field="class:c,width:w,id:my-id"

The names to the right of the colon are the keys in the supplied map. The names to the left of the colon are the HTML attributes. To fill this template, one might supply the data below.

{:c "example-class"
 :w 200
 :my-id "example-id"}

That is almost everything you need to know about creating templates in pedestal-app. Other than setting attributes, we may want to set the content of an element. To do this we use the special attribute name content.

<span class="counter" field="content:my-counter">40</span>

You may have noticed that the HTML above contains a template within a template. In the next section you will see how to extract and use each of these templates.

Update CSS

The generated CSS is located in the file

tutorial-client/app/assets/stylesheets/tutorial-client.css

The updated CSS for the counter application is shown below.

#content {
    margin-top: 30px;
}

.counter-row {
    margin-top: 20px;
    margin-bottom: 10px;
}

.counter-label {
    font-size: 30px;
    font-weight: bold;
    color: #888;
}

.counter {
    font-size: 30px;
    font-weight: bold;
    padding-left: 10px;
}

.stat-label {
    font-size: 16px;
    font-weight: bold;
    color: #666;
    margin-top: 10px;
}

.stat {
    font-size: 16px;
    font-weight: bold;
}

As one final improvement, change the class container to container-fluid in the main div under body in app/templates/application.html.

<div class="container-fluid">

Compiling SCSS files

Pedestal-app currently supports the compilation of SCSS. Just place SCSS files in the same location as the above CSS file and it will be compiled to CSS along with everything else.

It does this by "shelling out" to Compass. This means that you will need to have Compass installed. If you can successfully run compass compile then pedestal-app will do this for you when it notices that source files have changed.

To use Compass, you will also need to configure it by placing a config.rb file in the tutorial-client directory with at least the following contents

http_path = "/"
css_dir = "out/public"
sass_dir = "app/assets/stylesheets"
images_dir = "out/public"
javascripts_dir = "out/public"

Next steps

This section showed you how to create a template. The next two sections will show you how to use it.

The tag for this section is v2.0.9.

Home | Slicing Templates