이 문서에는 다음이 포함됩니다.Override form submission success and error handlers를 프리릴리스 기능으로 사용하십시오. 프리릴리스 기능은 다음을 통해서만 액세스할 수 있습니다. 프리릴리스 채널.

적응형 Forms(핵심 구성 요소)의 사용자 지정 기능

소개

AEM Forms은 사용자 정의 함수를 지원하므로 사용자가 복잡한 비즈니스 규칙을 구현하기 위한 JavaScript 함수를 정의할 수 있습니다. 이러한 사용자 지정 기능은 지정된 요구 사항을 충족하도록 입력된 데이터의 조작 및 처리를 용이하게 하여 양식의 기능을 확장합니다. 또한 사전 정의된 기준에 따라 양식 동작을 동적으로 변경할 수 있습니다.

사용자 정의 함수 사용 uses-of-custom-function

적응형 Forms에서 사용자 정의 함수를 사용할 때의 장점은 다음과 같습니다.

사용자 지정 함수는 기본적으로 JavaScript 파일에 추가되는 클라이언트 라이브러리입니다. 사용자 지정 함수를 만들면 규칙 편집기에서 적응형 양식에서 사용자가 선택할 수 있게 됩니다. 사용자 지정 함수는 규칙 편집기의 JavaScript 주석으로 식별됩니다.

사용자 지정 기능에 대해 지원되는 JavaScript 주석 js-annotations

JavaScript 주석은 JavaScript 코드에 대한 메타데이터를 제공하는 데 사용됩니다. 여기에는 /** 및 @과 같은 특정 기호로 시작하는 주석이 포함됩니다. 주석은 함수, 변수 및 코드의 기타 요소에 대한 중요한 정보를 제공합니다. 적응형 양식은 사용자 정의 기능에 대해 다음 JavaScript 주석을 지원합니다.

이름

이 이름은 적응형 양식의 규칙 편집기에서 사용자 지정 기능을 식별하는 데 사용됩니다. 다음 구문을 사용하여 사용자 지정 함수의 이름을 지정합니다.

매개변수

매개 변수는 사용자 지정 함수에서 사용하는 인수 목록입니다. 함수는 여러 매개 변수를 지원할 수 있습니다. 다음 구문을 사용하여 사용자 지정 함수에서 매개 변수를 정의할 수 있습니다.

매개 변수 형식은 대/소문자를 구분하지 않으며 매개 변수 이름에는 공백을 사용할 수 없습니다.

<Parameter Description> 에는 매개 변수의 용도에 대한 세부 사항이 포함되어 있습니다. 여러 단어가 있을 수 있습니다.

선택적 매개 변수
기본적으로 모든 매개 변수는 필수입니다. 다음을 추가하여 매개 변수를 선택 사항으로 정의할 수 있습니다 = 매개 변수 형식 뒤에 또는 매개 변수 이름을 바깥쪽으로 []. JavaScript 주석에서 선택 사항으로 정의된 매개 변수는 규칙 편집기에서 선택 사항으로 표시됩니다.
변수를 선택적 매개 변수로 정의하려면 다음 구문 중 하나를 사용할 수 있습니다.

위의 코드 행에서 Input1 는 기본값이 없는 선택적 매개 변수입니다. 선택적 매개 변수를 기본값으로 선언하려면 다음을 수행합니다.
@param {string=<value>} input1

input1 기본값이 로 설정된 선택적 매개 변수로 value.

위의 코드 행에서 Input1 는 기본값이 없는 선택적 매개 변수입니다. 선택적 매개 변수를 기본값으로 선언하려면 다음을 수행합니다.
@param {array} [input1=<value>]
input1 는 기본값이 로 설정된 배열 유형의 선택적 매개 변수입니다. value.
매개 변수 형식이 중괄호로 묶여 있는지 확인합니다. {} 매개 변수 이름은 대괄호로 묶습니다.

input2가 선택적 매개 변수로 정의된 다음 코드 스니펫을 고려하십시오.

        /**
         * optional parameter function
         * @name OptionalParameterFunction
         * @param {string} input1
         * @param {string=} input2
         * @return {string}
        */
        function OptionalParameterFunction(input1, input2) {
        let result = "Result: ";
        result += input1;
        if (input2 !== null) {
            result += " " + input2;
        }
        return result;
        }

다음 그림은 를 사용하여 표시됩니다. OptionalParameterFunction 규칙 편집기의 사용자 지정 함수:

필요한 매개 변수에 대한 값을 지정하지 않고 규칙을 저장할 수 있지만, 규칙이 실행되지 않고 다음과 같은 경고 메시지가 표시됩니다.

사용자가 선택적 매개 변수를 비워 두면 "정의되지 않음" 값이 선택적 매개 변수에 대한 사용자 지정 함수에 전달됩니다.

JSDocs에서 선택적 매개 변수를 정의하는 방법에 대해 자세히 알아보려면 여기를 클릭하십시오.

반환 유형

반환 형식은 사용자 지정 함수가 실행 후 반환하는 값의 형식을 지정합니다. 다음 구문을 사용하여 사용자 지정 함수에서 반환 유형을 정의합니다.

비공개

private으로 선언된 사용자 지정 함수는 적응형 양식의 규칙 편집기에서 사용자 지정 함수 목록에 표시되지 않습니다. 기본적으로 사용자 지정 함수는 공개입니다. 사용자 지정 함수를 private으로 선언하는 구문은 다음과 같습니다. @private.

사용자 정의 함수를 만드는 동안 지침

규칙 편집기에 사용자 정의 함수를 나열하려면 다음 형식 중 하나를 사용할 수 있습니다.

jsdoc 주석이 있거나 없는 Function 문

jsdoc 주석을 사용하거나 사용하지 않고 사용자 지정 함수를 만들 수 있습니다.

    function functionName(parameters)
        {
            // code to be executed
        }

사용자가 사용자 지정 함수에 JavaScript 주석을 추가하지 않으면 함수 이름으로 규칙 편집기에 나열됩니다. 그러나 사용자 정의 함수의 가독성을 높이기 위해 JavaScript 주석을 포함하는 것이 좋습니다.

필수 JavaScript 주석 또는 댓글이 있는 화살표 기능

화살표 함수 구문을 사용하여 사용자 지정 함수를 만들 수 있습니다.

    /**
    * test function
    * @name testFunction
    * @param {string} a parameter description
    * @param {string=} b parameter description
    * @return {string}
    */
    testFunction = (a, b) => {
    return a + b;
    };
    /** */
    testFunction1=(a) => (return a)
    /** */
    testFunction2 = a => a + 100;

사용자가 JavaScript 주석을 사용자 지정 함수에 추가하지 않으면 사용자 지정 함수가 적응형 양식의 규칙 편집기에 나열되지 않습니다.

필수 JavaScript 주석 또는 주석이 있는 함수 표현식

적응형 양식의 규칙 편집기에 사용자 정의 함수를 나열하려면 다음 형식으로 사용자 정의 함수를 만듭니다.

    /**
    * test function
    * @name testFunction
    * @param {string} input1 parameter description
    * @param {string=} input2 parameter description
    * @return {string}
    */
    testFunction = function(input1,input2)
        {
            // code to be executed
        }

사용자가 JavaScript 주석을 사용자 지정 함수에 추가하지 않으면 사용자 지정 함수가 적응형 양식의 규칙 편집기에 나열되지 않습니다.

사용자 정의 함수 만들기 create-custom-function

규칙 편집기에서 사용자 지정 함수를 호출할 클라이언트 라이브러리를 만듭니다. 자세한 내용은 클라이언트측 라이브러리 사용.

사용자 정의 함수를 만드는 단계는 다음과 같습니다.

사용자 지정 함수를 만들기 위한 사전 요구 사항

적응형 Forms에 사용자 지정 기능을 추가하기 전에 다음을 확인하십시오.

소프트웨어:

클라이언트 라이브러리 만들기 create-client-library

클라이언트 라이브러리를 추가하여 사용자 정의 함수를 추가할 수 있습니다. 클라이언트 라이브러리를 만들려면 다음 단계를 수행하십시오.

저장소 복제

복제 AEM Forms as a Cloud Service 저장소:

이 명령은 저장소를 다운로드하고 시스템에 복제된 저장소의 로컬 폴더를 만듭니다. 이 안내서 전체에서 이 폴더는 다음과 같습니다. [AEMaaCS 프로젝트 디렉터리].

클라이언트 라이브러리 폴더 추가

새 클라이언트 라이브러리 폴더를 [AEMaaCS 프로젝트 디렉터리], 다음 단계를 수행합니다.

클라이언트 라이브러리 폴더에 파일 및 폴더 추가

추가된 클라이언트 라이브러리 폴더에 다음을 추가합니다.

Location is: [AEMaaCS project directory]/ui.apps/src/main/content/jcr_root/apps/experience-league/customclientlibs/

filter.xml에 새 폴더 포함:

새로 만든 클라이언트 라이브러리 폴더를 AEM 환경에 배포합니다.

AEM as a Cloud Service 배포, [AEMaaCS 프로젝트 디렉터리]을 클릭하여 Cloud Service 환경에 추가합니다. Cloud Service 환경에 배포하려면 다음을 수행하십시오.

파이프라인을 아직 설정하지 않았다면 의 안내서를 참조하십시오. AEM Formsas a Cloud Service 용 파이프라인을 설정하는 방법.

파이프라인이 성공적으로 실행되면 클라이언트 라이브러리에 추가된 사용자 지정 함수를에서 사용할 수 있게 됩니다 적응형 양식 규칙 편집기.

적응형 양식에 클라이언트 라이브러리 추가 use-custom-function

클라이언트 라이브러리를 Forms CS 환경에 배포한 후에는 적응형 양식에서 해당 기능을 사용하십시오. 적응형 양식에 클라이언트 라이브러리를 추가하려면

에서 사용자 지정 함수를 사용할 수 있습니다. 적응형 양식의 규칙 편집기 사용 JavaScript 주석.

적응형 양식에서 사용자 정의 함수 사용

적응형 양식에서 다음을 사용할 수 있습니다 규칙 편집기 내의 사용자 지정 함수. JavaScript 파일에 다음 코드를 추가합니다(Function.js file)을 추가하여 생년월일(YYYY-MM-DD)을 기준으로 연령을 계산합니다. 사용자 정의 함수 만들기 calculateAge() 입력 시 생년월일을 사용하고 연령을 반환합니다.

    /**
        * Calculates Age
        * @name calculateAge
        * @param {object} field
        * @return {string}
    */

    function calculateAge(field) {
    var dob = new Date(field);
    var now = new Date();

    var age = now.getFullYear() - dob.getFullYear();
    var monthDiff = now.getMonth() - dob.getMonth();

    if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < dob.getDate())) {
    age--;
    }

    return age;
    }

위의 예에서 사용자가 생년월일을 형식(YYYY-MM-DD)으로 입력하면 사용자 지정 함수가 calculateAge 가 호출되고 월령을 반환합니다.

이제 양식을 미리 보기하여 사용자 정의 함수가 규칙 편집기를 통해 어떻게 구현되는지 살펴보겠습니다.

사용자 정의 함수를 사용하여 드롭다운 목록 옵션 설정

핵심 구성 요소의 규칙 편집기는 옵션 설정 속성을 사용하여 런타임 시 드롭다운 목록 옵션을 설정할 수 있습니다. 그러나 사용자 지정 함수를 사용하여 드롭다운 목록 옵션을 설정할 수 있습니다.

사용자 지정 함수를 사용하여 드롭다운 목록 옵션을 설정하는 방법을 보려면 아래 코드를 살펴보십시오.

    /**
    * @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"];
    }

위의 코드에서 setEnums 를 설정하는 데 사용됩니다. enum 속성 및 setEnumNames 를 설정하는 데 사용됩니다. enumNames 드롭다운 속성.

다음에 대한 규칙을 만들겠습니다. Next 버튼 - 사용자가 를 클릭할 때 드롭다운 목록 옵션의 값을 설정합니다. Next 단추:

표시 버튼을 클릭할 때 드롭다운 목록의 옵션이 설정되는 위치를 보여 주려면 아래 그림을 참조하십시오.

사용자 지정 함수에서 비동기 함수 지원 support-of-async-functions

비동기 사용자 지정 함수는 규칙 편집기 목록에 표시되지 않습니다. 그러나 동기 함수 표현식을 사용하여 만든 사용자 지정 함수 내에서 비동기 함수를 호출할 수 있습니다.

사용자 지정 함수를 사용하여 비동기 함수를 호출하는 방법은 아래 코드를 참조하십시오.

    async function asyncFunction() {
    const response = await fetch('https://petstore.swagger.io/v2/store/inventory');
    const data = await response.json();
    return data;
    }

    /**
    * callAsyncFunction
    * @name callAsyncFunction callAsyncFunction
    */
    function callAsyncFunction() {
    asyncFunction()
        .then(responseData => {
        console.log('Response data:', responseData);
        })
        .catch(error => {
         console.error('Error:', error);
    });
}

위의 예에서 asyncFunction 함수는 asynchronous function. 비동기 작업은 다음을 만들어 수행합니다. GET 요청 대상 https://petstore.swagger.io/v2/store/inventory. 다음을 사용하여 응답을 기다립니다. await는 다음을 사용하여 응답 본문을 JSON으로 구문 분석합니다. response.json()를 클릭한 다음 데이터를 반환합니다. 다음 callAsyncFunction 함수는 를 호출하는 동기 사용자 지정 함수입니다. asyncFunction 콘솔에서 응답 데이터를 표시합니다. 하지만 callAsyncFunction 이 함수는 synchronous이고, 비동기 asyncFunction 함수를 호출하고, 결과를 then 및 catch 명령문입니다.

작동 여부를 확인하려면 단추를 추가하고 단추 클릭 시 비동기 함수를 호출하는 단추에 대한 규칙을 만들어 보겠습니다.

사용자가 를 클릭할 때 표시되는 콘솔 창의 그림을 참조하십시오. Fetch 단추, 사용자 지정 함수 callAsyncFunction 가 호출되어 비동기 함수를 호출합니다. asyncFunction. Inspect 콘솔 창에서 버튼에 대한 응답을 봅니다. 클릭:

사용자 정의 함수의 기능에 대해 자세히 살펴보겠습니다.

사용자 정의 기능을 위한 다양한 기능

사용자 지정 함수를 사용하여 양식에 개인화된 기능을 추가할 수 있습니다. 이러한 기능은 특정 필드 작업, 전역 필드 사용 또는 캐싱과 같은 다양한 기능을 지원합니다. 이러한 유연성을 통해 조직의 요구 사항에 따라 양식을 사용자 정의할 수 있습니다.

사용자 지정 함수의 필드 및 전역 범위 개체 support-field-and-global-objects

필드 개체는 텍스트 필드, 확인란 등 양식 내의 개별 구성 요소 또는 요소를 나타냅니다. Globals 개체에는 사용자 지정 함수 내에서 양식을 수정하는 방법, 대상 필드 인스턴스 및 양식 인스턴스와 같은 읽기 전용 변수가 포함되어 있습니다.

사용자 지정 함수에서 필드를 사용하고 전역 개체를 사용하는 방법에 대해 알아보겠습니다. Contact Us 다양한 사용 사례를 사용하는 양식입니다.

    /**
    * 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});
       }
    }

    /**
    * validateField
    * @name validateField
    * @param {object} field
    * @param {scope} globals
    */
    function validateField(field,globals)
    {

        globals.functions.validate(field);

    }

    /**
    * resetField
    * @name  resetField
    * @param {string} input1
    * @param {object} field
    * @param {scope} globals
    */
    function  resetField(field,globals)
    {

        globals.functions.reset(field);

    }

    /**
    * 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 });
    }
}

    /**
    * 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);
    }

/**
 * 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);
}

/**
* @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});
}

/**
 * Tests import data
 * @name testImportData
 * @param {scope} globals
 */
function testImportData(globals)
{
    globals.functions.importData(Object.fromEntries([['amount','10000']]));
}

/**
 * @name testSetFocus
 * @param {object} emailField
 * @param {scope} globals
 */
    function testSetFocus(field, globals)
    {
        globals.functions.setFocus(field);
    }

/**
 * Tests add instance with dispatchEvent
 * @name testAddInstance
 * @param {scope} globals
 */
function testAddInstance(globals)
{
    var repeatablePanel = globals.form.traveler;
    globals.functions.dispatchEvent(repeatablePanel,'addInstance');
}

/**

 * @name testRemoveInstance
 * @param {scope} globals
 */
function testRemoveInstance(globals)
{
    var repeatablePanel = globals.form.traveler;
    globals.functions.dispatchEvent(repeatablePanel, 'removeInstance');
}

사용자 지정 기능에 대한 캐싱 지원

적응형 Forms은 규칙 편집기에서 사용자 지정 함수 목록을 검색하는 동안 응답 시간을 개선하기 위해 사용자 지정 함수에 대한 캐싱을 구현합니다. 다음으로 메시지: Fetched following custom functions list from cache 에 표시 error.log 파일.

사용자 지정 함수가 수정되면 캐싱이 무효화되고 구문 분석됩니다.

문제 해결 troubleshooting

고려 사항

추가 참조 see-also