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] 赞助开发