Open portal
Actions – Abstract
The Open portal action opens the specified portal.
The action Open portal opens a specific portal taking into account extensive configuration options, which are explained in detail in the following sections:
|
Section |
Subject |
|
Selection of the portal to be opened |
Target element and/or drop-down selection (under Action Type) |
|
Data assignment to the opened portal |
Behaviour data ($input) or option With empty data |
|
Parameters for opening the portal |
|
|
Processes when closing the portal |
|
Configuration
Selection of the portal to be opened
►IMPORTANT◄ On one hand, the portal to be opened must exist and have been published at least once. On the other hand, it must also be assigned in context at the time of calling with the effective permissions of the current session (see Association criteria, Company authorizations). Otherwise, the action is cancelled with an error ('Portal not registered'), which can only be tracked in the developer console of the browser. However, the following actions may still be executed.
CAUTION
If a portal is assigned a new Portal name, the references are not automatically updated.
There are two methods for defining the portal to be opened, which if necessary can also be used in combination:
If a target element that returns a text value at runtime is linked for the action, this value is used as the name of the portal to be opened.
The name must be case-sensitive and correspond exactly to a portal name.
If there is no access to a portal with the specified name at runtime, the action is canceled (see ►IMPORTANT◄ above).
If no target element is linked or if the linked Target element does not return a value ($null) at runtime, the optional static definition of a portal in the configuration of the action is evaluated:
The unlabeled combobox below Action type offers a selection of all portals that have read access for configuration in the context of the session.
Whether Association criteria are assigned to these portals and whether these criteria are currently in effect does not influence the dropdown selection.
However, at runtime, the specified portal must be 'accessible' if it is to be opened, otherwise the action is canceled (see ►IMPORTANT◄ above).
►NOTE◄ In contrast to other configuration elements, each 'portal name' must be unique in the system. Association criteria (and their visibility in the context of a session) therefore controls access to a portal that is uniquely targeted. A choice between the alternatives, such as when addressing a view via the specified context (see Open view (Form designer)), is not important.
Data assignment to the opened portal
The opened portal is assigned the following behaviour data ($input) by default. Unless more specific mechanisms are required, the Validate element behaviour type allows the preparation of an 'assignment' of (valid) element data from the current form to the opened portal.
The option With empty data should be set urgently if a portal is to be opened reliably without data assignment. For example, if a behaviour for a Button combines the Click triggering event with a Static behaviour type to execute the action Open portal, the default value true (as $input from Button) would be assigned to the open portal as form data without this option, which can cause undesired effects.
Parameters for opening the portal
|
Parameter |
Effect |
|
Only one instance |
Setting the Only one instance option causes the action to check at runtime whether an instance of the targeted portal is already open in the current session.
If the Only one instance option is not set, a new separate instance of the portal is always opened. |
|
Modal |
Setting the Modal option activates a number of dependent parameters (identified in this table by the preceding symbol '└' in the column header) and otherwise has the following effect:
Without the Modal option, each open instance of a portal occupies a separate view slot. |
|
└ Full size |
The Full size option has the effect that a 'modally' opened portal uses the entire area of the current view slot when opened and hides the calling form. |
|
└ Closable |
The Closable option determines whether or not the 'X' symbol for closing the portal appears in the window title of the 'modally' opened portal.
|
|
└ Size changeable |
The selection for Size changeable determines whether and, if so, in what respect (height/width) the user may change the window size of a 'modally' opened portal.
|
Processes when closing the portal
The optional parameter Execute behaviour after closed, allows you to select a behaviour configured for the calling form element.
This behaviour is executed when the window with the targeted portal is closed.
The details described apply depending on the options Only one instance, Modal and Closable.
►IMPORTANT◄ Data from the open portal is only transferred on to the 'Behaviour after closed' if the action Request close is executed there with the corresponding input data.
Example
Objective
In a 'Schedule meeting' portal, participants in the scheduled meeting are to be defined by adding the data of existing Lobster Data Platform / Orchestration Users to a Data grid ('Attendee list') as new rows:
To select the attendees, click on the 'Search' Button to open a specific search portal modally (see red arrow).
Via the 'Search profile' Combobox the calling portal offers two alternative methods ('Username' or 'Username OR name 1-3') for selection. Each selection corresponds to a search portal whose portal name is stored as a static key value.
The selected search portal offers 'matching' Users to click on in a Data grid taking into account a search text from the calling portal ('... contains ...') (see green arrow).
When you click on one of the users found in the search portal, it is closed and the corresponding entry is added to the 'List of attendees' in the calling portal (see orange arrow).
It should also be possible to end the search without making a selection by clicking the 'X' symbol at the top right of the modal window.
Configuration
In the following, only the configuration for components directly related to the Open portal action is described in detail.
Behaviour when calling the search portal:
For the 'Search' Button, a 'userSearch' behaviour is set up that reacts to the Triggering event Click (red arrow).
The Behaviour type Validate element is applied with the Column layout element (#9), which contains the Text field for the search criterion with the label '... contains ...' (green box, green arrow). This makes the relevant element data available in the portal opened by the action below. Here the Text field was assigned the data field criterion, which is also used in the search portal (see below).
The action Open portal specifies the Combobox 'Search profile' as target element. This returns the name of one of the alternatively usable search portals (USER_SEARCH_SIMPLE or USER_SEARCH_ADVANCED) as a text value based on the following service configuration:
In addition, if no selection is made, the dropdown in the configuration refers to the USER_SEARCH_SIMPLE portal as the default.
The option With empty data is not set so that the behaviour data (with the search criterion) is assigned to the search portal. Further details are described in the configuration of the search portals (below).
The portal should be able to be opened as Modal and Closable and be adjustable in width and height (see Size changeable).
The parameter Execute behaviour after closed refers to another behaviour 'addToList' which must be defined for the same Button ('Search') and defines the processing of the return value from the search portal (orange arrows).
Configuration in the search portal:
Only the search portal USER_SEARCH_SIMPLE is displayed here. The alternative search portal USER_SEARCH_ADVANCED has a similar structure, but uses a different condition for the Tuple search (Form designer).
The Text field 'Username contains' refers to the data field criterion (matching the Text field '... contains...' in the calling portal) and is therefore filled with the same text when the portal is opened.
For this Text field, the behaviour shown on the right is defined, which reacts to the Triggering event Changed with all Change types. Only 'Form data loaded' is relevant here as a change category, since value changes within the form are not intended.
The Behaviour type Tuple search (Form designer) uses a link to the Column layout marked green in the screen. The string transferred in the Text field 'User name contains ...' is now available within the search configuration as the value of a variable named criterion (data field name of the text field). The Tuple search (Form designer) should only return data from users whose username (username) contains this value. This is achieved, for example, by the following Field restriction in the condition of the tuple search Tuple search (Form designer):
The search result of the Tuple search (Form designer), projections for the fields ID (id), username (username), Name 1 (address.name1), Name 2 (address.name2) and Name 3 (address.name3), is assigned to the Data grid 'User' via the Grid: Fill action. Its column configuration uses the data field identifiers id, username, address_name1, address_name2, address_name3 for the corresponding columns. It is important to use an underscore instead of a dot in the three name fields, since an alias is automatically created in the Tuple search.
|
|
For the Data grid 'Users', the behaviour shown on the left is configured:
|
Behaviour after closing the search portal:
|
|
To close the search portal, either click on a line, which triggers the Request close action with the data of the row, or click on the 'X' symbol in the window title to end the modal search portal with a selection. Then the return value is $null. In both cases, the behaviour specified in the parameter Execute behaviour after closed is executed (here: 'addToList'), for which a case distinction is recommended.
|
