CME Data Grid Part 2- Actions

This is Part 2 of a series on using the CMEDataGrid. If you haven’t checked out Part 1 yet, you might want to do that first as it lays the foundation for displaying data in the grid. In this installment, we pick up where we left off and show you how to configure the grid to enable acting on the data.

If you want to work alongside the article, you can download the source code from the Consulting Maine GitHub repository. The Demo app is included in the repository in case you run into trouble or just want to step through the working code [ConsultingME/CMEDataGrid].

There are 3 built-in column types that render an interface to take action on a row of data:

ActionGroup

Let’s imagine you need to allow your users to approve or deny the opportunities displayed in your grid. We can render a green check for the approval action, and, just to show the option, the text “Deny” for the denial action. Add the following code to your columns array:

You’ll notice the ActionList property is an array containing an object for each action. If you don’t include an IconName property in the Action object, the output will be an HTML button. Check the documentation available on GitHub for the full list of available properties for an Action object.

We’ll also need to implement the CSS for the “green” style so add the following to the Demo style file:

When you reload your demo app, you should see the following:

Data grid with ActionGroup

ActionMenu

Now let’s imagine your users may need to take additional actions on these opportunities. Maybe they need to Clone, Follow, or Change Owner. Let’s add those actions to an ActionMenu. Add the following code to your columns array to create an Actions column:

Now you should see the new Actions column:

Data grid with the action menu

You can also create an ActionText column which just renders as a hyperlink but with all these fancy options, why would you want to?!

Handling Grid Actions

So now that you have all these fancy action triggers, you’re probably wondering how to hook into them so you can actually DO something! All of the grid actions fire the same event, so it’s as easy as creating an event handler for the CMEDataGridActionFired event. Just add the following markup to your demo component:

Now whenever any action is triggered, your onGridAction controller method will be executed. The event has two parameters:

So now let’s add some code to the controller to pop up an alert with the Action and the Name field from the SelectedRow:

In a real-world implementation, you’d probably want to switch (params.Action) and call the different helper methods that implement your action functionality.

Action Validation

“But wait,” you say! “I only want them to be able to approve an opportunity if the total value is under $100.” Ok, no problem. We’ll add a DisabledValidator to the Approve action. A DisabledValidator is a function that gets executed for each row. The function will be passed the row of data and must return an object with two properties:

So let’s write the function that will determine whether the Approve action should be disabled for each row. Add the following to your demo component helper:

Then update the action in the ActionGroup with a DisabledValidator property:

Data grid with mouseover validation

Selecting Rows

If the built-in Action types don’t support your UI design or if you need to act on multiple rows, the grid has a “selectedrows” attribute you can use. To enable it just set the selectAll attribute on the grid. Let’s also add a button to our demo component to simulate your custom action:

The default is to allow multiple rows to be selected but you can disable that by setting the multiSelect attribute to false.

For now, we’ll just have our controller action log the selectedrows to the browser developer tools console:

Selection Validation

But wait, you have multiple custom actions and each action has unique logic to validate whether it can be taken on a specific row, don’t you? OK, no problem. The grid exposes a method called updateSelectable() that is used to enable/disable the select boxes. Just pass in a list of objects with the following schema:

The first thing we need to do is tell the grid which property in our dataset is the primary key of the rows. In our case, we have a field called Id with a unique identifier per row. Add the primaryKey attribute to the data grid markup:

Now let’s add a dropdown with a couple of actions users can take. Add this markup between the grid and the Fire Custom Action button we added above:

Let’s set the width of the dropdown so it doesn’t stretch across the entire screen. Add the following css to your style file:

Now we need to implement the custom validation logic. If the user selects the “Act on Approved Rows” option, we need to disable all the rows that are not approved. Similarly, if they choose the “Archive Incomplete Records” action, only incomplete records should be selectable. Here’s how we do it:

So what’s happening here? Based on which action is taken – the value of the lightning:select component – we’re creating a different function that evaluates the row and returns the object we need to pass to the updateSelectable() method. Then we run the map() method on our list of data, passing it the appropriate function. We then call updateSelectable() on the grid passing it our new selectable list.

When you select “Act on Approved Rows” you should see:

Data grid with validation

Conclusion

As you can see, the CMEDataGrid offers a few built-in options for acting on the data, including ActionGroup and ActionMenu. If those options don’t fit your situation you can always use the selection functionality with your own action interface.

Stay tuned for Part 3 in our series on User Interface options with the grid. We’ll talk about filtering, paging, and using facets to integrate the grid into your design.