How to Convert a Website From Branch Code to Twig
As of March 2017, Branch Code is deprecated and no longer developed. This page outlines some best practices when converting to the Twig syntax instead.
Note, while it's not a requirement that you convert to Twig, it's highly recommended.
You do not need to create a copy of the website to do the conversion. BranchCMS can support both Branch Code and Twig while you are doing the conversion.
Overview
The first step to take is to do an inventory of the site to determine what the templates are that need to be converted and how apps are being used. This will allow you to plan the conversion and to keep track of your progress.
Start from the inside of the template hierarchy and work your way in. The last thing that you should is change the site templates. (Unless you are also doing a redesign at the same time. In that case, you are creating all new templates.)
Use the code conversion tool to make it easier to convert your code. Simply paste in your Branch Code, click Submit and the Twig equivalent is returned.
As you update each template be sure to change the "Template engine" field to "Twig". If there are any code errors an error message will show and the template won't be saved.
Make sure that you also update any Collection Widget or Feed Reader templates as well. All types of templates need to be updated.
Forms
Historically forms have allowed you to have individual templates for each form. A few years ago we added shared form templates to share templates between forms. Recently we moved that feature under the forms app to make it easier to find and use. We strongly recommend that all forms use shared form templates instead of individual form templates.
To enforce this best practice, websites running solely on Twig will no longer support form-specific templates. You must go to Forms -> Form Templates and create your templates there. You can then edit the form and under the Design tab and pick the appropriate shared form template.
Containers
Containers came about a number of years ago to overcome the limitation that BranchCode site templates and snippets didn't support any logic. They provide a way to output certain content based on what the URL of the page is.
As you convert to Twig you can consider if containers are necessary anymore. If there are only a few items in the container with a few different rules you could consider adding the logic to the template to test the URL and then output certain content using the Page Object.
{% if _page.url != '/content' %}
{{ _api.form.get.key('contact') }}
{% eiseif _page.url starts with '/blog' %}
{% inlcude 'snippets/blog-sidebar' %}
{% endif %}
Removed content types
If you continue to use containers (which is completely fine) just note that certain content types are no longer supported.
- Navigation
- Snippet
- Content Area
You should use the API content type instead and enter the API tag for the content.
App page titles and breadcrumbs
Apps allow you to use code to generate the page titles and breadcrumb text for certain pages. You will need to convert these to Twig.
Go to the app and under the SEO navigation item go to "Page Titles, Breadcrumbs, & Meta Descriptions". Update each setting as appropriate.
Last steps
Once you have converted all of your templates to use Twig you should change a site setting that will complete the switch to Twig.
Go to Site Settings -> General Settings and you will see a "Template engine" field. Change that to "Twig".
Doing this will have the following effects:
- The site will fully be using Twig and Branch Code will no longer be an option.
- All new templates will use Twig (since it's the only option available) and you won't have to set the "Template engine" field value anymore.
- You will no longer see the Template Engine value when viewing templates since all templates are on Twig anyways.
- Minor performance improvements since the system doesn't need to test which template engine should be used.
- Theme files will be enabled. Themes are new to BranchCMS but they will add a lot to the process of maintaining templates.
Finally, test, test, test. Visit every page (or representation of each page) and make sure that content is as you expect.
Get help
If you need any help at all don't hesitate to contact support with any question.