Lägg till anpassade felhanterare i AEM Adaptive Forms error-handlers-in-adaptive-form
Adobe rekommenderar att du använder den moderna och utbyggbara datainhämtningen Core Componentsför att skapa nya adaptiva Formseller att lägga till adaptiva Forms på AEM Sites-sidor. De här komponenterna utgör ett betydande framsteg när det gäller att skapa adaptiva Forms-filer, vilket ger imponerande användarupplevelser. I den här artikeln beskrivs det äldre sättet att skapa Adaptiv Forms med baskomponenter.
AEM Forms har färdiga funktioner och felhanterare för att skicka in formulär. Den innehåller även funktioner för att anpassa felhanterarfunktioner. Du kan till exempel anropa ett anpassat arbetsflöde i serverdelen för specifika felkoder eller informera kunden om att tjänsten inte fungerar. Hanterare är funktioner på klientsidan som körs baserat på serversvaret. När en extern tjänst anropas med API:er överförs data till servern för validering, som returnerar ett svar till klienten med information om lyckad eller felhändelse för överföringen. Informationen skickas som parametrar till den relevanta hanteraren för att köra funktionen. En felhanterare hjälper till att hantera och visa fel eller valideringsproblem som påträffats.
Det adaptiva formuläret validerar indata som du anger i fält baserat på förinställda valideringskriterier och söker efter olika fel som returneras av REST-slutpunkten som konfigurerats för att anropa en extern tjänst. Du kan ange valideringskriterier baserat på den datakälla som du använder med det adaptiva formuläret. Om du till exempel använder RESTful-webbtjänster som datakälla kan du definiera valideringskriterierna i en Swagger-definitionsfil.
Om indatavärdena uppfyller valideringskriterierna skickas värdena till datakällan i annat fall visas ett felmeddelande i Adaptiv form med hjälp av en felhanterare. På samma sätt som detta arbetssätt integreras Adaptive Forms med anpassade felhanterare för datavalidering. Om indatavärdena inte uppfyller valideringskriterierna visas felmeddelandena på fältnivå i det adaptiva formuläret. Detta inträffar när det valideringsfelmeddelande som returneras av servern har standardmeddelandeformatet.
Användning av felhanterare uses-of-error-handler
Felhanterare används för olika syften. Några av användningsområdena för felhanterarfunktioner visas nedan:
-
Utför validering: Felhanteringen börjar med att användarindata valideras mot fördefinierade regler eller villkor. När användarna fyller i ett adaptivt formulär validerar felhanteraren indata så att det uppfyller det format, den längd eller andra begränsningar som krävs.
-
Ge feedback i realtid: När ett fel upptäcks visar felhanteraren direkt feedback till användaren, till exempel textbundna felmeddelanden under motsvarande formulärfält. Denna feedback hjälper användarna att identifiera och åtgärda fel utan att behöva skicka in formuläret och vänta på ett svar.
-
Visa felmeddelanden: När en sändning med adaptiva formulär påträffar ett valideringsfel visar felhanteraren ett felmeddelande. Felmeddelandena ska vara tydliga, koncisa och markera de specifika fält som behöver åtgärdas.
-
Markerar det felaktiga fältet: För att dra användarens uppmärksamhet till specifika felaktiga fält markeras eller visas motsvarande fält i felhanteraren. Den utförs genom att ändra bakgrundsfärgen, lägga till en ikon eller kantlinje eller någon annan visuell indikator som hjälper användarna att snabbt hitta och åtgärda felen.
Fel-/felsvarsformat failure-response-format
I ett adaptivt formulär visas felen på fältnivå om servervalideringsfelmeddelanden är i följande standardformat.
Koden nedan visar den befintliga strukturen för felsvar:
{
errorCausedBy : "SERVER_SIDE_VALIDATION/SERVICE_INVOCATION_FAILURE"
errors : [
{
somExpression : <somexpr>
errorMessage / errorMessages : <validationMsg> / [<validationMsg>, <validationMsg>]
}
]
originCode : <target error Code>
originMessage : <unstructured error message returned by service>
}
Var:
errorCausedBy
beskriver orsaken till felet.errors
anger SOM-uttrycket för de fält som underkändes i valideringskriterierna tillsammans med valideringsfelmeddelandet.- Fältet
originCode
har lagts till av AEM och innehåller http-statuskoden som returneras av den externa tjänsten. - Fältet
originMessage
har lagts till av AEM och innehåller råa feldata som returnerats av den externa tjänsten.
Med förbättringarna i funktioner och efterföljande uppdateringar i AEM Forms-versionerna har den befintliga felsvarsstrukturen ändrats till ett nytt format baserat på RFC7807, som är bakåtkompatibel med den befintliga felsvarsstrukturen:
{
"type": "SERVER_SIDE_VALIDATION/FORM_SUBMISSION/SERVICE_INVOCATION/FAILURE/VALIDATION_ERROR", (required)
"title": "Server side validation failed/Third party service invocation failed", (optional)
"detail": "", (optional)
"instance": "", (optional)
"validationErrors" : [ (required)
{
"fieldName":"<SOM expression of the field whose data sent is invalid>",
"dataRef":<JSONPath (or XPath) of the data element which is invalid>
"details": ["Error Message(s) for the field"] (required)
}
],
"originCode": <Origin http status code>, (optional - in case of SERVER_SIDE_VALIDATION)
"originMessage" : "<unstructured error message returned by service>" (optional - in case of SERVER_SIDE_VALIDATION)
}
- Kontrollera att felsvarsstrukturen innehåller antingen fieldName eller dataRef.
- Kontrollera att rubriken ContentType är application/problem+json.
Var:
-
type (required)
anger typen av fel. Det kan vara något av följande värden:SERVER_SIDE_VALIDATION
indikerar ett fel på grund av validering på serversidan.FORM_SUBMISSION
indikerar ett fel under formuläröverföringenSERVICE_INVOCATION
indikerar ett fel under ett anrop av en tredjepartstjänst.FAILURE
indikerar ett allmänt fel.VALIDATION_ERROR
indikerar ett fel på grund av ett valideringsfel.
-
title (optional)
innehåller en titel eller en kort beskrivning av felet. -
detail (optional)
innehåller ytterligare information om felet om det behövs. -
instance (optional)
representerar en instans eller identifierare som är associerad med felet och hjälper till att spåra eller identifiera den specifika förekomsten av felet. -
validationErrors (required)
innehåller information om valideringsfel. Den innehåller följande fält:fieldname
omnämns SOM-uttrycket för de fält som inte uppfyller valideringskriterierna.dataRef
representerar JSON-sökvägen eller XPath för de fält som inte kunde valideras.details
innehåller valideringsfelmeddelandet med det felaktiga fältet.
-
Fältet
originCode (optional)
har lagts till av AEM och innehåller http-statuskoden som returneras av den externa tjänsten -
Fältet
originMessage (optional)
har lagts till av AEM och innehåller råa feldata som returnerats av den externa tjänsten.
Exempel på felsvarsformat sample-error-response-format
Vissa av alternativen för att visa felsvaren är:
-
Header:
content-type:application/problem+json
-
Response:
code language-javascript { "type": "VALIDATION_ERROR", "validationErrors": [ { "fieldName": "guide[0].guide1[0].guideRootPanel[0].textbox1686647736683[0]", "dataRef": "", "details": [ "Invalid ID supplied. Provided value is not correct!" ] } ]}
Du kan visa SOM-uttrycket för vilket fält som helst i ett adaptivt formulär genom att trycka på fältet och välja View SOM Expression.
-
Header:
content-type:application/problem+json
-
Response:
code language-javascript { "type": "VALIDATION_ERROR", "validationErrors": [ { "fieldName": "", "dataRef": "/Pet/id", "details": [ "Invalid ID supplied. Provided value is not correct!" ] } ]}
Du kan visa värdet för dataRef i Properties-fönstret för en formulärkomponent.
Lägg till felhanterare med Regelredigeraren add-error-handler-using-rule-editor
Med åtgärden Anropa tjänst i regelredigeraren kan du definiera valideringskriterier baserat på datakällan som du använder med det anpassade formuläret. Om du använder RESTful-webbtjänster som datakälla kan du definiera valideringskriterierna i en Swagger-definitionsfil. Genom att använda felhanterarfunktionerna och regelredigeraren i Adaptive Forms kan du effektivt hantera och anpassa felhanteringen. Du definierar villkoren med Regelredigeraren och konfigurerar de åtgärder som ska utföras när regeln aktiveras. Adaptiv form validerar indata som du anger i fält baserat på förinställda valideringskriterier. Om indatavärdena inte uppfyller valideringskriterierna visas felmeddelandena på fältnivån i ett adaptivt formulär.
- Om du vill använda felhanterare med regelredigerarens Invoke-tjänståtgärd konfigurerar du Adaptive Forms med en formulärdatamodell (FDM).
- En standardfelhanterare tillhandahålls för att visa felmeddelanden i fält om felsvaret finns i standardschemat. Du kan också anropa standardfelhanteraren från den anpassade felhanterarfunktionen.
Med regelredigeraren kan du:
Lägg till standardfelhanterarfunktion add-default-errror-handler
En standardfelhanterare stöds för att visa felmeddelanden i fält om felsvaret är i standardschema eller i valideringsfel på serversidan.
För att förstå hur du använder en standardfelhanterare med hjälp av åtgärden Anropa tjänst för regelredigerare ska du ta ett exempel på ett enkelt adaptivt formulär med två fält, Pet ID och Pet Name , och använda en standardfelhanterare i fältet Pet ID för att kontrollera om det finns olika fel som returneras av REST-slutpunkten som konfigurerats för att anropa en extern tjänst. exempel: 200 - OK
,404 - Not Found
, 400 - Bad Request
. Så här lägger du till en standardfelhanterare med hjälp av åtgärden Anropa tjänst i regelredigeraren:
- Öppna ett adaptivt formulär i redigeringsläge, markera en formulärkomponent och välj Rule Editor för att öppna regelredigeraren.
- Välj Create.
- Skapa ett villkor i avsnittet När i regeln. Till exempel ändras När[namnet på fältet Pet-ID] ändras. Markeringen ändras i listrutan Välj läge.
- I avsnittet Sedan väljer du Invoke Service i listrutan Välj åtgärd .
- Välj en Post-tjänst och dess motsvarande databindningar i avsnittet Indata. Om du till exempel vill validera Pet ID väljer du en Post-tjänst som GET /pet/{petId} och väljer Pet ID i avsnittet Indata .
- Välj databindningar i avsnittet Utdata. Välj Djurnamn i avsnittet Utdata.
- Välj Default Error Handler i avsnittet Felhanterare.
- Klicka på Done.
Som ett resultat av den här regeln kontrollerar de värden du anger för Pet ID valideringen för Pet Name med hjälp av den externa tjänsten som anropas av REST-slutpunkten. Om valideringskriterierna som baseras på datakällan misslyckas, visas felmeddelandena på fältnivå.
Lägg till anpassad felhanterarfunktion add-custom-errror-handler
Du kan lägga till en anpassad felhanterarfunktion för att utföra några av åtgärderna:
- hantera felsvar som använder icke-standard- eller standardfelsvar. Observera att dessa icke-standardfelsvar inte är kompatibla med standardschemat för felsvar.
- skicka analyshändelser till alla analysplattformar. Exempel: Adobe Analytics.
- visa modal dialog med felmeddelanden.
Förutom de nämnda åtgärderna kan de anpassade felhanterarna användas för att utföra anpassade funktioner som uppfyller specifika användarkrav.
Den anpassade felhanteraren är en funktion (klientbibliotek) som är utformad för att svara på fel som returneras av en extern tjänst och leverera ett anpassat svar till slutanvändarna. Alla klientbibliotek med anteckningen @errorHandler
betraktas som en anpassad felhanterarfunktion. Den här anteckningen hjälper till att identifiera felhanterarfunktionen som anges i filen .js
.
För att förstå hur du skapar och använder en anpassad felhanterare med hjälp av åtgärden Regelredigerarens anropstjänst kan vi ta ett exempel på Adaptiv form med två fält, Pet ID och Pet Name, och använda en anpassad felhanterare i fältet Pet ID för att kontrollera om det finns olika fel som returneras av REST-slutpunkten som konfigurerats för att anropa en extern tjänst, till exempel 200 - OK
,404 - Not Found
, 400 - Bad Request
.
Så här lägger du till och använder en anpassad felhanterare i ett adaptivt formulär:
1. Skapa en anpassad felhanterare create-custom-error-message
Så här skapar du en anpassad felfunktion:
-
Skapa en mapp i mappen
[AEM Forms as a Cloud Service repository folder]/apps/
. Skapa till exempel en mapp med namnetexperience-league
-
Navigera till
[AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/experience-league/
och skapa enClientLibraryFolder
somclientlibs
. -
Skapa en mapp med namnet
js
. -
Navigera till mappen
[AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js
. -
Lägg till en JavaScript-fil, till exempel
function.js
. Filen innehåller koden för den anpassade felhanteraren.
Låt oss lägga till följande kod i JavaScript-filen för att visa svar och rubriker som tagits emot från REST-tjänstens slutpunkt i webbläsarkonsolen.code language-javascript /** * Custom Error handler * @name customErrorHandler Custom Error Handler Function * @errorHandler */ function customErrorHandler(response, headers) { console.log("Custom Error Handler processing start..."); console.log("response:"+JSON.stringify(response)); console.log("headers:"+JSON.stringify(headers)); guidelib.dataIntegrationUtils.defaultErrorHandler(response, headers); console.log("Custom Error Handler processing end..."); }
Följande rad i exempelkoden används för att anropa standardfelhanteraren från din anpassade felhanterare:
guidelib.dataIntegrationUtils.defaultErrorHandler(response, headers)
note note NOTE Lägg till egenskaperna allowProxy
ochcategories
i filen.content.xml
.allowProxy = [Boolean]true
categories= customfunctionsdemo
I det här fallet anges till exempel [custom-errorhandler-name] somcustomfunctionsdemo
.
-
Spara filen
function.js
. -
Navigera till mappen
[AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js
. -
Lägg till en textfil som
js.txt
. Filen innehåller:code language-javascript #base=js functions.js
-
Spara filen
js.txt
.
Den skapade mappstrukturen ser ut så här:note note NOTE Om du vill veta mer om hur du skapar anpassade funktioner klickar du på anpassade funktioner i regelredigeraren. -
Lägg till, implementera och skicka ändringarna i databasen med följande kommandon:
code language-javascript git add . git commit -a -m "Adding error handling files" git push
När pipeline har körts blir den anpassade felhanteraren tillgänglig i regelredigeraren för adaptiva formulär. Nu ska vi förstå hur du konfigurerar och använder en anpassad felhanterare med hjälp av regelredigerarens Invoke-tjänst i AEM Forms.
2. Använd regelredigeraren för att konfigurera en anpassad felhanterare use-custom-error-handler
Innan du implementerar den anpassade felhanteraren i ett adaptivt formulär måste du se till att klientbiblioteksnamnet i Client Library Category justeras med det namn som anges i kategorialternativet i filen .content.xml
.
I det här fallet anges klientbiblioteksnamnet som customfunctionsdemo
i filen .content.xml
.
Så här använder du en anpassad felhanterare med åtgärden Rule Editor’s Invoke Service:
- Öppna ett adaptivt formulär i redigeringsläge, markera en formulärkomponent och välj Rule Editor för att öppna regelredigeraren.
- Välj Create.
- Skapa ett villkor i avsnittet När i regeln. Om till exempel [namnet på fältet för Pet-ID] ändras, ändras väljs i den nedrullningsbara listan Välj läge.
- I avsnittet Sedan väljer du Invoke Service i listrutan Välj åtgärd .
- Välj en Post-tjänst och dess motsvarande databindningar i avsnittet Indata. Om du till exempel vill validera Pet ID väljer du en Post-tjänst som GET /pet/{petId} och väljer Pet ID i avsnittet Indata .
- Välj databindningar i avsnittet Utdata. Välj till exempel Djurnamn i avsnittet Utdata.
- Välj Custom Error Handler i avsnittet Error Handler.
- Klicka på Done.
Som ett resultat av den här regeln kontrollerar de värden du anger för Pet ID valideringen för Pet Name med hjälp av den externa tjänsten som anropas av REST-slutpunkten. Om valideringskriterierna som baseras på datakällan misslyckas, visas felmeddelandena på fältnivå.
Öppna webbläsarkonsolen och kontrollera svaret och rubriken som tagits emot från REST-tjänstens slutpunkt för valideringsfelmeddelandet.
Den anpassade felhanterarfunktionen ansvarar för att utföra ytterligare åtgärder, som att visa en modal dialogruta eller skicka en analyshändelse, baserat på felsvaret. En anpassad felhanterarfunktion ger flexibilitet att anpassa felhanteringen efter specifika användarkrav.
Se även see-also
- Skapa ett AEM anpassat formulär
- Lägg till ett AEM anpassat formulär på AEM Sites-sidan
- Använda teman i ett AEM anpassat formulär
- Lägg till komponenter i ett AEM anpassat formulär
- Använd CAPTCHA i en AEM anpassad form
- Generera PDF-version (DoR) av ett AEM adaptivt formulär
- Översätt en AEM adaptiv form
- Aktivera Adobe Analytics för ett adaptivt formulär för att spåra formuläranvändning
- Ansluta anpassat formulär till Microsoft SharePoint
- Ansluta anpassat formulär till Microsoft Power Automate
- Ansluta anpassat formulär till Microsoft OneDrive
- Ansluta anpassat formulär till Microsoft Azure Blob Storage
- Ansluta anpassat formulär till Salesforce
- Använda Adobe Sign i en AEM anpassad form
- Lägga till en ny språkinställning för ett adaptivt formulär
- Skicka adaptiva formulärdata till en databas
- Skicka data för anpassat formulär till en REST-slutpunkt
- Skicka anpassade formulärdata till AEM arbetsflöde
- Använd Forms Portal för att lista AEM Adaptive Forms på en AEM webbplats
- Lägga till versioner, kommentarer och anteckningar i ett adaptivt formulär
- Jämför adaptiv Forms
- Skapa och använda anpassade felhanterare i Adaptive Forms (Core Components)