Themes in BranchCMS

Themes are the overall design for your website. They can be as simple or complex as you want. You have full control over all the HTML, CSS and Javascript for your website and you can build and customize the theme to suit your unique designs.

A theme is made up of an opinionated folder structure and template files.

The template files are mostly regular HTML with some Twig tags sprinkled in to add logic to the templates.

Template types

Within BranchCMS different types of templates can be used to manage the design and code of your website. They include:

  • Site templates
  • Snippets
  • Navigation templates
  • App templates
  • Form templates
  • Page content templates
  • Content builder element templates
  • Email campaign templates

There are also other mini-templates for things like breadcrumb trails or app page titles.

Just about everything has a template so that you have full control over how your content is displayed and what HTML code you use.

Folder structure

By default, all themes are stored in a folder called "theme". You can configure this under Design -> Themes -> Settings.

Within the "theme" folder is where the folder containing the theme files is located. By default, a new site's theme is called "custom".

Within the individual theme's folder is a theme.json file use for theme configuration and the templates folder where all site templates are organized.

Site templates are located right within the "templates" folder. 

Other template types like snippets, navigation, or app templates are organized in their own folders.

Below is an example folder structure for a theme.

  • themes
    • custom
      • theme.json
      • css
      • images
      • js
      • templates
        • home.twig
        • two-column.twig
        • blog
          • archive.twig
          • categories.twig
          • category.twig
          • home.twig
          • post.twig
          • posts.twig
          • tag.twig
          • tags.twig
          • forms
            • comments.twig
          • calendar
            • agenda.twig
            • event.twig
            • home.twig
            • search.twig
            • search-results.twig
          • content-builder
            • 2-columns-1-2-1-2.twig
            • large-image.twig
          • content-layouts
            • page-header.twig
          • navigation
            • main.twig
            • footer.twig
          • snippets
            • header.twig
            • footer.twig
          • widgets
            • collections
              • image-slider.twig
            • feed-reader
              • feed.twig

    themes/
    The root folder where themes are stored is by default called "themes". You can change that under Themes -> Settings.

    custom/
    By default, the theme is called "custom". You can change the name of that folder if you want by editing it via FTP or in the File Browser.

    Theme folders and files

    Within the theme folder (in this case the "themes/custom/" folder) are different files and folders for the theme.

    theme.json
    This is the theme configuration file. In it you can specify the theme name, theme configuration fields, and other settings for the theme.

    css/
    While not required, it's recommended to store the CSS for your theme design within the theme folder. You can of, course, call this folder something else or omit it entirely.

    images/
    While not required, it's recommended to store the images for your theme design within the theme folder. You can of, course, call this folder something else or omit it entirely.

    js/
    While not required, it's recommended to store the Javascript for your theme design within the theme folder. You can of, course, call this folder something else or omit it entirely.

    templates/
    This is the folder where all of the templates for the theme are stored. It is required. 

    Other folders

    A theme can include other folders. The "templates" folder is the only folder that is required. As a general rule, your theme should contain all the files needed to render your design.

    Some other folder names could be 

    • coffee
    • fonts
    • less
    • sass
    • svg

    You could also create a folder to store a specific library. For example, if you use the excellent Slick slider then you may have a folder called "slick" within your theme folder.

    Theme template folders and files

    Directly within the "templates" folder, the site templates are stored. These are the templates that are used to display most pages and are often extended by app templates to show app pages.

    All other templates are organized in subfolders depending on what they are for. Some folders are for specific things (like navigation or snippets) and others correspond to different apps.

    blog/
    This is an example of an app folder. It's for the blog app. The app's instance key is "blog" so the templates are stored in the "blog" folder. If, for example, the app instance key was "news" then the templates would be stored in a "news" folder instead of "blog".

    calendar/
    Another example of an app folder. In this case, it's for the calendar app.

    content-builder/
    This is the folder where all Content Builder Element templates are stored. The name of the template files matches the template key for the element.

    content-layouts/
    This folder is used to store Content Layout templates.

    navigation/
    This folder is used to store navigation templates.

    snippets/
    This folder is to store snippets.

    widgets/
    Both the Collection and Feed Reader widgets store their templates in the widgets folder.

    widgets/collections/
    This folder stores the different templates for Collection widgets.

    widgets/feed-reader/
    This folder stores the templates for different Feed Reader widgets.

    Custom folders

    While there are specific folders for different template types, you are free to organize other templates in other folders. For example, if you wanted to store re-usable snippets of code to use within certain apps and for some reason you didn't want to have them under the "snippets" folder, you could create your own folder and store your snippet templates there.

    Example Template

    For the most part, templates are regular HTML with some Twig tags sprinkled into output dynamic content. Below is a very basic site template to show how you would use Twig template tags within your HTML.

    <!doctype html>
<html>
    <head>
        <meta charset="utf-8">
        <title>{{ _page.title }}</title>
        <meta name="viewport" content="width=device-width, initial-scale=1">
        {{ _page.meta() }}
        <link type="text/css" rel="stylesheet" href="/layout/css/main.css">
        {{ _page.css() }}
        {{ _page.js('head') }}
        {{ _page.head() }}
    </head>
    <body>
        <div class="Container">
            <div class="Header">
                <a href="/"><img src="/layout/images/logo.png" width="200" height="100" alt="My Company"></a>
            </div>
            <div class="Nav">{{ _api.site.navigation.get.key('main') }}</div>
        </div>
        <div class="Content">
            <div class="Content-sidebar">{{ _page.content('sidebar') }}</div>
            <div class="Content-main">{{ _page.content('main') }}</div>
        </div>
        <div class="Footer">
            {{ _api.site.navigation.get.key('footer') }}
            <div class="Footer-copyright">Copyright {{ _core.date.year }} My Company</div>
        </div>
        <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.1/jquery.min.js"></script>
        <script src="/layout/js/main.js"></script>
        {{ _page.js('footer') }}
    </body>
</html>

    Brief explanation

    Here is a brief explanation of some of the concepts used in the above template.

    1. The page title is outputted with the {{ _page.title }} tag, which is part of the page object.
    2. The {{ _page.meta() }} tag is used to output any <meta> tags for the page like the meta description tag. If a meta description is set for the page then the {{ _page.meta() }} tag will output that. If it wasn't sent and no other meta tags were set then nothing is outputted.
    3. The {{ _page.css() }} tag is used to output any stylesheet links or inline CSS that may be set for the page. You can specify page-specific stylesheets and inline CSS when editing pages or other templates like app content templates or collection widget templates.
    4. The {{ _page.js('head') }} tag will output any Javascript file <script> tags or any inline Javascript that may be set for the page. Javascript files and inline code can be organized by groups. The "head" value is used to output and Javascript assigned to the default "head" group. You can create your own group names if desired. The default group is "head" and if you do not specify any other groups then {{ _page.js() }} can be used to output the default group.
    5. The navigation is pulled in through the navigation API tag {{ _api.site.navigation.get.key('main') }}. The "main" value for the key parameter tells the system to get the navigation menu that has "main" as it's unique identification key. The navigation HTML is managed through a navigation template.
    6. The content for the page is pulled in through the {{ _page.content('main') }} tag. The "main" value indicates that the content for the main content area will be displayed. Every site has at least one content area called Main Content. Additional content areas can be set up. In this example, there is a sidebar content area. The {{ _page.content('sidebar') }} outputs the content for the sidebar content area.
    7. This example site has a separate navigation menu to display in the footer.  The {{ _api.site.navigation.get.key('footer') }} navigation API tag displays that navigation menu.
    8. Many sites have a copyright statement in the footer of the site that includes the current year. The {{ _core.date.year }} will output the current 4-digit year.
    9. It's common to have Javascript loaded at the bottom of the HTML for a page. When you are assigning page-specific Javascript, you can organize it in groups. The {{ _page.js('footer') }} tag will output any Javascript files and inline Javascript that was assigned to the "footer" group.