Sidekick용 개발
이 문서의 목표는 개발자가 사이드 킥과 상호 작용하는 방법과 프로젝트 수준에서 이를 사용자 정의하는 방법을 설명하는 것입니다.
이벤트
사이드 킥은 다음 이벤트를 발생시킵니다.
event.detail 속성에서 이벤트의 페이로드를 찾을 수 있습니다.
이벤트 수신
프로젝트 코드(예: /scripts/scripts.js에서)에서는 다음과 같이 사이드 킥 이벤트에 반응할 수 있습니다(foo을(를) 수신하려는 이벤트 이름으로 바꾸기).
const doFoo = ({ detail: payload }) => {
console.log('something happened', payload);
// your custom code goes here
};
const sk = document.querySelector('aem-sidekick');
if (sk) {
// sidekick already loaded
sk.addEventListener('foo', doFoo);
} else {
// wait for sidekick to be loaded
document.addEventListener('sidekick-ready', () => {
// sidekick now loaded
document.querySelector('aem-sidekick')
.addEventListener('foo', doFoo);
}, { once: true });
}
Sidekick 맞춤화
프로젝트에 대한 사이드 킥을 사용자 지정할 수 있습니다. 프로젝트의 GitHub 저장소에 /tools/sidekick/config.json 구성 파일을 추가하거나 구성 서비스를 사용할 수 있습니다.
{
"project": "My project",
"host": "www.mydomain.prod",
"plugins": []
}
사용 가능한 모든 구성 옵션에 대해서는 구성 스키마를 참조하십시오. 다음은 시작하는 데 필요한 몇 가지 기본 사항입니다.
플러그인
플러그인을 사용하면 사이드 킥에 사용자 지정 기능을 추가할 수 있으므로 사용자 경험을 향상시킬 수 있습니다.
일반 플러그인 속성
다음 속성은 모든 플러그인 유형에 적용할 수 있습니다.
id(문자열)은 필수 항목이며 사이드 킥 구성 내에서 고유해야 합니다.- 플러그 인 단추에
title(문자열)이 표시됩니다. titleI18n(object<string, string>)은 선택적으로 번역된 제목을 정의합니다.pinned(부울)은 플러그인이 도구 모음(기본값)에 고정되었는지 또는 … 메뉴에 접혔는지 여부를 결정합니다.environments(string[])은 플러그인이 나타날 위치(dev, edit, admin, preview, live 또는 prod)를 지정합니다.exclude_paths(string[])은 현재 탭의 URL에 있는 경로를 기반으로 플러그인을 제외하는 패턴을 정의합니다.include_paths(string[])은 현재 탭의 URL에 있는 경로를 기반으로 플러그인을 포함하는 패턴을 정의합니다.
URL 기반 플러그인
플러그 인 단추를 클릭할 때 새 탭에서 열 url을(를) 지정할 수 있습니다.
{
"plugins": [
{
"id": "foo",
"title": "Foo",
"url": "/tools/sidekick/foo.html"
}
]
}
이벤트 기반 플러그인
또는 플러그 인 단추를 클릭할 때 실행할 event의 이름을 지정할 수 있습니다. 이렇게 하면 sidekick 요소에서 이벤트를 수신하여 페이지의 컨텍스트에서 사용자 지정 JavaScript 코드를 실행할 수 있습니다. 사용자 지정 이벤트에는 custom: 접두사가 있습니다. 편의상, 발송된 사용자 정의 이벤트에는 현재 사이드 킥 상태의 사본이 포함되어 있습니다.
참고: 이벤트 기반 플러그인은 개발, 미리 보기, 라이브 및 프로덕션 환경에서만 사용할 수 있습니다. 편집 또는 관리자에서는 사용자 지정 코드를 실행할 수 없습니다.
{
"plugins": [
{
"id": "foo",
"title": "Foo",
"event": "foo"
}
]
}
프로젝트 코드(예: /scripts/scripts.js에서)에서는 다음과 같이 이벤트에 반응할 수 있습니다.
const doFoo = ({ detail: payload }) => {
console.log('a custom event happened', payload);
// your custom code goes here
};
const sk = document.querySelector('aem-sidekick');
if (sk) {
// sidekick already loaded
sk.addEventListener('custom:foo', doFoo);
} else {
// wait for sidekick to be loaded
document.addEventListener('sidekick-ready', () => {
// sidekick now loaded
document.querySelector('aem-sidekick')
.addEventListener('custom:foo', doFoo);
}, { once: true });
}
특수 플러그인 유형
팔레트 플러그인
팔레트는 새 탭을 여는 대신 구성된 URL을 인라인으로 로드하는 URL 기반 플러그인의 변형입니다.
isPalette(부울)은 팔레트에서 새 탭 대신 URL 기반 플러그인의 대상을 엽니다.paletteRect(문자열)은 선택적으로 팔레트의 크기와 위치를 DOMRect 형식으로 정의합니다.
다음 예제에서는 창의 왼쪽 하단에 배치된 표준 팔레트를 만듭니다.
{
"plugins": [
{
"id": "tools",
"title": "Tools",
"url": "/tools/sidekick/foo-palette.html",
"isPalette": true
}
]
}
팔레트의 크기 및 위치를 변경하려면 paletteRect을(를) 사용하십시오.
{
"plugins": [
{
"id": "tools",
"title": "Tools",
"url": "/tools/sidekick/foo-palette.html",
"isPalette": true,
"paletteRect": "top:150px;left:7%;height:675px;width:85vw;"
}
]
}
컨테이너 플러그인
컨테이너를 사용하여 플러그인을 함께 그룹화하고 도구 모음의 공간을 절약할 수 있습니다. 컨테이너 플러그인을 클릭하면 자체 URL 또는 이벤트 작업이 있을 수 없습니다.
isContainer(부울)은 단추 대신 플러그인을 드롭다운으로 렌더링합니다.containerId(문자열)은 지정된 ID를 사용하여 컨테이너 플러그인에 플러그인을 추가합니다.
다음 예제에서는 "Tools"라는 컨테이너를 만들고 "Foo" 플러그인을 배치합니다.
{
"plugins": [
{
"id": "tools",
"title": "Tools",
"isContainer": true
},
{
"id": "foo",
"containerId": "tools",
"title": "Foo",
"event": "foo"
}
]
}
배지 플러그인
배지를 사용하면 특정 조건에서 사이드 킥에 레이블을 추가할 수 있습니다. 도구 모음의 오른쪽에 렌더링됩니다. 배지는 장식용으로 사용되며 클릭할 수 없습니다.
isBadge(부울)은 플러그인을 단추 대신 배지로 렌더링합니다.badgeVariant(문자열)은 선택적으로 배지의 색상 구성표(회색, 빨간색, 주황색, 노란색, chartreuse, 셀러리, 녹색, seafoam, cyan, blue, indigo, purple, fuchsia 또는 magenta)를 결정합니다.
다음 예제에서는 "Stage" 배지를 미리보기 환경의 사이드 킥에 추가합니다.
{
"plugins": [
{
"id": "stage",
"title": "Stage",
"isBadge": true,
"environments" ["preview"]
}
]
}
사용자 정의 편집 URL
프로젝트가 SharePoint 또는 Google 드라이브를 컨텐츠 소스로 사용하지 않는 경우 사용자가 편집 을 클릭할 때 사이드 킥에 사용자 지정 편집 환경에 연결하는 방법을 알려줄 수 있습니다.
다음 두 가지 구성 옵션을 사용할 수 있습니다.
editUrlLabel(문자열)이 사용자에게 표시되는 레이블을 설정합니다.editUrlPattern(문자열)은 사용자 지정 편집 환경에 대한 URL 패턴을 정의합니다.{{contentSourceUrl}}또는{{pathname}}과(와) 같은 자리 표시자를 지원합니다.
{
"editUrlLabel": "Your Editor",
"editUrlPattern": "{{contentSourceUrl}}{{pathname}}?cmd=open"
}
특별 보기
현재 탭의 URL이 특정 패턴과 일치하는 경우 리디렉션할 사이드 킥에 대한 특수 보기를 지정할 수 있습니다. 이렇게 하면 다양한 미디어 유형에서 원활한 사용자 경험을 제공할 수 있으며 사용자 지정 코드(이벤트 기반 플러그인)를 실행할 수도 있습니다. 원래 리소스 URL은 url 쿼리 매개 변수에서 사용할 수 있습니다.
path 및 viewer 속성은 필수입니다. 필요한 경우 맨 위에 표시되는 title을(를) 지정하고 titleI18n 개체에 지역화된 제목을 제공할 수 있습니다.
{
"specialViews": [
{
"title": "Custom JSON Viewer",
"path" : "**.json",
"viewer": "/tools/sidekick/custom-json-viewer/index.html"
}
]
}
viewer에서 지정한 경로에서 GitHub 저장소에 HTML 파일을 추가합니다. 예를 들면 다음과 같습니다.
<html>
<head>
<title>Custom JSON Viewer</title>
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="./custom-json-viewer.css">
<!-- add your custom code -->
<script src="./custom-json-viewer.js"></script>
</head>
<body>
</body>
</html>
동일한 디렉터리에 선택적 CSS 파일을 추가하고 사용자 지정 논리를 사용하여 JS 파일을 추가합니다. 예를 들면 다음과 같습니다.
try {
// get the resource URL from the url query parameter
const url = new URL(window.location.href).searchParams.get('url');
if (url) {
const res = await fetch(url);
if (res.ok) {
const text = await res.text();
const data = JSON.parse(text);
// do something with the data, e.g.
document.body.innerHTML = `
<pre>
${JSON.stringify(data, null, 2)}
</pre>
`;
} else {
throw new Error(`failed to load ${url}: ${res.status}`);
}
}
} catch (e) {
console.error('error rendering custom json view', e);
}
개발 워크플로
다음 워크플로는 프로덕션 사이트에서 작성자가 의도하지 않은 중단을 방지하기 위해 분리된 사이드 킥 개발용으로 설계되었습니다.
사이트 복사 사용
사이트 구성이 구성 서비스에 저장되어 있는 경우 임시 사이트 복사본을 사용하여 사이드 킥을 개발할 수 있습니다.
- 구성 서비스에서 사이트의 복사본을(를) 만듭니다. 예를 들어 원래 사이트의 이름이
site1인 경우 동일한 코드와 콘텐츠를 재사용하여site1-dev을(를) 만들 수 있습니다. - 브라우저에서
site1-dev의 미리 보기 URL을 엽니다.https://main--site1-dev--org.aem.page. site1-dev구성에서 사이드 킥 개체를 원하는 대로 변경합니다.- 변경 사항이 있을 때마다 브라우저 탭을 새로 고쳐 변경 사항을 테스트합니다.
- 완료되면
site1-dev에서site1구성으로 사이드 킥 개체를 복사하여 변경 내용을 모든 작성자에게 롤아웃합니다.
참고: 편집기 환경(Google 드라이브 또는 Microsoft Sharepoint)에서 사이드 킥을 사용하는 경우 기본적으로 원래 사이트에서 구성이 로드됩니다. 사이드 킥을 사용하여 로드할 구성을 선택하려면 먼저 미리 보기 또는 라이브 URL에서 사이드 킥에 새 사이트를 추가하십시오. 이제 사이드 킥에 일치하는 모든 사이트가 있는 선택기가 표시됩니다.
저장소 분기 사용
사이트 구성이 구성 서비스에 저장되지 않은 경우 GitHub의 분기를 사용하여 사이드 킥을 개발할 수 있습니다.
- 사이트의 GitHub 리포지토리에서
main에서 분기를 만듭니다. 이 예제에서는dev을(를) 분기 이름으로 사용합니다. - 브라우저에서
dev분기의 미리 보기 URL을 엽니다.https://dev--site1--org.aem.page. - 리포지토리에서
/tools/sidekick/config.json파일을 열거나 만듭니다. - 사이드 킥 구성 파일을 원하는 대로 변경하고
dev분기로 변경 내용을 푸시합니다. - 변경 사항이 있을 때마다 브라우저 탭을 새로 고쳐 변경 사항을 테스트합니다.
- 완료되면 끌어오기 요청을 만들고 변경 내용을 저장소의
main분기에 병합합니다.
주의: 원래 저장소의 main 분기에 직접 커밋하지 마십시오. main(으)로 병합하기 전에 항상 분기를 만들고 끌어오기 요청을 통해 변경 내용을 검토하도록 요청하세요.
참고: 편집기 환경(Google 드라이브 또는 Microsoft Sharepoint)에서 사이드 킥을 사용하는 경우 기본적으로 원래 사이트에서 구성이 로드됩니다. 사이드 킥을 사용하여 로드할 구성을 선택하려면 먼저 미리 보기 또는 라이브 URL에서 사이드 킥에 새 사이트를 추가하십시오. 이제 사이드 킥에 일치하는 모든 사이트가 있는 선택기가 표시됩니다.