Entity Action Forms
Level: Intermediate
Keywords: entity action, user input, form, business action
The result: Definition of Action form to handle user input for business action
Entity Action forms (details) are configured for cases where we require user input when carrying out the specific process or action associated with the entity. Or, when we need to set default values for control variables or reset their values when carrying out a process or action associated with the entity. In other words, entity action form is defined in case when standard functionality of entity edit form is not sufficient for us.
This detail is usually opened up automatically during corresponding step of the specific business action and requires user interaction to continue the business action.
Configuration​
There are two possibilities of configuring Action Forms: directly in the entity metadata, or referenced from a separate file located under the detail subfolder. See New Entity Detail.
Also, the detailMethod configuration parameter must be set to business.
A single Action form is a specific named context located within entity action detail metadata. Each entity configuration can contain many action forms (contexts) but each action form should have unique name. The Action form context name corresponds to the id of referencing business action.
Other metadata attributes are:
size: enumerator value whih the width of action form dialogheader: configuration of entity detail's headersections: array of objects (modules) which specify content and layout of action form. You can use many available modules for arranging and displaying entitie's attributes, related entities, workflow and so on.
A ery important parameter for data elements definition within action form sections is the property parameter. If defined element corresponds directly to the feature’s attribute then value of property should have the same name as the given attribute. Then value of the given attribute is taken directly from the existing entity and displayed in action form.
If the defined element does not correspond to some feature’s attribute (e.g. some auxiliary elements, derived elements, values which can be further processed by business action etc.) then the property parameter can have any value. In any case, the business action must know what the meaning of such element is and how they should be processed.
Attributes can be prefilled in the Action form using overrideProperties, searchDefaultValue (automatically inserts currently logged user) parameters or sent to script for later processing (insertDataContext). More about attribute preffiling can be found here.
The action form definition itself is not sufficient to meet the required functionality. Other types of metadata must be defined to fulfill required functionality because data entered by user into action form is mostly processed by business action.
These parts of metadata are typically defined together with action form:
- Definiton of relevant business action in entity (feature type) business metadata. It is required that business action has the same as name as the action form.
- Creating business action script – in case that one from the steps of the business action is represented by JavaScript function. Bussiness action script consumes the data entered by the user in the action form and performs the own creation or editing features and associations. Business Scripting API is used for creating bussiness action scripts.
- Definition of metadata which enables to use action form instead of the standard functionality. It can be achieved by definition of the intent or by using of special parameters inside the samo-browse, related-entity-list and other modules, see Examples.