Introduction

This section is meant for designers and developers with knowledge and experience in creating HTML.

The powerful BComposer templating system promotes the separation of the design and content generation tasks used in creating a new mailout. This means that content generators do not need to worry about not having sufficient technical knowledge to create complex bulletins, a task that can be left to the professional designer and developer.

Before creating templates in Bcomposer, you should read through the standard Liquid Markup documentation to get a good feel for how a liquid template hangs together.

Basic Structure Recap

Each bulletin in Bcomposer is composed of three levels:

1. bulletin - the bulletin itself including subject and title fields
2. section - a bulletin is split into as many sections as required, each with its own title.
3. entry - finally each section contains many entries. Each entry provides a set of fields such as titles, image, description, etc. that can be easily filled in by the user.

The template system allows access to each field of data contained in each entity and provides methods to access sections and iterate over entries it contains.

Additionally, BComposer supports a visual editing interface so that a bulletin can be edited directly. Methods are provided to define areas in a template that once presented to the end user, can be clicked on to enter and change the information.

Entities

The following entities and methods are provided. To access a field of data, something similar to following should be called:

 <h1>{{ bulletin.subject }}</h1>

(If you've not read the Liquid Markup documentation, this will make little sense.)

Another form of accessing field data is also available at a higher level than the liquid templates where fields are identified between two % symbols. For example:

 <p>Dear %recipient.full_name%,</p>

The original intention for this was to provide fast text replacement support so that the liquid or ERB templates could be stored in memory, and only the fields specific for each recipient would need to be updated to send the email. The current release of BComposer will however generate a new copy of the template for each recipient as the overheads for Liquid templates are comparatively low.

Sections

Each bulletin is divided into sections. A section contains fields for the title, a link perhaps and little else. They are defined as follows:

{% section 'name' %}
  <h1>Section title is: {{ section.title }}</h1>
{% endsection %}

Here we can see a section is defined called "name" and presents the title provided in the title field. The section name must be unique in the template to avoid repeated information!

Entries

Entries contain the body texts of the bulletin and must be defined inside a section. An entry contains many more fields than a section entity. Only one 'entry' definition can be defined inside a section, but there may be many entry records in which case the code defined inside the entry block will be duplicated many times. For example:

{% section 'name' %}
  <h1>Section title is: {{ section.title }}</h1>
  {% entry %}
    <div>{{ entry.body }}</div>
  {% endentry %}
{% endsection %}

In the first part of the sample we define the title, and then provide a simple paragraph to contain each entries payload.

Defining Edit Areas

One of the special features of BComposer is that any one may edit the contents of a bulletin with little or know HTML knowledge, and defining edit areas in a template is a key component of that feature. An "edit area" defines a region of a template that the user can click on to alter the section or entry contents easily.

Continuing from the example above:

{% section 'name' %}
  {% edit section %}
    <h1>Section title is: {{ section.title }}</h1>
  {% endedit %}
  {% entry %}
    <div>
      {% edit entry %}
        {{ entry.body }}
      {% endedit %}
    </div>
  {% endentry %}
{% endsection %}

As can be seen, in this sample we allow the section entity to be edited along with each of the entries.

It is worth noting that caution must be taken as too where an editable region can be defined. In many situations tables may be used to layout the information (CSS support in is very poor I'm affraid!) so it while an entry my be repeated on each for each table row, we only want to edit data in each table cell. For example:

{% section 'name' %}
  <h1>This is a sample section with a table</h1>
  <table>
  {% entry %}
    <tr>
    <td>
       <img src="{{ entry.image }}" border="1">
    </td>
    <td>
      {% edit entry %}
        <div>{{ entry.body }}</div>
      {% endedit %}
    </td>
    </tr>
  {% endentry %}
  </table>
{% endsection %}

Here we can see that an edit area is only defined around the entry body and not the entry image. The entry image can still be edited via the body region, but it will not be highlighted in the same way. This may be important to bear in mind when deciding where to place the edit regions to avoid breaking a design too much.