サイドキックライブラリとは？
サイドキックライブラリは、AEM サイドキックの拡張機能で、開発者がコンテンツ作成者向けの UI 駆動ツールを作成できるようにします。作成者にすべてのブロックのリストを直感的な方法で表示できる組み込みのブロックプラグインが含まれているので、作成者はブロックのあらゆるバリエーションを覚えたり検索したりする必要がなくなります。開発者は、サイドキックライブラリ用に独自のプラグインを作成することもできます。
Sidekick Library の使用方法
以下の手順では、サイドキックライブラリのセットアップ方法と、ブロックプラグインの設定方法について詳しく説明します。
ライブラリ シートの設定
サイドキックライブラリには、シートを使用したプラグインとプラグインのコンテンツが入力されます。
1.まず、SharePoint または gdrive で、ライブラリのコンテンツを保存するディレクトリを作成します。 コンテンツは、マウントポイントのルートの /tools/sidekick （または他の名前）に保存することをお勧めします。 次の手順では、ディレクトリが /tools/sidekick と呼ばれると仮定します。
2.次に、library （またはその他の名前）と呼ばれる /tools/sidekick ディレクトリにワークブック（Excel ファイル）を作成します。 ワークブック内の各シートは、Sidekick ライブラリによって読み込まれるプラグインを表します。 シートの名前によって、読み込まれるプラグインの名前が決まります。 シートに含まれるデータは、読み込み時にプラグインに渡されます。 プラグイン シート名の先頭には helix- が必要です。 例えば、tags というプラグインを読み込む場合、helix-tags という名前のシートを作成します。
3.このチュートリアルでは、blocks プラグイン用のシートを作成します。 シートを作成（または既定のシートの名前を変更）して'helix-blocks'と呼び、今のところ空のままにします。
Blocks プラグイン
Sidekick ライブラリには、blocks プラグインが付属しています。
ブロック プラグインの設定
ブロックプラグインのコンテンツを生成するには、含めるブロックごとに個別の Word ドキュメントを準備する必要があります。
1./tools/sidekick ディレクトリ内に、すべてのブロックバリエーションを保存するディレクトリを作成します。 例えば、/tools/sidekick 内に blocks というディレクトリを作成できます。
2.この例では、「columns」というブロックのすべてのバリエーションを定義するとします。 まず、blocks ディレクトリ内に columns という Word ドキュメントを作成し、columns ブロックのすべてのバリエーションの例を指定します。 ブロックの各バリエーションの後に、 セクション区切り文字を追加します。
3.columns ドキュメントをプレビューして公開します。
4.最後のセクションで作成したライブラリ ブックを開き、helix-blocks シート内に name と path という名前の 2 つの列を作成します。
6.次に、columns ブロックに行を追加する必要があります。 最初の列のブロック名と、2 番目の列のブロックのバリエーションを定義するドキュメントの URL を追加します。 例えば、columns ブロックを追加する場合は、名前が Columns でパスが /tools/sidekick/blocks/columns の行を作成できます。 ライブラリを複数の環境（ページ、ライブ、実稼動）で機能させるには、パス列に絶対 url を使用しないでください。
7.library ワークブックをプレビューして公開します。
> サンプルブロックは公開中なので、 一括メタデータを使用して、/tools/** 内のコンテンツのインデックスを作成しないようにする必要があります。
例 library.xlsx
ライブラリメタデータ
ブロックプラグインは library metadata という特殊なタイプのブロックをサポートしており、ブロックに関する情報やブロックのレンダリング方法を開発者がブロックプラグインに伝える手段を提供します。
サポートされるライブラリメタデータオプション
デフォルトのライブラリメタデータとライブラリメタデータ
library metadata には 2 つのタイプがあります。 ブロックを含むセクション内に存在するライブラリメタデータ library metadata デフォルト）。ドキュメント全体に適用され、それ自体がセクション内に存在する（セクション内の唯一の子として library metadata と呼ばれるブロック）。
5 つのバリアントを持つヒーローブロックの例を見てみましょう。 ブロックの各バリエーションに同じ説明を追加する場合、説明を含む library metadata を、バリエーションを含む各セクションに複製する必要はありません。 代わりに デフォルトlibrary metadata を使用して、ブロックのすべてのバリエーションに同じ説明を適用できます。 1 つのバリエーションに実際には少し異なる説明が必要な場合は、バリエーションを含むセクションに library metadata を追加すると、ブロックプラグイン内でレンダリングされる説明の デフォルトlibrary metadata を上書きできます。
ライブラリ メタデータを使用したブロック名と説明のオーサリング
デフォルトでは、ブロックプラグインで項目をレンダリングするために、（バリエーションを持つ）ブロック名が使用されます。 例えば、ブロックの名前が columns (center, background) の場合、その名前は、ブロックプラグインでレンダリングされるときにラベルとして使用されます。 これは、ブロックと同じセクション内に library metadata のセクションを作成することでカスタマイズできます。 ライブラリメタデータは、ブロックの説明の作成や、検索機能を使用する際にブロックのエイリアスを含めるための searchTags の追加にも使用できます。
カスタム名と説明を使用したブロックの例
コンテンツ
表示
自動ブロックとデフォルトコンテンツ
ブロックプラグインは、 デフォルトコンテンツおよび autoblocks をレンダリングできます。 これを実現するには、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 オブジェクトのキーは、プラグインの名前と一致する必要があります。プラグイン オブジェクトで定義されたその他のプロパティは、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'
}
> サイドキックライブラリに読み込むには、拡張ライブラリの library.json およびブロックで Access-Control-Allow-Origin ヘッダーを設定する必要があります。 詳しくは、 カスタム 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 関数も uses 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() 関数のクエリパラメーターで渡された検索文字列がトリガーされます。
プラグイン web コンポーネント
プラグイン作成者は、カスタムプラグインを構築する際に、Spectrum から選択した一連の web コンポーネントを利用できます。
Spectrum では、次のコンポーネントを使用できます
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))
}