{"id":560,"date":"2017-02-20T00:19:53","date_gmt":"2017-02-20T05:19:53","guid":{"rendered":"http:\/\/hardlikesoftware.com\/weblog\/?p=560"},"modified":"2017-03-31T10:33:58","modified_gmt":"2017-03-31T15:33:58","slug":"how-to-hack-apex-interactive-grid-part-3","status":"publish","type":"post","link":"https:\/\/hardlikesoftware.com\/weblog\/2017\/02\/20\/how-to-hack-apex-interactive-grid-part-3\/","title":{"rendered":"How to hack APEX Interactive Grid Part 3"},"content":{"rendered":"

If you haven’t read parts one<\/a> and two<\/a> yet you probably should before proceeding with this one. They covered some basics, configuration and toolbar and menu customization. In part 3 I’ll explain how to control and interact with Interactive Grid (IG) using JavaScript. As was already mentioned in parts 1 and 2 this is aimed at people with at least intermediate level experience with APEX and JavaScript Also most of the APIs are not documented or supported. <\/p>\n

[Update 5.1.1 28-Mar-2017] This article has been updated to reflect patch release 5.1.1<\/p>\n

<\/p>\n

Control<\/h2>\n

There are a few general ways to control and interact with IG from JavaScript code. One simple, common action that can be done to an IG is refresh the data. This is a documented and supported API.<\/p>\n

apex.region(\"regionStaticID\").refresh();\r\n<\/code><\/pre>\n
This same code will work to refresh any region that supports being refreshed (just supply the correct Static ID). This is the new official 5.1 way to refresh a region. There is also an equivalent dynamic action called Refresh<\/code> (same as in previous releases but internally uses the apex.region<\/code> API). A difference compared to other APEX components is that with IG the server returns just the data as JSON. Other components such as Interactive Reports return markup that includes more than just the data; for example the toolbar. This difference may only be of academic interest, but should not be a surprise once you understand the basic architecture of IG<\/a>. Another differences is that if the IG is editable and has any changes then the user is prompted to confirm the refresh so that they don’t loose changes by accident. <\/p>\n
If you don’t want to prompt the user you must explicitly clear the model changes first. The user should not be surprised about loosing changes. For example the following JavaScript code could be on a dynamic action on a button labeled “Cancel Changes”. (This is getting a bit ahead of ourselves by using a model API.)<\/p>\n
[Update 5.1.1] The following code was updated for 5.1.1 to use getCurrentView method.<\/p>\n
var ig$ = apex.region(\"emp\").widget(),\r\n    view = ig$.interactiveGrid(\"getCurrentView\");\r\n\r\nif ( view.internalIdentifier === \"grid\" ) { \/\/ only grid supports editing\r\n    view.model.clearChanges();\r\n}\r\napex.region(\"emp\").refresh();\r\n<\/code><\/pre>\n
Another supported API on the region interface is focus. You can give focus to an IG with the following:<\/p>\n
apex.region(\"regionStaticID\").focus();\r\n<\/code><\/pre>\n
At this time there isn’t a corresponding DA action (Set Focus works for items but not regions). <\/p>\n
Actions<\/h2>\n
The next easiest programmatic thing to do is invoke any of the menu or toolbar actions. In part 2 an example was given of defining an action and hooking it up to a toolbar button but little was said of what can be done with an action. (You should consult the doc comments in the libraries\/apex\/actions.js<\/code> file for full details on the apex.actions<\/code> API.) If you know the name of an action then you can run or execute the action with the invoke method. So the next logical question is “what are all the IG action names?” By now you probably know better than to ask where they are documented, right? <\/p>\n
The following code typed into the browser console window of an APEX page with an IG on it will print out a nice list of action names along with the label and for radio group actions the choice value.<\/p>\n
apex.region(\"emp\").widget().interactiveGrid(\"getActions\").list().forEach(function(a) { console.log(\"Action Label: \" + a.label + \", Name: \" + a.name + (a.choice !== undefined ? \", Choice: \" + a.choice : \"\") ); });\r\n<\/code><\/pre>\n
You should be able to match the action name with what it does by the label which matches the toolbar button label or tooltip or menu item label. In the case of a toggle action the menu item label may not include the word Toggle. In the case of radio group actions the label may be on the tooltip or on a sub-menu label.<\/p>\n
For example, the following code will open the IG Sort dialog just as if the user had clicked Actions menu, Data sub-menu and then Sort.<\/p>\n
apex.region(\"emp\").widget().interactiveGrid(\"getActions\").invoke(\"show-sort-dialog\");\r\n<\/code><\/pre>\n
The getActions<\/code> method of the interactiveGrid widget returns the apex.actions<\/code> context associated with the IG. Each IG has its own actions context. The action context is shared with all the sub widgets such as grid and recordView (Single Row View).<\/p>\n
There are 3 kinds of actions. The most obvious is just known as an action. These are generally associated with a button or menu item. It has an action<\/code> method which is a function that defines what it does when invoked. The above IG show-sort-dialog<\/code> action is an example.<\/p>\n
Toggle is another kind of action. These actions are generally associated with a checkbox, toggle button, toggle toolbar control, or toggle menu item. Rather than an action<\/code> method it has get<\/code> and set<\/code> methods that set or get a Boolean value. The IG action edit<\/code> is an example of a toggle action. To find out if the IG is currently in edit mode use this code:<\/p>\n
apex.region(\"emp\").widget().interactiveGrid(\"getActions\").get(\"edit\"); \/\/ returns true or false\r\n<\/code><\/pre>\n
To turn edit mode on:<\/p>\n
apex.region(\"emp\").widget().interactiveGrid(\"getActions\").set(\"edit\", true);\r\n<\/code><\/pre>\n
To turn edit mode off:<\/p>\n
apex.region(\"emp\").widget().interactiveGrid(\"getActions\").set(\"edit\", false);\r\n<\/code><\/pre>\n
The last kind of action is a radio group or choice action. It lets you select one value from a list of choices. These actions are generally associated with radio inputs, select lists, radio group menu items or radio group toolbar controls. These also have get<\/code> and set<\/code> methods. They also have an array of choices. The IG action change-view<\/code> is an example of a radio group action. To find out what view is currently selected use this code:<\/p>\n
apex.region(\"emp\").widget().interactiveGrid(\"getActions\").get(\"change-view\");\r\n<\/code><\/pre>\n
To change the current view to chart view (assuming it is defined) use this code:<\/p>\n
apex.region(\"emp\").widget().interactiveGrid(\"getActions\").set(\"change-view\", \"chart\");\r\n<\/code><\/pre>\n
To find out the available choices use this code and look through the returned array:<\/p>\n
apex.region(\"emp\").widget().interactiveGrid(\"getActions\").lookup(\"change-view\").choices\r\n<\/code><\/pre>\n
Another example is saving the current grid. For this you can use the save<\/code> action as follows:<\/p>\n
apex.region(\"emp\").widget().interactiveGrid(\"getActions\").invoke(\"save\");\r\n<\/code><\/pre>\n
This requires that the IG attribute Toolbar: Buttons Save is checked since it controls creation of both the button and the save<\/code> action. You could use toolbar customization to remove just the Save button. Currently there is no easy reliable way to detect when the save has completed.<\/del> [Update 5.1.1] If you need to do anything after the save is complete you can handle the save event. Events are covered in the next part of this series.<\/p>\n
All the above information about actions applies to actions you create and add to the IG context as described in part 2. The examples in part 2 created actions to be invoked but you can also create toggle or radio group actions by implementing the set and get methods and for radio groups also defining the choices.<\/p>\n
Widget Methods<\/h2>\n
If there isn’t a built-in IG action that does what you want there may be a way to accomplish it with JavaScript code calling methods on the various widgets<\/a> that make up IG. Many of the methods on the interactive grid widget itself are not very stable in 5.1. [Update 5.1.1] We have already seen all<\/del> many of the interactive grid widget methods that are useful right now. They are: getActions<\/code>, getViews<\/code>, getCurrentView<\/code> and getCurrentViewId<\/code>. [Update 5.1.1] Other IG widget methods are: resize<\/code>, refresh<\/code>, gotoCell<\/code>, getToolbar<\/code>, getSelectedRecords<\/code>, setSelectedRecords<\/code>, and focus<\/code>. Refer to doc comments in the libraries\/apex\/widget.interactiveGrid.js<\/code> source file for details on these.<\/p>\n
Each of the different views (grid, chart, icon, and detail) are implemented by a widget. You can drill down into the view widget by first getting at the IG view interface. Using code such as the following:<\/p>\n
apex.region(\"emp\").widget().interactiveGrid(\"getViews\", \"grid\");\r\n<\/code><\/pre>\n
Calling getViews<\/code> with no argument returns an object containing all the currently defined views. Each property is the id of a view and the value is the view interface. So the following is equivalent to the previous statement as long as the view exists.<\/p>\n
apex.region(\"emp\").widget().interactiveGrid(\"getViews\").grid;\r\n<\/code><\/pre>\n
You should make sure the view exists before trying to use it. You can use the getCurrentViewId<\/code> to get the id (internalIdentifier<\/code>) of the current view. [Update 5.1.1] You can use getCurrentView<\/code> to get the current view. This is shorter than getting the current view id and passing it in to the getViews<\/code> method.<\/p>\n
The view interface has these useful properties:<\/p>\n