Actions (tag actions)

• Action Types
• Action Attributes
• Grouped Actions
• Conditional Actions
• Example Actions

In DGS, the <actions> tag is used to define a set of operations that users can perform on table data. These actions include creating, editing, removing, viewing, importing, exporting, and customizing data interactions.

Actions determine how user controls (buttons, links, menus) are displayed in the interface and how they behave when triggered. You can configure both single-record actions (like edit or remove) and bulk actions (like bulk delete or export), and customize their appearance, permissions, behavior, and integration with JavaScript or backend logic.

This documentation explains the types of actions available, how to configure them, and how to integrate them into your DGS tables effectively.

To add some action to you DGS use actions tag.

<table>
    <actions>
        ...put your actions here...
    </actions>
</table>

Actions Tag Attributes

mode

Affects how actions are displayed when there are multiple. Can be buttons or list. If set to buttons, actions will not be grouped in a dropdown. Default is list:

<actions mode="buttons">
    <action type="list" caption="<?php echo __('Data')?>" />
</actions>

Action Types

• Store::ACTION_LIST
• Store::ACTION_INSERT
• Store::ACTION_EDIT
• Store::ACTION_REMOVE
• Store::ACTION_INFO
• Store::ACTION_PARENT
• Store::ACTION_CHILD
• Store::ACTION_DOWNLOAD
• Store::ACTION_CSV
• Store::ACTION_CSV_IMPORT
• Store::ACTION_BATCH_INSERT
• Store::ACTION_COLUMNS
• Store::ACTION_PLUGIN

Action type list (Store::ACTION_LIST)

This action is responsible for displaying a data list.

<action type="list"
        caption="<?php echo __('Deals'); ?>"
        isLoadAllColumns="true" />

Action Specific Attributes:

• isLoadAllColumns - if true, all column data will be loaded, including hidden ones, but only visible ones will be displayed in the list.

Action type insert (Store::ACTION_INSERT) / edit (Store::ACTION_EDIT)

Adding/editing data.

<action type="insert"
        caption="<?php echo __('Add'); ?>"/>
<action type="edit"
        caption="<?php echo __('Edit '); ?>"/>

Action type remove (ACTION_REMOVE)

Remove data.

<action type="remove"
        caption="<?php echo __('Remove'); ?>"/>

Action type info (ACTION_INFO)

Show readonly data.

<action type="info"
        caption="<?php echo __('Details'); ?>"/>

Action type parent (ACTION_PARENT)

Action type child (ACTION_CHILD)

Action type download (ACTION_DOWNLOAD)

Action type CSV (Store::ACTION_CSV)

Export data to CSV.

<action type="<?php echo Store::ACTION_CSV; ?>"
        mode="new"
        view="top"
        isLoadAllColumns="false"
        caption="<?php echo __('Export')?>"
        fileName="quotation_details" />

Action Specific Attributes:

• isLoadAllColumns - if false, only visible data will be exported (by default, all columns are exported).

Action type CSV Import (Store::ACTION_CSV_IMPORT)

Import data from CSV into storage.

<action type="<?php echo Store::ACTION_CSV_IMPORT; ?>"
        view="top"
        caption="<?php echo __('Import')?>"
        button="<?php echo __('Import');?>"
        delimiter=";"
        isFirstRowHeader="false"
        primaryKey="name"
        uploadDirPath="<?php echo FS_RESOURCES_ROOT;?>import/"/>

Action Specific Attributes:

• delimiter - CSV file delimiter (default is ,)
• isFirstRowHeader - if true, the first row is treated as headers and ignored
• primaryKey - key used to match data for updating, otherwise all rows are added
• uploadDirPath - directory path for uploaded CSV files

Action type batchInsert (Store::ACTION_BATCH_INSERT)

Mass addition of fields, used with mode="api".

<table name="settings"
       charset="UTF-8"
       primaryKey="id"
       mode="api">
    <fields>
        <field  type="text"
                caption="<?php echo __('Name'); ?>"
                name="name"
                width="30%"
                required="true" />
    </fields>
    <action type="batchInsert" caption="<?php echo __('Insert')?>" />
</table>

Example JSON string for adding fields:

[
    { "name": "some name" },
    { "name": "some name2" }
]

Action type columns Store::ACTION_COLUMNS

Manage DGS columns displaying and ordering. This data stores to session.

<action type="<?php echo Store::ACTION_COLUMNS; ?>"
        caption="<?php echo __('Columns'); ?>" />

Action type plugin (Store::ACTION_PLUGIN)

Executes a method in a specified plugin instance when the action is triggered.

<action type="<?php echo Store::ACTION_PLUGIN; ?>"
        caption="<?php echo __('Process Data'); ?>"
        plugin="MyPlugin"
        method="onProcessData"
        execute="true" />

Action Specific Attributes:

• plugin - (required) The name of the plugin to instantiate
• method - (required) The method to call in the plugin
• execute - When set to true, the action will be executed immediately in a StageBuilder block context without requiring a request. This is checked by the StageBuilder's _isExecBlockRequest method.

Action Attributes

caption

A label for displaying the action in DGS. Used for the action button label in the record list and the add/edit form if the title attribute is not specified.

title

Title in forms.

permission

If you need to limit the display of an action by access section, specify the permission section name.

<action type="csv"
        caption="<?php echo __('Export'); ?>"
        view="top"
        permission="employees_export" />

mode

Defines how add/edit/info forms are displayed:

mode = "new"

Values: * new - opens in a new page * right - slides out from the right * (unspecified) - opens in a modal

Attribute js

For custom action buttons, triggers specified JavaScript function.

$model['actions'] = array(
    'archive' => array(
        'type'    => 'archive',
        'caption' => __('Archive'),
        'js'      => "doArchive(%id%)",
    )
);

Attribute fast

Displays the add form inline in the list without reloading the page. Only for Store::ACTION_INSERT.

fast = "true"

You can also set a custom form:

fast = "forms/fast_insert"

In this case, template forms/fast_insert.php is used.

Attribute prefill

Pre-fills form with values from the previous entry.

prefill = "true"

cancelUrl

Override redirect when pressing Cancel in edit form:

<action type="edit"
        mode="new"
        caption="<?php echo __('Edit')?>"
        title="<?php echo __('Edit Request')?>"
        cancelUrl="<?php echo Core::getInstance()->getUrl('/user/requests/'); ?>" />

redirectUrl

If you need to change the redirect logic after performing the action.

<action type="insert"
        caption="<?php echo __('Add'); ?>"
        redirectUrl="<?php echo Core::getInstance()->getUrl('/company/%s/journal/', $id); ?>" />

button

Text for the button in the action form. Default: Submit.

---

confirmDialog

If a confirmation dialog is needed before performing the action, use the confirmDialog attribute. To set the title and message, use dialogTitle and dialogMessage.

You can also customize the confirm and cancel button captions using the dialogConfirmButtonCaption and dialogCancelButtonCaption attributes.

<action type="archive"
        caption="<?php echo __('Archive'); ?>"
        link="<?php echo Core::getInstance()->getUrl('/deal/archive/%id%/'); ?>"
        confirmDialog="true"
        dialogTitle="<?php echo __('Are you sure?'); ?>"
        dialogMessage="<?php echo __('Do you really want to archive this deal?'); ?>"
        dialogConfirmButtonCaption="<?php echo __('Yes'); ?>"
        dialogCancelButtonCaption="<?php echo __('No'); ?>" />

Attributes: - dialogTitle – title of the confirmation dialog. - dialogMessage – message shown in the dialog. - dialogConfirmButtonCaption – (optional) text for the confirm button. Defaults to "Ok". - dialogCancelButtonCaption – (optional) text for the cancel button. Defaults to "Cancel".

---

link

Specify the URL to which a POST request will be sent with record IDs in the grouped_items parameter.

js

Specify the name of the JavaScript function triggered on bulk action.

columns

Used with sectionIdent mode to define number of columns in form (only in mode="new"). Related to (sections)[./FieldsGrouping.ru.md]

<field  type="text"
        name="country"
        hide="true"
        caption="<?php echo __('Country'); ?>"
        sectionIdent="Bank Details"
        sectionCaption="<?php echo __('Bank Details'); ?>"/>
...
<action type="insert"
        mode="new"
        caption="<?php echo __('Add'); ?>"
        columns="2"
        title="<?php echo __('Add New'); ?>" />

Grouped Actions

To add bulk actions, use the grouped tag.

<grouped>
    <item caption="<?php echo __('Delete'); ?>"
          type="bulk_delete"
          link="<?php echo $core->getUrl('/test/'); ?>" />

    <item caption="<?php echo __('Move'); ?>"
          type="bulk_move"
          js="js_handler_function_name" />
</grouped>

More examples

<grouped>
    <item caption="<?php echo __('Delete Selected'); ?>"
          type="bulk_delete"
          link="<?php echo $core->getUrl('/items/delete/'); ?>"
          confirmDialog="true"
          dialogTitle="<?php echo __('Confirm Deletion'); ?>"
          dialogMessage="<?php echo __('Are you sure you want to delete selected items?'); ?>" />
</grouped>

<grouped>
    <item caption="<?php echo __('Move to Archive'); ?>"
          type="bulk_move"
          js="moveToArchiveHandler" />
</grouped>

Examples of Different Actions

Adding a top button linking to another URL

<action type="create"
        caption="<?php echo __('Create'); ?>"
        view="top"
        link="<?php echo Core::getInstance()->getUrl('/create/'); ?>"
        mode="new" />

Action linking to a specific URL

<action type="test_task"
        caption="<?php echo __('Test Task')?>"
        link="<?php echo Core::getInstance()->getUrl('/user/review/%id%/task/'); ?>"
        mode="new" />

<action type="remove"
        caption="<?php echo __('Delete'); ?>"
        confirmDialog="true"
        dialogTitle="<?php echo __('Are you sure?'); ?>"
        dialogMessage="<?php echo __('This action cannot be undone.'); ?>" />

<action type="external"
        caption="<?php echo __('Open Docs'); ?>"
        view="top"
        mode="new"
        link="https://docs.example.com/guide" />

<action type="custom"
        caption="<?php echo __('Archive'); ?>"
        js="archiveSelectedItems(%id%)"
        view="top" />

<action type="insert"
        caption="<?php echo __('Add and View Journal'); ?>"
        redirectUrl="<?php echo Core::getInstance()->getUrl('/company/%s/journal/', $id); ?>" />

Removing Row Actions Based on Conditions

Sometimes different rows need different available actions, depending on record data. For example, hide delete button if status equals created:

1. Subscribe to the Store::EVENT_ON_LIST_ACTIONS event:

<listeners>
    <listener event="<?php echo Store::EVENT_ON_LIST_ACTIONS; ?>"
              plugin="Finance"
              method="onListActions" />
</listeners>

1. Define handler:

/**
 * @event Store::EVENT_ON_LIST_ACTIONS
 * @param FestiEvent $event
 * @return bool
 */
public function onListActions(FestiEvent $event): bool
{
    $status = $event->target['values']['status'];
    if ($status !== 'created') {
        return false;
    }

    $actions = &$event->target['actions'];
    $index = array_search(Store::ACTION_REMOVE, $actions);
    unset($actions[$index]);

    return true;
}