Developing Zen Applications
Client Side Layout Managers
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

At runtime, Zen builds a page description on the server and ships it to the client, where the page description is unpacked, expanded, and displayed as specified. This is the classic browser-based web application that serves previously laid-out pages to remote users upon receiving their requests for display. In this case, the Zen application maintains full control over what it shows to the user.

Note:
For more about this typical case, see the section Zen Pages at Runtime in the “Zen Client and Server” chapter of Using Zen.
Client side layout provides a useful exception to this typical case. This chapter explains how to add components to Zen pages that permit a user to initiate client side adjustments to the page layout after the page has been rendered on the client. That is, the user directly manipulates the page layout by clicking and dragging the mouse.
Under this model, the user interface runs in a web browser, but it is not confined to the strict request-response interchange of a web application. Rather, the browser is the means for delivering a dynamic user interface that might otherwise be written in a language such as Visual Basic. Zen supports this type of application by providing several options for client side layout management.
Using Active Groups to Manage Layout
The simplest option for client side layout management is to write Zen pages using the built-in client side layout managers. These built-in components are called active group components. Each of them is a Zen group component, with special capabilities to permit direct manipulation on the client side. Each active group is also a client side layout manager; the terms are interchangeable.
The built-in active groups are:
This chapter describes how to use the built-in active groups. The next several sections describe:
If you want to customize active group behavior in a way that applies to all components within the group, you can use the Zen client side library module to write your own client side layout manager (active group). For a full reference guide, see the chapter Client Side Library in this book.
Vertical and Horizontal Active Groups
Suppose a designer wants to divide the screen into four regions:
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:
Zen Page Layout Using Active Groups
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:
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:
  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:
    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 following figure shows a conceptual view of this design:
Three-Column Work Area Using Active Groups
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.
Adding Objects Dynamically
In order to dynamically add a child object to an active group such as <desktop>, <corkboard>, or <snapGrid>, the active group needs to do client-side initialization of the child object.
The first step is to make sure that the entire DOM object is ready before calling the initialize code. Do this by calling the refreshContents() method with a parameter of 1 or true, to force a synchronous object creation.
Next re-initialize the active group and its children. You can do this with a call to ZLM.initLayout(), provided that the active group itself was statically defined as part of the base page.
You can call ZLM.initLayout() repeatedly as needed, but does take time to run, so if you know you are creating a number of drag groups in a row, it is best to call refreshContents() once after all the new children have been added, and call ZLM.initLayout() once after refreshContents() returns. You can add windows individually, but batching them when feasible cuts down on server chatter and client-side processing.
As an example, the following code shows the proper order for the calls to add an empty, resizable drag group from the client without a full page refresh.
XData Contents [ XMLNamespace = "http://www.intersystems.com/zen" ]
{
 <page xmlns="http://www.intersystems.com/zen">
  <hgroup>
   <button caption="add" onclick="zenPage.addClientSide();"/>
  </hgroup>
  <snapGrid id="snapGrid" cols="10" rows="10" 
   enclosingStyle="height:500px;width:500px;background-color:silver">
  </snapGrid>
 </page>
}

ClientMethod addClientSide() [ Language = javascript ]
{
 var sg=zen("snapGrid");
 var dg=zenPage.createComponent("dragGroup");
 dg.homeCol=1;
 dg.homeRow=1;
 dg.rowSpan=2;
 dg.colSpan=2;
 dg.header="new";

 sg.addChild(dg);
 sg.refreshContents(1)
 ZLM.initLayout();
}
<activeHGroup> and <activeVGroup>
An <activeHGroup> is an active group that displays a two-part split pane with left and right partitions, optionally separated by a moveable adjustment bar. An <activeHGroup> can have only two child components. The first child defined in the <activeHGroup> appears in the left partition and the second child appears in the right partition. The “H” in the <activeHGroup> name means horizontal.
There is also an <activeVGroup> for the same functionality with vertical alignment. The split panes for <activeVGroup> are top and bottom rather than left and right.
Usually, both children of an <activeHGroup> or <activeVGroup> are groups. Each of these child groups defines the layout for its partition. The two children of an <activeHGroup> or <activeVGroup> may contain any number or type of Zen components, according to their usual allowances and restrictions, depending on which types of group they are: <hgroup>, <desktop>, <activeVGroup>, and so on.
<activeHGroup> and <activeVGroup> each have the following attributes.
Attribute Description
Zen group attributes <activeHGroup> and <activeVGroup> have the same style and layout attributes as other Zen groups, except that the layout attribute is not used for active groups. For descriptions, see Group Layout and Style Attributes in the “Zen Layout” chapter of Using Zen.
autoExpand
If defined, this property indicates that one of the two partitions is an automatic open, automatic close sidebar panel. When this is the case, the designated panel should expand when the mouse enters the bounds defined by the split between the partitions, and grow until it reaches the width given by the autoExpand value.
The autoExpand value is always interpreted in pixels. A positive value designates the left (top) partition for automatic expansion. A negative value designates the right (bottom) partition.
The default value (null) disables the feature for this group.
handlePattern
String indicating a file name for an image to use to paint the dragable partition handle. For <activeHGroup>, this image should be at least as wide as the handle thickness and is repeated vertically along the length of the handle. Correspondingly, for <activeVGroup>, this image should be at least as tall as the handle height and is repeated horizontally along the length of the handle.
The default is a PNG image that produces a gray gradient effect.
handleThickness
Width in pixels of the adjustment handle, which is displayed along the dividing line between the two partitions. Due to the dynamic nature of active groups, the width of this bar cannot be set using CSS and must be specified via the handleThickness property.
The default is "7" which produces a drag handle of one-eighth inch (2 mm) on most screens.
noResize
If true, the user is not allowed to resize the partitions. If false, the user can adjust partition size by dragging the adjustment handle with the mouse. The default is false.
If resizing is enabled (noResize is false) the mouse pointer changes to an east-west (or north-south) resize cursor when the mouse is in a potential drag position.
onresizeBottom Specifies a handler for the onresizeBottom event. This event fires when the user resizes the bottom panel of this <activeVGroup>.
onresizeLeft Specifies a handler for the onresizeLeft event. This event fires when the user resizes the left panel of this <activeHGroup>.
onresizeRight Specifies a handler for the onresizeRight event. This event fires when the user resizes the right panel of this <activeHGroup>.
onresizeTop Specifies a handler for the onresizeTop event. This event fires when the user resizes the top panel of this <activeVGroup>.
soundFX String indicating a file name for a sound file to be played when an automatic expansion group grows or shrinks. If not defined or null (a blank string) no sound accompanies the animation. The default is null.
split
A string that defines the division between the two panes. Zen interprets the split value as follows:
  • A value that ends in % (the percent sign) is interpreted as a proportional division between the left and right (or top and bottom) panes and is recalculated whenever the base container is resized.
  • A positive value without % is interpreted as a fixed width for the left (or top) partition. In this case, any adjustments to the total width of the base container affect the right (or bottom) partition only.
  • A negative value (which cannot contain a % sign) is interpreted as a fixed width for the right (or bottom) partition. In this case, any adjustments to the total width of the base container affect the left (or top) partition only.
The default split value is this string:
Manual adjustment of the panes changes the size of the fixed width or percentage. The new sizes or ratios are respected when the base container is resized.
<activeHGroup> and <activeVGroup> divide the screen as specified by the split property based on the size of the window at the time the page is loaded, and allow the user to readjust this layout as desired with the adjustment handles. You can reset the size of the panes programmatically, including changing whether the split is calculated as a fixed size or a ratio. If the value of the split property is a string ending in a percent sign, such as “75%,” the split is calculated as a ratio. If the value of split is a string ending in px, such as “75px,” the split is calculated as a fixed width. If the value of split is a number, such as 50%, the split is resized using the specified number and retaining whatever units are in use at the time. For example, the following code fragment creates an <activeVGroup> with split set to the default value of 50%:
<activeVGroup id="activeVGroup" handleThickness="5">
 <vgroup>
  <hgroup>
   <button caption="Change To Pixels" valign="top"
    onclick="zenPage.changeSize('pixels');" />
   <button caption="Change To Percent" valign="top"
    onclick="zenPage.changeSize('percent');" />
   <button caption="Change Size Same Units" valign="top"
    onclick="zenPage.changeSize('same');" />
  </hgroup>
 </vgroup>
</activeVGroup>
The onclick event handler for the buttons changes the size and units of the split, as follows:
ClientMethod changeSize(mode) [ Language = javascript ]
{
  var avgr = zenPage.getComponentById('activeVGroup');
    switch (mode)
    {
      case 'pixels':
        avgr.setProperty('split',"75px");
        break;
      case 'percent':
        avgr.setProperty('split',"75%");
        break;
      case 'same':
        avgr.setProperty('split',30);
        break;
    }
}
If you want the groups to automatically recalculate their layouts in response to a resize of the base window itself, you need to add the following call inside the optional onlayoutHandler JavaScript callback method for the Zen page:
ZLM.notifyResize(document.body);
When this call is in place, the notifyResize function is called automatically both when the page first loads and in response to window resizing at the browser level. Placing notifyResize in the onlayoutHandler callback allows you to place other “resizing reactions” in the onlayoutHandler callback, if you desire further processing.
For more about onlayoutHandler, see the section Zen Layout Handler.”
<corkboard>
A <corkboard> may contain one or more <dragGroup> components. A <corkboard> is an active group whose child components may visually overlap. As soon as the user clicks on a <dragGroup> in a <corkboard>, that <dragGroup> comes to the foreground. The user can subsequently drag the <dragGroup> and drop it in a new position in the <corkboard>. The dragged component overlays everything else inside the <corkboard>. No other component, besides the dragged component, is moved out of its current position.
The user cannot move components into or out of the <corkboard>. Direct manipulation can only occur within the <corkboard> container.
The immediate children of a <corkboard> component must be <dragGroup> components, but there are no restrictions placed on the contents of the <dragGroup> components themselves. A <dragGroup> may contain any component that is valid in a group.
<corkboard> has the following attributes.
Attribute Description
Zen group attributes <corkboard> has the same style and layout attributes as other Zen groups. For descriptions, see Group Layout and Style Attributes in the “Zen Layout” chapter of Using Zen.
<desktop>
A <desktop> may contain one or more <dragGroup> components. A <desktop> is an active group that “tiles” its child components so that each one is fully visible and none of them overlap. As soon as the user clicks on a <dragGroup> in a <desktop>, that <dragGroup> comes to the foreground. The user can subsequently drag the <dragGroup> and drop it in a new position in the <desktop>. When the user drags and drops a <dragGroup> component into a new position, the dragged component moves the other <dragGroup> components in the <desktop> out of its way. All <dragGroup> components change position after the dragged component is dropped.
The user cannot move components into or out of the <desktop>. Direct manipulation can only occur within the <desktop> container.
The immediate children of a <desktop> component must be <dragGroup> components, but there are no restrictions placed on the contents of the <dragGroup> components themselves. A <dragGroup> may contain any component that is valid in a group.
<desktop> has the following attributes.
The underlying geometric model for the <desktop> is a simple one based on rows and columns. For this reason the <desktop> component supports row and column style settings that can enforce row and column alignment constraints on the <dragGroup> components that it contains.
The arrangement of <dragGroup> components within the <desktop> varies, but in general this arrangement is biased in favor of “row collapse.” This means that if a <dragGroup> is removed from a given row, any other groups in the same row move to the left, collapsing the length of the row and possibly creating blank space at the extreme right end of the row. This convention maximizes the use of the visible portions of the window and minimizes the need for horizontal scrolling.
You can suggest an initial layout of the <dragGroup> components within the <desktop> by supplying CSS styles such as valign:top and align:left for these components. You can also set the CSS style properties top and left to explicit pixel values; for example:
<dragGroup enclosingStyle="top:150px; left:233px;" >
    <!-- contents of drag group here -->
</dragGroup>
When rendering the <desktop> component, Zen makes every effort to abide by such suggestions within the other constraints that are currently active. However, row and column styles, automatic row collapse, and the prohibition against overlapping <dragGroup> components make it impossible to guarantee that the placement suggested via CSS is respected exactly.
The <desktop> component has the following attributes.
Attribute Description
Zen group attributes In addition to its capabilities as an active group, <desktop> has the same style and layout attributes as other Zen groups. For descriptions, see Group Layout and Style Attributes in the “Zen Layout” chapter of Using Zen.
colStyle The <desktop> can enforce sizing and alignment constraints on the <dragGroup> components within its columns. You can choose a column configuration by assigning a value to the colStyle attribute as described in the section <desktop> Column Style following this table.
rowStyle The <desktop> can enforce sizing and alignment constraints on the <dragGroup> components within its rows. You can choose a row configuration by assigning a value to the rowStyle attribute as described in the section <desktop> Row Style following this table.
It is possible to query, save, and restore the <desktop> state. The <desktop> component provides JavaScript methods that allow you to save and restore a particular user’s choice of geometry for the <desktop> — that is, how the user sized and placed components within the <desktop> during a previous session with the Zen page. You can work with this information as follows:
getState
layout=getState()
The getState method returns a string that records the <desktop> state. The format for this string is an internal encoding that you do not need to understand in order to use this method. Simply store the string, in any way desired, to retrieve it for later use with restoreState.
restoreState
restoreState(layout)
Inputs a string that tells the <desktop> which geometry to use when it displays. layout must be a string that was previously acquired using getState. The restoreState method does not actually open any windows. It takes whatever windows happen to be open, and restores them to where they were when the layout string was saved.
<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:
<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:
<snapGrid>
A <snapGrid> is an active group which can contain one or more <dragGroup> components, organized so that each one is aligned with a grid. The number of rows and columns specified defines the underlying grid. The resulting grid is a normalized space, meaning that a four column layout results in the width of each column being 25% of the total width.
You can define different layouts for portrait and landscape page orientation, such that the number of columns and rows changes if the geometry of the <snapGrid> becomes taller than it is wide (or vise versa). This is particularly useful for adapting layouts on devices such as tablets and mobile phones.
The immediate children of a <snapGrid> component must be <dragGroup> components, but there are no restrictions placed on the contents of the <dragGroup> components themselves. A <dragGroup> may contain any component that is a valid child of a group.
Child components may visually overlap. A <dragGroup> in a <snapGrid> comes to the foreground when the user clicks on it. If the appropriate user gestures are enabled, the user can drag and drop the <dragGroup>. When dropped, a <dragGroup> snaps to the closest grid lines. The grid itself does not scroll, however the <dragGroup> components in the grid may.
The user cannot move components into or out of the <snapGrid>. Direct manipulation can only occur within the <snapGrid> container.
<snapGrid> has the following attributes.
Attribute Description
Zen group attributes In addition to its capabilities as an active group, <snapGrid> has the same style and layout attributes as other Zen groups. For descriptions, see Group Layout and Style Attributes in the “Zen Layout” chapter of Using Zen.
cols Specifies the number of columns used for both portrait and landscape layouts. The default value is 3.
colsLandscape Specifies the number of columns used when the rendered width of the <snapGrid> is greater than or equal to its height.
colsPortrait Specifies the number of columns used when the rendered width of the <snapGrid> is less than its height.
rows Specifies the number of rows used for both portrait and landscape layouts. The default value is 2.
rowsLandscape Specifies the number of rows used when the rendered width of the <snapGrid> is greater than or equal to its height.
rowsPortrait Specifies the number of rows when the rendered width of the <snapGrid> is less than its height.
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.SnapGridDemo 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:
Note that when you run ZENDemo.SnapGridDemo, 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>
 }
}
<dragGroup>
A <dragGroup> is the only Zen group component that can be the direct child of a <desktop>, <corkboard>, or <snapGrid>. The <dragGroup> itself can contain any component you can put in a group.
A <dragGroup> can display a header bar, which can have a text label and various buttons. A <dragGroup> can be resized, maximized, minimized, closed, and restored by clicking its buttons and by dragging the header or the resize icon in the lower right corner. In many ways the <dragGroup> is similar to a desktop window such as you would typically see on a Macintosh or PC desktop.
<dragGroup> has the following attributes.
Attribute Description
Zen group attributes <dragGroup> has the same style and layout attributes as other Zen groups. For descriptions, see Group Layout and Style Attributes in the “Zen Layout” chapter of Using Zen.
centerHeader If set, this boolean flag indicates that the title section of the header should be centered over the <dragGroup>.
colSpan
If the <dragGroup> is a child of a <snapGroup>, this specifies the initial width of the <dragGroup> in columns of the <snapGroup>. See Dynamic and Static Layout for more information on resizing a <dragGroup> in a <snapGroup>.
header
Title to display in the header bar that displays across the top of this <dragGroup>.
Although you can enter ordinary text for this attribute, it has the underlying data type %ZEN.Datatype.caption. This makes it easy to localize its text into other languages, as long as a language DOMAIN parameter is defined in the Zen page class. The %ZEN.Datatype.caption data type also enables you to use $$$Text macros when you assign values to the invalidMessage property from client-side or server-side code.
headerLayout The header layout pattern determines the order in which controls are added to the header section of the <dragGroup> window frame. This is encoded as a five character string consisting of the following tokens :
  • 'I' represents the Iconify button 
  • 'T' represents the Title section with both application logo and header caption
  • 'F' represents the Full screen button 
  • 'C' represents the Close button 
  • 'U' represents the User content div (if desired) 
This string allows you restructure the location of the controls with a single call and can be useful if you are trying to match the look and feel of a given operating system. For example, MS-Windows systems follow the pattern of 'TIFC' whereas MacOS adopts the standard of CIFT with the title centered (see centerHeader). The Title section represent something of a breakpoint in the header layout. Everything prior to the header floats from the left end of the header; everything after the header, floats from the right end.
homeCol
If the <dragGroup> is a child of a <snapGroup>, this specifies the initial column where the top of the <dragGroup> is positioned. See Dynamic and Static Layout for more information on repositioning a <dragGroup> in a <snapGroup>.
homeRow
If the <dragGroup> is a child of a <snapGroup>, this specifies the initial row where the left edge of the <dragGroup> is positioned. See Dynamic and Static Layout for more information on repositioning a <dragGroup> in a <snapGroup>.
imageClose
URI of the image to display on the button that the user clicks to close this <dragGroup>. If you do not specify imageClose, Zen uses its default:
If imageClose is the relative pathname of a file, it is understood to be relative to the CSP directory in the Caché installation directory. Typically this path identifies the images subdirectory for your Zen application. For example, the following value:
finds image files in the directory:
This holds true for any image attribute of <dragGroup>.
imageCloseHover
The URI of the image to display for the close group button when the mouse hovers over the icon.
imageCloseWidth The width (in pixels) of the space allocated for the images for the close group button. The default images are 16 by 16 pixels. You cannot specify a different image height.
imageContract
URI of the image to display on the button that the user clicks to contract this <dragGroup>. If you do not specify imageContract, Zen uses its default:
. See imageClose.
imageContractHover The URI of the image to display for the contract group button when the mouse hovers over the icon.
imageContractWidth The width (in pixels) of the space allocated for the images for the contract group button.
imageExpand
URI of the image to display on the button that the user clicks to expand this <dragGroup>. If you do not specify imageExpand, Zen uses its default:
imageExpandHover The URI of the image to display for the expand group button when the mouse hovers over the icon.
imageExpandWidth The width (in pixels) of the space allocated for the images for the expand group button.
imageMinimize
URI of the image to display on the button that the user clicks to minimize this <dragGroup>. If you do not specify imageMinimize, Zen uses its default:
imageMinimizeHover The URI of the image to display for the minimize group button when the mouse hovers over the icon.
imageMinimizeWidth The width (in pixels) of the space allocated for the images for the minimize group button.
imageResize
URI of the image to display on the button that the user clicks to resize this <dragGroup>. If you do not specify imageResize, Zen uses its default:
imageResizeSize Size of the square to reserve for the resize icon. This is an integer value, in pixels. The default value is 16, which indicates a 16x16 pixel square.
minWidth This sets the minimum width (in pixels) for a dragGroup when the user is resizing it interactively. The value of minWidth has no bearing on programmatic setting of the dragGroup's size. If used within a snapGrid context, the actual minimum width is set to the next highest even multiple of the snapGrid column width.
The property is an integer with the implied units of pixels. It can be set either statically in the XData block or at run time with a call to setProperty() on the object. The default value is 96.
moveEnabled If true, this flag allows the user to reposition the <dragGroup> by drag and drop gestures within the containing active group area. The default value is true. moveEnabled has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.
onclosepending The onclosepending event handler: This event is fired when the user clicks the close button of this <dragGroup>. Unlike native browser windows, it is possible to prevent the window closure by calling abortClose() in response to this event.
onresize The onresize event handler: This event is fired when the user resizes the <dragGroup>.
onwindowdrop The onwindowdrop event handler: This event is fired when the user releases the title bar of this <dragGroup> after a drag and drop gesture.
onwindowgrab The onwindowgrab event handler: This event is fired when the user grabs this <dragGroup> by the title bar for a drag and drop gesture.
resizeEnabled If true, this flag allows the user to resize this <dragGroup>. The default value is true. resizeEnabled has the underlying data type %ZEN.Datatype.boolean. See Zen Attribute Data Types.
rowSpan
If the <dragGroup> is a child of a <snapGroup>, this specifies the initial height of the <dragGroup> in columns of the <snapGroup>. See Dynamic and Static Layout for more information on resizing a <dragGroup> in a <snapGroup>.