Sencha

Working with Layouts

in Designer

Sencha, Inc.
www.sencha.com
525 University Avenue, Suite 23
Palo Alto, CA 94301

Copyright © 2010, Sencha, Inc. All Rights Reserved.

 Working with Layouts in Designer

Contents
What is a Layout? .................................................................................................................. 1
Nested Layouts................................................................................................................. 1
Default Layouts................................................................................................................. 1
Flexible Box Layouts.......................................................................................................... 2
Stretching Components to Fit........................................................................................ 3
Basic Container Layouts .................................................................................................... 4
auto........................................................................................................................... 4
absolute..................................................................................................................... 4
accordion.................................................................................................................... 5
anchor....................................................................................................................... 5
border........................................................................................................................ 5
card........................................................................................................................... 6
column....................................................................................................................... 6
fit ............................................................................................................................. 7
form ......................................................................................................................... 7
hbox.......................................................................................................................... 8
table.......................................................................................................................... 8
vbox.......................................................................................................................... 9
Configuring the Layout for a Container .................................................................................... 10
Using CardLayout to Create a Wizard....................................................................................... 11
Using BorderLayout for a Viewport...........................................................................................15
Using HBoxLayout to Create Multiple Columns .......................................................................... 17

What is a Layout?
In ExtJS, layouts control the size and position of the components within an application. You configure
a layout on each container to manage how that container's children are rendered. The container layout
determines what size and position configuration options can be set on its child components.

Nested Layouts
A child component always takes its layout information from its direct parent. When you nest
containers, the layout you configure on each container manages the layout of whatever components
(including other containers) it contains. However, the layout doesn't have any effect on the contents
of any child containers, only the containers themselves.

Default Layouts
Some types of containers are automatically configured with a default layout. For example, a
FormPanel automatically uses the Form layout and a TabPanel defaults to the card layout. In most
cases, you'll want to use the default layout if one is configured, but you can change the layout if you
need to.

1
 Working with Layouts in Designer

Flexible Box Layouts

HBoxLayout and VBoxLayout support flexible box layouts that enable child components to be resized
to fit the available space in a container. To control how the space is distributed among the
components, you set the components' flex attributes.
The flex attribute is a numerical value that represents the proportion of the available space that a
component will be allotted. For example, assume there are three subpanels and flex is set to 1 for
Panel 1 and Panel 3, and flex is set to 2 for Panel 2. The available space is divided into four equal
portions (the sum of the flex values), and Panel 2 gets two portions and Panel 1 and Panel 2 each take
up one.

Note: For simplicity, these examples use whole numbers, but you can set the flex attribute to any
floating point value.

2
 Working with Layouts in Designer
If you set an absolute width or height for some components and a flex value for others, the absolute
sizes are subtracted from the total available space and the remaining space is allotted to the flexed
components. For example, if the container is 400 pixels wide and the width of Panel 1 is set to 200
pixels, the panels with flex attributes set share the remaining 200 pixels. If Panel 2 has a flex of 2 and
Panel 3 has a flex of 1, Panel 2 will get 2/3 of the space and Panel 3 will get 1/3 of the space.

Note: If neither an absolute size or a flex value are specified for a component, the framework checks
to see if the size is defined in the application's CSS. If no size is specified in the CSS, the framework
assigns the minimum necessary space to the item.

Stretching Components to Fit

If you specify stretch as the alignment option for a container that uses the HBoxLayout or
VBoxLayout, its subcomponents are automatically stretched to horizontally or vertically fit the size of
the container. When the HBoxLayout is used, the subcomponents are stretched vertically. When the
VBoxLayout is used, the subcomponents are stretched horizontally.
For example, when stretch is set on a Panel that uses the HBoxLayout, each of the subpanels is
automatically stretched to fill the available vertical space.

3
 Working with Layouts in Designer
The stretchmax option works just like stretch, except it stretches subcomponents to the size of the
tallest or widest component, rather than the size of the container.

Basic Container Layouts

ExtJS provides a number of basic container layouts. Some support specific, commonly-used
presentation models such as accordions and cards, while others provide more general-purpose models
that can be used for a variety of applications.

auto
If no other layout is set for a container, it defaults to the auto layout. For general purpose containers
such as a Panel, this means child components will be rendered sequentially. Note that some containers
are automatically configured to use a particular layout. For example, FormPanel defaults to the form
layout and TabPanel defaults to the card layout.

absolute
Arranges components using explicit x/y positions relative to the container. This enables you to
explicitly reposition and resize components within the container. While this gives you fine-grained
control over the layout, keep in mind that absolute-positioned components remain fixed even if their
parent container is resized.
When you use the absolute layout, Designer displays a grid within the container. By default,
components are snapped to the grid as you reposition them. You can change the grid size or disable
the grid by clicking on the container's flyout config button. The grid is only displayed as a layout guide
in the Design view, it is not visible when the component is rendered.

4
 Working with Layouts in Designer

accordion
Arranges panel components in a vertical stack where only one panel is expanded at a time. Only
panels (including FormPanel and TabPanel) can be added to a container that uses the accordion
layout.

anchor
Arranges components relative to the sides of the container. You can specify the width and height of
child components as a percentage of the container or specify offsets from the right and bottom edges
of the container. If the container is resized, the relative percentages or offsets are maintained.

border
Arranges panel components in a multi-pane layout. Panels are arranged in the container by assigning
them to one of five regions: North, South, East, West, or Center. A container that uses the border
layout has to have a child assigned to the Center region. The center panel is automatically sized to fit
the available space. You can resize the North, South, East, and West panes on the canvas by clicking
and dragging the right or bottom edge of the panel.
You can make any of the panels in a border layout collapsible by enabling the collapsible attribute.
When rendered, the child panels automatically resize when the container is resized.

5
 Working with Layouts in Designer

card
Arranges multiple child components but only one component is visible at a time. This layout can be
used to step through a series of components and is commonly used to create wizards.
To specify the component that you want to make visible, you need to call setActiveItem. Typically, you
attach this behavior to a navigation UI such as Previous and Next buttons in the footer of the
container.

column
Arranges components in a multi-column layout. The width of each column can be specified either as a
percentage (column width) or an absolute pixel width (width). The column height varies based on the
contents. You can enable autoscroll so it's possible to scroll to view column contents that exceed the
container height.

6
 Working with Layouts in Designer

fit
Expands a single child component to fill the available space. For example, you might use this to create
a dialog box that contains a single TabPanel. If the container is a type of panel component, you can
also add a Toolbar to it.

7
 Working with Layouts in Designer
form
Arranges a collection of labelled form fields. A FormPanel uses the form layout by default.

hbox
Arranges the child components horizontally. Setting the alignment of the container to stretch causes
the child components to fill the available vertical space. Setting the flex attribute of the child
components controls the proportion of the horizontal space each component fills.

table
Arranges components in an HTML table. You specify the number of columns in the table and can
create complex layouts by specifying the rowspan and colspan attributes on the child components.

8
Working with Layouts in Designer

9
 Working with Layouts in Designer

vbox
Arranges the child components vertically. Setting the alignment of the container to stretch causes the
child components to fill the available horizontal space. Setting the flex attribute of the child
components controls the proportion of the vertical space each component fills.

10
 Working with Layouts in Designer

Configuring the Layout for a Container

To set the layout for a container in Designer:
1. Click the container's flyout config button.
2. Select the layout you want to use.

You can also set the layout through the Component Config:
1. Select the container.
2. Set the layout attribute to the type of layout you want to use.

11
 Working with Layouts in Designer

Using CardLayout to Create a Wizard

When you add multiple subpanels to a CardLayout, only one panel is visible at a time. To create a
wizard, you can add panels to a Window that uses the CardLayout and configure a navigation toolbar
to step through the panels. You'll need to implement a handler that calls the setActiveItem function to
display the appropriate panel when one of the navigation buttons is clicked.
For example, to lay out the UI for a three step registration wizard:
1. Drag a Window onto the Designer Canvas. A Window can only be added as a top-level
component, it cannot be added as a child of an existing component.
2. Click the Window's flyout config button and select card from the layout menu.

3. Drag a Panel component onto the Window for the first step in the wizard. Panels in a
CardLayout are numbered in the order they are added to the container, starting with item 0.
By default, item 0 is set as the active item. To change the active item within Designer, select
the Window and set the activeItem attribute to the panel you want to make active.
4. Add two more panels to the Window. You can drag them onto the title bar of the Window on
the canvas, or onto the Window in the Components tab.

5. Edit the title of the Window to name the wizard. You can double-click the Window title on the
Canvas to edit it, or select the Window and set the title attribute in the Component Config
inspector.

12
 Working with Layouts in Designer

6. Hide the title bars of each Panel in the Wizard by selecting the Panel in the Components tab
and clicking the delete icon next to its title attribute in the Component Config inspector.

7. Add a Toolbar to the Window for the navigation buttons and dock it at the bottom of the
Window (bbar).

8. Add four buttons to the Toolbar and set the buttons' text attributes to Cancel, Previous, Next,
and Submit. You can double-click the button labels on the Canvas to edit them, and use tab to
move to the next button in the Toolbar.
9. To align the buttons, you can add a Fill between the Cancel and Previous button, and a Spacer
of width 20 between the Next and Submit buttons.

13
 Working with Layouts in Designer

10. Set the autoRef attribute for each button so you can easily reference the buttons in your
navigation handler. For example, autoRef: cancelBtn, autoRef: prevBtn, autoRef: nextBtn, and
autoRef: submitBtn.

Now we're ready to add the content for each card in the Wizard. However, since we want to gather
user input, we actually want each card to be a FormPanel rather than a Panel. Fortunately, in Designer
it's easy to transform a component into another type.
To change the Panels into FormPanels, right-click each one and choose Transform > FormPanel.

For this example, we built a registration wizard for a series of horsemanship clinics with the three
cards shown below. By default, card 0 is the active card. To add form fields to the card 1 and card 2,
you'll need to select the Window and set its activeItem attribute to the panel you want to work on. For
more information about creating forms in Designer, see Building Forms in Working with Components
in Designer.
14
Working with Layouts in Designer

15
 Working with Layouts in Designer

Using BorderLayout for a Viewport

When you want your application to take up the entire content area in a browser window (the browser
viewport), you can use the Viewport container. While you can use any layout for a Viewport, the
BorderLayout is commonly used to arrange a collection of subpanels. Subpanels in a BorderLayout can
be assigned to five regions: North, South, East, West, or Center. At a minimum, there must be a panel
assigned to the Center region, which is automatically sized to fit the available space.

For example, to lay out the UI for a class registration viewer:

1. Drag a Viewport onto the Designer Canvas. A Viewport can only be added as a top-level
component, it cannot be added as a child of an existing component.
2. Click the Viewport's flyout config button and select border from the layout menu.

16
 Working with Layouts in Designer

3. Drag a Panel into the Viewport. Because this is the only component currently in the layout, it
is automatically assigned to the Center region. This is going to be where we display
information about people who have signed up for one of our classes, so we set the title of the
Panel to Student Information.
4. Add a TreePanel to the Viewport. You can select the Viewport and double-click TreePanel in
the Toolbox to add it as a child of the Viewport, or drag the TreePanel onto the Viewport in the
Components tab. It will automatically be assigned to the West region. We're going to use the
tree to navigate through our classes, so we set the title of the TreePanel to Class List.

Note: To change the region that a subcomponent is assigned to, set its region attribute in the
17
 Working with Layouts in Designer
Component Config inspector.
Now we're ready to configure the Class List tree and the Student Information Panel to display our
content. We'll populate the tree with our list of classes as described in Working with Components in
Designer, and use a template to display data for individual students in the Student Information Panel.

Using HBoxLayout to Create Multiple Columns

The HBoxLayout enables you to arrange subcomponents horizontally, while VBoxLayout arranges
subcomponents vertically. These general-purpose layouts give you a lot of control over how
components are positioned, without resorting to using absolute positioning.
For example, if you have several related checkboxes, you might want to arrange them in multiple
columns to conserve space:
1. Add a FieldSet to your FormPanel for the checkboxes.
2. Set the layout of the FieldSet to hbox.

3. Add a Container component to the FieldSet for each column and configure the following
settings for both. It's easiest to select the column containers from the Component list, rather
than from the canvas. (When you first add them to the FieldSet, they are only 2 pixels tall.)
a. Set flex to 1.
b. Set the height to accommodate the checkboxes you want to add. For example, 60 pixels
will accommodate three rows of checkboxes.
4. Add checkboxes to each column container and set their boxLabel attributes.
Note: If you want to specify margins around the checkboxes, change the layout of the column
containers from auto to vbox, and then set the margin attribute for each individual checkbox.

18
Working with Layouts in Designer

19