Layouts

Alpaca features both automatic and layout-driven mechanisms for placing your fields onto a page. The automatic mechanism simply walks through your fields in the order they are expressed in schema and places them one by one in a stacked order. The layout-driven mechanism allows you to provide a layout template that finely describes where your fields should be placed using DOM-driven injection.

To use a layout, you simply need to provide a view that has a layout block. The layout block defines the HTML template to use and then optionally defines the bindings of fields into sections of the HTML.

The layout block requires a template value to identify the HTML template that will render the fields. The template is a Handlebars template, generally, though Alpaca supports custom rendering engines if you choose to use one. The template has access to the schema, options and other parameters if you need them for any rendering purpose.

An optional bindings block can be supplied which provides key/value mappings of field IDs to DOM elements. The field IDs are the keys and a CSS selector is the value. The CSS selector must resolve down to a single DOM element otherwise you will get some weird behavior.

If a bindings block is not provided, Alpaca supports looking up exact field matches within the template using the data-alpaca-layout-binding attribute where the value is the name of the field.

Explicit Bindings Example

Here is an example of a form with two fields that uses a custom layout with explicit bindings. The layout renders fields into an HTML TABLE. The layout file is layouts-example1-template.html.

Note that the bindings property of that layout allocates the fields to the right place inside of the layout.

Customer Profile Example

Here is a more elaborate exmaple with a more complex set of data. The concept is the same. We use explicit bindings via the bindings property of the layout. The layout here is a bit more interesting as it employs some Handlebars directives to work with the options context.

The layout file is layouts-example2-template.html and is used to render a Bootstrap two-column layout.

Layout-driven bindings

We can also let the layout explicitly tell us where it wants things to be placed. This is a more rigid approach but one that is useful if you have complex forms and want to take further control of the layout.

The data-alpaca-layout-binding attributes within the layout determine where fields are placed.

Two-Column Layout with sub-properties

Here is a simple two column layout with sub-properties. They layout is provided as a string in the config.