Sidekick 라이브러리란 무엇입니까?
Sidekick 라이브러리는 개발자가 콘텐츠 작성자를 위한 UI 기반 도구를 만들 수 있도록 하는 AEM Sidekick의 확장 기능입니다. 여기에는 작성자에게 모든 블록 목록을 직관적인 방식으로 표시할 수 있는 내장된 블록 플러그인이 포함되어 있어, 작성자가 블록의 모든 변형을 기억하거나 검색하지 않아도 됩니다. 개발자는 Sidekick 라이브러리용 플러그인을 직접 작성할 수도 있습니다.
Sidekick 라이브러리를 사용하는 방법
아래 단계에서는 사이드 킥 라이브러리를 설정하고 블록 플러그인을 구성하는 방법에 대해 자세히 설명합니다.
라이브러리 시트 설정
사이드 킥 라이브러리는 시트를 사용하여 플러그인 및 플러그인 콘텐츠로 채워집니다.
1. 라이브러리의 콘텐츠를 저장할 sharepoint 또는 gdrive에 디렉터리를 만들어 시작합니다. 탑재 지점의 루트에 있는 /tools/sidekick(또는 다른 이름)에 콘텐츠를 저장하는 것이 좋습니다. 다음 단계에서는 디렉터리 이름이 /tools/sidekick이라고 가정합니다.
2. 그런 다음 /tools/sidekick 디렉터리에 library(또는 다른 이름)이라는 통합 문서(Excel 파일)를 만듭니다. 통합 문서의 각 시트는 Sidekick 라이브러리에서 로드할 플러그인을 나타냅니다. 시트의 이름은 로드할 플러그인의 이름을 결정합니다. 시트에 포함된 모든 데이터는 로드할 때 플러그인으로 전달됩니다. 플러그 인 시트 이름 앞에 helix-을(를) 추가해야 합니다. 예를 들어, tags 플러그인을 로드하려면 helix-tags 시트를 만듭니다.
3. 이 자습서에서는 blocks 플러그인에 대한 시트를 만듭니다. 시트를 만들거나 기본 시트의 이름을 바꾸어 `helix-blocks`라고 하고 지금은 비워 둡니다.
블록 플러그인
Sidekick 라이브러리에는 blocks 플러그인이 포함되어 있습니다.
플러그인 설정 차단
블록 플러그인에 대한 콘텐츠를 생성하려면 포함할 각 블록에 대해 별도의 Word 문서를 준비해야 합니다.
1. 모든 블록 변형을 저장할 /tools/sidekick 디렉터리 내에 디렉터리를 만듭니다. 예를 들어 /tools/sidekick 내에 blocks 디렉터리를 만들 수 있습니다.
2. 이 예제에서는 columns이라는 블록의 모든 변형을 정의하려고 한다고 가정해 보겠습니다. 먼저 blocks 디렉터리 내에 columns(이)라는 Word 문서를 만들고 columns 블록의 모든 변형에 대한 예제를 제공합니다. 블록의 각 변형 뒤에 섹션 구분 기호를 추가합니다.
3. columns 문서를 미리 보고 게시합니다.
4. helix-blocks 시트 내부의 마지막 섹션에서 만든 라이브러리 통합 문서를 열고 name 및 path(이)라는 두 개의 열을 만듭니다.
6. 다음으로 columns 블록에 대한 행을 추가해야 합니다. 첫 번째 열에 있는 블록 이름과 두 번째 열에 있는 블록 변형을 정의하는 문서에 대한 URL을 추가합니다. 예를 들어 columns 블록을 추가하려면 이름이 Columns이고 경로가 /tools/sidekick/blocks/columns인 행을 만들 수 있습니다. 라이브러리가 환경(page, live, prod)에서 작동하려면 경로 열에 절대 URL을 사용하면 안 됩니다.
7. library 통합 문서를 미리 보고 게시합니다.
> 예제 블록이 게시되고 있으므로 일괄 메타데이터을(를) 사용하여 /tools/**의 콘텐츠가 인덱싱되지 않도록 제외해야 합니다.
예 library.xlsx
라이브러리 메타데이터
블록 플러그인은 개발자가 블록 플러그인에 블록에 대한 일부 정보 또는 블록 렌더링 방법을 알려줄 수 있는 library metadata이라는 특수 유형의 블록을 지원합니다.
지원되는 라이브러리 메타데이터 옵션
기본 라이브러리 메타데이터와 라이브러리 메타데이터 비교
두 가지 유형의 library metadata이(가) 있습니다. 블록이 포함된 섹션 내에 있는 라이브러리 메타데이터 또는 문서 전체에 적용되며 문서 자체의 섹션에 있는 default library metadata(섹션에서 유일한 하위 항목으로서 library metadata이라는 블록).
5개의 변형이 있는 히어로 블록을 예로 들어 보겠습니다. 설명이 포함된 library metadata을(를) 변형이 포함된 각 섹션에 복제하지 않고 블록의 각 변형에 대해 동일한 설명을 추가한다고 가정합니다. 대신 default library metadata을(를) 사용하여 블록의 모든 변형에 동일한 설명을 적용할 수 있습니다. 한 변형에 실제로 약간 다른 설명이 필요하다고 결정하는 경우 변형을 포함하는 섹션에 library metadata을(를) 추가할 수 있으며 블록 플러그인 내에서 렌더링될 때 기본 library metadata 설명을 무시할 수 있습니다.
라이브러리 메타데이터를 사용하여 블록 이름 및 설명 작성
기본적으로 블록 이름(변형 포함)은 블록 플러그인의 항목을 렌더링하는 데 사용됩니다. 예를 들어 블록 이름이 columns (center, background)이면 해당 이름은 블록 플러그인에 렌더링될 때 레이블로 사용됩니다. 블록과 동일한 섹션 내에 library metadata 섹션을 만들어 이를 사용자 지정할 수 있습니다. 검색 기능을 사용할 때 블록의 별칭을 포함하도록 searchTags을(를) 추가하고 블록의 설명을 작성하는 데에도 라이브러리 메타데이터를 사용할 수 있습니다.
사용자 정의 이름 및 설명이 포함된 예제 블록
콘텐츠
디스플레이
자동 블록 및 기본 컨텐츠
블록 플러그인은 기본 콘텐츠 및 자동 블록을 렌더링할 수 있습니다. 이렇게 하려면 전용 섹션에 default content 또는 autoblock을(를) 배치해야 합니다. 이 섹션에는 이전에 설명한 대로 name 속성을 정의하는 library metadata 테이블이 포함되어야 합니다. 라이브러리 메타데이터에 이름이 지정되지 않은 경우 항목은 "명명되지 않은 항목"으로 레이블이 지정됩니다.
후속 섹션의 콘텐츠로 구성된 블록
개발자가 블록이 후속 섹션의 콘텐츠로 구성되기를 원할 수 있습니다. 이 패턴은 여기에 설명된 이유로 권장되지 않지만, 이 패턴을 사용하도록 선택하면 블록 플러그인이 library metadata의 include next sections 속성을 사용하여 이러한 항목을 렌더링할 수 있습니다.
템플릿
템플릿은 전체 문서를 사이드 킥 라이브러리의 단일 요소로 그룹화하는 방법입니다. 문서를 서식 파일로 표시하려면 default library metadata에서 type을(를) template(으)로 설정합니다.
> 중요: library metadata은(는) 자신의 섹션에 있어야 하며 default library metadata(으)로 간주되는 유일한 자식이어야 합니다.
템플릿에 metadata을(를) 지원하는 것도 좋습니다. 템플릿에 메타데이터 테이블을 추가하려면 Page metadata 블록을 사용할 수 있습니다.
템플릿을 복사하면 값이 포함된 metadata이(가) 내용과 함께 클립보드에 추가됩니다.
Sidekick 플러그인 설정
사이드 킥 라이브러리는 콘텐츠와 동일한 원본에서 호스팅되므로 콘텐츠를 로드하고 구성하려면 정적 HTML 페이지를 만들어야 합니다.
1. tools/sidekick/에서 library.html(이)라는 파일을 만듭니다.
2. library.html에 다음 코드를 붙여넣습니다.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0, viewport-fit=cover"
/>
<meta name="Description" content="AEM Sidekick Library" />
<meta name="robots" content="noindex" />
<base href="/" />
<style>
html,
body {
margin: 0;
padding: 0;
font-family: sans-serif;
background-color: #ededed;
height: 100%;
}
helix-sidekick { display: none }
</style>
<title>Sidekick Library</title>
</head>
<body>
<script
type="module"
src="https://www.aem.live/tools/sidekick/library/index.js"
></script>
<script>
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
}
document.body.prepend(library)
</script>
</body>
</html>
위의 코드에서는 aem.live에서 사이드 킥 라이브러리를 로드한 다음 사용자 지정 sidekick-library 요소를 만들어 페이지에 추가합니다. sidekick-library 요소는 사이드 킥 라이브러리를 구성하는 데 필요한 config 개체를 수락합니다.
지원되는 구성 매개 변수
블록 플러그인은 plugins 개체를 사용하여 설정할 수 있는 다음 구성 속성을 지원합니다.
플러그인 구성 매개 변수 차단
예
이미지 인코딩
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
blocks: {
encodeImages: true,
}
}
}
사용자 정의 뷰포트(약식)
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
blocks: {
viewPorts: [600, 900],
}
}
}
사용자 지정 뷰포트
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
blocks: {
viewPorts: [
{
width: '599px',
label: 'Small',
icon: 'device-phone',
},
{
width: '899px',
label: 'Medium',
icon: 'device-tablet',
},
{
width: '100%',
label: 'Large',
icon: 'device-desktop',
default: true,
},
],
}
}
}
사용자 지정 테이블 머리글 색상
블록, 섹션 메타데이터 또는 블록 플러그인에서 복사한 메타데이터를 붙여넣을 때 테이블 머리글 배경색 및 전경색을 사용자 지정할 수 있습니다.
css 변수를 사용하여 library.html에서 기본 스타일을 설정할 수 있습니다.
<style>
:root {
--sk-block-table-background-color: #03A;
--sk-block-table-foreground-color: #fff;
--sk-section-metadata-table-background-color: #f30;
--sk-section-metadata-table-foreground-color: #000;
--sk-metadata-table-background-color: #000;
--sk-metadata-table-foreground-color: #fff;
}
</style>
이러한 값은 라이브러리 메타데이터를 사용하여 재정의할 수 있습니다.
> 사용자 컴퓨터(어두운 모드)에 대해 선택한 시스템 색 구성표에 따라 접근성을 개선하기 위해 선택한 색이 변경될 수 있습니다.
사용자 지정 플러그인 설정
아래 예제는 구성에서 tags 플러그인을 정의합니다. plugins 개체의 키는 플러그인의 이름과 일치해야 합니다. plugin 개체에 정의된 다른 속성은 decorate 메서드의 컨텍스트 인수를 통해 플러그인에서 사용할 수 있습니다.
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
plugins: {
tags: {
src: '/tools/sidekick/plugins/tags/tags.js',
foo: 'bar'
}
}
}
확장 라이브러리
일부 경우들에서, 2 개의 블록 라이브러리들을 병합하는 것이 바람직할 수도 있다. 확장 라이브러리가 정의되면 사이드 킥 라이브러리 응용 프로그램에서 기본 라이브러리와 확장 라이브러리를 작성자를 위한 단일 라이브러리 목록으로 병합합니다.
아래 예제는 기본 라이브러리와 기본 라이브러리에 병합될 확장 라이브러리(다른 원본에서)를 정의합니다.
const library = document.createElement('sidekick-library')
library.config = {
base: '/tools/sidekick/library.json',
extends: 'https://main--repo--owner.hlx.live/tools/sidekick/library.json'
}
> Access-Control-Allow-Origin 헤더가 사이드 킥 라이브러리에서 로드되려면 확장 라이브러리의 library.json 및 블록에 설정되어야 합니다. 자세한 내용은 사용자 지정 HTTP 응답 헤더를 참조하십시오.
> iframe의 브라우저에서 동일한 원본 정책을 적용하고 있으므로 지금은 확장 블록의 미리 보기를 로드할 수 없습니다.
Sidekick config.json 설정
다음으로 사이드 킥 라이브러리가 사이드 킥에 나타나도록 하려면 tools/sidekick/config.json에 구성 파일을 만들어야 합니다. 이 구성 파일은 코드 버스에서 만들어야 하며 github에 체크 인해야 합니다.
{
"project": "Example",
"plugins": [
{
"id": "library",
"title": "Library",
"environments": ["edit"],
"url": "/tools/sidekick/library.html",
"includePaths": ["**.docx**"]
}
]
}
플러그 인 구성의 url 속성은 사이드 킥이 플러그 인을 로드해야 하는 위치를 나타냅니다. 이전에 만든 library.html 파일을 가리켜야 합니다.
> 플러그인이 사이드 킥에 표시되도록 하려면 사이드 킥 구성을 main 분기로 확인해야 합니다.
> tools/sidekick/config.json 파일이 github 저장소에 없는 경우 파일을 만들어야 합니다. 사이드 킥 플러그 인 구성 옵션에 대한 자세한 내용은 docs을(를) 참조하십시오.
라이브러리에 대한 빌딩 블록 시 고려 사항
사이드 킥 라이브러리는 먼저 블록의 plain.html 렌디션을 가져와 블록을 렌더링한 다음 콘텐츠의 다른 블록에서 제거합니다(예를 들어 응답에 블록의 여러 변형이 있는 경우). 그런 다음 동일한 페이지(.plain.html 없이)를 요청하고 main 요소를 제거된 블록으로 바꾸고 srcdoc 특성을 사용하여 전체 문서를 iframe에 로드합니다.
window.location 사용
블록은 srcdoc 특성을 사용하여 iframe에 로드되므로 사이트 코드에서 사용하는 window.location 개체의 인스턴스에는 표시되는 일반적인 값이 포함되지 않습니다.
라이브러리에서 실행할 때의 window.location 개체 예
{
"host": "",
"hostname": "",
"href": "about:srcdoc"
"origin": "null"
"pathname": "srcdoc"
"port": ""
"protocol": "about:"
}
따라서 블록에 window.location 개체를 사용해야 하는 경우 scripts.js 파일에 다음 함수를 추가하고 사용할 수 있도록 함수로 가져오는 것이 좋습니다.
/**
* Returns the true origin of the current page in the browser.
* If the page is running in a iframe with srcdoc, the ancestor origin is returned.
* @returns {String} The true origin
*/
export function getOrigin() {
const { location } = window;
return location.href === 'about:srcdoc' ? window.parent.location.origin : location.origin;
}
/**
* Returns the true of the current page in the browser.mac
* If the page is running in a iframe with srcdoc,
* the ancestor origin + the path query param is returned.
* @returns {String} The href of the current page or the href of the block running in the library
*/
export function getHref() {
if (window.location.href !== 'about:srcdoc') return window.location.href;
const { location: parentLocation } = window.parent;
const urlParams = new URLSearchParams(parentLocation.search);
return `${parentLocation.origin}${urlParams.get('path')}`;
}
lib-aem의 createOptimizedPicture 사용
lib-aem의 createOptimizedPicture 함수도 사용 window.location.href됩니다. 이 함수를 사용하는 경우 scripts.js(으)로 이동하여 위의 getHref() 함수를 사용하도록 수정하는 것이 좋습니다.
사이드 킥 라이브러리가 있는지 확인
사이드 킥 라이브러리에서 페이지 또는 블록이 실행되고 있는지 알고 싶을 수 있습니다. 이를 위해 몇 가지 옵션이 있습니다.
1. window.location.href === 'about:srcdoc' 확인
2. main 요소와 블록 요소에는 sidekick-library 클래스가 포함됩니다.
플러그인 구축
플러그인을 개발하는 것은 AEM에서 블록을 구성하는 것과 비슷합니다. 사용자가 플러그인을 로드하려고 하면 사이드 킥 라이브러리가 플러그인에서 decorate() 메서드를 트리거합니다. 이 메서드는에서 플러그인을 렌더링할 컨테이너와 플러그인 시트에 포함된 모든 데이터를 받습니다.
/**
* Called when a user tries to load the plugin
* @param {HTMLElement} container The container to render the plugin in
* @param {Object} data The data contained in the plugin sheet
* @param {String} query If search is active, the current search query
* @param {Object} context contains any properties set when the plugin was registered
*/
export async function decorate(container, data, query, context) {
// Render your plugin
}
> 플러그인에서 decorate() 함수를 내보내야 합니다.
플러그인 기본 내보내기 및 검색
플러그인에서 기본 내보내기를 사용하면 작성자가 로드 시 헤더에 표시되는 플러그인 이름을 사용자 지정하고 사이드 킥 라이브러리 내에서 검색 기능을 활성화할 수 있습니다.
export default {
title: 'Tags',
searchEnabled: true,
};
searchEnabled 속성이 true이면 플러그인을 로드할 때 라이브러리 헤더에 검색 아이콘이 표시됩니다. 사용자가 쿼리를 입력하여 검색을 시작하는 경우 플러그인의 decorate() 함수가 다시 트리거되며, 이번에는 decorate() 함수의 쿼리 매개 변수에 전달된 검색 문자열을 사용합니다.
플러그인 웹 구성 요소
플러그 인 작성자는 사용자 지정 플러그 인을 빌드할 때 Spectrum에서 선택한 웹 구성 요소 집합을 활용할 수 있습니다.
스펙트럼의 다음 구성 요소를 사용할 수 있습니다
스펙트럼의 다음 아이콘도 사용할 수 있습니다
플러그 인 이벤트
플러그인 작성자는 로더를 표시하거나 알림 메시지를 표시하기 위해 플러그인의 이벤트를 상위 사이드 킥 라이브러리로 발송할 수 있습니다.
알림 메시지
import { PLUGIN_EVENTS } from 'https://www.aem.live/tools/sidekick/library/events/events.js';
export async function decorate(container, data, query) {
// Show a toast message
container.dispatchEvent(new CustomEvent(PLUGIN_EVENTS.TOAST, { detail: { message: 'Toast Shown!', variant: 'positive | negative' } }))
}
로더 표시 및 숨기기
import { PLUGIN_EVENTS } from 'https://www.aem.live/tools/sidekick/library/events/events.js';
export async function decorate(container, data, query) {
// Show loader
container.dispatchEvent(new CustomEvent(PLUGIN_EVENTS.SHOW_LOADER))
...
// Hide loader
container.dispatchEvent(new CustomEvent(PLUGIN_EVENTS.HIDE_LOADER))
}