Action (element)

From JRapid

Jump to: navigation, search

action is an element that can be:

  • child of entity (aka "entity actions") or
  • child of property (aka "property actions")


Contents

Description

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.


Action Locations

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:

listing
Renders the action widget at the bottom of the entity's listing, (right next to the ADD and REMOVE buttons).
local
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.
form
Renders the action at the bottom of the entity's form (right next to the OK and CANCEL buttons).


Action Types

The action type defines the operation the control will trigger.

JavaScript Actions
Execute a specified JavaScript function.
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.

Usage

<action
        name = NAME
        label = LABEL 
        type = "javascript" | "relatedentity" | "report" | "openentity" | "relatedlisting"
        location = "button" | "listing" | "local" | "form"
        widget = "link" | "button"
        description = DESCRIPTION
        function = FUNCTION 
        functionparams = PARAMS
        entity = ENTITY
        listing = LISTING 
        subset = SUBSET 
        subsetparams = SUBSETPARAMS
        defaultset = DEFAULTSET 
        defaultsetparams = PARAMS
        report = REPORT
        pdf = "pdf"
/>

Javascript Actions

This type of action executes a javascript function defined by the function attribute that must be implemented and made available by the developer (see usescript for more on this).

Entity Action with Location listing (default), local or form
The function called must receive two parameters:
  • arguments[0] = obj, a reference to the DOM element that triggered the event (ie. a button on the listing).
  • arguments[1] = ids, a JavaScript Array holding the ids of the listing's selected records (or THE selected record if 'local' or 'form').
  • 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[0] = 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.

Relatedentity Actions

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.

Report Actions

Report actions open reports in new browser windows. See reports wiki page for more information on specific features for reports.

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.

Openentity Actions

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

Relatedlisting Actions

Used on property actions only, they open an entity's listing. You must specify the entity and subset attributes to be used.

Examples

  • 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>

Relatedentity action child of entity with location button and select

  • 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>


Relatedlisting action child of property

See also

Personal tools