nuxtjs-drupal-ce

通过 Lupus Custom Elements Renderer 连接 Nuxt 和 Drupal

2.3K 下载•28 星•v2.5.0-rc.1

fago•

maximilianmikus•

TurtlBbx

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>

将 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 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：用于获取菜单的菜单端点模式。默认为 '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。
customElementJsonFormat：指定自定义元素的 JSON 格式。选项
- 'explicit'：建议的格式，带有独立的 props 和 slots 对象（默认）。如果检测到不同结构，则自动回退到旧版格式。
- 'legacy'：旧版格式，props 和 slots 扁平化在同一级别。为了提高与旧后端兼容性，请显式配置此选项。默认为 'explicit'。
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 将被用于渲染。

JSON 格式选项

该模块支持两种自定义元素的 JSON 格式

显式格式（默认，推荐）

{
  "element": "node-article-teaser",
  "props": {
    "title": "Article Title",
    "nid": 123
  },
  "slots": {
    "default": "Content goes here",
    "sidebar": { "element": "drupal-block", "props": {...} }
  }
}

旧版格式（用于向后兼容）

{
  "element": "node-article-teaser",
  "title": "Article Title",
  "nid": 123,
  "default": "Content goes here"
}

显式格式将 props 与 slots 明确分开，使结构更易于维护。

兼容性说明：默认的 'explicit' 格式在检测到不同结构时会自动回退到旧版格式。但是，为了提高与旧版 Drupal 后端的兼容性，建议显式配置 customElementJsonFormat: 'legacy'。

命名建议

我们建议使用 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：如果您想在运行时渲染自定义元素标记；即使用“markup”内容格式，则这是必需的。相反，可以通过 Nuxt 配置启用 vue 运行时编译器，请参阅此处。
axios：传递给 drupal-ceaxios 实例的选项。请改用 fetchOptions。

开发

克隆此仓库
安装依赖：npm install
生成类型存根：npm run dev:prepare
在开发模式下启动 playground：npm run dev
在 playground/nuxt.config.ts 中配置 drupalBaseUrl 指向您的 Drupal 实例

在 StackBlitz 上运行

在 StackBlitz 上启动它
在 Nuxt 配置中配置 drupalBaseUrl 指向您的 Drupal 实例

许可证

麻省理工学院许可证

鸣谢

由 drunomics 赞助开发 [email protected]