pp108 : Regions

Regions
This topic introduces the concept of regions, which are used to launch applications in Process Platform.


Regions are placeholders that host sub applications known as App Palettes in an application. An application can be divided into multiple regions, and a region can hold multiple App Palettes. Multiple App Palettes in a region are displayed as tabs. You can select a tab to display the respective App Palette.
The region definition can be set in two ways:

  • Inline in the HTML structure of an application.
  • As an XML in the Application Definition or in the application itself. In this scenario, the regions defined in the Application Definition take precedence over the region XML definition specified in the application itself.

    The following methods are available for regions:

Table 1. List of Methods

Method

Description

getOffset()

Gets the offset specified for the region.

getType()

Returns a string that specifies the type of region.

setOffset(value)

Sets the offset for the region. Values can be in percentage (%) or in pixels (px). If no unit is specified, it is taken as pixels by default.

setType(sType)

Sets the orientation of a region dynamically, when the region is loaded at runtime. Possible value are top, bottom, left, or right.

 

Region sets with multiple regions

In case more than two regions need to be defined for an application, they must be wrapped inside a regionset. The concept of region and regionset is similar to the frame and frameset concept in HTML. Different attributes need to be specified depending on if it is a region or a regionset.

Defining Regions inline in the HTML Structure of an Application


To define regions, set class="region" or class="regionset" for the DIV objects defined in the HTML document body.

When two regionset or regions are defined, the attributes of only the first declared region or regionset are considered for dimensions and type.

The following attributes are available for defining region-sets and regions for an Application:

Table 2. List of Attributes

Attribute

Description

appPaletteDefinitions

Denotes the XML Dataisland IDs of application definitions of the App Palettes to be loaded in the region by default. The IDs must be separated by spaces if more than one App Palette is to be loaded.

class

Mandatory. Optional values are regionset and region.

id

Denotes the unique identifier given to an App Palette, which is used to refer to it after loading an App Palette. If not specified, an auto-generated id is assigned.

regionName

 Denotes the name of the region. It will be displayed in the layout structure of the regions while dragging the App Palettes from one region to another region. If nothing is provided for the regionName, an empty layout structure of the regions will be displayed in the runtime.

multipleAppPalettes

Denotes whether multiple App Palettes can be loaded in a region. Available options are true and false(default).

offset

Mandatory; defined as offset = "<value>%". Denotes the percentage value (%) of offset required for the region.

orientation

Denotes the position of tab headers in case of multiple App Palettes. Possible values are:

  • left: Tab headers are positioned along the left edge of the tabbed multiple App Palettes.
  • right: Tab headers are positioned along the right edge of the tabbed multiple App Palettes.
  • top: Tab headers are placed at the top of the tabbed multiple App Palettes.
  • bottom: Default. Tab headers are placed at the bottom of the tabbed multiple App Palettes.

resizable

Denotes whether the region is resizable or fixed, with reference to the offset. It holds the value yes (default) or no.

textDirection

Denotes the orientation of text displayed in tab headers (in case of multiple App Palettes). Possible values are:

  • vertical: This is the default text direction for left- and right- oriented App Palettes.
  • horizontal: This is the default text direction for top- and bottom- oriented App Palettes.

type

Mandatory. Optional values are left, right, top, and bottom.

visibility

Available options are hidden(default), display, maximized, and minimized.The default value is hidden; if no content is specified in the region, the region is hidden from view.

 

HTML App Palettes in regions

It is possible to load more than one App Palettes in a region. The App Palettes can be loaded using the API application.loadAppPalette(appPaletteDefinition).


While defining inline HTML App Palettes inside a region, the static HTML must be wrapped in a DIV container. If multipleAppPalettes="true" for the region, the attributeclass="apppalette" has to be set to the same.
Other attributes that can be set to an App Palette are:

  • caption = <Caption>
  • title = "true/false". The default value is true.

While setting the HTML content in a region, use the getTab() method of the region object to get the GUI representation of the App Palette. The content can be set on the App Palette guirepresentation using the setContent() method.

You can define inline regions with App Palette as follows:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <title>Test AppPalette</title> <script src="/cordys/wcp/application.js"></script> <script type="cordys/xml" id="testCollapsible"> <Application focus="true" display="visible" title="false" inPreferences="true"> <id>testCollapsible</id> <url>/cordys/wcp/test/library/ui/testcollapsible.htm</url> <description>Collapsible</description> <caption>Collapsible</caption> <icon>/cordys/wcp/theme/default/icon/task/classicapplication.png</icon> <region docked="true" width="200px" height="400px">rightRegion</region> </Application> </script> <script type="cordys/xml" id="testCalendar"> <Application focus="true" display="visible" title="false" inPreferences="true"> <id>testCalendar</id> <url>/cordys/wcp/test/library/ui/testcalendar.htm</url> <description>Calendar</description> <caption>Calendar</caption> <icon>/cordys/wcp/theme/default/icon/task/classicapplication.png</icon> <region docked="true" width="200px" height="400px">rightRegion</region> </Application> </script> </head> <body scroll="no" leftmargin="0" topmargin="0" rightmargin="0" bottommargin="0"> <div style="width:100%;height:100%;overflow:auto"> <div class="regionset" style="width:100%;height:100%;"> <div class="region" id="leftRegion" regionName="Left Region" type="right" visibility="display" offset="70%" resizable="yes"> <div> <!-- No multiple AppPalettes. So class="apppalette" is not necessary --> <h1>Left Region</h1> </div> </div> <div class="region" id="rightRegion" regionName="Right Region" multipleAppPalettes="true" appPaletteDefinitions="testCollapsible testCalendar"> <!-- Multiple AppPalettes. So class="apppalette" is necessary --> <div class="apppalette" caption="Static HTML" title="false"> <div class="mainbody"> <h1>Right Region</h1> </div> </div> </div> </div> </div> </body> </html>

Defining Regions in the Application Definition


In the Application Definition, you can define a region as follows:

<script type="cordys/xml" id="testAppPaletteUIApplication"> <Application focus="true" display="visible"> <id>testAppPalette</id> <url>/cordys/wcp/test/library/ui/testapppaletteui.htm</url> <description>App Palette UI</description> <caption>App Palette</caption> <icon>/cordys/wcp/theme/default/icon/task/licensemanager.png</icon> <frame docked="false">main</frame> <info>This is a sample text that can be shown as Info</info> <regionsetid="parentSet"> <region id="leftRegion"type="left" visibility="display"offset="30%" resizable="yes" /> <region id="rightRegion"/> </regionset> </Application> </script>


The above definition divides an application as below:

If an application contains elements in the body and a regionset is defined in the application definition, the framework will identify the area where the body HTML is to be displayed. For example, if the region type is 'left', the body HTML is displayed on the right side and if the region type is 'right', the body HTML is displayed on the left side. Similarly, if the region type is 'top', the body HTML is displayed at the bottom and so on.

The following attributes are available for defining regions in the application definition:

 

Attribute

Description

id

Mandatory. Denotes the unique identifier given to a region, which is used to refer to the region while loading an App Palette .

type

Mandatory. Specifies whether the region should be placed to the left, right, top, orbottom.

offset

Mandatory; defined as offset = "<value>%". Denotes the percentage value (%) of offset required for the region.

visibility

Available options are hidden(default), display, maximized, and minimized.The default value is hidden; if no content is specified in the region, the region is hidden from view.

resizable

Denotes whether the region is resizable or fixed, with reference to the offset. It holds the value yes(default) or no.

appPaletteDefinitions

Denotes the XML Dataisland IDs of application definitions of the App Palettes to be loaded in the region by default. The IDs must be separated by spaces if more than one App Palette is to be loaded.