Multi Frame Pages

#### Search Results

Search

# Multi Frame Pages

Multi frame pages are a special set of pages. Normal pages represent a generated HTML page - a multi frame page represents a generated HTML frameset page.

- What are Multi Frame Pages?

- Definition of Multi Frame Pages

- Example

- Communication between Frames

- Combination with Normal Application Designer Pages

## What are Multi Frame Pages?

Multi frame pages are a special set of pages. Normal pages represent a generated HTML page - a multi frame page represents a generated HTML frameset page.

A multi frame page does not contain controls but frames in which other pages are positioned. Each frame is associated with an ID (called "target" in this section). A frame may be:

- a normal HTML page

- an intelligent Application Designer page

- a frameset itself containing frames

Multi frame pages are the preferred way of arranging Application Designer pages in a frameset. Besides enhanced possibilities of communication between frames, multi frame pages automatically take care of keeping all Application Designer frames inside the same session.

## Definition of Multi Frame Pages

The definition of multi frame pages is done with the Layout Painter. When you create a new layout, a dialog appears in which you select a template. To create a multi frame page, you have to select the "Multi Frame Page" template. The Layout Painter will open just as usual, but instead of having the PAGE control as the highest control, you now see the control MFPAGE. You can reach a number of controls that are related to multi frame page management.

The following controls are "normal frame controls" (they are described below):

- MFPAGE - the top element of multi frame pages.

- MFCISFRAME - a frame in which an Application Designer HTML page is loaded.

- MFHTMLFRAME - a frame in which a normal HTML page is loaded.

- MFFRAMESET - an area that can be subdivided into frames itself.

The following controls are "workplace controls". The Application Designer workplace is based on these controls.

- MFWPFUNCTIONS

- MFWPACTIVEFUNCTIONS

- MFWPCONTENT

This section covers the following topics:

- MFPAGE

- MFCISFRAME

- MFHTMLFRAME

- MFFRAMESET

### MFPAGE

The MFPAGE is the top node of every multi frame page. It can be subdivided into frames or framesets.

Basic
separation | Specifies how the corresponding internally used frameset is subdivided: choose "rows" for subdividing into rows, "cols" for subdividing into columns. | Obligatory | rows cols
sizing | Defines the size of the contained sub-frames. If you have three sub-frames to show up inside the page then you might specify "200,200,*" to specify how the height (if SEPARATION is "rows") or the width (if SEPARATION is "cols") is distributed among the frames. You can specify per frame either a pixel value or a "*". | Obligatory |
comment | Comment without any effect on rendering and behaviour. The comment is shown in the layout editor's tree view. | Optional |
Appearance
border | Space between frames contained in the frameset that is internally built up. | Optional | 1 2 3 int-value
bordercolor | Sets the border color of the frame set. | Optional | #FF0000 #00FF00 #0000FF #FFFFFF #808080 #000000
frameborder | Defines if to display a border around the contained frames. Valid values are "true" or "false". | Optional | true false
framespacing | Defines the amount of additional space between the frames. Value is a pixel value. | Optional | 1 2 3 int-value
framesetstyle | Style passed to the HTML-frameset definition that is internally generated. | Optional | background-color: #FF0000 color: #0000FF font-weight: bold

### MFCISFRAME

The MFCISFRAME represents a frame in which an Application Designer page is shown. The name of the page is passed as a parameter.

Basic
target | Id of the frame. Must be unique inside the frameset page. Must only contain alphanumeric characters. The id is important! CIS offers certain methods inside the Model-class that allow an adapter to start operations for a certain frame (e.g. openeCIPageInFrame(...)). As part of the parameters of these methods a target-id is passed. The target-id is exactly the id you specify with the TARGET property. | Obligatory |
cisurl | URL of the page to be shown inside. Use /project/page.html as syntax, e.g. "/HTMLBasedGUI/empty.html". Do NOT use only page.html believing that you do not have to specify the project because the multi frame page runs in the same project than the page you want to open - you ALWAYS have to specify the project! | Obligatory |
comment | Comment without any effect on rendering and behaviour. The comment is shown in the layout editor's tree view. | Optional |
Appearance
resizable | Decision if the user is able to resize the frame. This property must be in synch with the definition in the "neighbour frames". If the neighbour frames do not support resizing then it will not be offered to the user as consequence. Valid values are "true" and "false". Default is "true". | Optional | true false
withborder | Boolean value defining if the frame has a border on its own. Default is "false". | Optional | true false
framestyle | Style that is passed to the HTML-FRAME definition that is internally generated. | Optional | background-color: #FF0000 color: #0000FF font-weight: bold
bordercolor | Sets the border color of the frame set. | Optional | #FF0000 #00FF00 #0000FF #FFFFFF #808080 #000000
marginheight | Defines top and bottom margin height. Value is a pixel value. Default is "0". | Optional | 1 2 3 int-value
marginwidth | Defines left and right margin width. Value is a pixel value. Default is "0". | Optional | 1 2 3 int-value
withownborder | Flag that indicates if started pages show an own border. Default is false. | Optional | true false
Unload Behaviour
unloadbehaviour | Reaction that CIS should take if the page inside the frame is closed. Possible values are "NOTHING" for doing nothing and "REMOVESESSION" for removing the session on server side. Do not define this property just "by accident" but leave it to the default ("NOTHING"). You only switch to "REMOVESESSION" if you want that the server side session is destroyed when leaving the page. This is the case if you have one page that clearly indicates the closing of a session at the point of time when the page is closed. | Optional | NOTHING REMOVESESSION

Applications can change the page that is shown inside the MFCISFRAME by using the method `Adapter.openCISPageInTarget(...)`.

### MFHTMLFRAME

The MFHTMLFRAME represents a frame in which a normal HTML page is shown. This page can be a static HTML page or any URL - e.g. a URL referring to a certain JSP page.

Basic
target | Id of the frame. Must be unique inside the frameset page. Must only contain alphanumeric characters. The id is important! CIS offers certain methods inside the Model-class that allow an adapter to start operations for a certain frame (e.g. openeCIPageInFrame(...)). As part of the parameters of these methods a target-id is passed. The target-id is exactly the id you specify with the TARGET property. | Obligatory |
url | URL to be opened inside the frame. The URL can be defined relative to the multi frame page or can be defined in an absolute way.. Example: You can define "../HTMLBasedGUI/workplace/header2.html" - or "http://www.softwareag.com". | Obligatory |
comment | Comment without any effect on rendering and behaviour. The comment is shown in the layout editor's tree view. | Optional |
Appearance
resizable | Decision if the user is able to resize the frame. This property must be in synch with the definition in the "neighbour frames". If the neighbour frames do not support resizing then it will not be offered to the user as consequence. Valid values are "true" and "false". Default is "true". | Optional | true false
withborder | Boolean value defining if the frame has a border on its own. Default is "false". | Optional | true false
scrolling | Boolean that indicates whether the frame can be scrolled. Default is true. | Optional | true false
framestyle | Style that is passed to the HTML-FRAME definition that is internally generated. | Optional | background-color: #FF0000 color: #0000FF font-weight: bold
bordercolor | Sets the border color of the frame set. | Optional | #FF0000 #00FF00 #0000FF #FFFFFF #808080 #000000
marginheight | Defines top and bottom margin height. Value is a pixel value. Default is "0". | Optional | 1 2 3 int-value
marginwidth | Defines left and right margin width. Value is a pixel value. Default is "0". | Optional | 1 2 3 int-value

### MFFRAMESET

The MFFRAMESET represents a frame that is internally again divided into frames. The MFFRAMESET definition decides whether to divide into rows or columns, and how to size the inner frames.

Basic
target | Id of the frame. Must be unique inside the frameset page. Must only contain alphanumeric characters. The id is important! CIS offers certain methods inside the Model-class that allow an adapter to start operations for a certain frame (e.g. openeCIPageInFrame(...)). As part of the parameters of these methods a target-id is passed. The target-id is exactly the id you specify with the TARGET property. | Obligatory |
separation | Specifies how the corresponding internally used frameset is subdivided: choose "rows" for subdividing into rows, "cols" for subdividing into columns. | Obligatory | rows cols
sizing | Defines the size of the contained sub-frames. If you have three sub-frames to show up inside the page then you might specify "200,200,*" to specify how the height (if SEPARATION is "rows") or the width (if SEPARATION is "cols") is distributed among the frames. You can specify per frame either a pixel value or a "*". | Obligatory |
comment | Comment without any effect on rendering and behaviour. The comment is shown in the layout editor's tree view. | Optional |
Appearance
border | Space between frames contained in the frameset that is internally built up. | Optional | 1 2 3 int-value
bordercolor | Sets the border color of the frame set. | Optional | #FF0000 #00FF00 #0000FF #FFFFFF #808080 #000000
frameborder | Defines if to display a border around the contained frames. Valid values are "true" or "false". | Optional | true false
framespacing | Defines the amount of additional space between the frames. Value is a pixel value. | Optional | 1 2 3 int-value
framesetstyle | Style passed to the HTML-frameset definition that is internally generated. | Optional | background-color: #FF0000 color: #0000FF font-weight: bold

## Example

The example that will be built in this section produces the following output:

When selecting a customer on the left, the customer detail screen is displayed on the right:

When the user selects another record on the left, the screen on the right is updated accordingly.

This section covers the following topics:

- The Multi Frame Page Around

- The Left Frame

- The Right Frame

### The Multi Frame Page Around

First let us have a look at the multi frame page itself. The layout definition is as follows:

    <mfpage separation="rows" sizing="70,*">
        <mfhtmlframe target="HEADER"
                     url="../HTMLBasedGUI/workplace/welcome.html"
                     resizable="true"
                     withborder="false"
                     scrolling="false"
                     framestyle="border: 1px #808080 solid">
        </mfhtmlframe>
        <mfframeset target="AROUND"
                    separation="cols"
                    sizing="200,*">
            <mfcisframe target="INNERLEFT"
                       cisurl="/cisdemos/25_mfinnerleft.html"
                       framestyle="border-right: 1px solid #808080;
                       border-bottom: 1px solid #808080">
            </mfcisframe>
            <mfcisframe target="INNERRIGHT"
                         cisurl="/HTMLBasedGUI/empty.html"
                         framestyle="border: 1px solid #808080">
            </mfcisframe>
        </mfframeset>
    </mfpage

The page is subdivided into three frames: "HEADER", "INNERLEFT" and "INNERRIGHT". Two of them are Application Designer frames, one is an HTML frame. Every frame is pointing to a certain page.

### The Left Frame

The INNERLEFT frame's page displays a text grid and lets the user select from the list of items. The layout definition is:

    <page model="MFInnerLeftAdapter">
        <pagebody horizdist="false" takefullheight="true">
            <itr height="100%" fixlayout="true" width="100%">
                <textgrid2 griddataprop="customers" width="100%" height="100%" selectprop="selected"
                           singleselect="true" hscroll="true" directselectmethod="onSelect"
                           directselectevent="onclick">
                    <column name="Id" property="id" width="100">
                    </column>
                    <column name="Name" property="name" width="400">
                    </column>
                </textgrid2>
            </itr>
        </pagebody>
    </page>

The adapter implementation is done in the following way:

    import com.softwareag.cis.server.Adapter;
    import com.softwareag.cis.server.ServerLog;
    import com.softwareag.cis.server.util.TEXTGRIDCollection;

    public class MFInnerLeftAdapter
    	extends Adapter
    {
    	// ------------------------------------------------------------------------
    	// inner classes
    	// ------------------------------------------------------------------------

    	public class CustomerInfo
    	{
                boolean m_selected;
                String m_id;
                String m_name;
                public String getId() { return m_id; }
                public String getName() { return m_name; }
                public boolean getSelected() { return m_selected; }
                public void setId(String string) { m_id = string; }
                public void setName(String string) { m_name = string; }
                public void setSelected(boolean b) { m_selected = b; }
    	}
    	// ------------------------------------------------------------------------
    	// members
    	// ------------------------------------------------------------------------

    	TEXTGRIDCollection m_customers = new TEXTGRIDCollection();

    	// ------------------------------------------------------------------------
    	// property access
    	// ------------------------------------------------------------------------

    	public TEXTGRIDCollection getCustomers() { return m_customers; }

    	// ------------------------------------------------------------------------
    	// public methods
    	// ------------------------------------------------------------------------

    	public void init()
    	{
    		super.init();
    		for (int i=0; i<40; i++)
    		{
    			CustomerInfo info = new CustomerInfo();
    			ci.setId(""+i);
    			ci.setName("Customer " + i);
    			m_customers.add(ci);
    		}
    	}

    	public void onSelect()
    	{
    		try
    		{
    			CustomerInfo info = (CustomerInfo)m_customers.findLastSelectedItem();
    			// prepare adapter of right frame
    			MFInnerRightAdapter mfira =
                            (MFInnerRightAdapter)findAdapter(MFInnerRightAdapter.class);
    			mfira.prepare(ci.getId());
    			// preload adapter so that only one request is executed
    			includeAdapterInResponse("../_DevelopersGuide/mfinnerright.html",false);
    			// refersh target
    			refreshTarget("INNERRIGHT");
    		}
    		catch (Throwable t) { ServerLog.appendException(t); }
    	}
    }

The class contains the following:

- An inner class for the text grid items.

- An `init` method for filling the text grid.

- A `onSelect()` method that is called when the user selects a text grid line.

The "critical" lines of code are inside the `onSelect()` method. Inside the method

- the selected line is determined,

- the adapter of the right neighbor screen is prepared so that it shows the data of the selected line,

- the right page is switched to the detail page (if first call) or

- the right page is refreshed to present the correct adapter information.

### The Right Frame

The right frame is loaded with /HTMLBasedGUI/empty.html first. With the first selection in the text grid, the detail page is opened inside the right frame. Afterwards, the detail page is refreshed to update its content.

## Communication between Frames

You already saw some methods in the previous section enabling one frame to open pages in another frame and to refresh information of other frames.

This section covers the following topics:

- API inside the Adapter Class

- Pay Attention to Request Processing

- Session Management (I)

- Session Management (II)

### API inside the Adapter Class

The following table shows a summary of functions that you can reach in your adapter class which inherits from `com.softwareag.cis.server.Adapter`. See the JavaDoc documentation for implementation details.

Method | Description
--- | ---
`openCISPageInTarget(...)` | Opens a certain Application Designer HTML page inside a certain frame which is identified by its target ID. There is a set of methods with different parameter notation. The default method just needs to know the page URL and the ID of the frame. Other methods expect more information, e.g. if you want to open the Application Designer page in a different subsession.
`refreshTarget(...)` | Refreshes the target's frame content. This method is to be used if you want the target frame not to change its page but to update its content. In the example in the previous section, this method is used after having updated the right frame's adapter on the server side.
`invokeMethodInTarget(...)` | Invokes a method in the target frame's Application Designer HTML page. The call is triggered from the client - for example, imagine that a button supporting the method is pressed in the target frame's Application Designer HTML page.
`sizeTarget(...)` | Manipulate the size of the target. Each target gets a certain size by the frame set definition on top of it (e.g. if the frame set definition has a sizing of "200,300,*", then the second frame has a size of "300". You can change the size of a target by using this method.

### Pay Attention to Request Processing

Be aware of the request processing in the browser: only the page which sends a request (e.g. the left page in the example) is the active page and will process the response. All other pages living in neighboring frames are by default not affected.

Consequence: if you want to change or refresh these pages, you have to explicitly do so using the API presented in one of the previous sections.

Important
The adapter that processes the request is the one to call the API methods.

### Session Management (I)

Maybe you have already tried to build multi frame pages on your own, using HTML framesets:

    ...
    ...
    <frameset cols="*,*">
      <frame src="../servlet/StartCISPage?PAGEURL=/project/left.html">
      <frame src="../servlet/StartCISPage?PAGEURL=/project/right.html">
    </frameset>
    ...
    ...

If so, you will have seen that in each of the frames, the Application Designer page will be opened correctly. However, both pages are running in independent sessions (not subsessions).

Opening the same pages using Application Designer’s MF* controls (MFFRAMESET, MFCISPAGE) will keep both pages inside the same session and subsession.

Note
Details on session management are provided in the section Session Management.

### Session Management (II)

When communicating between frames, e.g. by using the method `Adapter.openCISPageInTarget()`, the default is that the page that is opened in another target will be opened in the same session/subsession as the one that initiated the frame communication. Session ID and subsession ID are taken over by default.

There are certain variants of the `openCISPageInTarget()` method that allow to control the management of a subsession in a more fine granular way: you may pass as parameter the ID of the subsession in which a page should be opened in another page; i.e. you can explicitly decouple the other frame’s subsession from your own one.

The workplace that comes with Application Designer makes use of this: every time you open a content window, this content is managed in its own subsession, being decoupled from the workplace’s subsessions and being decoupled from other content pages’ subsessions.

Use these functions with care: typically all application adapters should run in one subsession, and only an "outside function" (such as the workplace management) should take care of starting various contents in various subsessions.

## Combination with Normal Application Designer Pages

There is no problem to integrate multi frame pages into other Application Designer pages. The mechanisms described in the section Embedding Pages into Pages are valid for both normal Application Designer pages and multi frame Application Designer pages.

This means:

- You can embed multi frame pages into normal Application Designer pages via the SUBCISPAGE2 control.

- You can embed multi frame pages into normal Application Designer pages via the ROWTABSUBPAGES control.

### On this page

- What are Multi Frame Pages?
- Definition of Multi Frame Pages
- Example
- Communication between Frames
- Combination with Normal Application Designer Pages