Quad

Flexible layout system.

Overview

Quad is a layout engine usable for both fixed and responsive position-based layouts. An instance of Quad is created using an array of Layout objects, each of which can be targeted to a specific viewport or a range of viewport sizes, and containing an array of Box used to specify element positions that are only applied to that layout. Quad uses this collection of layouts to target multiple viewports by providing both height/width-specific layouts and layouts that target a definable range of viewport size.

Boxes

There are two main positioning models used in layouts:

1. Fixed (Absolute)
2. Grid (Responsive)

Both models declare element positions using 4-attribute box models:

1. Fixed (Absolute)

{
    x      : <int> // absolute x position of box
    y      : <int> // absolute y position of box
    width  : <int> // pixel width of box
    height : <int> // pixel height of box
}

2. Grid (Responsive)

{
    col  : <float> // the column (x) position of this box
    row  : <float> // the row (y) position of this box
    cols : <float> // the number of columns (width) this box occupies
    rows : <float> // the number of rows (height) this box occupies
}

Fixed layouts are used for viewports with unchanging dimensions, for example traditional IAB ad units.

For grid layouts, the four attributes values are converted into absolute dimensions using a layout-specified (default = 16) number of columns. The container viewport is divided into squares based on that number of columns, with their width equal to the viewport width divided by the number of columns and their height also equal to that width. The grid box values are converted to absolute pixel values by multiplying their values with this column width.

Each layout must specify the range of widths it is applied to using the size attribute.

Fixed size layouts are declared by providing a numeric width and height as size attributes. These layouts are only active when the viewport matches both the height and width exactly.

In contrast, grid layouts specify width via min and max arguments in order to describe the range of viewports for which they are applicable. Both arguments are optional. Min defaults to 0 and max defaults to Infinity, so that if neither are specified, the layout will apply to all viewport ranges. This allows for the user to specify a series of disjount layouts that apply to different ranges of viewport widths. For example, you could have three grid-based layouts one running from 0-480, one from 480-768, and another handling 768 and above.

These grid layouts can specify their height via either a ratio argument or ..