AEM 開発者向けのユニバーサルエディターの概要 developer-overview

ユニバーサルエディターの動作およびプロジェクトでのユニバーサルエディターの使用方法について興味がある AEM 開発者向けに、このドキュメントでは、WKND プロジェクトをユニバーサルエディターと連携させる方法を説明することで、エンドツーエンドの導入について説明します。

目的 purpose

このドキュメントは、ユニバーサルエディターの機能およびアプリケーションを使用するための実装方法の両方について、開発者向けに説明します。

この説明には、ほとんどの AEM 開発者が精通している標準的な例、コアコンポーネントと WKND サイトを参照し、そして、ユニバーサルエディターを使用して編集可能ないくつかのサンプルコンポーネントを実装します。

TIP
このドキュメントでは、ユニバーサルエディターの仕組みを追加の手順を説明し、開発者がエディターに対する理解を深めることを目的としています。したがって、アプリを実装するための最も直接的なルートではありませんが、ユニバーサルエディターとその仕組みを最もわかりやすく説明します。
できるだけすぐに使い始めるには場合は、AEM のユニバーサルエディターの概要ドキュメントを参照してください。

前提条件 prerequisites

この概要に従うには、次が必要になります。

このドキュメントは、web 開発に一般的に精通しているだけでなく、AEM 開発に関する基本的な知識を前提としています。AEM の開発経験がない場合は、続行する前に WKND チュートリアルを確認することを考慮してください。

AEM の起動およびユニバーサルエディターへのログイン sign-in

まだ実行していない場合は、前提条件で詳しく説明されるように、WKND をインストールし、HTTPS を有効にしてローカルの AEM 開発インスタンスを実行する必要があります。この概要は、インスタンスが https://localhost:8443 で実行されていることを前提としています。

  1. AEM エディターで WKND 英語メインページを開きます。

    code language-text
    https://localhost:8443/editor.html/content/wknd/language-masters/en.html
    
  2. エディターの​ ページ情報 ​メニューで、「公開済みとして表示」を選択します。新しいタブで同じページが開き、AEM エディターが無効になります。

    code language-text
    https://localhost:8443/content/wknd/language-masters/en.html?wcmmode=disabled
    
  3. このリンクをコピーします。

  4. 次に、ユニバーサルエディターにログインします。

    code language-text
    https://experience.adobe.com/#/aem/editor
    
  5. 以前に、WKND コンテンツをコピーしたリンクをユニバーサルエディターの「サイトの URL」フィールドに貼り付け、「開く」をクリックします。

    ユニバーサルエディターで WKND ページを開く

ユニバーサルエディターによるコンテンツの読み込みの試行 sameorigin

ユニバーサルエディターは、フレーム内で編集するコンテンツを読み込みます。AEM の X-Frame オプションのデフォルト設定により、この問題が回避されます。これは、WKND のローカルコピーを読み込もうとすると、ブラウザーでエラーとして表示され、コンソール出力で詳しく説明されます。

SAMEORIGIN オプションが原因のブラウザーエラー

X-Frame オプションの sameorigin は、フレーム内での AEM ページのレンダリングを防ぎます。このヘッダーを削除して、ユニバーサルエディターでページを読み込めるようにする必要があります。

  1. Configuration Manager を開きます。

    code language-text
    https://localhost:8443/system/console/configMgr
    
  2. OSGi 設定 org.apache.sling.engine.impl.SlingMainServlet の編集

    SAMEORIGIN の OSGi プロパティ

  3. 追加の応答ヘッダー ​プロパティの X-Frame-Options=SAMEORIGIN プロパティを削除します。

  4. 変更内容を保存します。

次に、ユニバーサルエディターを再読み込みすると、AEM ページが読み込まれます。

TIP

ユニバーサルエディターがページを読み込むと、そのページは AEM のログインページに読み込まれ、変更を加えるための認証が行われていることを確認します。

ただし、正常にログインできません。ブラウザーコンソールを表示すると、ブラウザがフレーム上の入力をブロックしていることがわかります。

入力がブロックされました

ログイントークン cookie は、サードパーティドメインとして AEM に送信されます。したがって、AEM では SameSite cookie を許可する必要があります。

  1. Configuration Manager を開きます。

    code language-text
    https://localhost:8443/system/console/configMgr
    
  2. OSGi 設定を編集しますcom.day.crx.security.token.impl.impl.TokenAuthenticationHandler

    SameSite cookie の OSGi プロパティ

  3. login-token cookie の SameSite 属性 ​プロパティを None に変更します。

  4. 変更内容を保存します。

ユニバーサルエディターを再読み込みすると、AEM に正常にログインでき、ターゲットページが読み込まれます。

TIP

ユニバーサルエディターをリモートフレームに接続 ue-connect-remote-frame

ユニバーサルエディターにページが読み込まれ、AEM にサインインすると、ユニバーサルエディターはリモートフレームへの接続を試みます。これは、リモートフレームに読み込む必要がある JavaScript ライブラリを介して行われます。JavaScript ライブラリが存在しない場合、ページは最終的にコンソールでタイムアウトエラーを生成します。

タイムアウトエラー

必要な JavaScript ライブラリを WKND アプリのページコンポーネントに追加する必要があります。

  1. CRXDE Lite を開きます。

    code language-text
    https://localhost:8443/crx/de
    
  2. /apps/wknd/components/page の下で、ファイル customheaderlibs.html を編集します。

    customheaderlibs.html ファイルの編集

  3. ファイルの最後に JavaScript ライブラリを追加します。

    code language-html
    <script src="https://universal-editor-service.experiencecloud.live/corslib/LATEST"></script>
    
  4. すべて保存」をクリックして、次にユニバーサルエディターを再読み込みします。

これで、ページが適切な JavaScript ライブラリで読み込まれて、ユニバーサルエディターがページに接続できるようになり、タイムアウトエラーがコンソールに表示されなくなりました。

TIP
  • ライブラリは、ヘッダーまたはフッターに読み込むことができます。
  • universal-editor-embedded.js ライブラリは NPMで使用でき、必要に応じて自分でホストしたり、アプリケーションに直接配置したりできます。

変更を保持する接続の定義 connection

WKND ページがユニバーサルエディターに正常に読み込まれ、JavaScript ライブラリが読み込まれて、エディターがアプリに接続されるようになりました。

ただし、ユニバーサルエディターではページを操作できないはずです。実際に、ユニバーサルエディターでページを編集することはできません。ユニバーサルエディターでコンテンツを編集するには、コンテンツの書き込み先を認識できるように接続を定義する必要があります。ローカル開発の場合は、https://localhost:8443 のローカル AEM 開発インスタンスに書き戻す必要があります。

  1. CRXDE Lite を開きます。

    code language-text
    https://localhost:8443/crx/de
    
  2. /apps/wknd/components/page の下で、ファイル customheaderlibs.html を編集します。

    customheaderlibs.html ファイルの編集

  3. ローカル AEM インスタンスへの接続に必要なメタデータをファイルの最後に追加します。

    code language-html
    <meta name="urn:adobe:aue:system:aem" content="aem:https://localhost:8443">
    
  4. ローカルユニバーサルエディターサービスへの接続に必要なメタデータをファイルの最後に追加します。

    code language-html
    <meta name="urn:adobe:aue:config:service" content="https://localhost:8000">
    
  5. すべて保存」をクリックして、次にユニバーサルエディターを再読み込みします。

ユニバーサルエディターは、ローカル AEM 開発インスタンスからコンテンツを正常に読み込むだけでなく、ローカルユニバーサルエディターサービスを使用して行った変更を保持する場所を認識することもできるようになりました。これは、アプリをユニバーサルエディターで編集できるようにするための最初の手順です。

TIP

コンポーネントの実装 instrumenting-components

しかし、ユニバーサルエディターで実行できる操作はまだほとんどありません。ユニバーサルエディターで WKND ページの上部にあるティーザーをクリックしようとしても、実際にそのティーザー(またはページ上のその他の要素)を選択することはできません。

ユニバーサルエディターで編集できるようにするには、コンポーネントも実装する必要があります。これを行うには、ティーザーコンポーネントを編集する必要があります。そのためには、コアコンポーネントが不変の /libs の配下に存在しているので、コアコンポーネントをオーバーレイする必要があります。

  1. CRXDE Lite を開きます。

    code language-text
    https://localhost:8443/crx/de
    
  2. ノード /libs/core/wcm/components を選択し、ツールバーで「ノードをオーバーレイ」をクリックします。

  3. オーバーレイの場所」として /apps/ を選択し、「OK」をクリックします。

    ティーザーをオーバーレイ

  4. /libs/core/wcm/components の下の teaser ノードを選択し、ツールバーの「コピー」をクリックします。

  5. /apps/core/wcm/components でオーバーレイされたノードを選択し、ツールバーの「貼り付け」をクリックします。

  6. /apps/core/wcm/components/teaser/v2/teaser/teaser.html ファイルをダブルクリックして編集します。

    teaser.html ファイルの編集

  7. 最初の div の終わり付近、おおよそ 26 行目に、コンポーネントの実装の詳細を追加します。

    code language-text
    data-aue-resource="urn:aem:${resource.path}"
    data-aue-type="component"
    data-aue-label="Teaser"
    
  8. ツールバーの「すべて保存」をクリックして、ユニバーサルエディターを再読み込みします。

  9. ユニバーサルエディターで、ページ上部のティーザーコンポーネントをクリックし、選択できることを確認します。

  10. ユニバーサルエディターのプロパティパネルで​ コンテンツツリー ​アイコンをクリックすると、エディターがページのあらゆるティーザーを認識しており、エディターの実装が完了したことがわかります。選択したティーザーがハイライト表示されています。

    インストルメント済みティーザーコンポーネントの選択

TIP
ノードのオーバーレイについて詳しくは、Adobe Experience Manager as a Cloud Service での Sling Resource Merger の使用ドキュメントを参照してください。

ティーザーのインストルメントサブコンポーネント subcomponents

これで、ティーザーを選択できるようになりましたが、まだ編集はできません。これは、ティーザーが画像やタイトルのコンポーネントなど、様々なコンポーネントの複合体であるためです。このようなサブコンポーネントを編集するには、対象のサブコンポーネントを実装する必要があります。

  1. CRXDE Lite を開きます。

    code language-text
    https://localhost:8443/crx/de
    
  2. ノード /apps/core/wcm/components/teaser/v2/teaser/ を選択し、title.html ファイルをダブルクリックします。

    title.html ファイルを編集する

  3. h2 タグの最後(17 行目付近)に、次のプロパティを挿入します。

    code language-text
    data-aue-prop="jcr:title"
    data-aue-type="text"
    data-aue-label="Title"
    
  4. ツールバーの「すべて保存」をクリックして、ユニバーサルエディターを再読み込みします。

  5. ページ上部の同じティーザーコンポーネントのタイトルをクリックし、選択できることを確認します。コンテンツツリーには、選択したティーザーコンポーネントの一部としてタイトルも表示されます。

    ティーザー内でタイトルを選択する

これで、ティーザーコンポーネントのタイトルを編集できます。

内容の確認? what-does-it-mean

ティーザーのタイトルを編集できるようになったところで、行った操作と達成方法について確認してみましょう。

ティーザーコンポーネントを実装することで、ティーザーコンポーネントをユニバーサルエディターで識別できるようになりました。

  • data-aue-resource は編集中の AEM 内のリソースを識別します。
  • data-aue-type は、項目が(コンテナとは異なり)ページコンポーネントとして扱われることを定義します。
  • data-aue-label は、選択したティーザーのわかりやすいラベルを UI に表示します。

また、ティーザーコンポーネント内にタイトルコンポーネントも実装しました。

  • data-aue-prop は、書き込まれる JCR 属性です。
  • data-aue-type は、属性の編集方法です。この場合、タイトルなので、テキストエディター(リッチテキストエディターとは異なる)を使用します。

認証ヘッダーの定義 auth-header

これで、ティーザーのタイトルをインラインで編集でき、変更がブラウザーに保持されます。

ティーザーの編集済みタイトル

ただし、ブラウザーを再読み込みすると、前のタイトルが再読み込みされます。これは、ユニバーサルエディターが AEM インスタンスへの接続方法を理解していても、まだ AEM インスタンスに対して認証を行い、JCR に変更を書き戻すことができないためです。

ブラウザー開発者ツールの「ネットワーク」タブを表示し、update を検索すると、タイトルを編集しようとしたときに 401 エラーが発生することがわかります。

タイトルを編集しようするとエラーが発生する

ユニバーサルエディターを使用して実稼動用 AEM コンテンツを編集する場合、ユニバーサルエディターは、JCR への書き戻しを容易にするために、エディターにログオンする際に使用したのと同じ IMS トークンを使用して AEM への認証を行います。

ローカルで開発している場合、IMS トークンはアドビが所有するドメインにのみ渡されるため、AEM ID プロバイダーを使用できません。認証ヘッダーを明示的に設定して、認証する方法を手動で指定する必要があります。

  1. ユニバーサルエディターインターフェイスで、ツールバーの​ 認証ヘッダー ​アイコンをクリックします。

  2. ローカル AEM インスタンスへの認証に必要な認証ヘッダーをコピーし、「保存」をクリックします。

    認証ヘッダーの設定

  3. ユニバーサルエディターを再読み込みして、ティーザーのタイトルを編集します。

ブラウザーコンソールにエラーが表示されなくなり、変更内容はローカルの AEM 開発インスタンスに保持されます。

ブラウザーの開発者ツールでトラフィックを調査し、update イベントを探すと、更新の詳細を確認できます。

ティーザータイトルの編集に成功しました

{
  "connections": [
    {
      "name": "aem",
      "protocol": "aem",
      "uri": "https://localhost:8443"
    }
  ],
  "target": {
    "resource": "urn:aem:/content/wknd/language-masters/en/jcr:content/root/container/carousel/item_1571954853062",
    "type": "text",
    "prop": "jcr:title"
  },
  "value": "Tiny Toon Adventures"
}
  • connections は、ローカルの AEM インスタンスへの接続です。
  • target は、JCR で更新される正確なノードおよびプロパティです。
  • value は自分が行った更新です。

変更が JCR に保持されていることがわかります。

JCR での更新

TIP
テストや開発の目的で必要な認証ヘッダーを生成するオンラインツールが多数あります。
基本的な認証ヘッダーの例 Basic YWRtaW46YWRtaW4= は、admin:admin のユーザーとパスワードの組み合わせに対するもので、ローカル AEM 開発では一般的です。

プロパティパネル用のアプリの実装 properties-rail

これで、ユニバーサルエディターを使用して編集できるように実装されたアプリが完成しました。

編集は、現在、ティーザーのタイトルのインライン編集に限られています。ただし、インプレース編集では不十分な場合があります。ティーザーのタイトルなどのテキストは、キーボード入力を使用して編集できます。ただし、より複雑な項目は、ブラウザーでのレンダリング方法とは別に、構造化データを表示して編集できる必要があります。プロパティパネルはこの機能を備えています。

プロパティレールを使用して編集するようにアプリを更新するには、アプリのページコンポーネントのヘッダーファイルに戻ります。この場所では、ローカルの AEM 開発インスタンスおよびローカルのユニバーサルエディターサービスへの接続が既に確立されています。ここで、アプリ内で編集可能なコンポーネントとそのデータモデルを定義する必要があります。

  1. CRXDE Lite を開きます。

    code language-text
    https://localhost:8443/crx/de
    
  2. /apps/wknd/components/page の下で、ファイル customheaderlibs.html を編集します。

    customheaderlibs.html ファイルの編集

  3. ファイルの最後に、コンポーネントを定義するために必要なスクリプトを追加します。

    code language-html
    <script type="application/vnd.adobe.aue.component+json">
    {
      "groups": [
        {
          "title": "General Components",
          "id": "general",
          "components": [
            {
              "title": "Teaser",
              "id": "teaser",
              "plugins": {
                "aem": {
                  "page": {
                    "resourceType": "wknd/components/teaser"
                  }
                }
              }
            },
            {
              "title": "Title",
              "id": "title",
              "plugins": {
                "aem": {
                  "page": {
                    "resourceType": "wknd/components/title"
                  }
                }
              }
            }
          ]
        }
      ]
    }
    </script>
    
  4. その下で、モデルを定義するために必要なスクリプトをファイルの最後に追加します。

    code language-html
    <script type="application/vnd.adobe.aue.model+json">
    [
      {
        "id": "teaser",
        "fields": [
          {
            "component": "text-input",
            "name": "jcr:title",
            "label": "Title",
            "valueType": "string"
          },
          {
            "component": "text-area",
            "name": "jcr:description",
            "label": "Description",
            "valueType": "string"
          }
        ]
      },
      {
        "id": "title",
        "fields": [
          {
            "component": "select",
            "name": "type",
            "value": "h1",
            "label": "Type",
            "valueType": "string",
            "options": [
              { "name": "h1", "value": "h1" },
              { "name": "h2", "value": "h2" },
              { "name": "h3", "value": "h3" },
              { "name": "h4", "value": "h4" },
              { "name": "h5", "value": "h5" },
              { "name": "h6", "value": "h6" }
            ]
          }
        ]
      }
    ]
    </script>
    
  5. ツールバーで「すべて保存」をクリックします。

内容の確認? what-does-it-mean-2

プロパティパネルを使用して編集するには、コンポーネントを groups に割り当てる必要があるため、各定義は、コンポーネントを含むグループのリストとして開始します。

  • title はグループの名前です。
  • id はグループの一意の識別子です。この場合、例えば、ページレイアウトの高度なコンポーネントなどとは異なり、ページコンテンツを構成する一般的なコンポーネントです。

各グループには components の配列があります。

  • title はコンポーネントの名前です。
  • id はコンポーネントの一意の識別子です。この場合はティーザーです。

各コンポーネントには、コンポーネントを AEM にマッピングする方法を定義するプラグイン定義が含まれます。

  • aem は編集を処理するプラグインです。これは、コンポーネントを処理するサービスと考えることができます。
  • page はコンポーネントの種類を定義します。この場合は標準ページコンポーネントです。
  • resourceType は実際の AEM コンポーネントへのマッピングです。

次に、各コンポーネントを model にマッピングして、個々の編集可能フィールドを定義する必要があります。

  • id はモデルの一意の識別子です。この識別子は、コンポーネントの ID と一致する必要があります。
  • fields は個々のフィールドの配列です。
  • component はテキストやテキスト領域などの入力のタイプです。
  • name はフィールドのマッピング先の JCR 内のフィールド名です。
  • label はエディター UI に表示されるフィールドの説明です。
  • valueType はデータのタイプです。

プロパティパネル用のコンポーネントの実装 properties-rail-component

また、コンポーネントで使用するモデルをコンポーネントレベルで定義する必要があります。

  1. CRXDE Lite を開きます。

    code language-text
    https://localhost:8443/crx/de
    
  2. /apps/core/wcm/components/teaser/v2/teaser/teaser.html ファイルをダブルクリックして編集します。

    teaser.html ファイルの編集

  3. 最初の div の終わり付近、おおよそ 32 行目で、前に追加したプロパティの後に、ティーザーコンポーネントで使用するモデルの実装の詳細を追加します。

    code language-text
    data-aue-model="teaser"
    
  4. ツールバーの「すべて保存」をクリックして、ユニバーサルエディターを再読み込みします。

これで、コンポーネント用に実装されたプロパティパネルをテストする準備が整いました。

  1. ユニバーサルエディターで、ティーザーのタイトルをクリックして、もう一度編集します。

  2. プロパティパネルをクリックして「プロパティ」タブを表示し、実装したフィールドを確認します。

    実装したプロパティパネル

ティーザーのタイトルを以前のようにインラインで編集することも、プロパティパネルで編集することもできるようになりました。どちらの場合も、変更はローカル AEM 開発インスタンスに保持されます。

プロパティパネルに追加フィールドを追加 add-fields

既に実装したコンポーネントのデータモデルの基本構造を使用して、同じモデルに従って、フィールドを追加できます。

例えば、フィールドを追加して、コンポーネントのスタイルを調整できます。

  1. CRXDE Lite を開きます。

    code language-text
    https://localhost:8443/crx/de
    
  2. /apps/wknd/components/page の下で、ファイル customheaderlibs.html を編集します。

    customheaderlibs.html ファイルの編集

  3. モデル定義スクリプトで、スタイルフィールドの fields 配列に項目を追加します。新しいフィールドを挿入する前に、最後のフィールドの後にコンマを追加します。

    code language-json
    {
       "component": "select",
       "name": "cq:styleIds",
       "label": "Style",
       "valueType": "string",
         "multi": true,
       "options": [
         {"name": "hero", "value":"1555543212672"},
         {"name": "card", "value":"1605057868937"}
       ]
    }
    
  4. ツールバーの「すべて保存」をクリックして、ユニバーサルエディターを再読み込みします。

  5. ティーザーのタイトルをクリックして、もう一度編集します。

  6. プロパティパネルをクリックして、コンポーネントのスタイルを調整するための新しいフィールドがあることを確認します。

    スタイルフィールドを含む実装したプロパティパネル

この方法で、コンポーネントの JCR 内の任意のフィールドをユニバーサルエディターで公開できます。

概要 summary

これで完了です。独自の AEM アプリを実装して、ユニバーサルエディターを操作できるようになりました。

独自のアプリの実装を開始する際は、この例で実行した基本的な手順に注意してください。

  1. 開発環境を設定します。

    • WKND がインストールされた HTTPS 上でローカルに実行される AEM
    • HTTPS 上でローカルに実行されるユニバーサルエディターサービス
  2. AEM の OSGi 設定を更新して、そのコンテンツをリモートで読み込めるようにしました。

  3. 次の項目を追加しました。

  4. 次の項目の変更を保持するための接続を定義しました。

    • ローカル AEM 開発インスタンスへの接続を定義しました。
    • また、ローカルのユニバーサルエディターサービスへの接続も定義しました。
  5. ティーザーコンポーネントを実装しました。

  6. ティーザーのサブコンポーネントを実装しました。

  7. ローカルのユニバーサルエディターサービスを使用して変更を保存できるように、カスタム認証ヘッダーを定義しました。

  8. プロパティパネルを使用するアプリを実装しました。

  9. プロパティパネルを使用するティーザーコンポーネントを実装しました。

これらと同じ手順に従って、ユニバーサルエディターで使用するために独自のアプリを実装できます。JCR 内の任意のプロパティをユニバーサルエディターに公開できます。

その他のリソース additional-resources

ユニバーサルエディターの機能について詳しくは、次のドキュメントを参照してください。

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab