action is an element that can be:
Actions are hooks (buttons, links, select lists) that can be added to JRapid applications in different locations (local, form, listing), with different widgets to trigger execution of processes or tasks.
Actions may be defined as property or entity actions, it all depends on which element is the action's parent.
Entity actions are triggered from listings and forms, and may receive the entity's selected record/s identifier/s (they can be triggered for more than one record at the same time too; see the multiple attribute).
Property actions are accessed through links generated right besides the corresponding property on the form. No location may be specified for this actions.
The name attribute, as in every other element, identifies the action at an entity level, and it's used to identify the HTML elements that render the action.
The label attribute is what is shown to the user on the buttons, links and select boxes.
The widget attribute is used to specify how we want to render the action, and it can be one of: 'button' or 'link'.
Depending on its parent (entity, property or actiongroup), type, widget and location, the action will have different look-and-feel, behavior and require different attributes/settings for it to work.
Take a look at the image on the right to identify how each action control is generated according to its parent and location. If location is not defined, listing is taken as the default value.
Available locations are:
- Renders the action widget at the bottom of the entity's listing, (right next to the ADD and REMOVE buttons).
- Listing views that handle this location will render the action somewhere at a record/row level.
- Built-in views that support the 'local' location are: 'basic', 'table' and 'thumbnails'.
- NOTE: in the case of the thumbnails view, the action widget is rendered inside the info box shown on mouse over of each record.
- Renders the action at the bottom of the entity's form (right next to the OK and CANCEL buttons).
The action type defines the operation the control will trigger.
- Related Entity Actions
- Open another entity's form.
- Report Action
- Open a report defined in the application.
- Open Entity Actions
- It opens the selected entity's form. It can be used on property actions, and on entity actions (useful in listings that use the mainaction attribute).
- Related Listing Action
- Open another entity's listing.
- Entity Action with Location listing (default), local or form
- The function called must receive two parameters:
- arguments = obj, a reference to the DOM element that triggered the event (ie. a button on the listing).
- arguments[2..n] = functionparams extra function parameters.
- In the 'local' location, we allow the use of dynamic (not constants) extra parameters for the called function.
- The parameters are separated by semicolons (;) from each other.
- Property Action
- The function triggered expects one parameter that will contain the DOM element that triggered the event (the link/button).
- The functionparams attribute is not supported by these actions.
- arguments = obj, the specified function will receive only one argument (a reference to the DOM element that triggered the event) which may be used to transverse the form and get property values.
When a relatedentity action is triggered, another entity's form is opened. This form may receive parameters to set its properties with values related to the calling one.
- Entity action with Location listing
- This actions open a new form passing the id of the first selected row in the listing as the only parameter.
- To make use of this parameter the defaultset specified by the action must define a single parameter of the calling entity type.
- Entity action with Location form or local
- Similar to the previous case, but allows the use of defaulsetparams attribute to pass more parameters to the defaultset.
- Nevertheless, the first parameter of the specified defaultset must be for the id of the calling entity.
- Property action
- Related entity actions defined as property children do not pass any parameters to the opened form.
- You must use the defaulsetparams attribute to send the values required by the opening form to be set accordingly.
The report attribute specifies the report element to be opened and an optional pdf parameter is used to force the report output to PDF, else, HTML is the default.
- Entity action with Location button, select, form, main or local
- This actions open a report passing the id of the calling record as a parameter. To make use of this parameter the specified report must declare a string parameter named "id".
- Property action
- Report entity actions defined as property children send the value of the property as parameter to the report.
Used on property actions, or in entity actions with location = 'listing' or 'local'.
In both cases it is used to open the form of the selected item/s.
- in property actions: The property should be of type entity.
- There's no need to define any other attribute because everything is inferred from the property that holds the action as child.
- in entity actions: It has sense for listings that override the default main action (via mainaction)
- Only valid for locations 'listing' (could be multiple or not) and 'local' (single, opens the selected record).
Used on property actions only, they open an entity's listing. You must specify the entity and subset attributes to be used.
- Relatedentity action as child of entity with locations button and select.
Select a Company from the listing, click on the "Create Sale" button and a new Sale form is opened with the corresponding company set.
<entity label="Company" menu="Company" name="Company"> <property label="Logo" name="logo" type="image" width="120"/> <property display="primary" label="Name" name="name" required="required"/> <property display="secondary" label="Active" name="active" type="boolean"/> <action defaultset="forCompanyDef" entity="Sale" label="Create Sale" location="button,select" name="newSaleAction" type="relatedentity"/> </entity> <entity label="Sale" menu="Menu" name="Sale"> <defaultset name="forCompanyDef"> <param entity="Company" name="companyParam"/> <default name="company" value="companyParam"/> </defaultset> <property display="primary" entity="Company" label="Company" name="company"/> <property label="Description" name="description" type="text" /> <property display="primary" label="Amount" name="amount"/> </entity>
- Property action of relatedlisting type. For the Employee entity, when editing a record through its form, add a link under the company property to allow the user to open a new listing showing other company employees.
Note that in this case, specifying a subset is mandatory.
<entity label="Company" menu="Menu" name="Company" order="name"> <property display="primary" label="Name" name="name"/> </entity> <entity label="Employee" menu="Menu" name="Employee" order="lastName, firstName, company.name"> <subset name="forCompany" order="lastName, firstName, company.name"> <param entity="Company" name="companyParam"/> <condition field="company" value="companyParam"/> </subset> <property display="primary" label="First Name" name="firstName"/> <property display="primary" label="Last Name" name="lastName"/> <property display="secondary" entity="Company" label="Company" name="company"> <action label="Other emplyees" name="actionEmployeeList" type="relatedlisting" entity="Employee" subset="forCompany" subsetparams="company"/> </property> </entity>