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.
<div id="box"> <div data-options="dxItem: firstItemOptions "> . . . </div> <div data-options="dxItem: secondItemOptions"> . . . </div> <div data-options="dxItem: thirdItemOptions"> . . . </div> </div>
$("#box").dxBox({})
Angular Approach
<div dx-box="{ }"> <div data-options="dxItem: firstItemOptions "> . . . </div> <div data-options="dxItem: secondItemOptions"> . . . </div> <div data-options="dxItem: thirdItemOptions"> . . . </div> </div>
Knockout Approach
<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 }
Set the element size to the baseSize value.
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
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
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.
20 + 10 * 0.5 = 25
15 + 10 * 1.5 = 30
25 + 10 * 2 = 45
The dxBox widget uses this algorithm to count item size along the specified direction. The dxResponsiveBox widget uses this algorithm to count height of rows and width of cols.
dxBox
The dxBox widget provides an easy way to arrange the specified markup elements in a row or column.
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 dxBox 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'.
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 dxResponsiveBox widget enables you to create a site with different layouts for different devices as illustrated by the following image.
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.
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.
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 dxResponsiveBox 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.
<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>
<div id="myResponsiveBox"> . . . <div data-options="dxItem: itemOptions"> <div style="height: 200px; width: 200px;" id="myCircularGauge"></div> </div> . . . </div>
Angular Approach
<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
<div data-bind="dxResponsiveBox: responsiveBoxOptions"> . . . <div data-options="dxItem: itemOptions"> <div style="height: 200px; width: 200px;" data-bind="dxCircularGauge: gaugeOptions"></div> </div> . . . </div>