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);

Public Sub OpenForm(FormName As String, Target As String, Parameters As String)

public void OpenForm(String FormName, String Target, String Parameters)

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.

Purpose Identifies the form to be opened.

Syntax

[ InstanceName: ] Name | Url

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

FX Code

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

OpenForm("Form1", "Self:Subform1", "")

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

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

FX Code

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

OpenForm("Instance1:Form1", "Self:Subform1", "")

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', '');

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

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

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

Syntax

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

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

FX Code

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

OpenForm("Form2", "Form1:Subform1", "")

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

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

FX Code

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

OpenForm("Form2", "ContinuousForm1:Subform1(2)", "")

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', '');

OpenForm("Form2", "BLANK", "")

OpenForm("Form2", "BLANK", "");

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

System Parameters - Popup Forms

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"');

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

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"');

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

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"');

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

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"');

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

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') + '"');

OpenForm("frmBookList", "Self:Subform1", """SQLFilter=" & EncodeParameter("""UnitPrice""<12.00") & """")

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.