Layout controls help you lay out your app. Most layout controls contain other controls, including other Layout controls.
The Intel® XDK App Designer supports a number of UI frameworks, and UI frameworks generally do not support the same set of controls. This topic describes layout controls provided by App Designer that appear for certain UI frameworks. For example, if you selected the jQuery Mobile* framework, these Layout controls are available:
Before You Begin Using Layout Controls
Before you start using App Designer to insert Layout controls into a page, you should be aware that:
- A default vertical Column control is added to each page.
- Many controls have integrated labels.
- You can show or hide guidelines for a page by clicking the Guidelines toolbar button.
Default Vertical Column
Each App Designer page provides a default vertical Column, so you insert controls into it. This is the default layout for any page and no extra layout controls are required to achieve this.
Typically, any control inserted into a vertical Column goes full width to the page/column, so you do not need to provide explicit sizing. For example:
Integrated Labels
Many controls support integrated labels, so you do not need to independently layout and position a separate text or label component.
After inserting a control with a label and customizing the integrated label, they may seem “jagged” when stacked.
The solution for this is very simple. Make a new widths style and configure the alignment of the label. Then apply that same style to the other controls (drag it to each, or select it from the menu on the widths style category).
This action aligns the integrated labels:
Also, most controls with integrated labels let you specify where the label is positioning. Instead of it appearing inline on the left, you can also choose to have its label precede the control on the left or the right.
Show or Hide Guidelines
indicates Guidelines are OFF and indicates that Guidelines are ON
On the main toolbar above App Designer is a small button whose tooltip says “Guidelines”. Click this button to toggle guidelines ON or OFF. For basic layout, when you aren’t using custom layout controls, consider turning the guidelines OFF. There are fewer distractions and the page looks more like it will when viewed by a user.
However, many of the layout controls do not have their own visible representation when inserted into a page. When using these controls, turn the guidelines ON. Here is a screen capture of a Side By Side control inserted between the Beethoven list item and the OK button, with guidelines OFF:
Here it is again, with guidelines ON:
Layout Controls in App Designer
This topic describes these layout controls, primarily for context-sensitive use in the App Designer Contextual Tab: Button Grid, Card, Card Columns, Card Grid, Columns, Header and Footer, Overlay and Popup, Row, and Side By Side. It also describes layout-related Animated Sidebars.
The descriptions below are presented based on their frequency of use.
Layout or Related Control | Description |
---|---|
Side By Side | Provides a simple way of placing two controls next to each other. It also does not force the controls within it to change their width. |
Column | Each page provides a default single vertical column. You must insert a Column inside a Row (you cannot insert it directly into a page), so insert a Row before you can insert any additional Columns. |
Row | A staple of responsive layout, the Row control serves as the default parent to Columns. When you insert a Row, it provides an initial Column (for free). You can insert a Row almost anywhere, even in a Column (nested). |
Header and Footer | Some frameworks have their own Header and Footer controls. The ability to insert controls into a Header or Footer control differs with each framework. |
Button Grid | Useful for filling a space with buttons, such as a calculator or movie-playing app. This is not a general layout control, so some controls will not “play well” when put into a button grid. |
Card | A general control that optionally supports a header, footer, or left or right area. Useful for data-driven presentation, you can insert a Card into a Card Grid or Card Column. |
Card Grid | Used to layout Cards into a flexbox grid. Flexbox will handle cases where the number of Cards is not evenly divisible by the column count. For a Pinterest presentation, use a Card Column. Useful for data-driven presentation. |
Card Columns | Like a Card Grid, use this to layout Cards. Card Columns layout a Pinterest style column of Cards, unlike the Flexbox layout provided by a Card Grid. Useful for data-driven presentation. |
Overlays and Popups | Unlike most controls, these dialog-related controls are not inserted next to other controls on the page. Instead they are added to the page itself, and then made visible by some event. |
Animated Sidebars controls | This is a separate category of layout-related controls. Like Overlay and Popup controls, they are added to the page itself and made visible by some event. They are available for all UI frameworks. |
In addition to these Layout controls, App Designer also provides:
- Absolute addressing and rest of space property for certain controls (described in a separate page).
Each UI framework provides controls specific to that UI framework (see UI framework links).
Side By Side Control
The Side By Side control is a simple way of placing two controls next to each other. It also does not force the controls within it to change their width, making them more natural. If you want a control to maximize the width it takes on a side, put a ‘Width’ style on it and set its width to 100%.
By default the Side By Side control gives each side 50% of the total parent width. But, if needed, there is a Side By Side Widths style that lets you control the percentage for each side.
It’s a good idea to turn ON guidelines when using the Side By Side control - otherwise it can be hard to see immediately after it is inserted into a document.
Don’t forget that many controls have integrated labels as part of the control, which may preclude the need for this layout control.
Here is the base HTML of the Side By Side control. It is just two divs nested in each other.
<div class="sbs-container widget" data-uib="layout/side_by_side" data-ver="0"><div class="leftContent widget-container"></div><div class="rightContent widget-container"></div></div>
Column Control
The column is the workhorse of layout in App Designer. By default, the page itself is a column. So for a straight up vertical layout, you may not need rows or columns.
A column cannot be inserted directly into a page. Columns are nested inside rows, so you need to insert a Row before you can insert any additional columns. When you insert a row, it comes with an initial Column (for free).
The column has a layout
property whose values are Vertical
, Wrapping
, or Centered (single widget)
.
When the column is Vertical
(the default), then there is an additional Align option which can be used to align the items within it left, center, or right. Note that by default the vertical column forces its children to be the full width of the column, which renders alignment meaningless. However, if the children are not full width (some controls do not support it, or it can be overridden with the width style) then alignment will be respected.
Some center-aligned check boxes
When the column is Wrapping
, then the controls within it line up sideways and will wrap as the column width changes. The children can be floated from the left or right.
Some wrapping checkboxes:
The last column alignment option Centered (single widget)
only works properly if the column has only one child. If there are multiple children, they will overlap each other. In this screenshot, a background style has been applied to the column to make it easier to see and it has exactly one child:
A column is, by itself, a double nested div, with a single shim span as its last child.
<div class="col" data-uib="layout/col" data-ver="0"><div class="widget-container content-area vertical-col left"><span class="uib_shim"></span></div></div>
Row Control
The Row is the staple of responsive layout. The Row control serves as the default parent to columns. A Row can contain multiple columns, up to a maximum of twelve. Whereas a column can only be inserted into rows, a Row can be inserted almost anywhere, even in a column. So nesting is supported.
Inserting a Column
When dragging a column into a row, be sure to drop it on the column dividers located between the columns. Column dividers are easier to see when Guidelines are ON. Initially, those may be on either side of the row.
Resizing a Column
Those same column dividers (easier to see when Guidelines are ON) can be used to resize columns. As you drag the dividers you’ll see the different widths of the columns. Note that the sum of all the columns always adds to 12.
Row Properties
Property | Description |
---|---|
Wrap From | By default, the columns are always next to one another. But as wrap points are added, then they may stack atop each other as the screen size shrinks. Wrap from determines which side of the Row will be on top as the columns wrap down and stack. |
Space Between Columns | How much space between the individual columns inside the row. If you want to adjust the spacing outside the row, that keeps it from the viewport or parent, adjust the grid-pad style |
Is Form | By default a Row is represented as a simple <div>. But it can optionally be represented as a <form> element. This is for the convenience of users who might be deploying to a web server (rather than an embedded Apache Cordova* app). |
Rest of Space | Some controls, like list views and rows, sport a property called Rest of Space. See Rest of Space Property. |
grid-pad Style
Rows are spaced away from the edges of the viewport by an initial grid-pad style that is assigned. Change the padding in that style to make the row be closer or further from the viewport edges.
A Row is just a div (or form) that contains column divs:
<div class="grid grid-pad urow row-height-1" data-uib="layout/row" data-ver="0"> . . .</div>
Header and Footer Controls
Some frameworks have their own header and footer controls. See the documentation for that particular framework to understand any aspects and limitations. Typically, headers and footers have insertion points on their edges where controls can be inserted (the blue vertical bars in the screenshot below). Some headers and footers support many controls, but others can only contain buttons, or only two or three controls.
Button Grid Control
The button grid is useful for filling a space with buttons, such as a calculator or movie playing app. You can drop other controls into the grid as well. If the control has an integrated label, that label will be hidden. This is not a general layout control, so some controls will not “play well” when put into a button grid.
The button grid is a set of trebly nested <divs. (control>row->cell)
<div class="uib-grid widget grid-text grid-height d-margins" data-uib="layout/grid"><div class="uib-grid-row"><div class="uib-grid-cell widget-container"> . . .</div></div></div>
Card Control
Card is a general control that optionally supports a header, footer, or left or right area. The properties area sports a control where you can determine how the vertical and horizontal controls align to one another.
It also supports a dimension style that lets you determine the size of those sections. The overall height of the Card is, by default, driven by the contents of the Card itself (not the content of the sub-sections).
The background style it supports allows you to scope the background to a given section. So each section can be given its own background CSS by making multiple styles.
Moreover, the Card is easily attached to a service method, making it a great option for making a custom list item. When driven by a service method, the Cards will form a big vertical list by default. However, if the Card is in
a Card Grid or Card Columns control, then you can get a grid or Pinterest* style columns of Cards.
The Card is an outer <div>, surrounding <section> elements and the direct content of the Card.
<div class="widget widget-container content-area vertical-col uib-card d-margins section-dimension-17 cpad-15 header-on-right left-on-header left-on-footer right-on-footer" data-uib="layout/card"><section class="card-header widget-container content-area vertical-col"></section><section class="card-footer widget-container content-area vertical-col"></section><section class="card-left widget-container content-area vertical-col"></section><section class="card-right widget-container content-area vertical-col"></section><p>this text is in the card, not any section</p></div>
Card Grid Control
The Card Grid is used to layout Cards into a flexbox grid. Flexbox will intelligently handle cases where the number of Cards is not evenly divisible by the column count. Also, by applying flex-grow, flex-shrink and flex-basis CSS to the individual cards, you can get cards that are bigger or smaller than their neighbors.
IMPORTANT: Flexbox is not well supported by older mobile browsers and devices, especially on Android*. If you target Android and use the Card Grid control, we recommend that you use the Crosswalk for Android build platform, so your app has a modern webview. See http://caniuse.com/#search=flexbox.
The Card Grid itself doesn’t have many properties. The base number of columns is controlled by the flex-basis style.
To space out cards, apply a margin style to the individual cards. Margins won’t be included by the flex-basis equation, so you may need to bump the number of columns value up.
To insert individual cards into the card grid, simply drag the card into the small rectangular insertion point at the sides of each card
For a data-driven grid:
- Apply a service method to one of the cards within the card grid.
- Delete any unused cards.
Here is an example of a card column being used with a movie search service method:
Card Columns Control
Similar to the Card Grid, the Card Column is used to layout cards.
Unlike a Card Grid, Card Column does not use flexbox. Instead, it generates a Pinterest style column of cards. Each Card Column receives an initial CSS Columns style that lets you configure the Card Column control.
For a data-driven grid:
- Apply a service method to one of the cards within the card grid.
- Delete any unused cards.
Here is an example of a card column being used with a movie search service method:
Overlay and Popup Controls
Many frameworks support a variety of Overlay or Popup dialog controls. Unlike most controls, these are not inserted next to other controls on the page. Instead they are added to the page itself, and then made visible by some event. Because these controls are not always initially visible when viewing a page, App Designer will place a black button or menu to the right of the document that will activate the control in question.
For example, here is a Popup control for the Bootstrap* framework and the button that will make it visible. Once it is visible you can select it to set properties, or insert other controls inside it.
Animated Sidebar Controls
App Designer provides four animated sidebars you can insert into any page regardless of which UI framework you are using. Like Overlays, the sidebars can be made visible when editing by clicking the black button to the side of the document.
Sidebar Properties
Property | Description |
---|---|
Style | There are three possible styles for a sidebar: overlap, push, and squeeze:
|
Duration | The duration property is the number of milliseconds it takes for the sidebar to animate on or off screen. |
Overhand Width | By default the sidebar is completely off-screen when it is not being used, so its overhang is 0. But if the overhang width is set, the sidebar will jut into the page even when not being used. |
Thumb | When using an overhang width, the thumb property can be elected. When set, the space of the overhang will be taken by a thumb <div> that supports an optional background property. |
Swipeable | Is the sidebar swipeable? |
Triggering Sidebars
The sidebars are interactivity targets and can be triggered by any interactive element in the Interactivity pane. Here we see a button being hooked up to a left sidebar.
Once it is hooked up, you will see the Edit Script button active when that interactivity entry is selected.
Clicking it will open the code editor to the event script for that button. Initially the button will be hooked up to the ‘toggle’ method for the sidebar. But other options are available.