Layout Widgets

This article describes common principles of working with layout widgets.

DevExtreme includes the following layout widgets.

Specify Layout Elements

A common task you encounter with when working with a layout widget is specifying layout elements arranged by the widget. You can solve this task using the dxItem markup component. Create a div element for each layout block and apply the data-options attribute set to dxItem.

HTML
<div id="box">
    <div data-options="dxItem: firstItemOptions ">
        . . .
    </div>
    <div data-options="dxItem: secondItemOptions">
        . . .
    </div>
    <div data-options="dxItem: thirdItemOptions">
        . . .
    </div>
</div>
JavaScript
$("#box").dxBox({})
AngularJS Approach
HTML
<div dx-box="{ }">
    <div data-options="dxItem: firstItemOptions ">
        . . .
    </div>
    <div data-options="dxItem: secondItemOptions">
        . . .
    </div>
    <div data-options="dxItem: thirdItemOptions">
        . . .
    </div>
</div>
Knockout Approach
HTML
<div data-bind="dxBox:{ }">
    <div data-options="dxItem: firstItemOptions ">
        . . .
    </div>
    <div data-options="dxItem: secondItemOptions">
        . . .
    </div>
    <div data-options="dxItem: thirdItemOptions">
        . . .
    </div>
</div>

To learn what set of item options is required for a specific widget, refer to the Default Item Template reference section of this widget.

The layout widgets implement common Collection Container Widget functionality. This enables you to specify widget items and customize item appearance using the approach supported by collection container widgets.

Specify An Element Size

Layout widgets arrange elements in the specified direction. The size of each element along the arranged direction is specified by values of the baseSize and ratio fields of an object associated with an element.

Layout widgets use the following algorithm to count the element size.

For example, there is a widget whose width is 100 pixels. This widget includes items with the baseSize and ratio values.

{ baseSize: 20, ratio: 0.5 }
{ baseSize: 15, ratio: 1.5 }
{ baseSize: 25, ratio: 2 }
  1. Set the element size to the baseSize value.

  2. Obtain free space, which equals the difference between the widget size and the total base size of all elements.

    In the given example, the free space is 100 - (20 + 15 + 25) = 40

  3. Obtain free space unit size, which equals the free space divided by the total ratio of all elements.

    In the given example, the free space unit is 40 / (0.5 + 1.5 + 2) = 10

  4. Increase the element size by the free space unit multiplied by the ratio value.

    In the given example, the widget elements have the following final size values.

    1. 20 + 10 * 0.5 = 25

    2. 15 + 10 * 1.5 = 30

    3. 25 + 10 * 2 = 45

NOTE
You can use the baseIndex and ratio fields together or separately. If you specify an element size using only the baseSize field, the element size always equals the specified value. If you use only the ratio field, the element size is counted relatively to the free space size and is hidden if the widget does not contain free space.

The Box widget uses this algorithm to count item size along the specified direction. The ResponsiveBox widget uses this algorithm to count height of rows and width of cols.

List of Layout Widgets

The following are DevExtreme UI layout widgets.

dxBox

The Box widget provides an easy way to arrange the specified markup elements in a row or column.

View Demo

Specify Layout Elements

The widget elements are usually specified using the dxItem markup component, as described in the Specify Layout Elements section of this article. The Box items support the following options specifying element size.

  • baseSize
    The base height of the row or base width of the column. This field can hold a value of the following types.

    • numeric
      The element size in pixels.

    • string
      A CSS measurement of size (e.g., "55px", "80%", "auto" and "inherit").

    • function
      The function returning the element size.

  • ratio
    The row or column size ratio.

For information on the complete set of item options, refer to the Default Item Template reference section of this widget.

Specify Arrange Direction

The widget arranges the elements in a column or in a row depending on the direction option value, which can be 'row' or 'col'.

JavaScript
var boxOptions = {
    direction: 'col'
}

Align Layout Elements

You can also specify the alignment applied to the the elements if they are not stretched to fill the entire widget container. For this purpose, the widget includes the align and crossAlign options, which specify alignment along the specified direction and cross-wise respectively.

dxResponsiveBox

The ResponsiveBox widget enables you to create a site with different layouts for different devices as illustrated by the following image.

Different Layouts

View Demo

Screen Factor

The widget selects which layout to use depending on the screen factor. The widget supports the following screen factors by default.

  • xs
    The screen width is less than 768 pixels. Used for a small phone screen.

  • sm
    The screen width is more than 768 and less than 992 pixels. Used for a small tablet screen.

  • md
    The screen width is more than 992 and less than 1200 pixels. Used for a large tablet screen.

  • lg
    The screen width is more than 1200 pixels. Used for a large desktop screen.

To specify custom screen factors, use the screenByWidth option of the widget. The function passed to this option takes on the screen width as a parameter and returns a string containing the screen factor corresponding to the current screen width.

JavaScript
var responsiveBoxOptions: {
    screenByWidth: function(width) {
        if( width < 768 )
            return 'xs';
        if( width < 992 )
            return 'sm';
        if( width < 1200 )
            return 'md';
        return 'lg';
    }
}

Layout Grid

The layout elements are positioned against the widget grid specified using the cols and rows options.

JavaScript
var responsiveBoxOptions: {
    rows: [
        { baseSize: 100 },
        { ratio: 1 },
        { ratio: 1, screen: 'sd md' },
        { baseSize: 100 }
    ],
    cols: [
        { ratio: 1 },
        { ratio: 2, screen: 'lg' },
        { ratio: 1 }
    ]
}

An item of an array passed to these options can include the following fields.

  • baseSize
    The base height of the row or base width of the column. This field can hold a value of the following types.

    • numeric
      The element size in pixels.

    • string
      A CSS measurement of size (e.g., "55px", "80%", "auto" and "inherit").

    • function
      The function returning the element size.

  • ratio
    The row or column size ratio.

  • screen
    The screen factor or factors by which the current row or column is used. If this field is not defined, the row or column is used by all screen factors.

Specify Layout Elements

The widget elements are usually specified using the dxItem markup component, as described in the Specify Layout Elements section of this article. The ResponsiveBox items support the following options used to specify the element position, size and screen factor.

  • row
    Specifies the row component of the element location.

  • col
    Specifies the column component of the element location.

  • rowspan
    Specifies the height of the element in rows.

  • colspan
    Specifies the width of the element in columns.

  • screen
    The screen factor or factors by which the current location is applied to the element.

For information on the complete set of item options, refer to the Default Item Template reference section of this widget.

HTML
<div class="header" data-options="dxItem: { 
    location: [{ row: 0, col: 0, colspan: 3, screen: 'lg'}, { row: 0, col: 0, colspan: 2, screen: 'xs sm md'}]}">Header</div>
<div class="content" data-options="dxItem: { 
    location: [{ row: 1, col: 1, screen: 'lg' }, { row: 1, col: 0, colspan: 2, screen: 'xs sm md' }]}">Content</div>
NOTE
If you display data visualization widgets within the ResponsiveBox widget, ResponsiveBox automatically locates them, however, it cannot resize them automatically. Thus, to display a data visualization widget within ResponsiveBox, you should specify its width and height in pixels. If the data visualization widget size is not specified or specified relatively to the parent container ('100%', 'auto', 'inherit'), the ResponsiveBox size is calculated incorrectly.
HTML
<div id="myResponsiveBox">
    . . .
    <div data-options="dxItem: itemOptions">
        <div style="height: 200px; width: 200px;" id="myCircularGauge"></div>
    </div>
    . . .
</div>
AngularJS Approach
HTML
<div dx-responsive-box="responsiveBoxOptions">
    . . .
    <div data-options="dxItem: itemOptions">
        <div style="height: 200px; width: 200px;" dx-circular-gauge="gaugeOptions"></div>
    </div>
    . . .
</div>
Knockout Approach
HTML
<div data-bind="dxResponsiveBox: responsiveBoxOptions">
    . . .
    <div data-options="dxItem: itemOptions">
        <div style="height: 200px; width: 200px;" data-bind="dxCircularGauge: gaugeOptions"></div>
    </div>
    . . .
</div>