Since January we have been working on changing the core template engine from our proprietary Branch Code to the popular Twig engine. We are about 95% done and figured that it was time to let everyone know about it.

For those that don't know, Branch Code (and now Twig) is the code that is used in templates to build your site and display your content.

Why Twig?

Because it has an awesome name that goes great with BranchCMS.

Well... the name was a nice bonus, but it wasn't the reason that we chose Twig. We've come to the conclusion that our proprietary template engine is becoming a liability, is too big of a task to maintain and develop, and was falling behind the capabilities of other template engines.

We considered starting over and creating something from scratch, but that didn't sit too well with us.

We also considered other template engines such as Liquid, Jinja, Nunjucks, and Django. 

After much research we decided on Twig because it has a long history, is well used and tested, has a great feature set, has a syntax similar to Branch Code, is extensible, and is frequently updated.

Benefits of Twig

There are a number of benefits that we get from Twig. They include:

• Saving on software development time by utilizing existing software
• More features than Branch Code has (filter chaining is a big one)
• Site templates and snippets now support the full template engine
• Site snippets can now be used in any type of template
• More powerful templates
• Ability to modify image, navigation, form and form field attributes before outputting a tag
• The ability to use filters in for loops, if logic and when setting values

To sum it up, Twig is more powerful, flexible and easier to maintain.

How to use Twig

We have started our documentation on Twig. There is still a lot to do, but if you have been using Branch Code, then Twig should be a relatively easy transition. We also began documenting differences between Branch Code and Twig. 

For existing sites, you can choose whether or not to use Twig or Branch Code when adding or editing existing templates, form templates, app templates, snippets and anywhere else code is used.

As you are adding new templates or updating existing templates to use Twig, you should set the "Template engine" field to "Twig" when you save it.

After you have updated all of your code go to Settings -> Site Settings -> General Settings and change the "Template engine" field to Twig.

Once you have done that the Branch Code engine will no longer be available and your website will be 100% powered by BranchCMS + Twig. 

To help with converting existing sites to use Twig we built a conversion tool that will convert Branch Code to Twig.

What about existing sites using Branch Code?

While it's strongly encouraged to take advantage of Twig for any new projects, all existing sites will continue to work with Branch Code. We are not adding to or improving the Branch Code engine, but it is still supported and will continue to work. Once no more sites are using Branch Code, we will remove it, but that's quite a ways away as currently hundreds of sites are built using Branch Code.

Do I need to update my website?

If you have a developer that is familiar with Twig then we do recommend updating the code for your site. You can use the code conversion tool to help with that. Or if you are adding new templates to the site we recommend using Twig instead of Branch Code. It's the default engine for new templates.

If you don't have a developer that you work with then don't worry. Your site will not stop working. As long as there are still sites using the Branch Code template engine it will continue to work.

We're not 100% done yet

There are a few small areas that are still using Branch Code where we haven't added support for Twig yet. That includes:

• Campaign email templates
• Request objects
• RSS settings
• Feed Widget templates

Those will be done soon. If you need to use those on a new project, please contact us for support.

Update May 3, 2017 - Request objects, RSS settings and Feed widget templates fully support Twig.

Feedback and questions welcomed

We want to hear from you if you are doing any template work. Let us know what you think of Twig and don't hesitate to ask questions.