Building projects

Editing templates

Tarbell projects consist of simple HTML pages that may use Jinja2 templating features.

If you create a file in your project directory called chapter1.html, you’ll be able to preview the file at http://localhost:5000/chapter1.html and publish to the same file. This file can be straight up HTML, or it can inherit from a Tarbell blueprint file.

Files and directories that start with an underscore (_) or a dot (.), like the _blueprint directory containing the Tarbell blueprint files, will not be rendered by the preview server or included in the generated static HTML.

Understanding Tarbell Blueprints

Blueprints are exactly what they sound like –– a basic structure for building projects upon. From the Flask documentation:

Flask uses a concept of blueprints for making application components and supporting common patterns. Blueprints can greatly simplify how large applications work, but a blueprint is not actually an application. Rather it is a blueprint of how to construct or extend an application.

Tarbell ships with a default blueprint called _blueprint. This folder contains boilerplate code like advertising, analytics, and common page elements. Tarbell projects should inherit from blueprints.

Here’s a simple _blueprint/_blueprint.html example.

<html>
  <head>
    <title>{{ title }}</title>
    {% block css %}
    <link rel="stylesheet" type="text/css" href="css/style.css" />
    {% endblock css %}
  </head>
  <body>
    {% block content %}{% endblock content %}
  </body>
</html>

To inherit from this template, you use the “extend” syntax in index.html or other project files you create. All your index.html needs to contain is:

{% extends '_base.html' %}

{% block content %}
<h1>{{ title }} </h1>
{{ content|markdown }}
{% endblock content %}

You might notice we’re using the |markdown filter. Blueprint templates also define filters, enabled by Jinja2. See building blueprint templates for more, and the Jinja2 docs for more on Jinja2.

If a blueprint defines a static file or template (e.g. _blueprint.css), it will be available relative to the project’s base path (e.g. http://127.0.0.1:5000/style.css). If a project defines a file with the same name, the project’s version will be used instead.

See the basic Tarbell template for a simple implementation of a Blueprint.

Template inheritance: Override files from Tarbell Blueprints by copying to your project directory

Any file in a Tarbell Blueprint can be overridden in your project files.

For example, if your blueprint includes a file _blueprint/_nav.html, you can create a file named _nav.html in your project directory and it will be published instead of the blueprint version.

This works for all files, static or templates.

Files prefixed with underscores (_) will not be generated or published

To suppress a file from publishing, use a filename like _filename.txt.

Configuring projects

Project configuration is kept in the tarbell_config.py file in your project’s blueprint directory. See Project settings (tarbell_config.py) for configuration documentation.

Creating JSON

You can publish the data coming from your Google spreadsheet as JSON if so desired. To do this, set the CREATE_JSON flag in tarbell_config.py to True. When you visit yoursite.com/data.json, Tarbell will create some JSON that will look something like this:

{
  name: "ethelpayne",
  title: "Ethel Payne: A life in journalism",
  headline: "Ethel Payne, Chicago journalist",
  quote: "I stick to my firm, unshakeable belief that the black press is an advocacy press, and that I, as a part of that press, can’t afford the luxury of being unbiased ... when it come to issues that really affect my people, and I plead guilty, because I think that I am an instrument of change.",
  data: [
    {
      name: "Ethel Payne",
      known_for: "civil rights journalism",
      born: "8/14/1911",
      died: 33386
    }
    {
      name: "Grace Hopper",
      known_for: "mathematics and computer programming",
      born: "12/9/1906",
      died: 33604
    },
  ]
}

The first block of keys and values comes from the values workbook. The data array represents another workbook. Any other workbooks you create within your spreadsheet will be represented as separate arrays.

Optionally, you can use the CONTEXT_SOURCE_FILE setting in tarbell_config.py to determine your data source, which can be a URL, local file, CSV or Excel file.

Note

The data.json file is created on the fly and will not appear in your project root. You can view and access it locally at 127.0.0.1:5000/data.json. If JSON creation is enabled, it will override any local file named data.json.

Using context variables

Template data can come from Google spreadsheets, a local or remote CSV or Excel file, or tarbell_config.py’s DEFAULT_CONTEXT. The context source is configured in tarbell_config.py (see Project settings (tarbell_config.py) for reference).

This simple DEFAULT_CONTEXT shows many of the key template features:

DEFAULT_CONTEXT = {
    'name': 'nellie-bly',
    'title': 'The Story of Nellie Bly',
    'font_size': '20px',
    # Nested dictionary
    'photos': {
        'intro': {
            'url': 'img/bly01.jpg',
            'caption': 'A caption',
        }
    },
    # Nested list
    'timeline': [
        {'year': '1902', 'description': 'Description...'},
        {'year': '1907', 'description': 'Description...'},
        {'year': '1909', 'description': 'Description...'},
    ],
  }
}

To print the title in your template, use {{ title }}:

<h1>{{ title }}</h1>

Address a nested dictionary:

<img src="{{ photos.intro.url }}" alt="{{ photos.intro.caption }}" />
<aside>{{ photos.intro.caption }}</aside>

Access a list of data:

<ul>
  {% for year in timeline %}
  <li><strong>{{ year }}</strong>: {{ description }}</li>
  {% endfor %}
</ul>

Where can context variables be used?

Context variables can be used in HTML, CSS, and Javascript files. If the text file causes a Jinja template error (which can happen if the file has Jinja-like markers), the file will be served as static and the preview server will log an error.

This means that CSS and Javascript files may include variables. style.css might include:

#content { font-size: {{ font_size }}; }

Similarly, a Javascript file could include:

var data = {{ photos|tojson }}
console.log(photos.intro.url);

Use this feature with care! Missing variables could easily break your CSS or Javascript.

Anatomy of a project directory

When you run tarbell newproject with the default blueprint, a number of new files and folders are created, many of them with special significance. Details may vary for other blueprints, but they’re likely to have many similar files and concepts.

Here’s a rundown of what they all do.

Files in the root directory:

index.html
The first page people will see when they visit your project. This is typically where most of the content lives, and is probably where you want to start editing.
tarbell_config.py
The settings and context for this specific project, described in more detail in the Configuring projects section above.

Files in the _blueprint directory:

Keep in mind that you rarely want to edit the blueprint files in the _blueprint/ directory - if you want to change something, copy the file to the root directory and make the change there. If a file of the same name exists in both the root directory and the _blueprint/ directory, Tarbell will rely on the one in the root directory.

The only time you should edit the files in the _blueprint/ directory is when you’d like to create or update the blueprint itself.

_base.html
The base page template, containing <head> and <body> tags, and pointing to many of the Javascript and CSS files that will be loaded for each page in the project.
_footer.html
The partial template containing anything you’d like to appear consistently in the footer at the bottom of each page.
_nav.html
The partial template containing the nav bar that runs along the top of the page.
_spreadsheet.xlsx
This is the template file that Google spreadsheets will be based upon. Unlike most other files in _blueprint, overriding it in your root directory won’t do anything. However, if you want future projects to be created with a different spreadsheet template, you can edit this file and commit it to a repository you control; learn more about this feature in the Developing blueprints section.
base.css
The base CSS file imported by the blueprint for this project. Override this file in your root directory if you’d like to make CSS changes.
blueprint.py
A Python file that contains a default set of template filters for use in this project. Override this file in your root directory if you’d like to alter the behavior of these filters, or add your own. If you’d like to make your changes available to other projects, check out the Developing blueprints section.
favicon.ico
Favicons are small logos for websites that typically appear next to a website’s name in a browser tab. Change this file in order to change the logo associated with your site in users’ browser tabs, though keep in mind that favicons have a number of rules about how they should be constructed.
favicon-preview.ico
This is the icon for the in-development version of a site that appears next to the website’s name in a browser tab, following the same rules as for favicon.ico above. The key difference is that this icon is meant to remind developers and testers that they’re not looking at a live site.
index.html
This is a fallback version of the project’s front page, in case the index.html file in the root directory is removed or renamed. It begins life as an exact copy of the root directory’s index.html.