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 four directories:

config - This contains files controlling how the site is built. At a minimum, it must contain a project_config.json file defining at least one build profile (more on that below).

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).

build - When Salal builds a site, this is where it puts the resulting files. Separate subdirectories are created for each build profile. For example, a profile called 'test' will be built in build/test', while a profile called 'production' will be built in build/production'.

Setting up a project configuration

Every project requires a project configuration file, which is in JSON format. This file should contain one or more sections which define build profiles. The contents of project_config.json for this demo are shown below. In this case, the file defines one build profile called test.

{
    "test": {
	"project": {
	    "site_title": "PNW Birds"
	}
    }
}

Salal will run if all you do is define a build profile. More commonly, though, you will want to use that profile to set the values of System variables and Project variables. In this case, the test profile defines one project variable called site_title and gives it the value PNW Birds. Project variables are used to insert a particular string of text into a template when the site is built, so let's now turn our attention to templates.

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}} - {{project.site_title}}</title>

This is where the project variable that was defined in the project config file gets substituted in. Double braces in templates indicate a variable substitution. Variable names beginning with project. are project variables, defined in the project config file. You will notice that there is another variable substitution here as well, for the variable this.title. Variable names beginning with this. are 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 trying to insert a template variable or a project variable. 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 were building the test profile, it would end up in build/test, 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. In this case we've only created one profile, called test. We can build the site using that profile like this:

python -m salal build test

The profile name at the end is optional, if you don't provide it, Salal will use whatever profile is listed first in project_config.json. So we could also have just done this:

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/test.

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.