Module templates are used to control the HTML output of individual content types. It’s possible to set the system up so a single content type can have many different templates. For example you might want to display a list of testimonials on your homepage in a completely different way to the testimonials listed in the teaser area of another page.
File structure
When a content type is added to the site tree its template files are copied into a single directory for each module e.g. /assets/templates/modules/<module_name>/ so that they can be edited. You cannot start editing a content type’s template file until it has been added to the site tree.
The template files are named after the content type which they output. e.g. news_blog.twig.html or quotes_list.twig.html. If the template needs to include additional twig templates these should be placed in a folder named after the content type, they can be named however you like e.g. /assets/templates/modules/<module_name>/news_blog/news_blog_details.twig.html
As previously mentioned a content type can have more than one template. Firstly you need to create a new template much like any other module template. Next it needs to be named in a specific way. The format is [content_type_name]__[template_name].twig.html. The template name portion of the filename must only use lowercase letters and underscores.
If more than one template exists for a content type, then an additional select menu appears in the site tree to users when they are adding or updating content. This select menu lists all the additional templates available for them to use (including the default). If only the default template exists then the menu isn’t shown and that template is selected automatically.
Step by step guide to adding a new template for the News blog
Here we’re going to take you through the steps required when creating a new template for the News blog.
- Access the module’s templates directory via FTP. /assets/templates/modules/
- Open the /news/ directory.
If it doesn’t exist then create it I.e. /assets/templates/modules/news/ - Create a new template file for the new blog content type. E.g. news_blog__my_template.twig.html
- Now save some HTML within the template file to be output on the front end.
- In the site tree, add a new News Blog content type to the page. You will see that the new template will be listed. If you select it then the HTML you saved in the previous step will be output to the page.
Common template variables
In addition to module specific template variables (such as news articles in the news blog content type), a set of common template variables is made available to use in any template.
content object
Holds useful information about the piece of content being output to the page
Properties
- id
Integer
The ID of the current piece of content - classes
Array
Each element in the array is a css class name which has either been set by the user through the site tree or automatically by OmCore. - title
String
The title of the content set in the site tree
template object
This contains useful variables which makes building templates quicker
Properties
- name
String
The filename (without the extension) of the current template. e.g. quotes_list or news_teasers__homepage_layout
options object
This object represents the options which have been set in the site tree for this piece of content. e.g. If an introduction has been set in the site tree it would be available under {{ options.introduction }}
To get a list of the current options available to the template, use the out filter which will display a debug message in the browser listing the keys and values which you can use.
e.g. {{ options|out }}
Template filters
OmCore also extends the default set of Twig filters and adds a few more which should be useful when building module templates.
- attr(String $attribute)
This filter is useful for outputting optional HTML tag attributes on the page. It takes a single parameter, attribute. If the given string is set then its wrapped in double quotes and preceded by the value set in attribute (as well as a space character).
e.g. <div id=”container”{{ javascript|attr(“onclick”) }}>
If the javascript variable has been set (in this case to alert(‘hi’);) then the resulting output is:
<div id=”container” onclick=”alert(‘hi’);”>
otherwise it’s just:
<div id=”container”> - resize(String $size)
This filter can be used to resize images which have been uploaded to a module. It takes one parameter, the size, which is a string in the format [width]x[height], where [width] is the desired maximum width in pixels and [height] is the desired maximum height in pixels. The aspect ratio of the original image is always preserved.
e.g. <img src=”{{ article.thumbnail|resize(‘100x100’) }}” alt=”A thumbnail image” />
Will result in an image which is 100px by 100px. - nl2br
Exactly the same as PHP’s nl2br function, this filter takes a given string and converts all new line characters to <br /> - basename
Exactly the same as PHP’s basename function, this filter takes a given string which should be a file path and returns only the filename part. e.g. /assets/templates/mytemplate/photo_of_person.jpg becomes photo_of_person.jpg - ellipsis(Integer $length)
If the variable passed to this filter is longer than the length parameter then its shortened accordingly and a … character is appended.
e.g. {{ ‘The quick brown fox’|ellipsis(13) }} would return The quick bro… - out
This filter is used for debugging. It outputs the variable passed to it in an easy to read manner whatever its type (string, array, or integer).