Documentation

1 Getting Started
2 Design Overview
3 Page Controller Boot Process
4 Your First App
5 Page Controller
6 Modules
7 Components
8 jqcEmpty
9 jqcLabel
10 jqcButton
11 jqcLayer
12 jqcPanelDeck
13 jqcAccordion
14 jqcProgressBar
15 Data Binding & Remote Data Synchronization
16 jqcDataService
17 jqcDataModel
18 jqcViewModel
19 jqcList
20 jqcTable
21 jqcForm
22 jqcResponsiveLayoutManager
23 jqcTreeList
24 Demos

jqcResponsiveLayoutManager


This document matches version 1.6.0 .

The jqcResponsiveLayoutManager component can layout your HTML page in a responsive manner. If you are not familiar with responsive web design, I have a free responsive web design tutorial I recommended that you read first (or at least scan it quickly).

You do not have to use the jqcResponsiveLayoutManager for your responsive web design. You can also use something else like Bootstrap or make your own CSS. That is entirely up to you.

JavaScript Based Layout Manager

Rather than being restricted by the limitations of CSS, jqcComponents uses JavaScript to layout the page. Using JavaScript makes the layout manager much more flexible than if only CSS was used.

The jqcResponsiveLayoutManager is activated during the layout boot phase by the page controller. This means that the layout takes place after the browser has initially rendered the page, but before any components have been rendered. This may result in your page making a quick flicker when it is being re-rendered after layout. In many cases though, the loading, rendering and re-rendering after layout is so fast that the user does not notice the flicker.

Additionally, many pages are anyways flickering when loading because of the asynchronous nature of loading the page, images, JavaScript etc. But, as I said, in many cases you do not even see the re-rendering happening. The page just appears as if it had been rendered correctly from the beginning.

The Layout Grid

Like most other responsive layout toolkits, the jqcResponsiveLayoutManager uses a grid for its layout. The grid consists of rows and columns. By default a horizontal row contains 12 columns. Inside each row you can put cells. A cell can be between 1 and 12 columns wide (in a 12 column grid).

This diagram shows how a row can contain cells with different widths in columns. It shows cells that are 1, 2, 3, 4, 6 and 12 columns wide.

For each cell you can specify its column width. You can specify different column widths for different browser widths. Thus, when the browser is wide, a cell may be displayed nicely with a column width of 3, but when the screen is more narrow, like on a phone, the same cell may need the whole screen width (12 columns).

You can use a different number of columns in the grid if you want to. For instance 6, 24, 48, or 7, 9, 13, or whatever else fits your layout. Furthermore, each row can use a different number of columns.

Width Intervals (AKA Breakpoints)

The jqcResponsiveLayoutManager has a set of width intervals defined. When the browser changes width, the jqcResponsiveLayoutManager checks the boundaries of its width intervals, to see what interval the width falls in. When it knows the width interval, it can check each cell to see how many columns that cell is to span in that width interval.

By default the jqcResponsiveLayoutManager uses these width intervals:

Index    Width
0 0 - 299
1 300 - 599
2 600 - 899
3 900 - 1199
4 1200 - *

Before version 1.3.0 the jqcResponsiveLayoutManager used the width of the browser window to determine what interval the width falls in. From version 1.3.0 the width of the parent element of the row element is used instead. For rows that have the body element as their parent there will be no difference. Using the parent element width enables you to nest rows inside the cells of other rows, or just inside other HTML elements in your page. That means that you can turn a smaller area of the web page into its own layout grid. How that is done is shown later in this text.

You can configure your own width intervals if you like, and you can use more or less intervals than these 5. You can create 3, 6, 10 or whatever number of intervals you like, and set the width boundaries of these intervals as you see fit. From version 1.3.0 you can even use different width intervals for each individual row! How that is done is shown later in this text.

Creating a jqcResponsiveLayoutManager

You create a jqcResponsiveLayoutManager like this:

<span id="layoutManager" jqc-type="jqcResponsiveLayoutManager"></span>    

It is just a standard component like any other component. The jqcPageController will detect it during the boot process and call its layout() function in the layout phase, which triggers the layout of the page.

The jqcResponsiveLayoutManager registers itself as a window resize listener during the configure boot phase, so every time the browser is resized, the layout is recalculated and re-rendered.

Creating Rows and Cells

As mentioned earlier, the layout grid consists of rows and cells.

Creating Rows

You create rows using div HTML elements with a jqc-row attribute inside. Here is an example:

<div jqc-row>
</div>

You can have more than one row, and each row can be configured separately. This text gets back to configuration of rows later. Here is a multi-row example:

<div jqc-row>
</div>

<div jqc-row>
</div>

Creating Cells

Inside this row you put one or more cells. These are also div elements but with a jqc-cell attribute. Inside this attribute you configure the width in columns of the cell. Here is an example:

<div jqc-row>
    <div jqc-cell="0:12c"></div>
</div>   

This example says, that in width interval 0 the cell is to be 12 columns wide. The first number (before the colon) is the width interval, and the second number with the c behind is the column width.

This example configures different widths for different width intervals:

<div jqc-row>
    <div jqc-cell="0:12c 4:3c"></div>
</div>

This cell configuration (0:12c 4:3c) means that the cell is to be 12 columns wide in width interval 0, and 3 columns wide in width interval 4.

The width for all intervals in between 0 and 4 will be the lowest specified width interval. Thus, if the browser width falls in width interval 3, the jqcResponsiveLayoutManager will search for a definition for interval 3, then 2, then 1 and finally 0 (where it finds a definition). The jqcResponsiveLayoutManager will always search from the current width interval and down (in interval number) and use the first definition it finds this way.

This behaviour means that you do not have to specify cell widths for all browser width intervals. You only need to specify widths for the intervals where the width of the cell is to actually change.

You can of course create multiple cells within a row. Here is an example of that:

<div jqc-row>
    <div jqc-cell="0:12c 4:3c"></div>
    <div jqc-cell="0:12c 4:3c"></div>
    <div jqc-cell="0:12c 4:3c"></div>
    <div jqc-cell="0:12c 4:3c"></div>
</div>

This example creates 4 cells inside a row. Each cell is to be 12 columns wide from width interval 0 (and up to width interval 3), and 3 columns wide from width interval 4 and up. This basically means, that below width interval 4 the cells will stack vertically, since they all need to take the full width of the row (12 columns) in width.

Here is a slightly more advanced example:

<div jqc-row >
    <div jqc-cell="0:12c 2:6c 4:3c">Cell 1</div>
    <div jqc-cell="0:12c 2:6c 4:3c">Cell 2</div>
    <div jqc-cell="0:12c 2:6c 4:3c">Cell 3</div>
    <div jqc-cell="0:12c 2:6c 4:3c">Cell 4</div>
</div>

This example creates a single row with 4 cells inside. All 4 cells are configured to be 12 columns wide in browser width interval 0 (and 1), 6 columns wide in interval 2 (and 3), and 3 columns wide in interval 4 and up.

This configuration means that in width interval 0 (and 1) the 4 cells will be stacked on top of each other. In width interval 2 (and 3) the 4 cells will be displayed 2 cells per horizontal row (6 columns wide each) and 2 horizontal rows. In width interval 4 and up each cell will be 3 columns wide. Since each row has 12 columns across, all 4 cells will be displayed on the same horizontal row.

The jqcResponsiveLayoutManager Basics Demo shows an example of how basic row and cell configuration works in practice.

You can have as many cells in a row as you like. Just remember that the sum of the cell column widths should sum up to the column width of the row (e.g. to 12, 24, 36 etc.) in all width intervals. Otherwise the cells will not stack so nicely.

Custom Width Intervals

If you are not happy with the built-in width intervals, you can specify your own width intervals. This may make sense if you are trying to target very specific screen sizes. Many mobile devices have different screen widths, so to target these widths you can create your own width intervals.

Width intervals can be set on the jqcResponsiveLayoutManager when it is created, or separately on each row. Here is how you set width intervals on the jqcResponsiveLayoutManager:

<span id="layoutManager" jqc-type="jqcResponsiveLayoutManager"
    jqc-width-intervals="0,320,640,800,1200" ></span>

It is the attribute jqc-width-intervals that sets the width intervals. The attribute contains a comma separated list of interval boundaries. The list must always start with 0, even if no screen widths ever fall into the bottom width interval. In this example width interval 0 spans from with 0 to width 319, width interval 1 spans from 320 to 639 etc. The boundary number is the lowest number in that interval, so e.g. a width of 320 is inside interval 1.

You can also set the width intervals individually on each row. Here is an example of that:

<span id="layoutManager" jqc-type="jqcResponsiveLayoutManager" ></span>
    
<div jqc-row jqc-width-intervals="0,320,640,800,1200"></div>    
<div jqc-row jqc-width-intervals="0,600,800,1000,1200"></div>    

This example sets different width intervals for the two rows.

In case a row has no explicit width intervals set, it will fall back to using the width intervals set on the jqcResponsiveLayoutManager. If no explicit width intervals are set on the jqcResponsiveLayoutManager it will use its default width intervals (described earlier in this text).

Custom Column Counts

The jqcResponsiveLayoutManager uses a default of 12 columns per row. If you want a different number of columns you can specify the number of columns yourself. From version 1.3.0 this is done using the jqc-column-counts attribute (notice the jqc-column-count (singular - no s in ending) used in version earlier than 1.3.0 has been deprecated). Here is an example:

<span id="layoutManager" jqc-type="jqcResponsiveLayoutManager" jqc-column-counts="0:24" ></span>

The attribute value 0:24 means that from width interval 0 and up each row should have 24 columns. You could actually specify different column counts for different width intervals if you needed it. For instance the attribute value 0:3 2:6 4:12 means that in width interval 0 (and 1) each row should contain 3 columns across, in width interval 2 (and 3) each row should contain 6 columns across, and in width interval 4 and up each row should contain 12 columns across.

You can also set the column counts separately for each row. Here is an example:

<span id="layoutManager" jqc-type="jqcResponsiveLayoutManager" ></span>

<div jqc-row jqc-column-counts="0:3  2:6  4:12"></div>
<div jqc-row jqc-column-counts="0:6  4:24" ></div>

This example sets the number of columns to use for the two rows differently.

If a row has no explicit column counts set it will default to the column counts set on the jqcResponsiveLayoutManager. If the jqcResponsiveLayoutManager has no explicit column counts set it will default to 12 from width interval 0 and up.

Variable Row Column Count, Fixed Cell Column Width

The configuration examples above sets a fixed number of columns per row (24 in the first example, 12 in the second), and then sets a variable number of column widths for the cells inside the row. The effect of that is that in different width intervals, the cells will take up a different number of columns horizontally. This is what makes the cells stack in different width intervals. For instance, in width interval 0 (from 0 pixels and up) each cell takes 12 columns in width, meaning they take the full row in width (if the row has 12 columns). In width interval 4 each cell only takes 3 columns, making space for 4 cells per row vertically. Here is a configuration example showing that behaviour:

<div jqc-row jqc-column-counts="0:12"
             jqc-row-widths="0:100% 4:1200"
        >

    <div jqc-cell="0:12c 2:6c 4:3c">Cell 1</div>
    <div jqc-cell="0:12c 2:6c 4:3c">Cell 2</div>
    <div jqc-cell="0:12c 2:6c 4:3c">Cell 3</div>
    <div jqc-cell="0:12c 2:6c 4:3c">Cell 4</div>

</div>

However, from version 1.3.0 it is possible to swap the configuration around to use a variable number of columns per row for different width intervals, and a fixed number of columns spanned per cell. Here is a configuration example showing that:

<div jqc-row jqc-column-counts="0:3  2:6  4:12"
             jqc-row-widths="0:100% 4:1200"
        >

    <div jqc-cell="0:3c">Cell 1</div>
    <div jqc-cell="0:3c">Cell 2</div>
    <div jqc-cell="0:3c">Cell 3</div>
    <div jqc-cell="0:3c">Cell 4</div>

</div>

Notice that the column width of the cells is always 3 columns. The number of columns that fit per vertical row is variable, though. From width interval 0 the row only contains 3 columns horizontally. That means that all the cells will take the full row horizontally, and thus stack beneath each other vertically. From width interval 2 the row contains 6 columns per row. That means that 2 cells will fit horizontally inside the row. The cells will thus be stacked 2 by 2 vertically. From width interval 4 and up the row contains 12 columns. The 4 cells will therefore be displayed floating next to each other horizontally (no stacking).

The jqcResponsiveLayoutManager - Variable Row Column Counts Demo shows you how the above example works live.

Whether you want to use a fixed number of columns per row and a variable number of columns for the cell widths, or a variable number of columns per row and a fixed number of columns for the cell widths, is up to you. It depends on the situation. However, if you need the relational width between cells to change between width intervals, you need to use variable cell widths. Width fixed cell widths the relational width between cells is always the same, regardless of width interval. It is only the amount of cells that can fit per row that changes.

You can actually also combine variable column counts with variable cell widths, if your special use case needs that.

Row Widths

By default a row takes up the full width of its parent element. If you want to change that behaviour, you can set the row width on the jqcResponsiveLayoutManager using the jqc-row-widths attribute. Here is an example:

<span id="layoutManager" jqc-type="jqcResponsiveLayoutManager" jqc-row-widths="0:100%  4:1200" ></span>

This example sets the row width to 100% from width interval 0 (to 3), and to 1200 pixels from width interval 4 and up. This basically means that below 1200 pixels in width the row will take up 100% of its parent element. From 1200 pixels in width and up it will fix itself to 1200 pixels and center itself in its parent element (via CSS rules setting left and right margin to auto in jqc-all.css).

You can also set the row widths separately for each row, as this example illustrates:

<span id="layoutManager" jqc-type="jqcResponsiveLayoutManager" ></span>

<div jqc-row jqc-row-widths="0:100%  4:1200"></div>
<div jqc-row jqc-row-widths="0:100%" ></div>

This example sets the row widths of the two rows to different values. The first row stops at 1200 pixels in width, but the last row always take up 100% of its parent element.

If a row has no explicit row widths set it will default to the row widths set on the jqcResponsiveLayoutManager. If no row width is set on the jqcResponsiveLayoutManager it will default to 100% in all width intervals.

Row Paddings

In case you need a bit of padding in the left and right side of each row, you can specify the padding of rows using the jqc-row-paddings attribute on the jqcResponsiveLayoutManager. Here is an example:

<span id="layoutManager" jqc-type="jqcResponsiveLayoutManager"
          jqc-row-paddings="0:16  2:24  4:32"></span>

This example sets the left and right padding of each row to 16 pixels in width interval 0 (and 1), 24 pixels in width interval 2 (and 3) and 32 pixels from width interval 4 and up.

You can also specify the row paddings separately for each row. Here is an example illustrating that:

<span id="layoutManager" jqc-type="jqcResponsiveLayoutManager" ></span>

<div jqc-row jqc-row-paddings="0:16  2:24  4:32"></div>
<div jqc-row jqc-row-paddings="0:24" ></div>

In case a row has no row paddings set it will default to the row paddings set on the jqcResponsiveLayoutManager. If no row paddings are set on the jqcResponsiveLayoutManager it will default to 0 pixels padding in all width intervals.

Cell Spacings

In case you want some space between the cells in the rows, you can specify that using the jqc-cell-spacings attribute on the jqcResponsiveLayoutManager. Here is an example:

<span id="layoutManager" jqc-type="jqcResponsiveLayoutManager"
          jqc-cell-spacings="0:8  2:12  4:16"></span>

This example will create an 8 pixel space between each cell in width interval 0 (and 1), a 12 pixel space in width interval 2 (and 3), and a 16 pixel space from width interval 4 and up.

You can also specify the cell spacings separately for each row. Here is an example illustrating that:

<span id="layoutManager" jqc-type="jqcResponsiveLayoutManager" ></span>

<div jqc-row jqc-cell-spacings="0:8   2:12  4:16"></div>
<div jqc-row jqc-cell-spacings="0:16  2:24  4:32" ></div>

This example sets the cell spacings of the two rows differently.

If a row has no explicit cell spacings set on it, it will default to the cell spacings set on the jqcResponsiveLayoutManager. If the jqcResponsiveLayoutManager has no cell spacings set on it, it will default to 0 pixel cell spacing in all width intervals.

Cell Reordering

From version 1.3.0 it is possible to reorder the cells in different width intervals. For instance, on a wide screen you might want the news cell on the right side of the page. When stacking the cells on a smaller screen, that would usually cause the news cell to be pushed to the bottom of the page. You might actually want the news cell shown as the very first cell on a mobile. You can do so by changing the cell index of the cell using the jqc-cell-indexes attribute on the cell element. Here is an example:

<div jqc-row >
    <div jqc-cell="0:12c  4:3c">Main Content</div>
    <div jqc-cell="0:12c  4:3c" jqc-cell-indexes="0:0  4:1">News</div>
</div>

The attribute value for the jqc-cell-indexes attribute is 0:0 4:1 . This means that this cell will have be reordered to have index 0 inside the row (the first element in the row) in width interval 0 to 3. Fro width interval 4 and up the cell will have index 1.

When a cell is given a specific index, all other cells are pushed back in the cell sequence. Thus, the cell that normally had index 0 will be pushed to index 1 etc. A non-indexed cell will be pushed to the closest index that has not been explicitly assigned to another cell. Cells are always pushed up in index this way, never down.