The extends and import instructions let you structure the template so you can write code once and reuse it in multiple parts of the template.
The extends instruction lets a page that defines content extend a file that defines the structure. The latter is called a “layout” file because it defines the layout of one or more pages. By convention, layout files are stored in a template folder called “layouts.”
The following is an example of a layout file:
<!DOCTYPE html>
<html>
<head>
<title>{{ Title() }}</title>
</head>
<body>
{{ Header() }}
{{ Body() }}
</body>
</head>It contains show instructions that display the Title, Header, and Body macros. Note that calling a macro looks like a function call, because macros are functions. Only the declaration syntax is different.
The three macros are not declared in the file itself, but will be declared in the pages that extend this layout file:
{% extends "/layouts/standard.html" %}
{% macro Title %}Fantastic product{% end %}
{% macro Header %}
<header>A fantastic product</header>
{% end %}
{% macro Body %}
This fantastic product is...
{% end %}
<!DOCTYPE html>
<html>
<head>
<title>Fantastic product</title>
</head>
<body>
<header>A fantastic product</header>
This fantastic product is...
</body>
</head>The extends instruction must be at the beginning of the page, before anything else, and the page must declare the macros that are called but not declared in the layout file. These macros must start with an uppercase letter in order to be visible (and therefore callable) by the layout file.
The page can also have other declarations, such as variables and macros, used internally by the page itself, but it cannot have any other content outside of what is inside the macros.
In the previous example we only used macros without parameters, but macros with parameters are also allowed.
The import instruction imports into the current file the declarations present in another file so that you can access its variables or call its macros. Only declarations whose names start with an uppercase letter are imported.
Imported files can contain only declarations and no content, except inside macros. They define macros and variables that can be used elsewhere in the template simply by importing the file. By convention, imported files are placed in a template folder called “imports.”
For example, if the "/imports/images.html" file defines the following macro:
{% macro Image(url string, width, height int) %}
<img src="{{ url }}" width="{{ width }}" height="{{ height }}">
{% end %}after importing it you can call the macro:
{% import "/imports/images.html" %}
{{ Image("offer.png", 200, 200) }}
<img src="offer.png" width="200" height="200">The import instructions must be at the beginning of the file, before anything else, but after an extends instruction if present.
The import instruction lets you specify an identifier to use for accessing declarations in the imported file:
{% import images "/imports/images.html" %}
{{ images.Image("offer.png", 200, 200) }}
<img src="offer.png" width="200" height="200">