nuxtjs-drupal-ce

透過 Lupus 自定義元素渲染器連線 Nuxt 和 Drupal

2.4K 下載量•28 顆星•v2.4.2

fago•

maximilianmikus•

TurtlBbx

nuxtjs-drupal-ce - Nuxt Drupal 自定義元素聯結器

透過 Lupus 自定義元素渲染器連線 Nuxt v3 和 Drupal

有關更多資訊，請參閱 https://www.drupal.org/project/lupus_decoupled。

該模組的 2.x 版本與 Nuxt 3 相容。對於與 Nuxt 2 相容的版本，請檢視 1.x 版本

先決條件

已安裝 Drupal 後端，並安裝了 Lupus 自定義元素渲染器模組或 Lupus 解耦 Drupal。

設定

進入您的 Nuxt 專案。如有必要，啟動一個新專案

npx nuxi@latest init <project-name>

將 nuxtjs-drupal-ce 模組新增到您的 Nuxt 專案

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 解耦 Drupal 配合良好——在這種情況下，設定 drupalBaseUrl 足以開始使用。

搭建初始檔案。搭建完成後，根據需要進行編輯。

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

功能

透過 Lupus 自定義元素渲染器提供的自定義元素 API 獲取頁面
提供 Nuxt 萬用字元路由，以便所有 Drupal 頁面都可以透過 Nuxt.js 和 vue-router 渲染。
將頁面元資料和頁面標題與 Nuxt 整合。
支援麵包屑和本地任務（“標籤頁”）
支援經過身份驗證的請求。預設情況下，Cookie 會傳遞給 Drupal。
支援在前端顯示 Drupal 訊息。
提供無樣式的骨架元件，以便快速入門。
透過 Rest 選單項模組支援獲取和顯示 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 選單項 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 將被選擇用於渲染。

命名建議

我們建議使用 kebab-case 將元件命名為小寫，以便 API 響應中使用的自定義元素名稱與前端元件之間存在清晰的 1:1 對映。例如，使用 custom-element-name.vue 而不是 CustomElementName.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

表單處理程式中介軟體

表單處理程式中介軟體用於透過將表單 POST 請求轉發到 Drupal 並照常渲染響應來處理 Drupal 表單提交。此選項允許您繞過特定路由的中介軟體或全域性停用它。

路由級別

要繞過某些路由的表單處理程式中介軟體，您可以使用 disableFormHandler 選項並傳入路由陣列

export default defineNuxtConfig({
  drupalCe: {
    disableFormHandler: ['/custom-form'],
  },
})

全域性級別

要全域性停用表單處理程式中介軟體，您可以使用 disableFormHandler 選項並傳入 true

export default defineNuxtConfig({
  drupalCe: {
    disableFormHandler: true,
  },
})

已棄用的選項

以下選項已棄用，僅用於提高向後相容性。

baseURL: Drupal /ce-api 端點的基礎 URL，例如 https://: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。
使用 Lupus 解耦 Drupal 例項 URL 更新 Nuxt 配置中的 baseURL 設定，並附加 API 字首 /ce-api，例如 https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api

在 StackBlitz 上執行

在 StackBlitz 上啟動它
使用 Lupus 解耦 Drupal 例項 URL 更新 Nuxt 配置中的 baseURL 設定，並附加 API 字首 /ce-api，例如 https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api

許可證

麻省理工學院許可證

鳴謝

由 drunomics [email protected] 贊助開發