Editing themes
adva cms allows you to completely change every aspect of the design for a site using themes. You can also easily export, share and import themes as zip files.
The create and edit a theme with adva cms you need to:
- understand how Ruby on Rails views work
- be able to edit ERB templates (more templating engines are planned to be supported in future)
- be able to edit CSS and integrate it using the provided theme_asset_helper methods
To create a new theme simply navigate to the “Themes” section in the admin backend, click on “New theme” and fill in the form. This will create a new, empty theme.
You can activate and deactivate any theme in the same “Themes” section in the admin backend. To do that simply click on a “select”/”unselect” links below a listed theme. You can activate multiple themes per site.
Adding and editing theme files
A theme can contain any number of templates, stylesheets, javascript and image files.
To create a new template, stylesheet or javascript file simply click on “Create a new file” at the top of the right sidebar and fill in the form. You can also upload files (including images) by using the file upload form at the top of the right sidebar.
Make sure to name the file correctly. A few rules apply:
- Any files named *.erb will automatically sorted into the
templates/directory. (You can add subdirectories.) - Any files named *.css will automatically sorted into the
stylesheets/directory. (You can add subdirectories.) - Any files named *.js will automatically sorted into the
javascripts/directory. (You can add subdirectories.) - Any image files will automatically sorted into the
image/directory. (You can add subdirectories by manually editing the filename after uploading the file.)
adva cms will by default use the shipped default templates for rendering a view. You can add templates to your themes that overwrite these default templates by simply naming them in the same way and putting them into the same subdirectory (relative to their view directory).
For example adva cms comes the with the default layout template placed at:
vendor/engines/adva_cms/app/views/layouts/default.html.erb
Thus you can overwrite this file by creating a template named:
templates/layouts/default.html.erb
Right now you’ll have to look for a template in the several engines beneath vendor/engines/adva_*. In future we plan to make this a little easier by providing a way to select available template names.
Inside of your theme templates you’re free to do whatever you’d do in a default Rails view template: like these they are just ERB templates. That means you can: access the controller and request objects, access any assigned template variables and their methods or render your own partials.
For the same reason make sure you only use templates from sources that you trust and do not download themes from arbitrary sources without reviewing them for what they’re doing! For future versions we plan to also provide a completely secure template engine based on Ruby safe_mode.
Using theme_asset_helpers
When you’ve added stylesheets, javascript and/or image files to your theme (you most probably want to include at least a stylesheet) you need to use them in your layout so the visitor’s browser will load them. For this purpose adva cms comes with a few helper methods that make it easy to include your stylesheets, javascripts and images:
theme_stylesheet_link_tag theme_id, stylesheet_name
theme_javascript_include_tag theme_id, javascript_name
theme_image_tag theme_id, image_name
These helper methods basically work the same way as Rails’ helper methods stylesheet_link_tag, javascript_include_tag and image_tag work, besides that you also need to specify the theme_id.
The theme_id is your theme name formatted using common permalink conventions, i.e. lowercased and with spaces and special characters replaced by underscores. You can easily lookup the theme_id by looking at the URL when editing your theme in the backend. E.g. the theme_id for a theme named “adva cms” would be “adva_cms”.
So, for example, if you have a theme named “adva cms” and you have added a stylesheet named stylesheets/default.css you can include this stylesheet by adding the following ERB tag to your default.html.erb layout template:
<%= theme_stylesheet_link_tag 'adva_cms', 'default' %>