Template Documentation

• Introduction
• Template Syntax
• Fields to be used in templates
• Special Helpers (QR-Codes)

Introduction

We are using HTML & CSS to typeset and layout publications. HTML (Hypertext Markup Language) is a markup language and the base of every website. HTML contains your contents in a structured, machine readable form. CSS (Cascading Style Sheets) adds styling to HTML documents, so they no longer just a wall of text.

HTML

A basic HTML document would look like this:

This is not a useful template and just an example how basic HTML works

<!DOCTYPE html>
<html>
<body>

<h1>My First Heading</h1>
<p>My first paragraph.</p>

</body>
</html> 

Templates

Our templates are not pure HTML, they are written with handlebars. The templates contain HTML but also adds placeholders where your content blocks (e. g. a headline and a paragraph) will be added later. The template is used to generate the finished HTML file.

So this template:

<!DOCTYPE html>
<html>
<body>

{{#each children}}
{{html}}
{{/each}}  

</body>
</html> 

with two content blocks inside, children could generate the HTML above.

CSS

When we created a template, we can add CSS to style our publications. There are multiple ways to add CSS:

Inline CSS

This should only be used if you only want to style one specific element.

<!DOCTYPE html>
<html>
<body>

<h1 style="color: red;">My First Heading</h1>
<p>My first paragraph.</p>

</body>
</html> 

This will result in a red headline.

Stylesheets

This is the preferred way to style your publications since it defines universal styling rules that will be automatically applied.

Firstly, we have to add a head block with a link to our css file (here book.css):

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="book.css">
</head>
<body>

<h1>My First Heading</h1>
<p>My first paragraph.</p>

</body>
</html> 

Now we will need to create this css file:

h1{
color: red;
}

Now all level 1 headings (h1) will be rendered red.

More Resources

This article can only give you a first impression of what HTML/CSS is. You can find a detailed guide to create templates in the next articles, but you should learn the HTML/CSS basics first.

Here is a list of good resources for learning the basics:

• W3Schools HTML Tutorial
• W3Schools CSS Tutorial

Template Syntax

Templates are mostly used to create an HTML version of your content, which then can be used to create further formats (e.g., PDF, EPUB). Our templates are based on Handlebars, a simple template engine.

Print a value

To display a value (see available fields) you can use two curly brackets:

<h1>Book Title: {{metadata.title}}</h1>

You will need to use three curly brackets, if your fields contain HTML:

<h1>Book Title with HTML: {{{metadata.title}}}</h1>

Conditions

You may want to hide/show fields depending on if they are empty/unset or not.

If-Condition

Use the if condition to only do something, if the value is not null/empty:

{{#if metadata.subtitle}}
<h2>{{metadata.subtitle}}</h2>
{{/if}}

This code snippet will only create a heading if metadata.subtitle is not null/empty.

Why should I bother using if's?
You could just use {{metadata.subtitle}} and if it's empty it will not show. But it will typically still affect spacing/etc. if you create the HTML element (e.g., an empty <h2></h2>)

You can also add an else branch, which will be executed if the specified field is null/empty:

{{#if metadata.title}}
<h1>{{metadata.title}}</h1>
{{else}}
<h1>Lorem Ipsum</h1>
{{/if}}

This code snippet will print “Lorem Ipsum” if metadata.title is null/empty.

Unless-Condition

If you want to show something, unless a variable is set & not empty, you can use unless:

{{#unless metadata.title}}
<h1>Warning: Title missing!</h1>
{{/unless}}

Iterate through multiple Entries

Often you will need to iterate through a list of things, e.g. authors or sections. You can use each for that:

<h1>Contributing Authors:</h1>

{{#each metadata.authors}}
<p>{{first_names}} {{last_names}}</p>
{{/each}}

This snippet will show first and last names of every author in the project.

Context Change
Note that the context changes with the use of each: You may expect we would use {{metadata.authors.first_names}}, but we have to strip away metadata.authors since we "entered" the context when we used each.

Partials

You may want to split your template into several, reusable parts. Just create another template file (e.g. metadata_page.hbs.html) and include it via {{> metadata_page}} or  {{> global_assets/metadata_page}} if you created the template as a global asset.

Fields to be used in templates

This section contains a list of all fields you can currently use in templates.

Notation: List<Person> = a list of values with the type Person,

Project Metadata

Prefix: metadata.
(e.g. metadata.title prints the book title)

Field	Type (string/number/list/type/bool)	Optional (true/false)	Description
title	string	false	Project title
subtitle	string	true	Project subtitle
authors	List<PersonOrString>	false (but may be empty)	List of all authors, either added to the project or to one of the (sub)sections
editors	List<PersonOrString>	false (but may be empty)	List of all editors, either added to the project or to one of the (sub)sections
web_url	string	true	URL to a web version of this project (e.g. blog symposium)
identifiers	List<Identifier>	true	List of identifiers, e.g. ISBNs, DOIs, etc.
published	DetailedDate	true	publish date
languages	List<Language>	true	project language(s)
number_of_pages	number	true	currently not used
short_abstract	string	true	short abstract / content summary
long_abstract	string	true	long abstract / content summary
keywords	List<Keyword>	true	List of keywords with optional gnd identifier
ddc	string	true	DDC class
license	License	true	License of the publication - either Creative Commons or a custom license.   Variants: CC0 CC_BY_4 CC_BY_SA_4 CC_BY_ND_4 CC_BY_NC_4 CC_BY_NC_SA_4 CC_BY_NC_ND_4 other (contains a string)
series	string	true	Series this publication belongs to
volume	string	true	Volume this publication belongs to
edition	string	true	Edition of this publication
publisher	string	true	Publisher of this publication

PersonOrString

One of these variants:

• Person -> type Person
• NameString -> type String

Person

Field	Type (string/number/list/type/bool)	Optional (true/false)	Description
id	string	true	internal unique id
first_names	string	true	one or more first names
last_names	string	false	one or more last names
orcid	Identifier	true	ORCID (Open Researcher and Contributor ID)
gnd	Identifier	true	GND (Gemeinsame Normdatei)
bios	List<Biography>	true	list of biographies for this person, with specified language
ror	Identifier	true	ROR (Research Organization Registry ID)

Identifier

Field	Type (string/number/list/type/bool)	Optional (true/false)	Description
id	string	true	internal unique id
name	string	false	custom name of the identifier (e.g. "ebook ISBN)
value	string	false	value of the identifier (e.g. the ISBN)
identifier_type	IdentifierType	false	Identifier Type - one of these variants: DOI ISBN ISSN URL URN ORCID ROR GND Other (contains a string)

Language

One of these variants:

• DE
• EN

Biography

Field	Type (string/number/list/type/bool)	Optional (true/false)	Description
content	string	false	the biography
lang	Language	true	language of the biography

Keyword

Field	Type (string/number/list/type/bool)	Optional (true/false)	Description
title	string	false	the keyword
gnd	Identifier	true	GND belonging to this keyword

DetailedDate

Field	Type (string/number/list/type/bool)	Optional (true/false)	Description
year	number	false	the year
month	number	true	month as number without leading zero
month_leading_zero	string	true	month as string with leading zero
month_name	MonthName	true	Matches one of these variants:   january february march april may june july august september october november december
day	number	true	day as number without leading zero
day_leading_zero	string	true	day as string with leading zero
day_weekday	Weekday	true	Matches one of these variants: monday tuesday wednesday thursday friday saturday sunday

Project Settings

Prefix: settings.
(e.g. settings.cover_image_path)

Note: settings is an optional field

Field	Type (string/number/list/type/bool)	Optional (true/false)	Description
toc_enabled	bool	false	Whetether a table of contents should be shown
csl_style	string	true	name of the enabled csl (citation style language)
csl_language_code	string	true	used language code for csl
metadata_page_additional_html	string	true	Information to be shown on the metadata/imprint page
cover_image_path	string	true	filename of the cover image. You can include the image with <img src="uploads/{{settings.cover_image_path}}">
backcover_image_path	string	true	filename of the backcover image. You can include the image with <img src="uploads/{{settings.backcover_image_path}}">

Project Contents

sections is a List of Sections.

Example to print all section titles:

{{#each sections}}
<h1>{{metadata.title}}</h1>
{{/each}}

Section

Field	Type (string/number/list/type/bool)	Optional (true/false)	Description
id	string	false	unique section id
sub_sections	List<Section>	false (but can be empty)	a (nested) list of sections
children	List<ContentBlock>	false (but can be empty)	content blocks of this section
metadata	SectionMetadata	false	Metadata of this section
visible_in_toc	bool	false	whetether this section should be shown in the toc
endnotes	List<Endnote>	false (but can be empty)	list of endnotes used in this section

ContentBlock

Field	Type (string/number/list/type/bool)	Optional (true/false)	Description
id	string	false	unique content block id
block_type	BlockType	false	BlockType variants: Paragraph Heading Raw List Quote Image
html	string	false	content of this block as html

SectionMetadata

Field	Type (string/number/list/type/bool)	Optional (true/false)	Description
title	string	false	title of this section
toc_title_subtitle_override	string	true	optional version of the title + subtitle for the table of contents
subtitle	string	true	subtitle of this section
authors	List<PersonOrString>	false (but can be empty)	authors of this section
editors	List<PersonOrString>	false (but can be empty)	editors of this section
web_url	string	true	url to web version of this section (e.g. blog post)
identifiers	List<Identifier>	false (but can be empty)	identifiers of this section (e.g. chapter doi)
published	DetailedDate	true	date the section was published
lang	Language	false	language of this section

Endnote

Field	Type (string/number/list/type/bool)	Optional (true/false)	Description
num	number	false	number of the endnote in this section
id	string	false	unique id of the endnote
content	string	false	formatted endnote as html

Special Helpers (QR-Codes)

Currently, we provide a special handlebars helper that can be used in templates:

QR-Code Helper

Syntax: {{qrcode <content> <dark_color> <light_color>}}

With this helper, you can create QR-Codes (as svg) with the specified content (e.g. a URL). Optionally, you can provide a dark and/or a light colour (as hex string) to be used in the QR-Code.

Examples:

{{qrcode "https://verfassungsblog.de"}} - Creates a simple QR-Code leading to verfassungsblog.de with black colour on white background

{{qrcode "https://verfassungsblog.de" "#FB5074"}} - Creates a QR-Code with pink colour on white background