In its most basic form, this plug-in will add a button to an Interactive Grid's toolbar. In this case, the button is positioned in the last toolbar group, has a label, an icon, and triggers a notification when clicked.

But wait, there's more ... buttons! You can add as many buttons in the toolbar as you wish. 1 Dynamic Action = 1 Button.

What you should first know is that the IG toolbar consists of 7 groups: "Search Box", "Saved Reports", "View Switch", "Actions Menu", "Edit & Save", "Add Row" and "Reset". By default, buttons will be added to the last group - Reset. But this can, of course, be configured.

In this example we've added a new button in each of these 7 groups.

Finer positioning of the buttons within a group can also be achieved. In the following example, buttons Left and Right are placed in the same group as the Actions menu, but Left is set to take the first position, while Right takes the last position in the group. For groups with more than 1 item, you can set the button to be inserted at any index you wish.

An option to set the icon position is also available. As you can see, button Left has the icon on the left, while button Right has the icon on the right.

Another option is to style a button as Hot. Simply check the checkbox, and your toolbar button will take the primary color of the application.

Once we have positioned and styled our buttons accordingly, it's time to define their functionality. This plug-in provides a number of ways to react to their click event.

1. Trigger Event

   In most cases, it will make sense to define an event name. This will be triggered on the IG region when the button is clicked. One can listen on this event in its own Dynamic Action, and perform any number of subsequent actions.

2. Execute JavaScript Code

   You can specify an inline JavaScript function that will fire when the button is clicked. If on click of the button you don't need more than 1 dynamic action, this makes most sense as you can provide the code inline, and don't have to create an extra dynamic action.

3. Do nothing - Action is handled externally

   One can also simply provide the name of a built-in "action" under the "Action Name" attribute, and let the IG do the work. There is actually a big number of built-in "actions" in the Interactive Grid. For example: show the downloads dialog, save changes, refresh the selected rows, and many, many more. These are defined by a simple string, such as "show-download-dialog", "save", or "selection-refresh". You can find a complete list on https://apex.oracle.com/jsapi > Interactive Grid > Actions.

   Simply provide the action name under "Action Name", and set the "On Click" attribute to "Do nothing - Action is handled externally". This will inform the plug-in to not react to the click event, as the built-in Interactive Grid action will take care of it.

   In this example, the 3rd button will open the download dialog, simply by providing the string "show-download-dialog"

Actions give you the ability to control your button after initialization. One can hide, show, disable, enable, and change a button's label, only by knowing its action name.

Although in most cases this won't be needed, this plug-in still gives you the ability to fine-control and dynamically update your buttons.

In the following example, we've given the "Update Rows" button an action name of "custom-update-rows". Make sure the action name you provide does not conflict with an already existing action name from the list mentioned above.

Then separately, in its own Dynamic Action listening on selection change of the grid, we execute the following:

var actionName = 'custom-update-rows';
var regionId = this.triggeringElement.id;
var region = apex.region(regionId);
var selCount = this.data.selectedRecords.length;

// change the button label
region.call('getActions').lookup(actionName).label = `Update ${selCount} Row${selCount != 1 ? 's' : ''}`;
region.call('getToolbar').toolbar('refresh');

Take it for a spin! As you select or deselect records, the button will update accordingly.

Note: disabling/enabling the button could also be done via JavaScript in a similar way, but this plug-in provides a declarative option, namely "Disable On No Selection" that does it for you. It is toggled on for this example.

This plug-in also enables you to add buttons to the Row Actions Menu, in order to perform an action on a specific row.

Features:

1. Returning the Primary Key

   In most cases, you will most likely want to return the primary key of the affected row into a page item, listen to a change event on that item, and take it from there. For the button "Get ID" in the following grid's Row Action Menu, we've set the action to be "Return Primary Key(s) into Item" and provided "P2010_ROW_ID" as the associated item. Try it out. Click the button and you should see the primary key appear in the item.

2. Conditional Entries

   Perhaps you wish to show a button for some rows, but not for others. Or perhaps the button should be conditionally shown as disabled. This is easily achievable by creating a hidden column that contains either "hidden", "disabled" or simply is null based on your own business logic. Then provide the name of this column under the "Condition Column" attribute of this plug-in and the button will behave accordingly. For example, the "Conditional Button" will be shown normally for KING, it will be disabled for BLAKE, and it will be hidden for CLARK.

3. Separators

   If adding multiple buttons, you might wish to keep them organized by adding separators. On a button basis, you can add separators before, after, or before & after the button. In this example, both buttons have separators around them.

Similarly to adding buttons to the Row Actions Menu, one can add button to the Selection Actions menu as well. This is the menu just above all the others, that usually "bulk" processes rows.

In the following example we've combined many of the above discussed plug-in settings. For the button "Get IDs", the position is First in the list, it has a separator below it, it's set to show as disabled when no rows are selected, and it will return an array of all selected primary key's into item P2010_ROWS_IDS when clicked.

If you have the requirement for many custom buttons, your toolbar might get quite busy. A good idea in such a case is to add the less frequently used buttons to the Actions popup menu of the toolbar.

In the following example, we've added 3 custom buttons to the Actions Menu, at different positions.

Usually users should be made clear an action is not possible unless multiple records are present or selected, depending on the business logic.

To fine-control this behavior without writing any JavaScript, you can choose any of the following plug-in settings, which disable or hide a button based on the state of the grid and which are updated accordingly:

1. Disable On No Selection
2. Disable On No Data
3. Hide On No Selection
4. Hide On No Data

In the following example there are 4 buttons, each with 1 of these options enabled. Play around with the selection or search for an inexistent value to see how they react.