Client Side Layout Managers

Vertical and Horizontal Active Groups

Suppose a designer wants to divide the screen into four regions:

• A fixed menu area across the top

• An output pane across the bottom

• A detailed information display area on the right

• A main work area that would expand to use all remaining window real estate once the other areas had been addressed

The designer also wants the user to be able to interactively adjust how much of the screen is devoted to the output and detail panes at runtime. Furthermore, the designer wants the layout to automatically adjust to changes in window size. That is, increasing the browser window to full screen mode would resize the main work and supplemental detail areas while leaving the size of the menu and output areas fixed. The following figure shows a conceptual view of this design:

The <activeVGroup> and <activeHGroup> are ideally suited for addressing these design objectives. Unlike <vgroup> and <hgroup> which are ultimately based on HTML tables, active groups use CSS and JavaScript to divide their available screen area into discrete subsections. This subdivision is always a binary split, resulting in top and bottom children for vertical divisions, or left and right for horizontal divisions.

This binary geometry is an implementation constraint, but not a design restriction. Active groups can be nested within one another to create the illusion of multi-way splitting of the available screen real estate. An example of this is shown in the previous figure where there are three divisions along the vertical: the menu area at the top, the combined main and supplemental areas across the center, and the output area at the bottom.

You can provide the layout shown in the previous figure by using three nested active groups as shown in the following Zen page class:

Class MyApp.ActiveTest Extends %ZEN.Component.page
{
Parameter PAGENAME = "ActiveGroupLayout";

XData Style
{
<style type="text/css">
  #outerSplit {
    width:100%;
    height:100%;
    }
</style>
}

XData Contents [ XMLNamespace = "http://www.intersystems.com/zen" ]
{
<page xmlns="http://www.intersystems.com/zen" layout="none">
  <activeVGroup id="outerSplit" noResize="true" handleThickness="1" split="30" >
    <group enclosingStyle="width:100%;height:100%;background:white;">
      <!-- Menu Area -->
    </group>
    <activeVGroup id="innerVSplit"  split="-150" >
      <activeHGroup id="horizontalSplit" split="80%" >
        <group enclosingStyle="width:100%;height:100%;background:#ccccff;">
          <!-- Main Work Area -->
        </group>
        <group enclosingStyle="width:100%;height:100%;background:#ccffff;">
          <!-- Supplemental Detail Area -->
        </group>
      </activeHGroup>
      <group enclosingStyle="width:100%;height:100%;background:cyan;">
        <!-- Output Area" -->
      </group>
    </activeVGroup>
  </activeVGroup>
</page>
}

ClientMethod onloadHandler() [ Language = javascript ]
  {
    ZLM.refreshLayout();
  }

ClientMethod onlayoutHandler() [ Language = javascript ]
  {
    ZLM.notifyResize(document.body);
  }
}

In the previous code example:

• The <activeVGroup> called outerSplit divides the window vertically into two regions. The top area is 30 pixels tall, is not user adjustable, and is partitioned off from the bottom area by a divider that is 1 pixel wide. The bottom area uses all but 31 pixels of the window’s height; 31 is the top height plus the handle thickness. The top area contains the label identifying the menu area. The bottom area contains an additional <activeVGroup>.

• The <activeVGroup> called innerVSplit again divides the window vertically where one region is 150 pixels tall. In this case, however, the split property is negative, indicating that the property is referring to space reserved for the bottom area. By default, the split is user adjustable and displays an adjustment bar of sufficient thickness to be easily grabbed by the mouse pointer.

• The constraints set up by the two <activeVGroup> elements have the effect of reserving 30 pixels at the top of the window, 150 pixels at the bottom, and a few (actually, 8) for adjustment and partition bars. All remaining vertical pixels are funneled into the first child of the innerVSplit group. This child is an <activeHGroup> that partitions the middle band of the window into the main work area and the supplemental detail area. This split is an 80% division of the available window width and is user adjustable by default.

Active Groups that Resize Proportionally

<activeVGroup> and <activeHGroup> allow “size to fit” operations on their contents. The following four steps are required to enable this functionality. Once this is set up, the groups automatically expand to fill the window on initial page load and adjust their sizes automatically in response to window resize events:

1. The <page> component must have its layout attribute set to "none":

   <page xmlns="http://www.intersystems.com/zen" layout="none">
   

   

   This shifts responsibility for page layout from the server to the browser.

2. The outermost active group in the XData Contents block must have its CSS width and height explicitly set to 100%. This can be set using the enclosingStyle attribute for the <activeVGroup> or <activeHGroup>. Alternatively you can do it as shown in the previous example of a Zen page class:

   • Define a CSS style rule:

     XData Style
     {
     <style type="text/css">
       #outerSplit {
         width:100%;
         height:100%;
         }
     </style>
     }

     

   • ...and apply this rule to the outermost active group using the id attribute:

     XData Contents [ XMLNamespace = "http://www.intersystems.com/zen" ]
     {
     <page xmlns="http://www.intersystems.com/zen" layout="none">
       <activeVGroup id="outerSplit" noResize="true" handleThickness="1" split="30" >
         <!-- Everything else -->
       </activeVGroup>
     </page>
     }

     

3. The following must be true all the way down the hierarchy of group components, from the top-level <page> container down to any group that you wish to resize automatically along with the window that contains it. If you do not wish a group to resize in this way, these restrictions are not necessary:

   • No active group can use the layout attribute.

   • Every group that is not an active group must have its CSS width and height attributes set to 100%.

   The previous Zen page class example adheres to these rules. It also shows examples of using the enclosingStyle attribute, instead of a formal CSS style rule, to define the CSS width and height. For example:

   <group enclosingStyle="width:100%;height:100%;background:#ccffff;">
   

   

4. onloadHandler and onlayoutHandler methods in the Zen page class must call back into the Zen client side library module to ensure that any user adjustments to the window size force a recalculation of the active groups’ geometry. The previous Zen page class example shows the correct calls, as follows:

   
   ClientMethod onloadHandler() [ Language = javascript ]
     {
       ZLM.refreshLayout();
     }
   
   ClientMethod onlayoutHandler() [ Language = javascript ]
     {
       ZLM.notifyResize(document.body);
     }
   
   

   

Calculating Percentages for Three-Way Splits

The following class code shows how to implement a page that requires areas of the screen to be split three ways, using the binary splits provided by <activeVGroup> and <activeHGroup>. This design has the following features:

• The screen has a 10% top margin, 10% bottom margin, 12.5% left and right margins and a work area in the middle. Thus, the main work area consumes 75% of the width and 80% of the height of the available pixels in the window.

• The main work area is divided into thirds. Each of these thirds has its own vertical scroll bar. Resizing the window resizes these areas automatically.

• Visible handle thicknesses shows how the screen is being cut up. Setting handleThickness to zero would make these handles disappear entirely.

The following figure shows a conceptual view of this design:

You can create the layout by using active groups as shown in the following Zen page class:

Class MyApp.LayoutTest Extends %ZEN.Component.page
{

Parameter PAGENAME = "LayoutTest";

/// This Style block contains page-specific CSS style definitions.
XData Style
{
<style type="text/css">
#outerSplit {
    width:100%;
    height:100%;
  }
</style>
}

/// This XML block defines the contents of this page.
XData Contents [ XMLNamespace = "http://www.intersystems.com/zen" ]
{
<page xmlns="http://www.intersystems.com/zen" >
  <activeVGroup id="outerSplit" noResize="true"
                handleThickness="1" split="90%" >
    <activeVGroup id="topMarginSplit" noResize="true"
                  handleThickness="1" split="11%" >
      <!-- Top Margin -->
      <group id="Top"/>
      <activeHGroup id="rightMarginSplit" handleThickness="1"
                    noResize="true" split="88%" >
        <activeHGroup id="leftMarginSplit" handleThickness="1"
                      noResize="true" split="14%" >
          <!-- Left Margin -->
       <group id="Left"/>
          <group layout="none"
                 enclosingStyle="width:100%;height:100%;background:#ccccff;">
            <!-- Main Work Area -->
            <activeHGroup id="outerThreeway" noResize="true"
                          handleThickness="2" split="67%" >
              <activeHGroup id="innerThreeway" noResize="true"
                            handleThickness="2" split="50%" >
                <group id="leftLeft"
    enclosingStyle="width:100%;height:100%;overflow:scroll;background:#ffcccc;">
                  <label value="Left-Left"/>
                </group>
                <group id="leftRight"
    enclosingStyle="width:100%;height:100%;overflow:scroll;background:#ccffcc;">
                  <label value="Left-Right"/>
                </group>
              </activeHGroup>
              <group id="rightRight"
    enclosingStyle="width:100%;height:100%;overflow:scroll;background:#ffffcc;">
                <label value="Right-Right" />
              </group>
            </activeHGroup>
          </group>
        </activeHGroup>
        <!-- Right Margin -->
      </activeHGroup>
    </activeVGroup>
    <!-- Bottom Margin -->
  </activeVGroup>
</page>
}

ClientMethod onloadHandler() [ Language = javascript ]
  {
    ZLM.refreshLayout();
  }

ClientMethod onlayoutHandler() [ Language = javascript ]
  {
    ZLM.notifyResize(document.body);
  }
}

In this example, the binary nature of active group splits, combined with this design’s requirement that all geometries be measured in percentages, requires the developer to pay close attention to the underlying constraints enforced by active groups. Within the main work area, the developer achieves an equal three-way split by nesting two horizontal splits. The outer split divides the total area at 67%, giving two-third of the horizontal pixels to the left child and one-third to the right. The inner split divides the left child at 50%, not 33%. Dividing the two-thirds area evenly in half yields the desired result of visually splitting the total area into equal thirds.

A similar technique correctly balances the left and right margins of the page relative to the central work area. The outer split divides the total area at 88%, giving the larger portion to the left child and creating a 12% right margin. The inner split divides the left child at 14%, not 12%. This produces a left margin that is of equal width to the right margin created by the outer split. The central work area is now approximately 75% of the window width and is correctly centered between the left and right margins.

<desktop> Row Style

The <desktop> can enforce sizing and alignment constraints on the <dragGroup> components within its rows. You can choose a configuration by assigning a value to the rowStyle attribute. Valid values are:

• FILL_ROW — All groups within a row have the height of the tallest group in the row. By default the top and bottom edges of all the sub-windows align. Height is allowed to vary from one row to the next.

• ALIGN_ROW_TOP — (the default) The top edge of all <dragGroup> components within a row align. The height of individual <dragGroup> components within the row is allowed to vary. The row spacing is driven by the tallest group within the row.

• ALIGN_ROW_CENTER — All <dragGroup> components are centered vertically within their respective rows. The height of individual <dragGroup> components is allowed to vary. The row spacing is driven by the tallest group within the row.

• ALIGN_ROW_BOTTOM — The bottom edge of all <dragGroup> components within a row align. The height of individual <dragGroup> components within the row is allowed to vary. The row spacing is driven by the tallest group within the row.

• FILL_UNIFORM — All <dragGroup> components within the desktop take on the height of the tallest <dragGroup>. This results in all rows being uniformly spaced vertically and all <dragGroup> components being both top and bottom aligned.

• ALIGN_UNIFORM_TOP — All rows within the desktop take on uniform spacing dictated by the height of the tallest group within the component. Within each row, the top edges of individual <dragGroup> components align. The height of individual <dragGroup> components is allowed to vary.

• ALIGN_UNIFORM_CENTER — All rows within the desktop take on uniform spacing dictated by the height of the tallest group within the component. Within each row, individual <dragGroup> components are centered vertically. The height of individual <dragGroup> components is allowed to vary.

• ALIGN_UNIFORM_BOTTOM — All rows within the desktop take on uniform spacing dictated by the height of the tallest group within the component. Within each row, the bottom edges of individual <dragGroup> components align. The height of individual <dragGroup> components is allowed to vary.

<desktop> Column Style

In general, the <desktop> geometry conventions are biased towards rows. In fact, by default the <desktop> does not recognize the existence of columns.

However, assigning a value to the colStyle attribute alters this behavior, so that the <desktop> counts all the first elements of the rows as column one, all the second elements as column two, and so forth. Unlike rows, which repack themselves when they are removed or added, columns are allowed to have embedded gaps in which a short row does not reach a given column.

You can choose a column style, and force <desktop> to recognize columns, by assigning a value to the colStyle attribute. If you do not, the concept of columns is ignored and only row-based constraints apply.

Valid values for colStyle are:

• FILL_COLUMN — All <dragGroup> components within a given column take on the width of the widest group within the column. All <dragGroup> components become both left and right aligned. The spacing of the columns is allowed to vary from one column to the next

• ALIGN_COLUMN_LEFT — The width of the column is dictated by the width of the widest group within that column but the width of individual sub- windows is allowed to vary. All <dragGroup> components are left aligned within their columns. The spacing of the columns is allowed to vary from one column to the next

• ALIGN_COLUMN_CENTER — The width of the column is dictated by the width of the widest group within that column, but the width of individual <dragGroup> components is allowed to vary. All <dragGroup> components are centered within their columns. The spacing of the columns is allowed to vary from one column to the next

• ALIGN_COLUMN_RIGHT — The width of the column is dictated by the width of the widest group within that column, but the width of individual <dragGroup> components is allowed to vary. All <dragGroup> components are right aligned within their columns. The spacing of the columns is allowed to vary from one column to the next

• FILL_WIDTH — The total width of the longest row dictates the layout bounds for the entire <desktop>. The widths of <dragGroup> components within shorter rows are scaled up proportionately to ensure that right edge of the last group in each row is aligned with that of every other row in the <desktop>.

• ALIGN_WIDTH_LEFT — Similar to FILL_WIDTH. The <dragGroup> components within rows are horizontally spaced based on the width of the longest row. The widths of individual <dragGroup> components are not padded, creating the appearance of random spacing within a row.

• ALIGN_WIDTH_CENTER — Similar to FILL_WIDTH. The <dragGroup> components within rows are horizontally spaced based on the width of the longest row. The widths of individual <dragGroup> components are not padded, and the <dragGroup> components are centered within the revised spacing bounds.

• ALIGN_WIDTH_RIGHT — Similar to FILL_WIDTH. The <dragGroup> components within rows are horizontally spaced based on the width of the longest row. The widths of individual <dragGroup> components are not padded, and the <dragGroup> components are right aligned within the revised spacing bounds.

• FILL_UNIFORM — All columns take on the width and spacing dictated by the widest <dragGroup> within the <desktop>. All <dragGroup> components are given uniform width, and are automatically left and right aligned

• ALIGN_UNIFORM_LEFT — Similar to FILL_UNIFORM, but all <dragGroup> components within a column are left aligned.

• ALIGN_UNIFORM_CENTER — Similar to FILL_UNIFORM, but all <dragGroup> components within a column are centered within the column spacing.

• ALIGN_UNIFORM_RIGHT — Similar to FILL_UNIFORM, but all <dragGroup> components within a column are right aligned.

Dynamic and Static Layout

The ability to resize and drag and drop <dragGroup> components in a <snapGrid> is primarily controlled by the <dragGroup>. The attributes moveEnabled and resizeEnabled specify whether you can move or resize the group. <dragGroup> also relies on the header and the resize button to provide affordances for user drag and resize gestures. Without them, the drag group cannot be moved or resized. You can use the <snapGrid> method broadcast to control various aspects of appearance and behavior for all <dragGroup> components in the grid. The method restyleHeaderStyles in the class ZENDemo.SnapGridDemoOpens in a new tab in the SAMPLES namespace illustrates this use of broadcast.

broadcast sends a signal to each of the active drag group components in the snap grid. Valid signals include:

• resize – call the onresize handler for each of the drag groups.

• disableResize – remove the resize button from the lower right corners of the drag groups.

• disableMaxToggle – redefine the drag group header to be a drag handle rather than a maximize button.

• enableMaxToggle – redefine the drag group header to be a maximize button rather than a drag handle.

• enableResize – restore the resize button to the lower right corners of the drag groups.

• processAppMessage – simply pass the value given to the <dragGroup> children. Subclasses of <dragGroup> can override the default processAppMessage() method to extend the broadcast facility to address application specific signals. The mechanism only passes a single value argument, but this value can take the form of a JSON string or an arbitrary JavaScript object so multiple discrete data can be packaged into a single broadcast value.

• removeDragHeader – completely hide the drag handle and resize the window to use the recovered space.

• restoreDragHeader – restore the drag handle and resize the window to account for the newly used space.

• setBodyStyle– given a JSON representation of a style object in value, add the given rules to the existing style of the drag body.

• setHeaderStyle – given a JSON representation of a style object in value, add the given rules to the existing style of the drag header.

• setHeaderLayout – set the headerLayout property of all child drag groups to the given value.

Note that when you run ZENDemo.SnapGridDemoOpens in a new tab, it comes up with headers and resize buttons visible, and you can move and resize the drag groups. The Remove Headers button removes these affordances, and as a result, the grid layout is static. The Restyle Headers button restores the headers functioning as maximize buttons.

Orientation-specific Layout

The <snapGrid> component can adjust the layout of rows and columns in response to the geometry of the window it is being viewed in. The properties rowsPortrait and colsPortrait specify the number of rows and columns for portrait mode, and rowsLandscape and colsLandscape for landscape mode. If you set only one of these two sets of properties, Zen uses the default row and column values for the unspecified set.

This feature is useful when creating applications to be viewed on a device such as a cell phone or tables, that changes the display orientation when the orientation of the device changes. The following example codes a page that responds to changes in window geometry when viewed in a browser. CSS sets the height and width of the <snapGrid> to 100%, and the page layout must be set to “none” as described in the section “Active Groups that Resize Proportionally.”

Class demo.SnapGridLP Extends %ZEN.Component.page
{
 /// This Style block contains page-specific CSS style definitions.
 XData Style
 {
  <style type="text/css">
   #snapGrid {
    width: 100%;
    height: 100%;
    background-color: silver;
   }
  </style>
}
 /// This XML block defines the contents of this page.
 XData Contents [ XMLNamespace = "http://www.intersystems.com/zen" ]
 {
  <page xmlns="http://www.intersystems.com/zen" 
   layout="none">
   <snapGrid id="snapGrid" 
    colsLandscape="10" 
    colsPortrait="5" 
    rowsLandscape="5" 
    rowsPortrait="10" 
   >
    <dragGroup id="dg1" onclick="" 
     moveEnabled="true" resizeEnabled="true" 
     headerLayout="C" header="1"
     homeCol="1" homeRow="1" 
     colSpan="1" rowSpan="1">
    </dragGroup>
   </snapGrid>
  </page>
 }
}