Templates

Templates in AVCMS are built using the Twig template engine.

Getting Started

If you are not familiar with the Twig template engine then your first step is to learn the basics by reading the Twig documentation.

Next you will want to enable Developer Mode so that the changes you make during development are instantly reflected. If you are not in developer mode, you will need to refresh the caches in the admin panel every time you modify a template file.

Overriding Templates and Assets

The only template required in your theme is the index.twig file. But if you want to change the layout of other pages beyond what you are able to do with CSS, you can override them. You can also override default CSS and Javascript files. Remember, the more files you override, the more work you need to do when AVCMS is updated and changes are made.

The first step to overriding a file is finding out the name and location of the file you want to overwrite. When in developer mode you can find the name of the current page template on the developer toolbar at the bottom of all pages. To see the actual location of the template file, hold your cursor over the name and it will appear.

Lets say you are overwriting the homepage.twig template from the bundle CmsFoundation. The dev bar will show the name like so:

CmsFoundation/homepage.twig

Hovering your mouse over the template name will show you the location of the file on your server.

If you want to overwrite this file, all you need to do is create your own copy in the following directory):

[your-template-directory]/resources/CmsFoundation/templates/homepage.twig

Overwriting any template or asset is done in the same way within your template's resources folder, the structure being:

/resources/[bundle name]/[resource type]/[filename]. 

You will most likely want to copy the original template over to your template folder and modify it.

Template Configuration

Every template must come with a file called template.yml that contains configuration. These files are written in the YAML format. YAML is a "a human friendly data serialization standard" and is easy to read.

Here is an example of a standard template configuration:

details:
  name: Flatly
  description: Flatly Theme
  version: 1.0
  author: AV Scripts & Bootswatch

assets:
  style.css:
    priority: -100

admin_settings_sections:
  template: Template Settings

admin_settings:
  logo_image_url:
    type: text
    section: template
    label: Logo URL
  template_no_sidebar:
    type: checkbox
    section: template
    label: No sidebar
    help: Disable the right sidebar throughout the site
    default: 0
  template_sidebar_position:
    type: radio
    label: Sidebar Position
    choices:
      left: Left
      right: Right
    default: right
    section: template
  template_container_style:
    type: radio
    label: Template Width
    choices:
      max: Limit Width
      fluid: Fill Screen
    default: max
    section: template

module_positions:
  sidebar:
    name: Sidebar
    description: The main sidebar on the site
  content_top:
    name: Content Top
    description: The top of content pages (not on pages without the sidebar)
  content_bottom:
    name: Content Bottom
    description: The bottom of content pages (not on pages without the sidebar)
  page_footer:
    name: Page Footer
    description: The bottom of all pages, full-width
  header_bottom:
    name: Header Bottom
    description: Under the main navigation on all pages

menus:
  frontend_footer:
    label: Frontend Footer

Details

This section of the template configuration lets you set information about the template: the name, author, version & description

Assets

In AVCMS all CSS and Javascript files are combined together so that only one CSS file & one Javascript file need to be downloaded by the end user. In the assets section of the template config, you can add any custom CSS and Javascript that you want to be compiled. CSS files must be found in the /css folder of your template, and javascript files in the /javascript folder.

You can optionally add "compress: false" under the priority of the asset if you don't want the Javascript or CSS to be minified.

Admin Settings Sections

Here you can add new categories to the admin panel settings page. In the above example, we just add a category called "Template Settings".

Admin Settings

Here you can add extra fields to the admin panel settings for use in your template.

The above example shows how to make text, checkbox and radio fields. You can also make textareas (same syntax at "text" above) and select fields (same syntax as radio types).

Once you have created a setting, you can use that setting in your template by using "settings.setting_name", like:

 {% if settings.template_no_sidebar == 0 %}

Module Positions

Here you can specify the names and information about the module positions in your template. Adding the module positions to this file allows admins to assign modules to those positions, but you will still need to make sure the module position is rendered in your template in the position where you want it.

To render the module position somewhere in your template, use the "render_modules" function:

 {{ render_modules('sidebar') }}

Bootstrap

AVCMS makes use of the Bootstrap 3 CSS framework. If you want to redesign any bootstrap element, like buttons, forms or components like panels, you will want to create your own version of the bootstrap.min.css file. You can customise a custom Bootstrap CSS file using their website here. You can also download Bootstrap's source code and work directly with their LESS or SASS stylesheets.

Overriding the bootstrap.min.css file works just like overriding any other file as detailed above. The specific location for the bootstrap CSS is:

 [your-template-directory]/resources/CmsFoundation/css/bootstrap.min.css

You can also find some free Bootstrap themes to get you started from Bootswatch