Exempel på utveckling och användning av anpassade funktioner
- Gäller:
- Experience Manager as a Cloud Service
Skapat för:
- Nybörjare
- Mellanliggande
- Användare
- Utvecklare
Artikeln innehåller detaljerade exempel på anpassade funktioner för ett adaptivt formulär baserat på kärnkomponenter, och ger värdefulla insikter om hur de kan implementeras i olika scenarier. Anpassade funktioner används i regelredigeraren för en AEM Forms, vilket gör att utvecklare kan definiera och styra logiken som styr formulärbeteendet.
I den här artikeln beskrivs olika implementeringar av anpassade funktioner, och den visar hur de kan användas för att skräddarsy formulär för att uppfylla specifika krav och förbättra den övergripande funktionaliteten.
Fylla i alternativen i listrutan med anpassade funktioner
Regelredigeraren i kärnkomponenterna stöder inte egenskapen Set Options för att fylla i listrutealternativ dynamiskt vid körning. Du kan dock fylla i alternativ för listrutor med anpassade funktioner, som gör att du kan hämta alternativ baserat på en viss logik. Anpassade funktioner ger större flexibilitet och kontroll över hur och när listrutorna fylls i, vilket förbättrar användarupplevelsen.
Om du vill fylla i alternativen i listrutan med en anpassad funktion lägger du till följande kod enligt beskrivningen i avsnittet create-custom-function :
/**
* @name setEnums
* @returns {string[]}
**/
function setEnums() {
return ["0","1","2","3","4","5","6"];
}
/**
* @name setEnumNames
* @returns {string[]}
**/
function setEnumNames() {
return ["Sunday","Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
}
I ovanstående kod används setEnums för att ange egenskapen enum och setEnumNames används för att ange egenskapen enumNames för listrutan.
Låt oss skapa en regel för knappen Next, som anger värdet för alternativet för nedrullningsbar lista när användaren klickar på knappen Next:
Se bilden nedan för att visa var alternativen i listrutan ställs in när du klickar på knappen Visa:
Visa en panel med regeln SetProperty
Låt oss lära oss hur anpassade funktioner använder fält och globala objekt med hjälp av ett Contact Us-formulär.
Lägg till följande kod i den anpassade funktionen enligt beskrivningen i avsnittet create-custom-function för att ange formulärfältet som Required.
/**
* enablePanel
* @name enablePanel
* @param {object} field1
* @param {object} field2
* @param {scope} globals
*/
function enablePanel(field1,field2, globals)
{
if(globals.functions.validate(field1).length === 0)
{
globals.functions.setProperty(field2, {visible: true});
}
}
NOTE- Du kan konfigurera fältegenskaperna med hjälp av de tillgängliga egenskaperna i
[form-path]/jcr:content/guideContainer.model.json. - Ändringar som görs i formuläret med metoden
setPropertyför Global-objektet är asynkrona och återspeglas inte när den anpassade funktionen körs.
I det här exemplet valideras panelen personaldetails när du klickar på knappen. Om inga fel upptäcks på panelen visas en annan panel, feedback-panelen, när du klickar på knappen.
Låt oss skapa en regel för knappen Next som validerar panelen personaldetails och gör panelen feedback synlig när användaren klickar på knappen Next.
Se bilden nedan för att visa var panelen personaldetails valideras när du klickar på knappen Next. Om alla fält i personaldetails valideras blir panelen feedback synlig.
Om det finns fel i fälten på panelen personaldetails visas de på fältnivå när du klickar på knappen Next och panelen feedback visas inte.
Validera fältet
Låt oss lära oss hur anpassade funktioner använder fält och globala objekt för att validera fältet med hjälp av ett Contact Us-formulär.
Lägg till följande kod i den anpassade funktionen enligt anvisningarna i avsnittet create-custom-function för att validera fältet.
/**
* validateField
* @name validateField
* @param {object} field
* @param {scope} globals
*/
function validateField(field,globals)
{
globals.functions.validate(field);
}
validate() valideras formuläret.I det här exemplet används ett anpassat valideringsmönster för fältet contact. Användare måste ange ett telefonnummer som börjar med 10 följt av 8 siffror. Om användaren anger ett telefonnummer som inte börjar med 10 eller innehåller fler eller färre än 8 siffror visas ett valideringsfelmeddelande när knappen klickar:
Nästa steg är nu att skapa en regel för knappen Next som validerar fältet contact vid knappklicket.
Se bilden nedan för att visa att om användaren anger ett telefonnummer som inte börjar med 10 visas ett felmeddelande på fältnivå:
Om användaren anger ett giltigt telefonnummer och alla fält på panelen personaldetails valideras visas panelen feedback på skärmen:
Återställ en panel
Låt oss lära oss hur anpassade funktioner använder fält och globala objekt för att återställa fältet med hjälp av ett Contact Us-formulär.
Lägg till följande kod i den anpassade funktionen enligt anvisningarna i avsnittet create-custom-function för att återställa panelen.
/**
* resetField
* @name resetField
* @param {string} input1
* @param {object} field
* @param {scope} globals
*/
function resetField(field,globals)
{
globals.functions.reset(field);
}
reset() valideras formuläret.I det här exemplet återställs panelen personaldetails när du klickar på knappen Clear. Nästa steg är att skapa en regel för knappen Clear som återställer panelen när du klickar på knappen.
Se bilden nedan för att visa att panelen personaldetails återställs om användaren klickar på knappen clear:
Visa ett anpassat meddelande på fältnivå och markera fältet som ogiltigt
Låt oss lära oss hur anpassade funktioner använder fält och globala objekt för att visa ett anpassat meddelande på fältnivå och markera fältet som ogiltigt med hjälp av ett Contact Us-formulär.
Du kan använda funktionen markFieldAsInvalid() för att definiera ett fält som ogiltigt och ange ett anpassat felmeddelande på fältnivå. Värdet fieldIdentifier kan vara fieldId, field qualifiedName eller field dataRef. Värdet för objektet option kan vara {useId: true}, {useQualifiedName: true} eller {useDataRef: true}.
Syntaxerna som används för att markera ett fält som ogiltigt och ange ett anpassat meddelande är:
globals.functions.markFieldAsInvalid(field.$id,"[custom message]",{useId: true});globals.functions.markFieldAsInvalid(field.$qualifiedName, "[custom message]", {useQualifiedName: true});globals.functions.markFieldAsInvalid(field.$dataRef, "[custom message]", {useDataRef: true});
Lägg till följande kod i den anpassade funktionen enligt beskrivningen i avsnittet create-custom-function för att aktivera ett anpassat meddelande på fältnivå.
/**
* customMessage
* @name customMessage
* @param {object} field
* @param {scope} globals
*/
function customMessage(field, globals) {
const minLength = 15;
const comments = field.$value.trim();
if (comments.length < minLength) {
globals.functions.markFieldAsInvalid(field.$id, "Comments must be at least 15 characters long.", { useId: true });
}
}
I det här exemplet visas ett anpassat meddelande på fältnivå om användaren skriver färre än 15 tecken i textrutan för kommentarer.
Nästa steg är att skapa en regel för fältet comments:
Se demonstrationen nedan för att visa att om du anger negativ feedback i fältet comments utlöses visningen av ett anpassat meddelande på fältnivå:
Om användaren skriver in mer än 15 tecken i textrutan för kommentarer valideras fältet och formuläret skickas:
Skicka ändrade data till servern
Låt oss lära oss hur anpassade funktioner använder fält och globala objekt för att skicka manipulerade data på servern med hjälp av ett Contact Us-formulär.
Följande kodrad:globals.functions.submitForm(globals.functions.exportData(), false); används för att skicka formulärdata efter manipulering.
- Det första argumentet är de data som ska skickas.
- Det andra argumentet anger om formuläret ska valideras innan det skickas in. Det är
optionaloch inställt somtruesom standard. - Det tredje argumentet är
contentTypei överföringen, som också är valfritt med standardvärdet sommultipart/form-data. De andra värdena kan varaapplication/jsonochapplication/x-www-form-urlencoded.
Lägg till följande kod i den anpassade funktionen enligt beskrivningen i avsnittet create-custom-function för att skicka manipulerade data till servern:
/**
* submitData
* @name submitData
* @param {object} field
* @param {scope} globals
*/
function submitData(globals)
{
var data = globals.functions.exportData();
if(!data.comments) {
data.comments = 'NA';
}
console.log('After update:{}',data);
globals.functions.submitForm(data, false);
}
I det här exemplet skickas NA till servern när formuläret skickas om användaren lämnar textrutan comments tom.
Skapa nu en regel för knappen Submit som skickar data:
Titta på bilden för console window nedan för att visa att om användaren lämnar textrutan comments tom så skickas värdet som NA på servern:
Du kan även kontrollera konsolfönstret för att visa data som skickats till servern:
Åsidosätt formulärskickning och felhantering
Låt oss lära oss hur anpassade funktioner använder fält och globala objekt för att åsidosätta inskickningshanterare med hjälp av ett Contact Us-formulär.
Lägg till följande kodrad enligt anvisningarna i avsnittet create-custom-functions för att anpassa överförings- eller felmeddelandet för formulärinskickning och visa formulärinskickningsmeddelandena i en modal ruta:
/**
* Handles the success response after a form submission.
*
* @param {scope} globals - This object contains a read-only form instance, target field instance, triggered event, and methods for performing form modifications within custom functions.
* @returns {void}
*/
function customSubmitSuccessHandler(globals) {
var event = globals.event;
var submitSuccessResponse = event.payload.body;
var form = globals.form;
if (submitSuccessResponse) {
if (submitSuccessResponse.redirectUrl) {
window.location.href = encodeURI(submitSuccessResponse.redirectUrl);
} else if (submitSuccessResponse.thankYouMessage) {
showModal("success", submitSuccessResponse.thankYouMessage);
}
}
}
/**
* Handles the error response after a form submission.
*
* @param {string} customSubmitErrorMessage - The custom error message.
* @param {scope} globals - This object contains a read-only form instance, target field instance, triggered event, and methods for performing form modifications within custom functions.
* @returns {void}
*/
function customSubmitErrorHandler(customSubmitErrorMessage, globals) {
showModal("error", customSubmitErrorMessage);
}
function showModal(type, message) {
// Remove any existing modals
var existingModal = document.getElementById("modal");
if (existingModal) {
existingModal.remove();
}
// Create the modal dialog
var modal = document.createElement("div");
modal.setAttribute("id", "modal");
modal.setAttribute("class", "modal");
// Create the modal content
var modalContent = document.createElement("div");
modalContent.setAttribute("class", "modal-content");
// Create the modal header
var modalHeader = document.createElement("div");
modalHeader.setAttribute("class", "modal-header");
modalHeader.innerHTML = "<h2>" + (type === "success" ? "Thank You" : "Error") + "</h2>";
// Create the modal body
var modalBody = document.createElement("div");
modalBody.setAttribute("class", "modal-body");
modalBody.innerHTML = "<p class='" + type + "-message'>" + message + "</p>";
// Create the modal footer
var modalFooter = document.createElement("div");
modalFooter.setAttribute("class", "modal-footer");
// Create the close button
var closeButton = document.createElement("button");
closeButton.setAttribute("class", "close-button");
closeButton.innerHTML = "Close";
closeButton.onclick = function() {
modal.remove();
};
// Append the elements to the modal content
modalFooter.appendChild(closeButton);
modalContent.appendChild(modalHeader);
modalContent.appendChild(modalBody);
modalContent.appendChild(modalFooter);
// Append the modal content to the modal
modal.appendChild(modalContent);
// Append the modal to the document body
document.body.appendChild(modal);
}
I det här exemplet, när användaren använder de anpassade funktionerna customSubmitSuccessHandler och customSubmitErrorHandler, visas meddelanden om lyckade och misslyckade åtgärder i ett modalt format. JavaScript-funktionen showModal(type, message) används för att dynamiskt skapa och visa en modal dialogruta på en skärm.
Skapa nu en regel för att skicka in formulär:
Se bilden nedan för att visa att när formuläret har skickats visas meddelandet om att det lyckades visas i ett modalt format:
På samma sätt kan vi skapa en regel för misslyckade formulärinskickade formulär:
Se bilden nedan för att visa att felmeddelandet visas i ett modalt format när formuläröverföringen misslyckas:
Funktionerna Default submit Form Success Handler och Default submit Form Error Handler är tillgängliga i paketet om du vill visa om formuläret har skickats in eller misslyckats på ett standardsätt.
Om den anpassade överföringshanteraren inte fungerar som förväntat i befintliga AEM projekt eller formulär, se avsnittet felsökning.
Utför åtgärder i en specifik instans av den repeterbara panelen
Regler som skapas med den visuella regelredigeraren på en repeterbar panel tillämpas på den sista instansen av den repeterbara panelen. Om du vill skriva en regel för en viss instans av den repeterbara panelen kan vi använda en anpassad funktion.
Låt oss skapa ett annat formulär som Booking Form för att samla in information om resenärer som är på väg till en destination. En resande panel läggs till som en upprepningsbar panel, där användaren kan lägga till information för 5 resenärer med knappen Add Traveler.
Lägg till följande kodrad enligt beskrivningen i avsnittet create-custom-function för att utföra åtgärder i en specifik instans av den repeterbara panelen, förutom den sista:
/**
* @name hidePanelInRepeatablePanel
* @param {scope} globals
*/
function hidePanelInRepeatablePanel(globals)
{
var repeatablePanel = globals.form.travelerinfo;
// hides a panel inside second instance of repeatable panel
globals.functions.setProperty(repeatablePanel[1].traveler, {visible : false});
}
I det här exemplet utför den anpassade funktionen hidePanelInRepeatablePanel en åtgärd i en specifik instans av den repeterbara panelen. I ovanstående kod representerar travelerinfo den repeterbara panelen. Koden repeatablePanel[1].traveler, {visible: false} döljer panelen i den andra instansen av den repeterbara panelen.
Låt oss lägga till en knapp med etiketten Hide och lägga till en regel som döljer den andra instansen av en repeterbar panel.
Titta på videon nedan för att visa att panelen i den andra upprepningsbara instansen döljs när användaren klickar på Hide:
Fyll i fältet i förväg med ett värde när formuläret läses in
Låt oss lära oss hur anpassade funktioner använder fält och globala objekt för att förifylla fält med hjälp av en Booking Form.
Lägg till följande kodrad, enligt beskrivningen i avsnittet create-custom-function , för att läsa in det förfyllda värdet i ett fält när formuläret initieras:
/**
* Tests import data
* @name testImportData
* @param {scope} globals
*/
function testImportData(globals)
{
globals.functions.importData(Object.fromEntries([['amount','10000']]));
}
I ovanstående kod fyller funktionen testImportData i förväg i textrutefältet Booking Amount när formuläret läses in. Låt oss anta att bokningsformuläret kräver att det minsta bokningsbeloppet är 10,000.
Låt oss skapa en regel vid formulärinitiering, där värdet i textrutefältet Booking Amount är förifyllt med ett angivet värde när formuläret läses in:
Titta på skärmbilden nedan som visar att när formuläret läses in är värdet i textrutan Booking Amount förifyllt med ett angivet värde:
Sätt fokus på det specifika fältet
Låt oss lära oss hur anpassade funktioner använder fält och globala objekt för att sätta fokus på specifika fält med hjälp av en Booking Form.
Lägg till följande kodrad, enligt beskrivningen i avsnittet create-custom-function , för att ange fokus på det angivna fältet när användaren klickar på knappen Submit:
/**
* @name testSetFocus
* @param {object} emailField
* @param {scope} globals
*/
function testSetFocus(field, globals)
{
globals.functions.setFocus(field);
}
Låt oss lägga till en regel till knappen Submit för att ställa in fokus på fältet Email ID när någon klickar på det:
Titta på skärmbilden nedan som visar att när användaren klickar på knappen Submit ställs fokus in på fältet Email ID:
NOTE$focusOption om du vill fokusera på nästa eller föregående fält i förhållande till fältet email.Lägg till eller ta bort upprepningsbar panel med egenskapen dispatchEvent
Låt oss lära oss hur anpassade funktioner använder fält och globala objekt för att lägga till eller ta bort repeterbara paneler med egenskapen dispatchEvent med hjälp av en Booking Form.
Lägg till följande kodrad, enligt beskrivningen i avsnittet create-custom-function , för att lägga till en panel när användaren klickar på knappen Add Traveler med egenskapen dispatchEvent :
/**
* Tests add instance with dispatchEvent
* @name testAddInstance
* @param {scope} globals
*/
function testAddInstance(globals)
{
var repeatablePanel = globals.form.traveler;
globals.functions.dispatchEvent(repeatablePanel,'addInstance');
}
Låt oss lägga till en regel till knappen Add Traveler för att lägga till den repeterbara panelen när någon klickar på den:
Se gif nedan som visar att panelen läggs till med egenskapen dispatchEvent när användaren klickar på knappen Add Traveler:
Lägg på samma sätt till följande kodrad, enligt beskrivningen i avsnittet create-custom-function , för att ta bort en panel när användaren klickar på knappen Delete Traveler med egenskapen dispatchEvent :
/**
* @name testRemoveInstance
* @param {scope} globals
*/
function testRemoveInstance(globals)
{
var repeatablePanel = globals.form.traveler;
globals.functions.dispatchEvent(repeatablePanel, 'removeInstance');
}
Låt oss lägga till en regel till knappen Delete Traveler för att ta bort den repeterbara panelen när någon klickar på den:
Se gif nedan som visar att när användaren klickar på knappen Delete Traveler tas den resande panelen bort med egenskapen dispatchEvent:
Felsökning
-
Utför följande steg om den anpassade överföringshanteraren inte fungerar som förväntat i befintliga AEM projekt eller formulär:
-
Kontrollera att kärnkomponentversionen för är uppdaterad till 3.0.18 och senare. För befintliga AEM och formulär finns det dock ytterligare steg att utföra:
-
För det AEM projektet bör användaren ersätta alla instanser av
submitForm('custom:submitSuccess', 'custom:submitError')medsubmitForm()och distribuera projektet via Cloud Manager pipeline. -
Om de anpassade överföringshanterarna inte fungerar som de ska i befintliga formulär måste användaren öppna och spara regeln
submitFormpå knappen Skicka med regelredigeraren. Den här åtgärden ersätter den befintliga regeln frånsubmitForm('custom:submitSuccess', 'custom:submitError')medsubmitForm()i formuläret.
-
Se även
- Introduktion till regelredigeraren för adaptiv Forms baserat på kärnkomponenter
- Operatortyper och händelser i regelredigeraren för ett adaptivt formulär baserat på kärnkomponenter
- Regelredigerarens användargränssnitt för adaptiv Forms baserat på kärnkomponenter
- Olika användningsområden för regelredigeraren för ett adaptivt formulär baserat på kärnkomponenter
- Skillnader i olika utgåvor av regelredigeraren
- Använda asynkrona funktioner i ett adaptivt formulär
- Anropa tjänstförbättringar i Visual Rule Editor för formulär som baseras på kärnkomponenter
- Introduktion till anpassade funktioner för adaptiv Forms baserat på kärnkomponenter
- Skapa en anpassad funktion för ett adaptivt formulär baserat på kärnkomponenter
- Omfångsobjekt i anpassade funktioner
- Exempel på utveckling och användning av en anpassad funktion