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

이 문서에서는 다음과 같은 최신 기능이 포함된 최신 적응형 양식 핵심 구성 요소로 사용자 정의 기능을 만드는 방법에 대해 설명합니다.

사용자 지정 함수의 최신 기능을 사용하려면 AEM Forms 핵심 구성 요소 환경에서 최신 양식 버전을 설정해야 합니다.

소개

AEM Forms 6.5에는 규칙 편집기를 사용하여 복잡한 비즈니스 규칙을 정의할 수 있는 JavaScript 기능이 포함되어 있습니다. AEM Forms에서는 다양한 기본 사용자 정의 함수를 제공하지만, 많은 사용 사례에서는 여러 양식에서 사용할 사용자 정의 함수를 정의해야 합니다. 이러한 사용자 지정 기능은 특정 요구 사항을 충족하도록 입력된 데이터를 조작 및 처리할 수 있도록 함으로써 양식의 기능을 향상시킵니다. 또한 사전 정의된 기준에 따라 양식 동작을 동적으로 변경할 수 있습니다.

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

적응형 Forms 핵심 구성 요소에서 사용자 지정 기능을 사용할 때의 장점은 다음과 같습니다.

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

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

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

이름

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

매개변수

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

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

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

반환 유형

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

반환 형식은 대/소문자를 구분하지 않습니다.

비공개

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

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

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

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 주석을 사용자 지정 함수에 추가하지 않으면 사용자 지정 함수가 적응형 양식의 규칙 편집기에 나열되지 않습니다.

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

적응형 Forms에 사용자 정의 기능을 추가하기 전에 시스템에 다음 소프트웨어가 설치되어 있는지 확인하십시오.

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

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

AEM Project Archetype을 사용하여 클라이언트 라이브러리 만들기 create-client-library-archetype

AEM Project Archetype을 사용하여 만든 프로젝트에 클라이언트 라이브러리를 추가하여 사용자 지정 함수를 추가할 수 있습니다.
기존 프로젝트 이(가) 있는 경우 사용자 지정 함수를 로컬 프로젝트에 직접 추가할 수 있습니다.

Archetype 프로젝트를 만들거나 기존 프로젝트를 사용한 후에 클라이언트 라이브러리를 만듭니다. 클라이언트 라이브러리를 만들려면 다음 단계를 수행하십시오.

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

새 클라이언트 라이브러리 폴더를 [AEM 프로젝트 디렉터리]에 추가하려면 다음 단계를 수행합니다.

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

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

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

filter.xml에 새 폴더 포함:

CRXDE를 통해 사용자 정의 함수 만들기 및 배포 create-add-custom-function

최신 AEM Forms 및 Forms 추가 기능을 사용하는 경우 CRXDE를 통해 사용자 정의 함수를 만들어 사용자 정의 함수의 최신 업데이트를 사용할 수 있습니다. 이렇게 하려면 다음 단계를 수행합니다.

다음 사용자 지정 함수 폴더를 참조할 수 있습니다. 이 폴더를 다운로드하여 AEM 인스턴스에 설치합니다.

이제 클라이언트 라이브러리를 추가하여 적응형 양식에서 사용자 지정 기능을 사용할 수 있습니다.

적응형 양식에 클라이언트 라이브러리 추가 add-client-library

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

이제 규칙 편집기에서 사용자 정의 함수를 사용하는 규칙을 만들 수 있습니다.

이제 AEM Forms 6.5🔗에서 규칙 편집기의 호출 서비스를 사용하여 사용자 지정 함수를 구성하고 사용하는 방법에 대해 알아보겠습니다

적응형 양식에서 사용자 정의 함수 사용 use-custom-functions

적응형 양식에서는 규칙 편집기 내에서 사용자 지정 함수를 사용할 수 있습니다.
JavaScript 파일(Function.js 파일)에 다음 코드를 추가하여 생년월일(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이(가) 호출되고 연령을 반환합니다.

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

사용자 지정 함수에서 비동기 함수 지원 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입니다. https://petstore.swagger.io/v2/store/inventory에 GET을(를) 요청하여 비동기 작업을 수행합니다. await을(를) 사용하여 응답을 기다리고 response.json()을(를) 사용하여 응답 본문을 JSON으로 구문 분석한 다음 데이터를 반환합니다. callAsyncFunction 함수는 asyncFunction 함수를 호출하고 콘솔에 응답 데이터를 표시하는 동기 사용자 지정 함수입니다. callAsyncFunction 함수는 동기식이지만 비동기 asyncFunction 함수를 호출하고 그 결과를 then 및 catch 문으로 처리합니다.

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

사용자가 Fetch 단추를 클릭하면 사용자 지정 함수 callAsyncFunction이(가) 호출되어 비동기 함수 asyncFunction이(가) 호출되는지 보여 주려면 아래 콘솔 창의 그림을 참조하십시오. 버튼 클릭 시 응답을 볼 수 있는 콘솔 창 Inspect:

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

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

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

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

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

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

사용 사례: SetProperty 규칙을 사용하여 패널 표시

create-custom-function 섹션에 설명된 대로 사용자 지정 함수에 다음 코드를 추가하여 양식 필드를 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});
       }
    }

이 예제에서는 단추를 클릭하면 personaldetails 패널의 유효성 검사가 수행됩니다. 패널에서 오류가 감지되지 않으면 버튼을 클릭할 때 다른 패널인 feedback 패널이 표시됩니다.

Next 단추에 대한 규칙을 만들어 personaldetails 패널의 유효성을 검사하고 사용자가 Next 단추를 클릭할 때 feedback 패널이 표시되도록 하겠습니다.

Next 단추를 클릭할 때 personaldetails 패널의 유효성을 검사한 위치를 보여 주는 아래 그림을 참조하십시오. personaldetails 내의 모든 필드의 유효성을 검사하면 feedback 패널이 표시됩니다.

personaldetails 패널의 필드에 오류가 있는 경우 Next 단추를 클릭하면 필드 수준에서 오류가 표시되고 feedback 패널은 표시되지 않습니다.

사용 사례: 필드의 유효성을 검사합니다.

create-custom-function 섹션에 설명된 대로 사용자 지정 함수에 다음 코드를 추가하여 필드의 유효성을 검사합니다.

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

        globals.functions.validate(field);

    }

이 예제에서는 사용자 지정 유효성 검사 패턴이 contact 필드에 적용됩니다. 사용자는 전화 번호를 10(으)로 시작하여 8 자릿수를 입력해야 합니다. 사용자가 10(으)로 시작하지 않거나 8자리보다 많거나 적은 전화 번호를 입력하면 단추를 클릭할 때 유효성 검사 오류 메시지가 나타납니다.

이제 다음 단계는 단추 클릭에서 contact 필드의 유효성을 검사하는 Next 단추에 대한 규칙을 만드는 것입니다.

사용자가 10(으)로 시작하지 않는 전화 번호를 입력하는 경우 필드 수준에 오류 메시지가 표시되는지 확인하려면 아래 그림을 참조하십시오.

사용자가 올바른 전화 번호를 입력하고 personaldetails 패널의 모든 필드가 유효성이 확인되면 feedback 패널이 화면에 나타납니다.

사용 사례: 패널 재설정

create-custom-function 섹션에 설명된 대로 사용자 지정 함수에 다음 코드를 추가하여 패널을 재설정합니다.

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

        globals.functions.reset(field);

    }

이 예제에서는 Clear 단추를 클릭하면 personaldetails 패널이 재설정됩니다. 다음 단계는 단추 클릭 시 패널을 재설정하는 Clear 단추에 대한 규칙을 만드는 것입니다.

사용자가 clear 단추를 클릭하면 personaldetails 패널이 재설정됨을 표시하려면 아래 그림을 참조하십시오.

사용 사례: 필드 수준에서 사용자 지정 메시지를 표시하고 필드를 잘못된 것으로 표시하려면

markFieldAsInvalid() 함수를 사용하여 필드를 잘못된 필드로 정의하고 필드 수준에서 사용자 지정 오류 메시지를 설정할 수 있습니다. fieldIdentifier 값은 fieldId, field qualifiedName 또는 field dataRef일 수 있습니다. 이름이 option인 개체의 값은 {useId: true}, {useQualifiedName: true} 또는 {useDataRef: true}일 수 있습니다.
필드를 유효하지 않은 것으로 표시하고 사용자 정의 메시지를 설정하는 데 사용되는 구문은 다음과 같습니다.

create-custom-function 섹션에 설명된 대로 사용자 지정 함수에 다음 코드를 추가하여 필드 수준에서 사용자 지정 메시지를 사용하도록 설정합니다.

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

이 예제에서 사용자가 주석 입력란에 15자 미만을 입력하면 사용자 정의 메시지가 필드 수준에 나타납니다.

다음 단계는 comments 필드에 대한 규칙을 만드는 것입니다.

comments 필드에 부정적인 피드백을 입력하면 필드 수준에서 사용자 지정 메시지를 표시하도록 트리거됨을 표시하려면 아래 데모를 참조하십시오.

사용자가 댓글 텍스트 상자에 15자 이상을 입력하면 필드의 유효성이 검사되고 양식이 제출됩니다.

사용 사례: 변경된 데이터를 서버에 제출

다음 코드 줄:
globals.functions.submitForm(globals.functions.exportData(), false);은(는) 조작 후 양식 데이터를 제출하는 데 사용됩니다.

create-custom-function 섹션에 설명된 대로 사용자 지정 함수에 다음 코드를 추가하여 조작된 데이터를 서버에 제출합니다.

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

이 예제에서 사용자가 comments 텍스트 상자를 비워 두면 양식 제출 시 NA이(가) 서버로 제출됩니다.

이제 데이터를 전송하는 Submit 단추에 대한 규칙을 만듭니다.

사용자가 comments 텍스트 상자를 비워 두면 NA 값이 서버에 제출된다는 것을 증명하려면 아래 console window 그림을 참조하십시오.

또한 콘솔 창을 검사하여 서버에 제출된 데이터를 볼 수도 있습니다.

콘솔 창의

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

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

캐시를 지원하는

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

문제 해결 troubleshooting

고려 사항