Module reahl.web.bootstrap.grid

New in version 3.2.

This module contains tools for controlling how elements are positioned.

The main tool here is an invisible layout grid which changes depending on the size of the device being used to browse. The module also contains several other related tools.

When creating a visual layout it is often useful to arrange elements on an invisible grid. The tools here allows building such a grid, but with a twist: the grid can resize depending on the size of the device that is used to view it.

User devices come in a wide range of sizes. In order to be able to change a layout depending on the size of a device, devices are classified into several device classes: ‘xs’ (extra small), ‘sm’ (small), ‘md’(medium), ‘lg’ (large), ‘xl’ (extra large).

Whenever you need to specify a size for Bootstrap grid element, you can specify the size that element should have for each class of device.

Bootstrap’s grid system works on units of 1/12th the size of a given parent width. A size for a particular device class is thus an integer denoting a size in 1/12ths of its container’s width.


class reahl.web.bootstrap.grid.Container(fluid=False)

A Container Layout manages the positioning of the main areas of a page. By default it ensures that the HTMLElement it is used with to be has a size that stays at a fixed width per device class and that it stays centered in the horizontal.

Using a Container is compulsory if you want to make use of a ColumnLayout.

Parameters:fluid – If True, the container fills the entire available width.


class reahl.web.bootstrap.grid.ResponsiveSize(xs=None, sm=None, md=None, lg=None, xl=None)

A size used for layouts that can adapt depending on how big the user device is.

Sizes kwargs for each device class are given as integers that denote a number of 12ths of the size of the container of the element being sized. Eg: 6 would mean 6 12ths, or 1/2 the size of the container.

If you specify a size for a device class, that size will be used for all devices of that class or bigger.

It is not necessary to specify a size for every device class. By default, if a device class is omitted, it is assumed to be sized as per the nearest specified smaller device class. If there is no smaller device class, a value of 12/12ths is assumed.

  • xs – Size to use if the device is extra small.
  • sm – Size to use if the device is small.
  • md – Size to use if the device is medium.
  • lg – Size to use if the device is large.
  • xl – Size to use if the device is extra large.


class reahl.web.bootstrap.grid.ColumnLayout(*column_definitions)

A Layout that divides an element into a number of columns.

Each argument passed to the constructor defines a column. Columns are added to the element using this Layout in the order they are passed to the constructor. Columns can also be added to the Widget later, by calling ColumnLayout.add_column().

To define a column with a given ResponsiveSize, pass a tuple of which the first element is the column name, and the second an instance of ResponsiveSize.

If an element is divided into a number of columns whose current combined width is wider than 12/12ths, the overrun flows to make an additional row.

It is customary, for example to specify smaller sizes (ito 12ths) for bigger devices where you want the columns to fit in next to each other, but use BIGGER sizes (such as 12/12ths) for the columns for smaller sized devices. This has the effect that what was displayed as columns next to each other on the bigger device is displayed as “stacked” cells on a smaller device.

By default, the smallest device classes are sized 12/12ths.


Called to add a column of given size.

Parameters:column_size – A ResponsiveSize, used to size the column.