Edge Delivery Services 블록 개발

목표는 서드파티 API에서 동적 데이터를 가져오기 위해 AEM Edge 함수를 호출하는 동적 Edge Delivery Services 블록을 빌드하는 것입니다.

두 번째 단계는 JSON 모델, JavaScript 및 CSS를 스캐폴드하고 유니버설 편집기에서 작성하는 Edge Delivery Services 블록을 개발하는 것입니다. 블록 모델 구문과 JavaScript 및 CSS 구조의 기본 사항에 대해서는 블록 만들기 및 블록 작성을 참조하십시오. 이 자습서와 관련된 부분만 여기에서 다룹니다.

이 단계에서는 아직 이전 단계에서 빌드한 AEM Edge 함수를 호출하지 않습니다. Edge Delivery Services 블록은 AEM Edge 함수에 블록을 연결하여 가져오기를 연결할 때까지 자리 표시자 결과를 렌더링합니다.

분기 만들기

Edge Delivery Services 사이트 프로젝트에서 이 기능의 분기를 만듭니다.

$ git checkout -b estimated-delivery

블록 모델 정의

JavaScript을 작성하기 전에 콘텐츠 모델이 작게 유지되도록 작성자가 제어하는 필드와 코드가 스스로 렌더링하는 필드를 정의합니다.

_estimated-delivery.json의 모델은 머리글과 단추 레이블의 두 필드만 표시합니다. 제품 목록, 양식 마크업 및 결과 상태는 작성된 콘텐츠가 아니라 Edge Delivery Services 블록의 JavaScript에 의해 렌더링됩니다.

// blocks/estimated-delivery/_estimated-delivery.json
{
  "definitions": [
    {
      "title": "Estimated Delivery",
      "id": "estimated-delivery",
      "plugins": {
        "xwalk": {
          "page": {
            "resourceType": "core/franklin/components/block/v1/block",
            "template": {
              "name": "Estimated Delivery",
              "model": "estimated-delivery",
              "title": "When will it arrive?",
              "ctaText": "Check estimated delivery"
            }
          }
        }
      }
    }
  ],
  "models": [
    {
      "id": "estimated-delivery",
      "fields": [
        {
          "component": "text",
          "valueType": "string",
          "name": "title",
          "value": "When will it arrive?",
          "label": "Heading",
          "description": "Main heading shown above the delivery checker form."
        },
        {
          "component": "text",
          "valueType": "string",
          "name": "ctaText",
          "value": "Check estimated delivery",
          "label": "CTA Text",
          "description": "Label for the submit button."
        }
      ]
    }
  ],
  "filters": []
}

text 이상의 필드 형식에 대해서는 블록 만들기의 모델 구문을 따르십시오.

유니버설 편집기에 블록 등록

블록 모델 파일만으로는 유니버설 편집기가 삽입 선택기에서 블록을 제공하기에 충분하지 않습니다. 두 개의 파일이 자동으로 검색되지 않고 이름별로 블록을 나열하므로 먼저 수동 항목이 필요합니다.

models/_component-definition.json의 “블록” 그룹에 블록 추가:

{ "...": "../blocks/estimated-delivery/_*.json#/definitions" }

블록을 섹션 내부에 삽입할 수 있는 경우 해당 ID를 models/_section.json의 filters[0].components에도 추가하십시오.

"estimated-delivery"

models/_component-models.json은(는) 이 처리가 필요하지 않습니다. 와일드카드 ../blocks/*/_*.json#/models을(를) 통해 모든 블록이 자동으로 포함되므로 블록의 필드 스키마만 component-models.json에 도달할 수 있습니다. models/_component-definition.json과(와) models/_section.json은(는) 이 프로젝트에 와일드카드를 사용하지 않으므로 해당 모델이 올바르게 컴파일되더라도 이름으로 두 프로젝트에 모두 추가될 때까지 새 블록이 선택기에 표시되지 않습니다.

프로젝트 JSON 빌드에 포함된 프로젝트의 집계 파일(component-definition.json, component-filters.json 및 component-models.json)로 편집 내용을 컴파일합니다.

블록 구현

추가할 파일

blocks/estimated-delivery/
├── _estimated-delivery.json   # the block model, shown above
├── estimated-delivery.js      # decorate() renders the form and result states
└── estimated-delivery.css     # form layout and result state styling

양식 및 자리 표시자 결과 렌더링

제품 선택, 우편 번호 입력, 제출 단추 및 빈 결과 영역을 렌더링하도록 decorate() 함수를 빌드합니다. 지금은 제출 처리기를 스텁으로 유지합니다.

readBlockContent()은(는) 블록의 DOM에서 두 개의 작성된 필드를 읽습니다. Universal Editor는 필드 순서로 각 모델 필드를 하위 <div>(으)로 렌더링하므로 머리글은 첫 번째 하위 텍스트이고 단추 레이블은 두 번째 하위 텍스트이며 필드가 비어 있을 때 기본값으로 돌아갑니다.

// blocks/estimated-delivery/estimated-delivery.js
const DEFAULTS = {
  title: 'When will it arrive?',
  ctaText: 'Check estimated delivery',
};

const PRODUCTS = [
  { value: 'house-blend-medium-roast', label: 'House Blend - Medium Roast' },
  { value: 'frescopa-smart-machine', label: 'Fréscopa Smart Machine' },
  { value: 'insulated-travel-thermos', label: 'Insulated Travel Thermos' },
];

const PRODUCT_OPTIONS_HTML = PRODUCTS.map(
  (p) => `<option value="${p.value}">${p.label}</option>`,
).join('');

function getBlockText(el, fallback) {
  const text = el?.textContent?.trim();
  return text || fallback;
}

function readBlockContent(block) {
  const props = [...block.children].map((row) => row.firstElementChild);

  return {
    title: getBlockText(props[0], DEFAULTS.title),
    ctaText: getBlockText(props[1], DEFAULTS.ctaText),
  };
}

export default function decorate(block) {
  const { title, ctaText } = readBlockContent(block);

  block.innerHTML = `
    <div class="estimated-delivery">
      <h3 data-aue-prop="title" data-aue-label="Heading" data-aue-type="text">${title}</h3>
      <form class="estimated-delivery__form">
        <select name="sku">${PRODUCT_OPTIONS_HTML}</select>
        <input name="postcode" type="text" placeholder="e.g. 10001" required />
        <button type="submit" data-aue-prop="ctaText" data-aue-label="CTA Text" data-aue-type="text">${ctaText}</button>
      </form>
      <div class="estimated-delivery__result" aria-live="polite">
        <p>Select a product, enter your postcode, and click the button.</p>
      </div>
    </div>
  `;

  // form submit logic added in the next step
}

data-aue-prop, data-aue-label 및 data-aue-type은(는) 머리글 및 단추 텍스트를 블록 만들기에 사용된 것과 동일한 패턴인 범용 편집기에서 편집 가능한 필드로 표시합니다. 이것은 최종 파일이 아닌 스캐폴드입니다. 참조 구현의 estimated-delivery.js에는 블록을 AEM Edge 함수에 연결하는 가져오기 논리도 포함되어 있습니다. 이 함수는 해당 논리가 적용되면 전체 파일에 연결됩니다.

블록 스타일 지정

CSS 및 JavaScript을 사용하여 블록을 개발한 후 양식 레이아웃, 자리 표시자 상태 및 Edge Delivery Services 블록이 나중에 렌더링되는 결과 상태(로드, 오류, 성공)에 대한 CSS를 추가하십시오. estimated-delivery.css의 대표 발췌:

/* blocks/estimated-delivery/estimated-delivery.css */
.estimated-delivery__form {
  display: grid;
  gap: var(--spacing-small);
  padding: var(--spacing-medium);
  background: #fff;
  border-radius: 12px;
  box-shadow: 0 4px 12px rgb(0 0 0 / 6%);
}

.estimated-delivery__placeholder {
  display: grid;
  gap: var(--spacing-xsmall);
  align-content: center;
  border: 2px dashed var(--color-neutral-400);
  border-radius: 12px;
  text-align: center;
}

전체 파일은 로드 스피너 및 성공 카드의 상태 색상(in-stock, low-stock, out-of-stock)도 스타일링합니다. 이 색상은 AEM Edge 함수에 블록을 연결할 때까지 Edge Delivery Services 블록이 렌더링되지 않습니다.

코드 푸시 및 블록 작성

로컬에서 블록 미리 보기

Edge Delivery Services 사이트를 로컬로 실행하고 가져오기 호출을 배선하기 전에 자리 표시자 렌더링을 확인합니다.

$ aem up

http://localhost:3000/dev/branches/estimated-delivery에서 작성한 페이지를 열고 제목, 양식 및 자리 표시자 텍스트가 작성된 것으로 렌더링되는지 확인합니다. 제출 버튼이 아직 작동하지 않습니다.

다음 단계

블록을 AEM Edge 함수에 연결에서 이 Edge Delivery Services 블록을 이전 단계에서 빌드한 AEM Edge 함수로 연결하여 자리 표시자 결과를 라이브 데이터로 바꿉니다.

추가 리소스