pegros / PEG_LIST

Set of configurable/actionable LWC list components for Salesforce Lightning UX
MIT License
20 stars 9 forks source link
lightning lwc salesforce

Logo   SFPEG LIST Components

Introduction

This package contains a set of LWC components primarily dedicated to the display of custom lists of information (related records, KPIs, messages, fields...). They are based on some common powerful features required to easily customise the end-user experience (context information merge, action framework, apex logic extension).

List View

These components were built as contributions/examples for former & ongoing Advisory assignments by Pierre-Emmanuel Gros, porting in LWC and optimising (for end-user performances and easier configuration mutualisation among page layouts) some components previously available in a former Aura component package (known as PEG Components not available on GitHub).

They heavily rely on standard Lightning framework features such as the Lightning Data Service (LDS) or the Lightning Message Service (LMS) and try to apply as much as possible the standard Salesforce Lightning Design System (SLDS). The goal was to make them appear as much as possible as standard native Salesforce platform components while overriding usual limitations of the standard platform.

Communities (Experience Cloud) are now supported and requires the Object API Name and the Record ID to be explicitly set when configuring the components within Experience Cloud pages.

They are not available for Flow Designer but another package with components explicitly dedicated to these use cases is available (see PEG_FLW package).

As much attention as possible has been paid to internationalisation requirements (at least languages), leveraging standard mechanisms to translate labels, field names, picklist values...

Package Documentation

This readme document provides an overview of the different elements available in the package as well as some general configuration guidelines and technical implementation principles.

As LWC does not provide embedded documentation for the components, this readme file provides links to component dedicated sub-pages providing detailed information about their configurations and various implementation examples. This applies to the different App Builder components, but some more technical ones are also described (e.g. merge utility). Direct links to these component help pages are also available in the component footers when activating debug mode.

For the few Aura components, you may have a look at their standard .auradoc and for Apex classes a @ApexDoc like approach (with @description... tags) has been used.

Most components may also be embedded in other custom LWC components but these use cases are currently not documented for the time being. You may however look at the source code to see how to reuse some of them (main action bar component, or display or utility ones) or reach out to the author for more informations.

Package Availability

The package is freely available for use under the MIT license from this GiHub repository. Periodic upgrades will be posted depending on fixes/evolutions implemented as part of assignments & personal interactions.

For now, all commits are made exclusively by the author but you may push Pull Requests that may then be then merged after review.

Package Installation

Two options are available to deploy the package on your Org.

⚠️ Beware when deploying new versions of the package on an Org where it is already installed (whatever the option used) ! If you have already customized on your Org the custom labels or static resources included in the package, you may need to retrieve first a copy of their current situations before the new package version deployment and redeploy them afterwards.

Git Deployment

To retrieve the SFDX project, you may simply execute a git clone from the GitHub repository.

git clone git@github.com:pegros/PEG_LIST.git

Via SFDX you may then deploy it on you Org

sfdx force:source:deploy -u <yourOrgAlias> -w 10 --verbose -p force-app

Quick Direct Deploy

For a quick and easy deployment, you may alternatively use the following deploy button leveraging the GitHub Salesforce Deploy Tool implemented by Andrew Fawcett.

To deploy only the whole package to your Org, you may use the following button.

<img alt="Deploy Package to Salesforce" src="https://raw.githubusercontent.com/afawcett/githubsfdeploy/master/deploy.png">

Usage Prerequisite

Please assign to your users the sfpegListUsage permission set provided in the package!

Otherwise component initialisations and data fetches will systematically fail as users will be denied any execution of Apex controller logic.


Package Overview

The PEG_LIST package provides a whole set of LWC components for the App Builder, as well as some Aura ones. They are summarized hereafter by use case with links to their dedicated description pages.

All these components rely on various configuration custom metadata also included in the package, the detail of which is provided here. They also heavily reuse two powerful features:

App Builder Components

A main set of LWC components is available for use in Lightning App Builder:

Utility Bar Components

Some additional components are available for use in the Lightning Utility bar

Addressable Aura Components

There is a single Aura Addressable component available for use in navigation actions:

Component Configuration

Configuration is done at 2 levels:

Such an approach enables to easily reuse the same detailed configuration in multiple Lightning page layouts and enables a more efficient local configuration caching (for better performances).

The following example illustrate the configuration of the sfpegListCmp component in the App Builder, referencing 2 custom metadata records (orange zones) respectively for the data fetch/display configuration and for the header actions.

App Builder Config

*Beware to add yourself (and all users accessing the components) the proper sfpegListUsage permission set in order to access all the underlying Apex controller classes.

Configuration Contextualisation

In the main property of most metadata records, context merge tokens may be used to dynamically set some values based on the applicable record(s) and user. See the sfpegMergeUtl for more details about the applicable syntax and all the possible tokens.

Configuration Scoping

All custom metadata objects include a Scope property to define the pages for which the configuration record is applicable, i.e. a set of space separated strings

This value is then taken into account by the Datasource Apex controllers to let the users only choose the appropriate records when cconfiguring a component in the App Builder.

Setting a Scope is optional, e.g. for sfpegAction__mdt records used as row actions of other component metadata records (e.g. sfpegList__mdt).

Note: for Communities (Experience Cloud), the GLOBAL scope is mandatory for now, the scope not being properly evaluated when rendering a record page (KNOWN ISSUE).

Debug Mode Activation

All App Builder components include Debug xxx ? properties to enable to display some configuration information within the component (usually in its wrapping card footer) and activate debug logs within the browser console.

On server side, all controllers have Apex debug logs implemented at various levels (error, warning, debug, fine...).


Technical Details

Hereafter are provided various technical details about the way the components have been implemented, which may help better understand their behaviours.

Aura vs LWC

Most of the logic is implemented in LWC components.

However, in order to be able to leverage some interesting APIs or components not yet available in LWC (workspaceAPI, overlayApi, utilityBarApi, flow...) or some behaviours not supported by LWC (dynamic component instantiation via $A.createComponent()), some logic still had to be implemented in the legacy Aura technology for various action types.

All this custom Aura logic has been centralised in the sfpegActionUtilityCmp component and its supporting sfpegFlowDsp component.

Local Initialisation Cache of Configuration

In order to optimise initialisation time of the different components, a 2 stage approach has been used:

This approach enables to dramatically reduce initialisation times when the same configuration is used in multiple pages. E.g. when opening Account pages

Lightning Data Service vs DMLs

Lightning Data Service (via @wire methods or lightning-record-form components) is heavily used in the components to execute actions or fetch/display record data.

Lightning Message Service Based Communication

In order to integrate the action framework with custom LWC components, the Lightning Message Service has been leveraged to support bi-directional communication between components in this package and custom external logic. This mechanism relies on a set of message channels for inbound / outbound communication with the package components.

This mechanism is also used internally to communicate from a tab component to the utility sfpegActionHandlerCmp component via utility actions and may be used e.g. to propagate refresh requests to multiple sfpegListCmp components in a tab after an update action via notify actions.

Apex Extensibility

In order to extend the standard capabilities made available in the package, an extension framework (via virtual classes and forname() class instantiation) has been implemented to let developers implement and integrate additional custom Apex logic.

This applies to the following features:

Community Usage

For component usage in Communities (Experience Cloud), 2 additional properties are displayed at the bottom of the component configuration panel in the Experience Builder:

Note: The {!objectApiName} value seems to be sometimes not valued when initializing the components. In order to mitigate such issues, and if possible, a fixed test value (e.g. Account)is then preferrable.