---
title: "Layouts"
description: "Optimize your field placement with Alpaca's automatic and layout-driven options for seamless form design. (Gitana 4.0)"
product: "Gitana"
version: "4.0"
url: "/documentation/gitana/4.0/forms/api/layouts"
---

# 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](./layouts-example1-template.html "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 example 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](./layouts-example2-template.html "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. The layout is provided as a string in the config.