Embedding Forms in another application

IYOPRO forms can be displayed embedded in other applications. When using this mode, additional functions are available to control the processing of the form by the hosting application.

The functions will only be invoked, if the form is displayed inside another application using the Internet Explorer control.

Controlling form submission

Prior to the submission of the form a "pre-submit handler" can be invoked in the hosting application. This handler can check, amend or modify the form data. If an exception occurs during execution of the handler the form submission will be canceled. As the name indicates the handler is invoked prior to any potentially defined form end action.

The pre-submit handler can be specified in the workflow properties of the form. It needs to enabled and allows to specify a text string which is transferred to the hosting application. Which information is passed to the hosting application depends on the implementation. Please note, that the information is always transferred as text. Usually the data defined as "Host application parameter" will be a string representation of a data structure the application understands. But simple text commands like e.g. "CHECKDATA" can be used as well.

NewItem924

When the user clicks "submit" on the form, it is checked, if the form is

a) embedded in another application

b) the hosting application provided an accessible function "OnFormPreSubmit"

If both conditions are met, the function is invoked in the hosting application and a representation of the form is passed.

Exchange information between the form and the hosting application

Information about specific form properties can be obtained by the hosting application by calling a function via the InvokeScript method of the browser control. IYOPRO provides a set of functions allowing to obtain information about the pre-submit handler, the form variable values and to set the form variable values.

string WPFGetFormDataProperty(string name): Get the value form property <name>.

Within the hosting application the pre-submit handler property values can be read by querying the properties PreSubmitExpression.IsEnabled and PreSubmitExpression.Info. The first returns the value of the above checkbox, while the second returns the string provided as pre-submit handler parameter.

The values of individual form variable values can be read in a similar way, using the function:

string WPFGetFormObjectPropertyAsJson(string name): Get the value form form variable <name> as JSON.

Please note that all provided form variable names must be prefixed with "FormValues".

To return data to IYOPRO another function is available.

void WPFSetFormDataProperty(string name, string value): Set form variable <name> to the value <value>. Value has to be a JSON representation of the desired value.

Controlling action button processing

A form with a button of the type "action" has an identical feature as the pre-submit handler. The button pre-click handler allows to specify an information which is transferred to the hosting application prior to executing the action script of the button.

NewItem926

Similar to the processing for the pre-submit handler, if the action button is clicked, IYOPRO checks that the form is:

a) embedded in another application

b) the hosting application provided an accessible function "OnActionButtonClicked"

If both conditions are met, the function is invoked in the hosting application and the host application parameter is provided to it.

With the available functions described above form variable values can be read and also changed.

Please refer to the following pre-submit example for an example implementation.

Pre Submit Handler Example

If the form is embedded in IYOPRO.PLM.Components as a workflow start form, a function in IYOPRO.PLM.Components can be invoked to process the form data prior to the form submission.

The protocol used with IYOPRO.PLM.Components expects a string that contains a python dictionary as data. This dictionary contains a key to define the function to executed and a parameter to control which form variable should be provided to function.

Pre-Submit Example Data

{ "TYPE" : "FB", "NAME" : "IYOPRO.PLM.TEST.PRESUBMIT", "FBPARAMETER" : "Text" }

This would instruct IYOPRO to call the hosting IYOPRO.PLM.Components application when the submit function of the form is invoked. As part of the of this call the above text is transferred. IYOPRO.PLM.Components decodes the information and obtains the value of the form variable specified by "FBPARAMETER". This value is passed to the function module (TYPE="FB") with the name "IYOPRO.PLM.TEST.PRESUBMIT".

The function module itself processes the data and optionally returns information to the form. For example the value of the text variable can be changed and an information, indicating the the form data was already processed, is set.

IYOPRO.PLM.Components Example function module

! IYOPRO.PLM.TEST.PRESUBMIT
! ------------------------------------------------------------------------------------------------
! Example of a synchronous call form the IYOPRO web client via the pre-submit handler
! Parameters:
! P1 = (IN) Dictionary of the form data
! Not all expected key might be present, depending on the form values
! P2 = (IN) Variable name
! Set this variable with a string representing a Python dictionary.
! Keys are the form variable names and their respective values (as JSON) to be modified.

LOCAL FORMDATA[]
CREATE ARRAY FORMDATA FROM P1 OPT 'PYTHON'
SET ARR FORMDATA ROW -1 COL ACOLUMNS(FORMDATA)

LOCAL TXT
TXT = FORMDATA[0='Text'][1]
TXT = 'Pre-Submit-Handler(' + TXT + ')'

LOCAL RET
RET = '{ "Text" : "\"'+TXT+'\"", "PROCESSED" : "\"Yes\"" }'
EXEC P2+'=RET'

Another typical usage is that within the form there is a checkbox, allowing the user to specify if he wants to have the form data processed directly in the application embedding the form or by the workflow. Depending on the value of the checkbox the function triggered by the pre-submit handler would either perform the processing or do nothing. Likewise the workflow either perform the processing or skip it.

Thus the user can decide if a time consuming operation is to be performed while he waits (within the pre-submit handler of the hosting application) or asynchronous by the workflow.