OpenForm Function

From time to time an XApp running in the browser needs to display new content to the user. This is often in response to some action by the user, for example clicking on a link. While there are many ways of displaying new content in an XApp, probably the most common way is to open a form. When a form is opened, HTML code representing the form is downloaded from the server, and then displayed in a specified area of the page. The opening of a form often happens implicitly, for example when the user clicks on a control whose hyperlink property has been set. However, forms may also be opened explicitly in browser-side code by use of the OpenForm function.

The OpenForm function allows a form to be opened in a subform, in a popup form, as the top-level form in the current browser window, or in a new browser tab/window. It also allows the display of content from external websites or from other XApps. Its declaration is as follows:


FX Code

Procedure OpenForm(FormName, Target, Parameters : String);


The OpenForm function is asynchronous, and therefore returns immediately. Use the OnReady event of the opened form to carry out any operations that need to be performed after the form is opened.


FormName

Purpose Identifies the form to be opened.

Syntax

[ InstanceName: ] Name | Url


Attribute Description
Name The class name of the form being opened.
InstanceName A specific identifier for the instance of the form being opened. If none is specified, the instance name is implicitly set to be the same as the class name.
Url External content to be opened in an IFrame. If Url points to another XApp, the XApp running in the IFrame will have its own instance of the script process.


Example 1 Opening a form 'Form1' in a subform.


FX Code

OpenForm('Form1', 'Self:Subform1', '');


Example 2 Opening an explicitly named instance 'Instance1' of Form1 in a subform.


FX Code

OpenForm('Instance1:Form1', 'Self:Subform1', '');


Example 3 Displaying content from an external website in a subform.


FX Code

OpenForm('http://www.google.com', 'Self:Subform1', '');

Target

Purpose Identifies the context in which the form is to be opened.

Syntax

InstanceName:SubformName [ (BandIndex) ] | BLANK | SAME | POPUP | FLOAT


Attribute Description
SubformName The subform that the form is to be opened in. The special string '_' may be used to denote the containing subform of the current form
InstanceName The instance name of the form containing the target subform. The following special strings may be used: 'Self' (the current form), 'Parent' (the parent form of the current form), 'Top' (the root subform of the XApp)
BandIndex If the target subform belongs to a continuous form, the BandIndex parameter may be used to specify the band in which the target subform is located. If BandIndex is not specified then the first band (corresponding to BandIndex=0) is assumed
BLANK The form is to be opened in a new browser window with a new instance of the XApp script process
SAME The form is to be opened in the current browser window with a new instance of the XApp script process
FLOAT The form is to be opened as a popup form in the current browser window. For more information about popup forms, refer to System Parameters - Popup Forms


Example 1 Opening 'Form2' in 'Subform1' of 'Form1'.

FX Code

OpenForm('Form2', 'Form1:Subform1', '');


Example 2 Opening 'Form2' in 'Subform1' in the third band of 'ContinuousForm1'.


FX Code

OpenForm('Form2', 'ContinuousForm1:Subform1(2)', '');


Example 3 Opening 'Form2' in a new browser tab/window with a new instance of the XApp script process.


FX Code

OpenForm('Form2', 'BLANK', '');

Parameters

Purpose The Parameters parameter is a compound parameter: it accepts a list of any number of named parameters. Each individual parameter is expressed as a Name=Value pair, enclosed in double quotes (""), and separated from the following parameter(s) by a comma. Many aspects of the form's content, appearance and behaviour can be influenced by the use of parameters. See the following sections System Parameters - Genera, Popup Forms, Query Parameters and Form Parameters for more information about the available parameters.

Syntax

["Name=Value"[{,"Name=Value"}]]


System Parameters - General

Attribute Description
OpenMode This parameter relates to the use of the subform cache. It has three possible values:

'' (blank - default value) - The Morfik framework checks first to see if a copy of the requested form already exists in the subform cache. If so, it displays this copy immediately. If not, it downloads a copy of the form from the server, displays it, and stores it in the subform cache.

Refresh - The Morfik framework downloads a copy of the form from the server, displays it, and stores it in the subform cache. The copy already existing in the subform cache (if any) is overwritten.

DoNotActivate - The Morfik framework checks first to see if a copy of the requested form already exists in the subform cache. If so, it does nothing. If not, it downloads a copy of the form from the server, and stores it in the subform cache for future use, but does not display it. Pre-fetching commonly-used forms in this fashion can make the XApp more responsive and result in an improved experience for end users.

StartingOffset For databound continuous forms, this parameter can be used to specify the (zero-based) index of the first record displayed
PageSize For databound continuous forms, this parameter can be used to specify the number of records displayed.
SQLFilter This parameter can be used to filter the records displayed in a databound form. The SQLFilter is appended as a WHERE clause to the SQL statement used to obtain the records from the database


System Parameters - Popup Forms

Attribute Description
Draggable Specifies whether the user should be able to reposition the popup form by dragging its title bar. Possible values: 'False', 'True' (default).
Modal Specifies whether the user should be able to interact with the controls on the rest of the page while the popup form is displayed. Possible values: 'False' (default), 'True'.
NoFadeIn Specifies whether a translucent overlay should be displayed over the rest of the page while the popup form is displayed. Possible values: 'False' (default), 'True'. Note: this parameter is ignored if Modal=False.
Center Specifies whether the popup window should be positioned in the centre of the page. Possible values: 'False', 'True' (default).
NoBorder Specifies whether a border should be displayed around the popup form. Possible values: 'False' (default), 'True'.
Title Specifies a caption to be displayed in the title bar of the popup form. (By default no text is displayed.)
Closable Specifies whether a close button (in the form of an 'X') should be displayed in the top-right corner of the popup form. Possible values: 'False', 'True' (default).
Left Specifies the horizontal position of the popup window. Note: this parameter is ignored if Center=True.
Top Specifies the vertical position of the popup window. Note: this parameter is ignored if Center=True.


Query Parameters If the form's data source is a parameteric query, values for the query parameters can be specified as part of the parameter list.

Form Parameters If the developer has defined any parameters for the form (by use of the Parameters dialog in the form designer), values for these parameters can be specified as part of the parameter list.


Example 1 Displaying records number 3 to 7 in a databound continuous form.

FX Code

OpenForm('Form1', 'Self:Subform1', '"StartingOffset=2","PageSize=5"');


Example 2 Opening a popup form at position (30,10), with caption "Hello World!"; access to controls on the rest of the page is blocked while the popup form is displayed.


FX Code

OpenForm('Form1', 'POPUP', '"Center=False","Left=30","Top=10","Title=Hello World!","Modal=True"');


Note: the OpenWindow function can be used as an alternative to OpenForm for opening popup forms.


FX Code

OpenWindow('Form1', '"Center=False","Left=30","Top=10","Title=Hello World!","Modal=True"');


Example 3 Open frmBookList of the BookCollector sample project, displaying only those records matching the criteria prmGenre=Fiction:


FX Code

OpenForm('frmBookList', 'Self:Subform1', '"prmGenre=Fiction"');


Example 4 Open frmBookList of the BookCollector sample project, displaying only those records where the UnitPrice less than $12.00.


FX Code

OpenForm('frmBookList', 'Self:Subform1', '"SQLFilter=' + EncodeParameter('"UnitPrice"<12.00') + '"');

Note: the value of the SQLFilter parameter must be encoded with the EncodeParameter function to prevent the double quote symbol in the parameter value from being interpreted as a parameter delimiter.