透過 100+ 個秘訣學習 Nuxt！
56.4K

drupal-ce
nuxtjs-drupal-ce

透過 Lupus Custom Elements Renderer 將 Nuxt 與 Drupal 連接
1.6K 下載
26 個星號
v2.2.5
fagofago
maximilianmikusmaximilianmikus
TurtlBbxTurtlBbx

nuxtjs-drupal-ce - Nuxt Drupal Custom Elements 連接器

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 進行呈現。

命名建議

我們建議使用小寫的 kebap-case 命名組件，以便在 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。如果設定，則 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：如果您想在執行階段呈現自訂元素標記，則這是必要的；即使用 'markup' 內容格式。相反，可以在 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