Minimal project tutorial

This tutorial covers the critical files that are necessary in order for Salal to actually build a site, using the minimal-project demo provided on Github to illustrate. After completing this tutorial, you will have a basic understanding of how Salal works. You can then use the reference guide to learn more about individual features.

Getting the demo

1. Go to https://github.com/haskelt/salal.
2. Click on the 'Code' button, and choose 'Download ZIP.'
3. Extract the zip archive.
4. Navigate to the directory demos/minimal-project.

Exploring the project structure

Every Salal project requires at least two directories:

design - This contains files controlling the look, feel, and behavior of the site as a whole. At a minimum, it must contain a templates subdirectory that must hold at least one template. However, even in a very basic site, it will probably also contain another subdirectory resources that will hold CSS files, JS files, icons, etc.

content - This contains XML source files, one for each page on your site. Each source file must invoke one or more templates, and also provide the necessary parameters for those templates. The parameters are how you specify the unique content of that particular page (text, images, and so on).

In addition, when Salal builds a site, it will create a build directory, where it puts the resulting files. If you haven't defined any Build profiles, the files will be placed in build/default.

More complex projects will generally have a config directory as well. If you don't create one yourself, Salal will create it when you build your site so it can store dependency tracking information.

Working with templates

The design/templates directory contains the templates that are used to build the demo site. Template files should have an .html extension, and most of their content is usually HTML code. You will need at least one top-level template that builds a valid HTML page; in this case we have just called it page.html. The whole template is too long to reproduce here, but there are a few specific sections that are worth looking at. Near the top is the following line:

    <title>{{this.title}} - PNW Birds</title>

Double braces in templates indicate a variable substitution. Here, they indicate that the value of the variable this.title should be inserted. Variable names beginning with this. are called template variables; their values are provided when a template is used in a source file. Another example of a template variable can be found later in the file:

    <main>
      {{this.content}}
    </main>

The variable this.content is special because its value can be not only text, but also other templates. This is how Salal implements nested templates.

Let's look at one more example of a template to illustrate how nested templates can work, specifically bird-details.html. Here's what that template looks like:

<section class="bird-details">
  <div class="detail-item"><span class="detail-label">Latin name:</span> <span class="detail-value">{{this.latin_name}}</span></div>
  <div class="detail-item"><span class="detail-label">Habitat:</span> <span class="detail-value">{{this.habitat}}</span></div>
  <div class="detail-item"><span class="detail-label">Wingspan:</span> <span class="detail-value">{{this.wingspan}}</span></div>
</section>

This template provides a layout for three pieces of information about a bird: Its Latin name, its habitat, and its wingspan. Each piece of information is provided via a template variable - this.latin_name, this.habitat, and this.wingspan. In order to create a page presenting this information, your source file would first use the page template, and then set its content variable to be the bird-details template. In this way templates function as reusable building blocks for creating various kinds of pages. The precise way this is done will become more clear once we look at a source file, which we turn to next.

Preparing source files

Here's an example of one of the source files in the demo, specifically content/northern-flicker/index.xml:

<page title="Northern Flicker">
  <bird-heading>Northern Flicker</bird-heading>
  <bird-details
      latin_name="Colaptes auratus"
      habitat="Open woodlands"
      wingspan="42-51cm"
      />
</page>

This file tells Salal to start by using the page template. Note that when you refer to a template in a source file, you don't need to include the .html extension, that is assumed. For the page template, the title template variable is set to Northern Flicker, and the content template variable is set to whatever is between the open and close tags. In this case that content consists two other templates, bird-heading and bird-details. We looked at the bird-details template above; now you can see how the values for the template variables are specified. Note that you do not use this. before the variable name when defining a template variable, only when inserting it within a template. In the source file, it's clear from its location that it's a template variable. But in a template, it's important to let Salal know whether you are using template variables or Global variables. The this. notation indicates that it's a template variable.

Adding resource files

It's hard to imagine building a modern website without using CSS, and use of JavaScript isn't far behind. We haven't talked yet about how you can incorporate external resource files like this into your project.

You might have noticed in the page.html template file that it referenced a local style sheet:

    <link rel="stylesheet" href="/css/style.css" type="text/css" />

You will find this style sheet in design/resources/css/style.css. When Salal builds a site, everything in the design/resources directory gets copied over to the appropriate build directory. So if we are just using the default configuration, it would end up in build/default, where it can then be used by your pages.

Building the site

Once you've defined build profiles, assembled the templates you need, and created your source files, you're ready to build the site. Here's how to do that:

python -m salal build

You should get some output showing what Salal is doing. After the build is complete, the site files can be found in build/default.

That covers the basics of using Salal. Salal does have a lot of features we haven't covered here, but it's intentionally designed so that you only need to learn about the features you want to use. If you want to learn more about what it can do, take a look at the other pages in the wiki.