Bolt Cheatsheet
You are reading the official Bolt Cheat sheet. This page contains a wealth of information, packed together in a small package.
Use CTRL-F
or OPTION-F
to quickly search inside the cheat sheet.
1. Sample theme structure ¶
This is the common structure of a Bolt theme. The files are located in themes/
. Define the theme to be used with the theme:
setting in the global config.yml
.
Filename | Function |
---|---|
|
Homepage or root of the site, i.e. |
|
listing page for overview of pages, entries or listings per category or search results, e.g. |
|
single page for a record of the 'entries' ContentType, e.g. |
|
fallback single template for any ContentType that doesn't have its own single record template, e.g. |
|
template for the sidebar |
|
template for the common footer of all pages |
|
template for the common header of all pages |
|
meta-information for a single page or record |
|
template for the markup of the menu. See also |
|
template for the markup for the search box. |
|
graphical assets used in the theme |
|
any used javascripts should go in here |
|
contains the (compiled) CSS for the theme |
|
optional folder for Sass source files, to be compiled into CSS. |
|
optional config file with settings specific to the theme. |
Read more: Templates and routing
2. Template cascading ¶
Bolt has some rules to help you quickly build custom templates for your site.
If your template is named exactly like the singular_slug
or slug
for the content
type or record it will automatically be used.
Rules for Records | |
---|---|
The ContentType has a ‘templateselect field’ and a template is selected for this record. |
|
The ContentType definition has a value for |
|
Bolt will check if a template with a suited name exists, like |
|
|
|
If no other rule matches, Bolt will use a template named |
Read more: Automatic template selection
3. Menus and menu.yml
¶
You can define one or more menus in
the file app/config/menu.yml
, which can then be inserted in your
templates using the {{ menu() }}
tag.
Example |
---|
|
Insert the menu in the site, using the {{ menu() }}
tag. Add a menu_main.twig
file in your theme folder, replacing 'name' with the name of your menu.
Example |
---|
|
Read more: Menus in the docs
4. ContentTypes and contenttypes.yml
¶
The ContentTypes in Bolt are defined in the file app/config/contenttypes.yml
. You can edit
this file directly, or from within the Bolt interface under 'Settings' > 'ContentTypes'.
Key | Function |
---|---|
|
The name of the ContentType, should be plural. |
|
The name of one record in the ContentType. Should be singular. |
|
(optional) This determines the slug of the ContentType, and therefore the URLs that are generated for this ContentType. |
|
(optional) This determines the slug of the a single record in this ContentType, and therefore the URLs that are generated. |
|
(optional) A short description of the ContentType. |
|
The fields that make up the content in this ContentType. See the section Field definitions for details. |
|
An array listing the different taxonomies used by this ContentType. See the section on Taxonomies for details. |
|
An array listing the different relations available to this ContentType. See the section on Relations for details. |
|
The default template to use, when displaying a single record of this ContentType. |
|
The default template to use, when displaying an overview of records of this ContentType. |
|
The amount of records to show on a single overview page in the frontend. |
|
(optional) The default sorting of this ContentType. For example |
|
(optional) The amount of records shown on each page in the Bolt backend. If there are more records, they will be paginated. |
|
(optional) When set to |
|
(optional) When set to |
|
(optional) The default status for new records in this ContentType, i.e. |
|
(optional) A boolean value to determine whether this ContentType should show up in search results. |
|
(optional) A boolean value to determine whether this ContentType should have routing or not. |
|
(optional) A Font Awesome icon to be used in the sidebar for this ContentType. For example: |
|
(optional) A Font Awesome icon to be used in the sidebar for a single record of this ContentType. For example: |
Read more: Defining ContentTypes in the docs
5. Fields for ContentTypes in contenttypes.yml
¶
The fields
option in a ContentType lists the fields for that ContentType. The available fields are below. See also Field options
Key | function |
---|---|
|
Simple text-input, for single-line fields |
|
The slug is a required field, but you can include it in the fields list to customize it. |
|
Simple image upload/select field. |
|
A field to create a list of images. Useful for slideshows and galleries. |
|
Simple file upload/select field. Also set |
|
A more complex upload/select field. |
|
WYSIWYG HTML field. |
|
Simple multi-line textarea input, for longer texts without HTML markup. |
|
A drop-down list to make a pre-defined selection from. |
|
A set of fields for embedding videos from websites like Youtube and Vimeo. |
|
A generic embed field for different sources like YouTube, Vimeo, Twitter, SoundCloud and those compatible with the OEmbed standard. |
|
A set of fields for easy selection of a geolocation (latitude/longitude). Requires |
|
Datepicker widget, to set/select a date. |
|
Similar to the |
|
A field to store integers. |
|
A field to store (floating point) numbers. |
Read more: Field definitions in the docs
6. Field options for ContentTypes in contenttypes.yml
¶
Each field in the ContentType is an array with several options. The available options are below. See also Field definitions
Key | function |
---|---|
|
Will show the field in a larger font, for |
|
Will show the field extra wide, for filling out the column. |
|
Will show the field narrow, for fields that should take only a couple of characters. For |
|
Will show the field to the right of the label, taking up less space vertically. For |
|
If omitted, the name of the field will be used as a label in the edit-screen. Replace 'Foo' with the desired label of the field. |
|
For |
|
Add a database index for this field, use with caution. |
|
Separate this and all subsequent fields (until another group declaration) into a tab with the name 'Foo'. Replace 'Foo' with the desired label of the tab. |
|
HTML to add before the field. |
|
HTML to add after the field. |
|
Add |
|
The default value for a field, if applicable. See below for an example. |
|
Use this to make a field required. Only works on |
|
Use this to make a field read-only. Only works on |
|
Use this to validate a field against a certain pattern, using regular expressions. |
|
Explicitly allow twig to be used in this field. |
|
Use for displaying extra information about the field. |
|
A list of allowed file extensions for uploading. Used with |
|
A custom path for uploaded files. Used with |
Read more: Field definitions in the docs
7. Relationships ¶
You can use relationships between records by adding a relation to a ContentType. Relationships are always bidirectional.
Example |
---|
|
Accessing record.relation
will give you nothing but the ContentTypes and id’s: {{ print(record.relation) }}
. To get the actual related records, use {% set relatedrecords = record.related() %}
.
Read more: Relationships in the docs
8. Taxonomies and taxonomy.yml
¶
You can create taxonomies by adding them to taxonomy.yml
. You can define your own taxonomies, and choose how they behave.
Type | Function |
---|---|
|
Tags are a sort of ‘freeform’ labeling. Each record can have several tags, that do not have to be selected from a predefined list. |
|
Categories are chosen pre-defined categorizations for your record. These are often found on weblogs. |
|
Grouping is like categories but it is - by definition - more strict. When a grouping applies to a certain record, that record should be viewed as a part of the other records with the same grouping. |
Read more: Taxonomies in the docs
9. Permissions and permissions.yml
¶
The permissions needed to perform an action are configurable by editing app/config/permissions.yml
.
This can be done either directly, or through Bolt’s back-end UI. By changing the permissions you basically change the way
how people can interact with Bolt, and who is allowed to do what.
Read more: Permissions in the docs
10. Routing and routing.yml
¶
Bolt allows you to configure the routing to your needs. This basically
means that you can configure Bolt to generate and interpret URLs the way
you need them to be. There are some caveats with regards to correct
canonical URLs, but otherwise you can change it to anything you like.
The easiest way to add your own is to follow the examples defined in the
distributed routing.yml.dist
file. The order of the routes is important
because it is routing is done on a first-come first-serve basis.
Read more: Routing in the docs
11. Twig ¶
The templates in Bolt are written in Twig. This is a fast, flexible and elegant templating language.
Syntax | Meaning |
---|---|
|
Output someting, like 'echo' or 'print'. |
|
Do someting, like 'for', 'if' or 'setcontent'. |
|
Do nothing, this is a comment. |
|
A variable named 'foo'. |
|
Integers and floating point numbers can be used as-is. |
|
A literal sting, that has the value 'foo'. |
|
An array containing three elements. |
|
A hash is a list of keys and value-pairs, separated by a comma. |
12. Setting variables ¶
Syntax | Meaning |
---|---|
|
Set the variable |
|
You can set variables to contain literals, arrays, hashes, etc. |
|
Use set to append strings or merge arrays. |
13. Including other templates ¶
Use this to include another Twig template in the current template.
Twig parses the template like any other template, so you can use any
tags in your included template that you would use in the ‘main’
template. You can also use include
inside the included templates."
Syntax | Meaning |
---|---|
|
Includes the file |
|
You can set variables to contain literals, arrays, hashes, etc. |
An alternative to using 'include', is to set up your templates using Template Inheritance. This is a method of defining a base template, and then expand it in more detail in the templates that extend this base template. See the section on Template inheritance on the twig website.
Read more: Including other templates, Template inheritance
14. Using macros in Twig ¶
Macros in Twig can be thought of as functions in PHP or Javascript.
Syntax | Explanation |
---|---|
|
Define a macro in '_macros.twig' |
|
Import the macros in your template. |
|
Call the macro in your template. |
If you've defined the macros in the same file, you need to import them, using _self
:
{% import _self as macro %}
Read more: Macro in the Twig docs
15. The {% if %}
control structure
¶
The if
tag is used to check if 'something' (an expression) is true
or false
, and act accordingly.
Syntax | Explanation |
---|---|
|
Simple 'if' statement. |
|
'if' statement, with an |
Read more: If in the Twig docs
16. The {% for %}
control structure
¶
The for
tag is used to iterate over a hash or array, repeating the same code for each element.
Syntax | Explanation |
---|---|
|
Simple 'for' loop. Note the use of |
|
You can use 'if' in the 'for' statement. |
|
Use a filter, for example to sort on |
Read more: For in the Twig docs
17. Bolt functions in Twig ¶
Functions in twig look like this: {{ foo('bar', 1, 2) }}
. A
function can take zero or more parameters. Basically, a function does
something, and then returns the result for output or further processing.
Name | Function |
---|---|
|
Print a nicely formatted dump of the contents of |
|
Print a formatted dump of the backtrace stack, with the "followed path" through the code. |
|
Create a short excerpt from |
|
Parse a given string as Markdown. * |
|
Checks if a given record corresponds to the page being shown in the browser. * |
|
Returns the language value for in tags where the language attribute is required |
|
Output a simple pager, for paginated listing pages. |
|
Switch the debugbar |
|
Check if the current page is viewed on a mobile device |
|
Output a menu. See the section on menus. |
|
Check if a certain action is allowed for the current user (and possibly content item) |
|
Helper function to make a path to an image thumbnail. * |
|
Helper function to show an image on a rendered page. * |
|
Helper function to make a path to an image. * |
|
Helper function to wrap an image in a Magnific popup HTML tag, with thumbnail. * |
|
Get an array with the dimensions of an image, together with its aspectratio and some other info. * |
|
Check if a file exists |
|
Ouputs all or some fields from a record. Many options are available and documented here |
|
Return the requested parameter from |
|
Returns the first item of an array. * |
|
Randomly shuffle the contents of a passed array. * |
|
Translate a label to the current localisation settings. * |
|
Redirect the browser to another page. |
Note: functions()
marked with an '*' can be used as |filter
as well.
18. Default functions in Twig ¶
Bolt uses the Twig template engine. As such, all default
twig {{ functions() }}
also work in Bolt. Most of these have a
similar meaning in plain PHP or Javascript. The available functions are:
attribute,
block,
constant,
cycle,
date,
dump,
include,
max,
min,
parent,
random,
range,
source,
template_from_string.
19. The {% setcontent %}
tag
¶
The {% setcontent %}
tag is one of the most important tags in Bolt, because it allows you to get content in any location to use however you need.
Parameter | Function |
---|---|
variable name |
The first parameter (before the '=') is always the variable that will contain the result set |
|
The name of the ContentType to fetch records from |
|
get the latest 10 records from |
|
get the record from |
|
get the record from |
|
use |
|
use |
|
you can also use taxonomies in your |
|
use shortcuts like 'now', 'today', 'tomorrow' for date selection. |
Read more: {% setcontent %} in the documentation
20. Twig default tags ¶
21. Bolt Filters in Twig ¶
Filters in twig look like this: {{ 'foo'|filter }}
, and can take
optional parameters. A filter basically transforms whatever you put into
it, so it can be processed further. Filters can be chained together, for
example: {{ record.title|excerpt(20)|lower }}
.
Name | Function |
---|---|
|
Returns the date and time in a particular format. Takes the locale into account. See |
|
Formats the given string as Twig in HTML |
|
Make a string's first character uppercase. |
|
Return the 'sluggified' version of a string: 'Lørüm Ipsum' -> 'lorum-ipsum' |
|
Add 'soft hyphens' to a string. These normally inivisble hyphens, allow a browser to wrap a string, if it wouldn't fit the layout otherwise. |
|
Return a 'safe string' version of a given string: 'Lørüm Ipsum' -> 'lorum ipsum' |
|
Order an array, based on the given 'key'. |
|
Leniently decode a serialized compound data structure to an array / object. Note: |
22. Default filters in Twig ¶
Bolt uses the Twig template engine. As such, all default
twig {{ |filters }}
also work in Bolt. Most of these have a
similar meaning in plain PHP or Javascript. The available filters are:
abs,
batch,
capitalize,
convert_encoding,
date,
date_modify,
default,
escape,
first,
format,
join,
json_encode,
keys,
last,
length,
lower,
merge,
nl2br,
number_format,
raw,
replace,
reverse,
round,
slice,
sort,
split,
striptags,
title,
trim,
upper,
url_encode.
23. Twig tests in Bolt ¶
Name | Function |
---|---|
|
Test whether a passed string contains valid JSON |
25. Default variables in Twig ¶
Key | Value |
---|---|
|
An array containing the specifics of the currently logged on user. Empty if the user is not logged on. |
|
A string containing the current name of the Bolt version. |
|
The current version number, like '2.0.2'. |
|
A boolean that's |
|
A boolean that's |
|
A boolean that's |
|
An array containing the users in the system. |
|
An array, containing the theme-specific settings, as defined in the |
|
An object containing the current configuration. See the block Config object. |
26. Debugging Bolt ¶
If you’re coding and you want to get a quick look at whatever variable or object you’re trying to manipulate, you can dump its contents to the browser. In templates, use the following: The variable can be a normal variable, a single record, multiple records, or other stuff.
Code | Function |
---|---|
|
Dump 'variable' in the template. |
|
Dump 'variable' in your code. |
|
Get a backtrace throught the code to the current point in the execution, in the template. |
|
Get a backtrace throught the code to the current point in the execution, in your code. The optional parameter denotes the maximum depth of the output of the backtrace. |
Read more: {{ dump() }} in the documentation
27. The app.request
variable.
¶
The app.request
variable holds all request variables, like those in
$_GET
and $_POST
, but also session variables and attributes set by
Bolt itself. Use {{ app.request.get('foo') }}
to access them.
Key | Value |
---|---|
|
An array with the specifics of the current controller |
|
The name of the (current) matching route. |
|
Parameters of the currently matching route, if there are any. |
|
The current app object. Usually |