All theme files are loaded as a WebJars dependency to Sunrise. This includes Handlebars source templates, all web assets (i.e. CSS, JS, images and fonts) and i18n YAML files. The expected structure being as follows:
META-INF
+-- resources
+-- webjars
+-- css
+-- fonts
+-- img
+-- js
+-- i18n
| +-- de
| +-- en
| +-- ..
+-- templates
Sunrise uses Handlebars.java by default as a template engine.
In order to find the corresponding template source file, it searches first inside the classpath /templates. If the file is not found there, then it tries inside the Theme's Webjars dependency (i.e. /META-INF/resources/webjars/templates). This enables a practical way to override parts of the template without the need of replacing it completely, as we will see in the section Customize HTML.
Learn how to modify this behaviour in Change template source loaders.
By calling the AssetsController in your routes, your application will first try to load the requested web asset inside Play's public folder and then inside the Theme's Webjars. If no web asset with the given path is found, it will return a 404 status error.
Notice that by placing web assets in Play's public folder you can easily extend Sunrise's functionality, as explained in Customize Web Assets.
Sunrise uses YAML files by default to provide text in different languages. Translations are grouped according to the page or section they belong, which is known as bundles (e.g. home, checkout). Each YAML file contains the translated text for a particular language and bundle.
The following structure would be used to have translations in German and English for the home and checkout bundles:
i18n
+-- de
| +-- home.yaml
| +-- checkout.yaml
+-- en
+-- home.yaml
+-- checkout.yaml
Similarly as it works with templates, the application tries to find the translated text first inside the classpath /i18n. If that particular translation is not found there, then it tries inside the Template's Webjars dependency (i.e. /META-INF/resources/webjars/i18n). This enables a practical way to override a particular translation without the need of replacing them all, as it is explained in the section Customize Internationalization.
Learn how to modify this behaviour in Change i18n resource loaders.
This guide shows you how to customize different parts of the template in an easy and convenient way. Note it is assuming the configuration has not been changed and that you have installed the Theme Importer SBT Plugin.
Run Sunrise and open it in a browser to inspect the part of the code you want to change. In the website's source code you will find comments indicating the template source file containing each component. In the following example we can see that the template source file containing the logo is common/logo.hbs.
...
<div class="col-sm-8">
<!-- start common/logo.hbs -->
<a href="/en/home" class="brand-logo">
<img class="img-responsive" src="/assets/img/logo.svg" alt="SUNRISE">
</a>
<!-- end common/logo.hbs -->
</div>
...In order to override this component we need to create a Handlebars template source file in conf/templates with the desired content, so that the new code is used instead of the original code. To do so, Sunrise Theme Importer offers a convenient SBT command sunriseThemeImportTemplateFiles, which given a whitespace-separated list of template files copies them from the original location to conf/templates.
Let's execute it for the previous example:
sbt 'sunriseThemeImportTemplateFiles common/logo.hbs'After the execution, conf/templates/common/logo.hbs has been created with the content of the original template source file:
With that, you are ready to start modifying the template. For example, let's replace the logo image with a simple text:
If you run Sunrise and reload the page, the image has been effectively replaced by the text:
...
<div class="col-sm-8">
<!-- start common/logo.hbs -->
<a href="/en/home" class="brand-logo">
Sunrise
</a>
<!-- end common/logo.hbs -->
</div>
...To learn how to write Handlebars templates, please check the Handlebars.js documentation. In particular, the sections about Expressions, Built-In Helpers and @data Variables.
You may need to provide additional HTML <meta> tags or other kind of information to the HTML <head>. To do so, just add them to the template source file conf/templates/common/additional-html-head.hbs, as shown in the example:
If you want to provide your own images, you just have to place them inside the public/images/ folder and modify the HTML accordingly as explained in the section Customize HTML. Following the logo example used in that section, you should obtain:
Notice that the image path has been replaced to public/images/.
Sunrise comes with the file public/stylesheets/sunrise.css where you can add your own CSS rules. As this is the last CSS file loaded of the website, from here you can override any previous rule set by the template.
If you want to provide your own CSS file instead, you just have to place the file inside the public/stylesheets/ folder and add the HTML <link> tag in the template source file conf/templates/common/additional-html-head.hbs, as shown in the example:
Sunrise comes with the file public/javascripts/sunrise.js where you can add your own JavaScript code.
If you want to provide your own JavaScript file instead, you just have to place the file inside the public/javascripts/ folder and add the HTML <script> tag in the template source file conf/templates/common/additional-html-scripts.hbs, as shown in the example: