Extends and Import

The extends and import declarations allow you to structure the template in order to write some code once and then call it in different parts of the template.

Extends

The extends declaration allows a file, that contains some content, to extend another file that defines its layout. Such file is called extended file or layout file.

The following is an example of layout file:

<!DOCTYPE html>
<html>
<head>
  <title>{{ Title() }}</title>
</head>
<body>
  {{ Header() }}
  {{ Body() }}
</body>
</head>

It contains show statements that call the macros Title, Header and Body. Note that a call to a macro looks like a function call, and this is because macros are functions. Declaration syntax is different.

These three macros are not declared in the file itself, but they will be declared in files that extend the layout file:

{% extends "/layouts/standard.html" %}
{% macro Title %}Awesome product{% end %}
{% macro Header %}
 <header>An awesome product</header>
{% end %}
{% macro Body %}
  This awesome product is...
{% end %}

<!DOCTYPE html>
<html>
<head>
  <title>Awesome product</title>
</head>
<body>
  <header>An awesome product</header>
  This awesome product is...
</body>
</head>

The extends declaration should be at the beginning of the file, before others declarations, and the file declares macros called but not declared in the layout file. These macros should have the first letter in uppercase to be visible and callable in the extended file.

The page can have other declarations, such as variables and macros, used in the same file, but it cannot have any content other than the one contained within the macros.

The previous example used only macro with no parameters, but there is nothing preventing the use of macro with parameters.

Import

The import declaration imports declarations from another file into the current file, so you can access its variables or call its macros. Only the exported declarations (declarations with the first letter in upper case) are imported.

Imported files can only contain declarations and cannot have content, other than that inside the macros. They define macros and variables that can be referred in other parts of the template by importing their file.

For example, if the file "images.html" defines the following macro:

{% macro Image(url string, width, height int) %}
  <img src="{{ url }}" width="{{ width }}" height="{{ height }}">
{% end %}

after importing the file, it is possible to call the macro:

{% import "images.html" %}
{{ Image("offer.png", 200, 200) }}

<img src="offer.png" width="200" height="200">

Import declarations should be at the beginning of the file, before anything else, but after an extends declaration if it is present.

Import for

As an alternative, you can also indicate the names you want to import into the current file from the other file. In this case only these names will be imported.

{% import "images.html" for Image, Banner %}
{{ Image("offer.png", 200, 200) }}

Import prefix

As an alternative, the import declaration allows you to indicate an identifier to be used as a prefix to access the declarations in the imported file.

{% import images "images.html" %}
{{ images.Image("offer.png", 200, 200) }}

✍️ Edit on GitHub, PRs are welcome.