Configurazione dei componenti di una colonna in un modello di griglia di immissione regalo nell'istruzione

Componenti visualizzazione cella

Per impostazione predefinita, il componente colonna Designazioni visualizza un valore vuoto. Se alla riga Ingresso regalo è associata una designazione, il componente colonna concatena l'ammontare a quella designazione e lo visualizza nella griglia, ad esempio 100 $. Se sono presenti due o più designazioni, la griglia mostra un valore riepilogato, ad esempio 2 Designazioni.

I componenti Cell Display hanno i seguenti requisiti:

• Valore tagName nel file JavaScriptjs.
• @api params che funge da proprietà in entrata passata dalla griglia.

In questo esempio, il componente visualizzato mostra una colonna Codice a barre. Prima di essere immessi, i dati vengono visualizzati come in sospeso. Quando il sistema trova un valore corrispondente, la colonna si aggiorna per visualizzare il nome del donatore.

giftEntryGridBarCodeDisplayColumn.html

<template>
    <p>{columnDisplayValue}</p>
</template>

giftEntryGridBarCodeDisplayColumn.js

import { api, LightningElement } from 'lwc';

export default class GiftEntryGridBarCodeDisplayColumn extends LightningElement {
    /**
     * params is the only inbound property passed to this component from Gift Entry Grid
     */
    @api params;

    /**
     * Example Method:
     * This getter function displays various fields in a display component
     * that is specified in the yaml file configuration.
     * @returns {*|string}
     */
    get columnDisplayValue() {
        let response = this.params?.data?.properties?.barCodeValue;
        if (this.params?.data?.LastName) {
            response = this.params?.data?.FirstName + " " + this.params?.data?.LastName;
            if (this.params?.data?.Salutation) {
                response = this.params?.data?.Salutation + " " + response;
            }
        }
        return response || '(pending)';
    }
}
// Tagname is required for the component to function
GiftEntryGridBarCodeDisplayColumn.tagName = 'c-gift-entry-grid-bar-code-display-column';

Componenti Modifica cella

Nel modello predefinito, il componente di modifica per la colonna Designazioni ha un campo di input Lightning che funziona in modo simile a un campo di ricerca. Quando l'utente immette un valore, il sistema cerca un valore corrispondente in un oggetto Codice a barre personalizzato. Se viene trovata una corrispondenza, i valori di quel record compilano le altre colonne nella griglia delle voci regalo.

I componenti Modifica cella hanno i seguenti requisiti:

• Un parametro tagName nel file JavaScript.
• Un parametro isPopup nel file JavaScript impostato su true.
• Utilizzo di un canale Lightning Message Service della griglia di immissione regalo da @salesforce/messageChannel/lightning__giftEntryGridComponentAction.
• Altri metodi e variabili come indicato nell'esempio seguente.

giftEntryGridBarCodeColumnComponent.html

<template>
    <lightning-input
        label="Bar Code"
        name="barCode"
        value={barCode}
        onblur={handleBarCodeChanged}
        onerror={handleError}
        placeholder="Scan bar code here"
        variant="label-hidden">
    </lightning-input>
</template>

giftEntryGridBarCodeColumnComponent.js

import { LightningElement, api } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';

/**
 * Apex controller used by this example to handle data queries, etc.
 */
import getBarCodeScanData from '@salesforce/apex/GiftEntryBarCodeScanLookupController.getBarCodeScanData';

/**
 * Lightning Message Service to enable this component to communicate back to Gift Entry Grid
 */
import { publish, createMessageContext } from 'lightning/messageService';
import GiftEntryGridComponentAction from "@salesforce/messageChannel/lightning__giftEntryGridComponentAction";
const messageContext = createMessageContext();


const DEFAULT_GIFT_AMOUNT = 100.00;
const DEFAULT_PAYMENT_METHOD = "Credit Card";

export default class GiftEntryGridBarCodeColumnComponent extends LightningElement {

    /**
     * Required for the underlying grid component to properly render this as a gift entry grid cell
     */
    static delegatesFocus = true;

    /**
     * The data entry property used in this example
     */
    @api barCode = "";

    /**
     * The column definition as defined within the underlying grid component
     * Set from data in params in the connectedCallback.
     */
    _columnDefinition;

    /**
     * Contains properties that represent each field on the GiftEntry record/row within the grid. 
     * Set from data in params in the connectedCallback.
     */
    _rowData = {};

    /**
     * _params is the only inbound property passed to this component from Gift Entry Grid
     * The properties retrieved in the example below are the primary ones required for grid functionality
     */
    _params;
    @api
    get params() {
        return this._params;
    }
    set params(value) {
        this._params = value;
        this._rowData = this._params?.data;
        this._columnDefinition = this._params?.colDef;
        const _headerLabel = this._columnDefinition?.headerName; // informational

        // Useful mechanism to pull in the previously entered barcode as the default value
        // Values in the `properties` object of the row are transient for the current session only. They persist until the page is closed/refreshed
        if (this._rowData && this._rowData?.properties?.barCode) {
            this.barCode = this._rowData?.properties?.barCode;
        }
    }

    /**
     * Recommended Method: Ensures the column width is set properly on load
     */
    connectedCallback() {
        this.template.host.style.setProperty('--min-width', this._params?.column?.actualWidth + 'px');
    }

    /**
     * Example Method:
     * Handle a change to the entered bar code in the field
     * @param {*} event 
     */
    handleBarCodeChanged(event) {
        event.stopPropagation();

        try {
            if (event.target?.value && event.target?.value !== "") {
                this.sendDataBackToGrid(event.target.value);
            } else if (event.target?.value === "") {
                this.clearCurrentRowOfAllData();
            }
        } catch (e) {
            this.dispatchEvent(
                new ShowToastEvent({
                    title: 'Error',
                    message: 'An error occurred while querying the entered barcode: ' + (e.body?.message || e.message),
                    variant: 'error'
                })
            );
        }
        this.applyFocus();
    }

    /**
     * Example Method:
     * Call the apex controller with the entered bar code
     * Parse the response and pass that data back to GiftEntryGrid using the Lightning Message Service channel
     * @param {*} barCode 
     */
    async sendDataBackToGrid(barCode) {
        // Call the Apex controller to query and retrieve data
        const result = await getBarCodeScanData({ barcodeValue: barCode });
        if (result && result !== null) {

            // Convert the query result from the apex controller into an object of GiftEntry fields to apply to the row in the grid
            const giftEntryFields = this.buildResponse(result);
    
            // Build the "message" obhect to send back to Gift Entry Grid following the documented contract
            const message = {
                action: "ColumnEdit",                       // Required property
                componentName: this.tagName,                // Required property (use as is)
                colId: this._columnDefinition.colId,        // Required property (use as is)
                details: {                                  // Optional property - include if there is data to write to the row in Gift Entry
                    rowId: this.params?.data?.id,           // Required (use as is)
                    rowIndex: this.params?.data?.rowIndex,  // Required (use as is)
                    giftEntryFields,                        // Required - all GiftEntry fields to write to rowData
                    rowProperties: {                        // Optional - use this to persist values in memory in the grid for use elsewhere, such as the Display Component
                        barCode,                                // Example: Used to persist the value of the barcode on the row temporarily to retrieve elsewhere
                        barCodeValue: result.donorName  // Example: This is used by GiftEntryGridColumnDisplay
                    },
                    matchingGiftTransactionId: result?.matchingGiftTransactionId,         // Optional, to set a matching gift on the row
                    matchingGiftTransactionName: result?.matchingGiftTransactionName      // Optional, to set a matching gift on the row
                }
            }
            publish(messageContext, GiftEntryGridComponentAction, message);
        }
    }

    /**
     * Example Method:
     * Clear out the entire row if the barCode is set to null
     */
    clearCurrentRowOfAllData() {

        const giftEntryFields = {
            DonorId: null,
            Donor: null,
            GiftType: "Individual"
        };
        if (this.params && this.params.data) {
            const keepKeys = ['id', 'Id', 'rowId', 'rowIndex', 'properties', 'GiftType'];
            Object.keys(this.params.data).forEach(key => {
                if (!keepKeys.includes(key)) {
                    giftEntryFields[key] = null;
                }
            });
        }

        const message = {
            action: "ColumnEdit",                       // Required property
            componentName: this.tagName,                // Required property (use as is)
            colId: this._columnDefinition.colId,        // Required property (use as is)
            details: {                                  // Optional property - include if there is data to write to the row in Gift Entry
                rowId: this.params?.data?.id,           // Required (use as is)
                rowIndex: this.params?.data?.rowIndex,  // Required (use as is)
                giftEntryFields,
                rowProperties: {
                    barCode : null,
                    barCodeValue: null
                }
            }
        };     
        publish(messageContext, GiftEntryGridComponentAction, message);
    }

    /**
     * Example Method:
     * 
     * Notes
     * - Lookup fields such as Campaign and OutreachSourceCode should be represented as an object with "id" and "name" to allow them
     *   render properly in the grid. This does not apply to DonorId
     * - Pick List fields, such as PaymentMethod, can a string representing the pick list API Name or an object as {apiName: x, value: y}
     * - To take advantage of Gift Entry Grid's built in Donor logic that retrieves all donor fields, including custom mapped fields, the
     *   response object should include a property for DonorId and GiftType ("Individual" or "Organizational" only)
     * - Any field on GiftEntry can be included in this resonse and it will populate fields on the grid
     * @param {*} result from call to Apex with query results
     * @returns an object that represents fields on the GiftEntry object to be updated on the GiftEntryGrid row
     */
    buildResponse(result) {
        const response = {
            GiftType: result.giftType,  // Required to use the built-in donor logic
            DonorId: result.donorid,    // Required to use the built-in donor logic

            // Examples(s) Populate other fields on the row 
            GiftReceivedDate: new Date().toISOString().split('T')[0],
            PaymentMethod: DEFAULT_PAYMENT_METHOD,
            GiftAmount: DEFAULT_GIFT_AMOUNT,

            CampaignId: result.campaign,
            Campaign: {
                id: result.campaign,
                Name: result.campaignName
            },

            OutreachSourceCodeId: result.outreachSourceCode,
            OutreachSourceCode: {
                id: result.outreachSourceCode,
                Name: result.outreachSourceCodeName
            }
        };

        return response;
    }


    /**
     * For keyboard accessibility, allows the lookup component to be focused on keyboard tabbing
     */
    applyFocus() {
        const _gridElement = this.template.querySelector('lightning-input');
        return new Promise((resolve) => {
            Promise.resolve().then(() => {
                _gridElement.focus();
                resolve();
            });
        });
    }

    /**
     * Example Method
     */
    handleError(event) {
        event.stopPropagation();
    }
}
// Required Properties for Column Components:
GiftEntryGridBarCodeColumnComponent.tagName = 'c-gift-entry-grid-bar-code-column-component';
GiftEntryGridBarCodeColumnComponent.isPopup = true;

Esecuzione di query e trasmissione di dati

Utilizzare questo Apex Code per eseguire query e passare i dati al componente personalizzato Griglia immissione regalo.

GiftEntryGridBarCodeScannerLookupController.apex

/**
 * Salesforce Fundraising - Gift Entry Grid Custom Component Example
 * 
 * Controller class for handling barcode scan data lookup from a column component
 */
public with sharing class GiftEntryBarCodeScanLookupController {
    
    /**
     * Wrapper class to return the selected donor and any other info that would be applied to the grid row
     */
    public class ReponseObject {
        @AuraEnabled public String barCode { get; set; }
        @AuraEnabled public String giftType { get; set; }
        @AuraEnabled public String donorid { get; set; }
        @AuraEnabled public String donorName { get; set; }
        @AuraEnabled public String campaign { get; set; }
        @AuraEnabled public String campaignName { get; set; }
        @AuraEnabled public String giftDesignation { get; set; }
        @AuraEnabled public String giftDesignationName { get; set; }
        @AuraEnabled public String outreachSourceCode { get; set; }
        @AuraEnabled public String outreachSourceCodeName { get; set; }
        @AuraEnabled public String matchingGiftTransactionId { get; set; }
        @AuraEnabled public String matchingGiftTransactionName { get; set; }
        @AuraEnabled public Double amount { get; set; }
    }
    
    /**
     * Retrieves barcode scan data based on the provided barcode value
     * @param barcodeValue The barcode value to search for
     * @return ReponseObject object with all fields or null if not found
     */
    @AuraEnabled(cacheable=false)
    public static ReponseObject getBarCodeScanData(String barcodeValue) {        

        try {
            if (String.isBlank(barcodeValue)) {
                return null;
            }
            
            // Query the BarCodeScanData__c object for the matching barcode
            // Include related fields from Donor (Account), Campaign, and Outreach Source Code
            List<BarCodeScanData__c> results = [
                SELECT Id, 
                       BarCode__c,
                       Donor__c,
                       Donor__r.Name,
                       Donor__r.IsPersonAccount,
                       Campaign__c,
                       Campaign__r.Name,
                       OutreachSourceCode__c,
                       OutreachSourceCode__r.Name
                FROM BarCodeScanData__c 
                WHERE BarCode__c = :barcodeValue 
                LIMIT 1
            ];

            if (results.isEmpty()) {
                return null;
            }

            BarCodeScanData__c barCodeRecord = results[0];
            ReponseObject response = new ReponseObject();
            
            // a value for DonorId and GiftType required for the donor logic to work
            response.donorid = barCodeRecord.Donor__c; 
            response.giftType = (barCodeRecord.Donor__r.IsPersonAccount ? 'Individual' : 'Organizational');

            // Extra fields used within this example component
            response.barCode = barCodeRecord.BarCode__c;
            response.donorName = barCodeRecord.Donor__r?.Name;
            response.campaign = barCodeRecord.Campaign__c;
            response.campaignName = barCodeRecord.Campaign__r?.Name;
            response.outreachSourceCode = barCodeRecord.OutreachSourceCode__c;
            response.outreachSourceCodeName = barCodeRecord.OutreachSourceCode__r?.Name;                

            // Is there an unpaid gift transaction installment for a commitment for this donor?
            // If so, populate the GiftTransactionId field to simulate selecting a matching gift
            List<GiftTransaction> matchingGifts = [
                SELECT Id, Name,
                    OriginalAmount, TransactionDueDate, 
                    CampaignId, Campaign.Name, 
                    OutreachSourceCodeId, OutreachSourceCode.Name,
                    GiftCommitmentId
                FROM GiftTransaction
                WHERE DonorId = :response.donorid
                    AND Status = 'Unpaid'
                ORDER BY TransactionDueDate ASC
                LIMIT 1
            ];
            if (matchingGifts.size() > 0) {
                response.matchingGiftTransactionId = matchingGifts[0].Id;
                response.matchingGiftTransactionName = matchingGifts[0].Name;
                response.amount = matchingGifts[0].OriginalAmount;
                response.campaign = matchingGifts[0].CampaignId;
                response.campaignName = matchingGifts[0].Campaign.Name;
                response.outreachSourceCode = matchingGifts[0].OutreachSourceCodeId;
                response.outreachSourceCodeName = matchingGifts[0].OutreachSourceCode.Name;   
            }

            return response;
            
        } catch (Exception e) {
            // Log the error and throw a user-friendly exception
            System.debug(LoggingLevel.ERROR, 'Error in getBarCodeScanData: ' + e.getMessage());
            throw new AuraHandledException('Error retrieving barcode scan data: ' + e.getMessage());
        }
    }
}