透過 100 多個技巧學習 Nuxt！
55.5K

drupal-ce
nuxtjs-drupal-ce

透過 Lupus Custom Elements Renderer 連接 Nuxt 與 Drupal
1.2K 下載
25 顆星
v2.1.2
fagofago
maximilianmikusmaximilianmikus
TurtlBbxTurtlBbx

nuxtjs-drupal-ce - Nuxt Drupal 自訂元素連接器

npm versionnpm downloadscicodecovLicense

透過 Lupus Custom Elements Renderer 將 Nuxt v3 連接到 Drupal

請參考 https://www.drupal.org/project/lupus_decoupled 以獲取更多資訊。

此模組的 2.x 版本與 Nuxt 3 相容。對於 Nuxt 2 相容版本，請查看 1.x 版本

先決條件

設定

  1. 前往您的 Nuxt 專案。如有必要，請建立一個新的專案
npx nuxi@latest init <project-name>
  1. 將 nuxtjs-drupal-ce 模組新增至您的 Nuxt 專案
npx nuxi@latest module add drupal-ce
  1. 在您的 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 就足以開始使用。

  1. 建立初始檔案。建立之後，請根據您的需求編輯它們。
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：用於擷取選單的選單端點模式。預設值為 'api/menu_items/$$$NAME$$$'，以符合 Rest menu items Drupal 模組提供的 API。$$$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：如果啟用，此模組會建立一個 Nitro 伺服器處理常式，將 API 要求代理至 Drupal 後端。對於 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'：僅記錄錯誤。
  • disableFormHandler：如果設定為 true，將停用表單處理常式中介軟體。預設值為 false。

使用環境變數覆寫選項

執行時間組態值可以透過 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 對應關係。例如，使用 custom-element-name.vue 而不是 CustomElementName.vue。這兩種變體都能運作。

預設元件（僅限 JSON）

當使用自訂元素的 JSON 基礎呈現時，該模組會提供回退元件支援。如果自訂元素缺少對應的 Vue 元件，該模組會嘗試尋找合適的預設元件。

運作方式

  1. 該模組會從元素名稱中移除最後一個以 - 分隔的前綴。
  2. 然後，它會附加 --default 後綴。
  3. 如果存在此修改的元件，則會使用它進行呈現。
  4. 如果元件不存在，則會重複此過程。

此方法允許將一般預設元件（如 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。如果設定，則會使用提供的 URL 的來源設定 drupalBaseUrl。

錯誤處理

該模組為 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：如果您想在執行時間呈現自訂元素標記，則必須使用此選項；即使用「標記」內容格式。相反地，可以在 Nuxt 設定中啟用 Vue 執行時間編譯器，請參閱此處。
  • axios：傳遞到 drupal-ceaxios 執行個體的選項。請改用 fetchOptions。

開發

  1. 複製此儲存庫。
  2. 使用 npm install 安裝相依性。
  3. 執行 npm run dev:prepare 以產生類型存根。
  4. 使用 npm run dev 以在開發模式下啟動 playground。
  5. 使用 Lupus Decoupled Drupal 執行個體 URL 更新 Nuxt 設定中的 baseURL 設定，並附加 API 前綴 /ce-api，例如 https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api

在 StackBlitz 上執行

  1. 在 StackBlitz 上啟動它
  2. 使用 Lupus Decoupled Drupal 執行個體 URL 更新 Nuxt 設定中的 baseURL 設定，並附加 API 前綴 /ce-api，例如 https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api

授權

MIT 授權

感謝

由 drunomics 贊助開發 hello@drunomics.com