nuxtjs-drupal-ce - Nuxt Drupal カスタム要素コネクタ

Lupus Custom Elements Renderer を介して Nuxt v3 を Drupal に接続します。

詳細については、https://www.drupal.org/project/lupus_decoupled を参照してください。

モジュールの 2.x バージョンは Nuxt 3 と互換性があります。Nuxt 2 互換バージョンについては、1.x バージョンをチェックアウトしてください。

前提条件

Drupal バックエンドと、Lupus Custom Elements Renderer モジュール、または Lupus Decoupled Drupal がインストールされていること。

セットアップ

Nuxt プロジェクトに移動します。必要に応じて、新しいプロジェクトを開始します。

npx nuxi@latest init <project-name>

Nuxt プロジェクトに nuxtjs-drupal-ce モジュールを追加します。

npx nuxi@latest module add drupal-ce

nuxt.config.js で nuxtjs-drupal-ce を設定します。

export default defineNuxtConfig({
  modules: [
    'nuxtjs-drupal-ce',
  ],
  drupalCe: {
    drupalBaseUrl: 'https://your-drupal.example.com',
    // more options...
  }
})

モジュールのデフォルトは Lupus Decoupled Drupal でうまく動作します。その場合、drupalBaseUrl を設定するだけで開始できます。

初期ファイルをスキャフォールドします。スキャフォールディング後、必要に応じて編集します。

rm -f app.vue && npx nuxt-drupal-ce-init

機能

Lupus Custom Elements Renderer によって提供されるカスタム要素 API を介してページをフェッチします。
Nuxt ワイルドカードルートを提供するため、すべての Drupal ページを Nuxt.js および vue-router を介してレンダリングできます。
ページメタデータとページタイトルを Nuxt と統合します。
パンくずリストとローカルタスク ("タブ") をサポートします。
認証済みリクエストをサポートします。Cookie はデフォルトで Drupal に渡されます。
フロントエンドでの Drupal メッセージの表示をサポートします。
すぐに開始できるように、スタイルのないスケルトンコンポーネントを提供します。
Rest menu items モジュールを介して Drupal メニューのフェッチと表示をサポートします。

オプション

drupalBaseUrl: Drupal のベース URL (例: https://example.com:8080)。必須。
serverDrupalBaseUrl: オプションで、サーバーコンテキストで適用する代替 Drupal ベース URL。
ceApiEndpoint: カスタム要素 API エンドポイント。デフォルトは /ce-api。
fetchOptions: Drupal からフェッチするときに適用するデフォルトの fetchOptions。デフォルトは { credentials: 'include' }。
fetchProxyHeaders: useRequestHeaders を介して Drupal に渡す HTTP リクエストヘッダー。デフォルトは ['cookie']。
menuEndpoint: メニューのフェッチに使用されるメニューエンドポイントパターン。Rest menu items Drupal モジュールによって提供される API に適合するように、デフォルトは 'api/menu_items/$$$NAME$$$' です。$$$NAME$$$ は、フェッチされるメニュー名に置き換えられます。
menuBaseUrl: メニューのベース URL。デフォルトは drupalBaseUrl + ceApiEndpoint。
addRequestContentFormat: 指定した場合、指定された値がリクエストに _content_format URL パラメータとして追加されます。デフォルトでは無効になっています。
addRequestFormat: true に設定すると、_format=custom_elements URL パラメータがリクエストに自動的に追加されます。デフォルトは false。
customErrorPages: デフォルトでは、Drupal によって提供されるエラーページ (例: 403、404 ページ) が、正しいステータスコードを維持しながら表示されます。customErrorPages を有効にすると、代わりに通常の Nuxt エラーページが表示されるため、ページを Nuxt でカスタマイズできます。デフォルトは false。
useLocalizedMenuEndpoint: 有効にすると、メニューエンドポイントは nuxtjs/i18n モジュールによって設定された言語プレフィックスを使用します。デフォルトは true。
serverApiProxy: 有効にすると、モジュールは、API リクエストを Drupal バックエンドにプロキシする Nitro サーバーハンドラーを作成します。SSR の場合はデフォルトで true (SSG の場合は無効)。
passThroughHeaders: Drupal からクライアントに渡すレスポンスヘッダー。デフォルトは 'cache-control', 'content-language', 'set-cookie', 'x-drupal-cache', 'x-drupal-dynamic-cache'。注: これは SSR モードでのみ使用可能です。
serverLogLevel: サーバー側のログに使用するログレベル。デフォルトは 'info'。オプション
- false: サーバープラグインはロードされず、デフォルトの Nuxt エラーログが維持されます。
- 'info': すべてのサーバーリクエストとエラーをログに記録します。
- 'error': エラーのみをログに記録します。

環境変数を使用したオプションのオーバーライド

ランタイム構成値は、NUXT_PUBLIC_ プレフィックスを介して環境変数でオーバーライドできます。サポートされているランタイムオーバーライド

drupalBaseUrl -> NUXT_PUBLIC_DRUPAL_CE_DRUPAL_BASE_URL
serverDrupalBaseUrl -> NUXT_PUBLIC_DRUPAL_CE_SERVER_DRUPAL_BASE_URL
menuBaseUrl -> NUXT_PUBLIC_DRUPAL_CE_MENU_BASE_URL
ceApiEndpoint -> NUXT_PUBLIC_DRUPAL_CE_CE_API_ENDPOINT

カスタム要素のレンダリング

一般に、カスタム要素は動的コンポーネントとしてレンダリングされ、グローバルコンポーネントとして登録するだけです。

コンポーネントは ~/components/global に配置する必要があります。例については、/playground ディレクトリを参照してください。たとえば、カスタム要素 node-article-teaser の場合、グローバルコンポーネント node-article-teaser.vue がレンダリングのために選択されます。

命名に関する推奨事項

API 応答で使用されるカスタム要素名とフロントエンドコンポーネントとの間に明確な 1 対 1 のマッピングがあるように、コンポーネントはケバブケースを使用して小文字で名前を付けることをお勧めします。たとえば、CustomElementName.vue の代わりに custom-element-name.vue を使用します。ただし、両方のバリアントが機能します。

デフォルトのコンポーネント (JSON のみ)

カスタム要素の JSON ベースのレンダリングを使用する場合、モジュールはフォールバックコンポーネントのサポートを提供します。カスタム要素に対応する Vue コンポーネントがない場合、モジュールは適切なデフォルトコンポーネントを検索しようとします。

仕組み

モジュールは、要素名から最後の - で区切られたプレフィックスを削除します。
次に、--default サフィックスを追加します。
この変更されたコンポーネントが存在する場合、レンダリングに使用されます。
コンポーネントが存在しない場合、プロセスが繰り返されます。

このアプローチにより、drupal-form--default.vue のような汎用的なデフォルトコンポーネントを、drupal-form-user-login-form.vue のような特定の要素に使用できます。カスタマイズのために、開発者は必要に応じてデフォルトコンポーネントをコピーして変更できます。

ルックアッププロセスの例

特定のコンポーネントが見つからない場合、モジュールはカスタム要素名からセグメントを段階的に削除してデフォルトコンポーネントを検索します。たとえば、カスタム要素 node-custom-view をレンダリングする場合、次の順序でコンポーネントを検索します。

x node-custom-view.vue
x node-custom-view--default.vue
x node-custom--default.vue
✓ node--default.vue

非推奨のオプション

以下のオプションは非推奨であり、下位互換性を向上させるためだけに残されています。

baseURL: Drupal /ce-api エンドポイントのベース URL (例: https://127.0.0.1:8888/ce-api)。設定した場合、drupalBaseUrl は、指定された URL のオリジンで設定されます。

エラー処理

モジュールは、fetchPage および fetchMenu メソッドのデフォルトのエラーハンドラーを提供します。

fetchPage: Drupal によって提供されたステータスコードとメッセージを含むエラーをスローします。
fetchMenu: エラーメッセージをコンソールにログ記録し、フロントエンドにメッセージを表示します。

エラー処理のカスタマイズ

fetch メソッドを呼び出すときにパラメータを使用することで、デフォルトのエラーハンドラーをオーバーライドするオプションがあります。

fetchPage:

<script lang="ts" setup>
  const { fetchPage } = useDrupalCe()

  function customPageError (error: Record<string, any>) {
    throw createError({ statusCode: error.value.statusCode, statusMessage: 'No access.', data: {}, fatal: true })
  }
  const page = await fetchPage(useRoute().path, { query: useRoute().query }, customPageError)
</script>

fetchMenu:

<script lang="ts" setup>
  const { fetchMenu } = useDrupalCe()
  const { getMessages } = useDrupalCe()
  const messages = getMessages()

  function customMenuError (error: Record<string, any>) {
    messages.value.push({
      type: 'error',
      message: `Menu error: Unavailable. ${error.value.statusCode}`
    })
  }
  const mainMenu = await fetchMenu('main', {}, customMenuError)
</script>

注: error パラメータはオプションであり、省略できます。

2.x バージョンでサポートされていない以前のオプション

次のオプションは 1.x でサポートされていましたが、削除されました。

addVueCompiler: これは、カスタム要素マークアップをランタイムでレンダリングする場合 (つまり、「マークアップ」コンテンツ形式を使用する場合) に必要です。代わりに、Vue ランタイムコンパイラは Nuxt 構成で有効にできます。こちらを参照してください。
axios: drupal-ceaxios インスタンスに渡すオプション。fetchOptions を代わりに使用してください。

開発

このリポジトリをクローンします。
npm install を使用して依存関係をインストールします。
npm run dev:prepare を実行して、型スタブを生成します。
npm run dev を使用して、開発モードでplayground を開始します。
Nuxt 構成の baseURL 設定を Lupus Decoupled Drupal インスタンス URL で更新し、API プレフィックス /ce-api を追加します。例: https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api

StackBlitz で実行

StackBlitz で起動します。
Nuxt 構成の baseURL 設定を Lupus Decoupled Drupal インスタンス URL で更新し、API プレフィックス /ce-api を追加します。例: https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api

ライセンス

MIT ライセンス

クレジット

drunomics hello@drunomics.com が開発をスポンサーしました