What are layouts, regions, and viewports?

Ext uses Panels, which are the basis of most layouts. We have used some of these, such as FormPanel and GridPanel, already. A viewport is a special panel-like component that encloses the entire layout, fitting it into the whole visible area of our browser. For our first example, we are going to use a viewport with a border layout that will encapsulate many panels.

A viewport has regions that are laid out in the same way as a compass, with North,South, East and West regions—the Center region represents what’s left over in the middle. These directions tell the panels where to align themselves within the viewport and, if you use them, where the resizable borders are to be placed:

The example we’re creating will look like the following image, and combines many of the previous examples we have created:

This layout is what’s called a ‘border’ layout, which means that each region is separated by a somewhat three dimensional border bar that can be dragged to resize the regions. This example contains four panel regions:

• North: The toolbar
• West: A form
• Center: Grid in a tab panel
• East: A plain panel containing text

Note that there is no ‘South’ panel in this example—not every region needs to be used in every layout.

Our first layout

Before we create our layout that uses only four regions let’s go ahead and create a layout that utilizes all the regions, and then remove the South panel. We are going to create all of the regions as ‘panels’, which can be thought of as blank canvases to which we will add text, HTML, images, or even Ext JS widgets.

var viewport = new Ext.Viewport({
  layout: 'border',
  renderTo: Ext.getBody(),
  items: [{
    region: 'north',
    xtype: 'panel',
    html: 'North'
  },{
    region: 'west',
    xtype: 'panel',
    split: true,
    width: 200,
    html: 'West'
  },{
    region: 'center',
    xtype: 'panel',
    html: 'Center'
  },{
    region: 'east',
    xtype: 'panel',
    split: true,
    width: 200,
    html: 'East'
  },{
    region: 'south',
    xtype: 'panel',
    html: 'South'
  }]
});

Each region is defined as one of the four compass directions—East, West, North, and South. The remainder in the middle is called the center region, which will expand to fill all of the remaining space. Just to take up some blank space in each region and to give a visual indicator as to where the panels are, we defined an ‘HTML’ config that has just text. (This could also contain complex HTML if needed, but there are better ways to set the contents of panels which we will learn about soon).

Ext JS provides an easy, cross-browser compatible, speedy way to get a reference to the body element, by using Ext.getBody().

If everything works out ok, you should see a browser that looks like this:

Now we have a layout with all five regions defined. These regions can have other text widgets added into them, seamlessly, by using the xtype config. Alternatively they can be divided up separately into more nested regions—for instance, the center could be split horizontally to have its own South section.

A ‘Center’ region must always be defined. If one is not defined, the layout will produce errors and appear as a jumbled set of boxes in the browser.

Splitting the regions

The dividers are set up for each panel by setting the split flag—the positioning of the dividers is determined automatically based on the region the panel is in.

split: true

For this page, we have set the West and East regions as ‘split’ regions. This, by default, makes the border into a resizing element for the user to change the size of that panel.

I want options

Typically, when a split is used, it’s combined with a few other options that make the section more useful, such as width, minSize, and collapseMode.

Here are some of the more commonly-used options:

Option	Value	Description
split	true/false	Boolean value that places a resizable bar between the sections
collapsible	true/false	Boolean value that adds a button to the title bar which lets the user collapse the region with a single click
collapseMode	Only option is mini mode, or undefined for normal mode	When set to ‘mini’, this adds a smaller collapse button that’s located on the divider bar, in addition to the larger collapse button on title bar; the panel also collapses into a smaller space
title	String	Title string placed in the title bar
bodyStyle	CSS	CSS styles applied to the body element of the panel.
minSize	Pixels, ie: 200	The smallest size that the user can drag this panel to
maxSize	Pixels, ie: 250	The largest size that the user can drag this panel to
margins	In pixels: top, right, bottom, left, i.e.,: 3 0 3 3	Can be used to space the panel away from the edges or away from other panels; spacing is applied outside of the body of the panel
cmargins	In pixels: top, right, bottom, left, i.e.,: 3 0 3 3	Same idea as margins, but applies only when the panel is collapsed

 

Let’s add a couple of these options to our west panel:

{
  region: 'west',
  xtype: 'panel',
  split: true,
  collapsible: true,
  collapseMode: 'mini',
  title: 'Some Info',
  bodyStyle:'padding:5px;',
  width: 200,
  minSize: 200,
  html: 'West'
}

Adding these config options to our west panel would give us the following look:

Expanding and collapsing a panel that does not have a width specified can produce rendering problems. Therefore, it’s best to specify a width for panels—of course this is not needed for the center, as this panel automatically fills the remaining space.

Tab panels

With Ext JS, tab panels are also referred to as a “card” layout because they work much like a deck of cards where each card is layered directly above or below the others and can be moved to the top of the deck, to be visible. We also get pretty much the same functionality in our tab panel as a regular panel, including a title, toolbars, and all the other usual suspects (excluding tools).

Adding a tab panel

If the Ext JS component is a panel type component, for instance GridPanel andFormPanel, then we can add it directly to the layout using its xtype. Let’s start by creating a tabPanel:

{
  region: 'center',
  xtype: 'tabpanel',
  items: [{
    title: 'Movie Grid',
    html: 'Center'
  }]
}

The items config is an array of objects that defines each of the tabs contained in this tabpanel. The title is the only option that’s actually needed to give us a tab, and right now html is just being used as a placeholder, to give our empty tab some content.

We will also need to add an activeTab config that is set to zero to our tab panel. This is the index of the tabs in the panel left to right starting with zero and counting up for each tab. This tells the tab panel at position zero to make itself active by default, otherwise, we would have no tabs displayed, resulting in a blank section until the user clicked a tab.

{
  region: 'center',
  xtype: 'tabpanel',
  activeTab: 0,
  items: [{
    title: 'Movie Grid',
    html: 'Center'
  }]
}

If we take a look at this in a browser, we should see a tab panel in the center section of our layout.

Adding more tabs is as easy as adding more items into the items array. Each tab item is basically its own panel, which is shown or hidden, based on the tab title that has been clicked on the tab panel.

{
  region: 'center',
  xtype: 'tabpanel',
  activeTab: 0,
  items: [{
    title: 'Movie Grid',
    html: 'Center'
  },{
    title: 'Movie Descriptions',
    html: 'Movie Info'
  }]
}

Both the Movie Grid and Movie Descriptions tabs are just plain panels right now. So let’s add some more configuration options and widgets to them.

Widgets everywhere

Earlier, I mentioned that any type of panel widget could be added directly to a layout, just as we had done with the tabs. Let’s explore this by adding another widget to our layout—the grid.

Adding a grid into the tabpanel

As we now have these tabs as part of our layout, let’s start by adding a grid panel to one of the tabs. Adding the xtype config option to the grid config code will produce a grid that fills one entire tab:

{
  region: 'center',
  xtype: 'tabpanel',
  activeTab: 0,
  items: [{
    title: 'Movie Grid',
    xtype: 'gridpanel',
    store: store,
    autoExpandColumn: 'title',
    columns: // add column model //,
    view: // add grid view spec //
  },{
    title: 'Movie Descriptions',
    html: 'Movie Info'
  }]
}

xtypes offer a quick way to instantiate a new component with minimal typing. This is sometimes referred to as ‘lazy rendering’ because the components sit around waiting to be displayed before they actually execute any code. This method can help conserve memory in your web application.

As we are adding this grid to a tab—which is essentially just a panel—there are some things that we no longer need (like the renderTo option, width, height, and a frame).The size, title, and border for the grid are now handled by our tab panel.

Now we should have a layout that looks like this:

Accordions

The accordion is a very useful layout that works somewhat like a tab panel, where we have multiple sections occupying the same space, with only one showing at a time. This type of layout is commonly used when we’re lacking the horizontal space needed for a tab panel, but instead have more vertical space available. When one of the accordion panels is expanded, the others will collapse. Expanding and collapsing the panels can be done either by clicking the panel’s title bar or by clicking the plus/minus icons along the rightmost side of the panel.