Skip to content

Files

Latest commit

6666e5f · May 23, 2024

History

History
executable file
·
354 lines (287 loc) · 13.5 KB

sfpegActionUtilityCmp.md

File metadata and controls

executable file
·
354 lines (287 loc) · 13.5 KB

Logo   sfpegActionUtilityCmp component

Introduction

The sfpegActionUtilityCmp component is an Aura wrapper of the sfpegActionHandlerCmp utility bar component to handle a few additional actions & utility bar specific behaviours currently not possible in LWC : automatic closing of the utility upon action Trigger, console tab operations (close all tabs, close tab and open another one...), custom/flow popup open...

Action utility!

This Aura component is a Lightning component to be used as an utility item within a Lightning App configuration. It enables to display an action menu (based on the sfpegActionHandlerCmp component) and handle a whole series of Aura specific action types not supported by the LWC framework.

Multiple additional action types are indeed implemented based on various standard Aura APIs:

  • workspace API for console specific actions:
    • openTab to close the current tab and open a new one
    • closeTabs to force the closing of all (or all but current) tabs not pinned
    • refreshTab to refresh the content of the current tab
  • Overlay Library for custom action modal popups:
    • openPopup to open a custom Aura component in a Popup
    • openFlow to open a Flow in a custom popup
  • utilityBar API for utility bar specific actions
    • minimize to close the sfpegActionUtilityCmp component utility bar popup
  • $A namespace for Aura specific actions
    • fireEvent to trigger an Aura Application Event

They may be invoked directly from the sfpegActionUtilityCmp component menu or called from any action bar (sfpegActionBarCmp component) within a tab leveraging the utility action type (to forward the action to the utility bar component, see sfpegActionHandlerCmp for details).


Component Configuration

Its configuration is identical to the sfpegActionHandlerCmp one.

Beware to opt for automatic component launch in the App Builder (Start automatically checkbox in the component utility bar configuration), in order to properly handle utility actions triggered from the pages.


Specific Action Types

Compared to the sfpegActionHandlerCmp LWC component, this Aura component supports an additional set action types presented hereafter.

openPopup Action Type

The openPopup action type provides dynamic Aura component instantiation within a popup managed via the Overlay Library.

From a sfpegActionBarCmp component, the following action configuration enables to open a custom TST_Component Aura component in a Popup.

{
    "name": "Component", "label":"Component",
    "action": {
        "type": "utility",
        "params": {
            "type": "openPopup",
            "params": {
                "name": "c:TST_Component",
                "params":{"recordId":"{{{GEN.recordId}}}"},
                "header":"Test Popup Header",
                "doRefresh":true
            }
        }
    }
}

Note: LWC dynamic instantiation is (currently?) not supported and this acction type only works with Aura ones!

openFlow Action Type

The openFlow action type enables to launch a Lightning Flow within a popup (instead of a tab) leveraging the standard lightning:flow component and the Overlay Library.

From a sfpegActionBarCmp component, the following row action configuration enables to launch a flow called TEST_TST_Flow in a Popup (and refresh the content of the originating sfpegListCmp once the flow completes, leveraging a notify action type within a next property).

{
    "name": "Flow", "label":"Flow",
    "action": {
        "type": "utility",
        "params": {
            "type": "openFlow",
            "params": {
                "name":"TEST_TST_Flow",
                "params":[{"name" : "recordId", "type" : "String", "value" : "{{{ROW.Id}}}"}],
                "header":"Test Flow Header",
                "doRefresh":false,
                "class": "slds-modal slds-fade-in-open slds-slide-down-cancel slds-modal_large",
                "next": {
                    "type": "notify",
                    "channel": "RefreshList",
                    "params": {
                        "type": "done",
                        "params": { "type": "refresh" }
                    }
                }
            }
        }
    }
}

Note: For the notify action to work properly, the Notification Channel of the sfpegAction row action configuration used in the originating sfpegListCmp should be set to include the RefreshList channel used here.

openFlow Action Type for Mass operations

The openFlow Action Type may be also used as a mass action when triggered from the header actions of the sfpegListCmp (first via a utility notification action), in which case information about the the selected items may be fed as input to the Flow.

This is done via an additional selection property enabling to transform the selection list into a list input parameter of the Flow. This parameter is then added to the set of inputs specified by the params property.

Two options are basically available:

  • extracting a single field of each selected item and populating a simple String list input property for the Flow; in the example below, the Id of each selected items are provided for the selectedIDs String multi-value Flow input variable.
{
    "name": "Flow1","label": "Launch Flow1",
    "action": {
        "type": "utility",
        "params": {
            "type": "openFlow",
            "params": {
                "name": "TEST_Flow1",
                "params": [{"name": "recordId","type": "String","value": "{{{GEN.userId}}}"}],
                "selection": {"name": "selectedIDs","type": "String","field": "Id"},
                "header": "Test Flow1 Header",
                "doRefresh": false,
                "class": "slds-modal slds-fade-in-open slds-slide-down-cancel slds-modal_large",
                "next": {
                    "type": "notify","channel": "RefreshList",
                    "params": {"type": "done","params": {"type": "refresh"}}
                }
            }
        }
    }
}
  • building JSON objects with a set of fields for each selected item and populating an Apex class list input property for the Flow; in the example below, the Id and Name of each selected items are provided for the selectedRecords Apex class multi-value Flow input variable.
{
    "name": "Flow2","label": "Launch Flow2",
    "action": {
        "type": "utility",
        "params": {
            "type": "openFlow",
            "params": {
                "name": "TEST_Flow2",
                "params": [{"name": "recordId","type": "String","value": "{{{GEN.userId}}}"}],
                "selection": {"name": "selectedRecords","type": "String","fields": ["Id","Name"]},
                "header": "Test Flow2 Header",
                "doRefresh": false,
                "class": "slds-modal slds-fade-in-open slds-slide-down-cancel slds-modal_large",
                "next": {
                    "type": "notify","channel": "RefreshList",
                    "params": {"type": "done","params": {"type": "refresh"}}
                }
            }
        }
    }
}

In this example, this requires the definition of a custom Flow visible Apex class to define the selectedRecords variable in the Flow, e.g. as

public with sharing class sfpegTestClass {
 
    @AuraEnabled
    public String Id;
 
    @AuraEnabled
    public String Name;
}

closeTabs Action Type

The closeTabs action type enables to launch a Lightning Flow within a popup (instead of a tab) leveraging the standard workspace API.

This is a typical utility bar menu action, two options being available:

  • closing all tabs
  • closing all but the current active one. In any case, pinned tabs are ignored and never closed.

From a sfpegActionUtilityCmp component, the following action configuration provides the two options.

{
    "label":"Close Tabs", "name":"closeAllTabs",
    "action":{
        "type":"closeTabs",
        "params":{
            "closeAll":true
        }
    },
    "next":{
        "type":"minimize"
    }
},
{
    "label":"Close All other tabs", "name":"closeAllTabsButCurrent",
    "action":{
        "type":"closeTabs",
        "params":{
            "closeAll":false
        }
    },
    "next":{
        "type":"minimize"
    }
}

Note: In this example, the minimize action type is also used to automatically close the utility bar menu once the closeTabs action is triggered.

openTab Action Type

The openTab action type enables to open a target page / record according to the utility configuration and possibly automatically close the origin tab.

It relies on the workspace API to determine if the current appliccation is in console mode and execute the various tab navigation and tab management operations.

TO BE COMPLETED

refreshTab Action Type

The refreshTab action type is mostly used as a next property of another action type to trigger a refresh of the current tab upon action completion.

Depending on the application mode (console or standard), it leverages different technical solutions to do it:

  • via a simple $A.get('e.force:refreshView').fire() statement when in standard mode
  • via the refreshTab() method of the workspace API when in console mode.
    ...
    "next": {
        "type": "refreshTab"
    }
    ...

minimize Action Type

The minimize action type is mostly used as a next property of another action type to automatically close the utility bar menu of the sfpegActionUtilityCmp component once this action has been triggered.

It leverages the utilityBar API to execute the action.

    ...
    "next": {
        "type": "minimize"
    }
    ...

Note: please see the closeTabs action type for a more complete example.

fireEvent Action Type

The fireEvent action type enables to trigger any standard or custom Aura Application Event (e.g. when navigation actions are not enough).

It simply executes a standard $A.get(xxx).fire() statement to trigger the event of the specified type with the provided params.

From a sfpegListCmp component displaying a list of files, the following row action configuration enables to fire a standard Lightning openFile event.

{
    "name":"preview", "label":"Preview",
    "iconName":"utility:preview",
    "action": {
        "type":"utility",
        "params": {
            "type": "fireEvent",
            "params": {
                "type":"e.lightning:openFiles",
                "params":{
                    "recordIds": ["{{{ROW.ContentDocumentId}}}"]
                }
            }
        }
    }
}

Note: this is especially useful in communities, as the file preview is (still) not supported by the LWC navigation service in such a case.


Configuration Examples

Popup with Notification back to original Component

TO BE CONTINUED


Technical Details

The sfpegActionUtilityCmp component is a pure Aura wrapper of the LWC sfpegActionHandlerCmp utility bar component and simply implements a set of Aura specific action types. All its configuration is done in the child sfpegActionHandlerCmp component.

The specific action type names are known from child sfpegActionHandlerCmp component, which automatically pushes them to its parent component via a done event.

Most of these specific action types support next properties which may be executed by the child sfpegActionHandlerCmp component.

Even if initially meant for the utility bar, the sfpegActionUtilityCmp Aura component may be also used in the footer of a community template to provide the same features in this technical context.