nuxtjs-drupal-ce - Nuxt Drupal 自定义元素连接器

通过 Lupus 自定义元素渲染器将 Nuxt v3 与 Drupal 连接

请参考 https://www.drupal.org/project/lupus_decoupled 获取更多信息。

该模块的 2.x 版本与 Nuxt 3 兼容。对于与 Nuxt 2 兼容的版本，请查看 1.x 版本

先决条件

一个安装了 Lupus 自定义元素渲染器模块或 Lupus 解耦 Drupal 的 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'：仅记录错误。

使用环境变量覆盖选项

可以通过 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

已弃用的选项

以下选项已弃用，仅用于改进向后兼容性。

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。

开发

克隆此存储库。
使用 npm install 安装依赖项。
运行 npm run dev:prepare 以生成类型存根。
使用 npm run dev 以开发模式启动 playground。
使用 Lupus 解耦 Drupal 实例 URL 并追加 API 前缀 /ce-api 更新 Nuxt 配置中的 baseURL 设置，例如 https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api

在 StackBlitz 上运行

在 StackBlitz 上启动它
使用 Lupus 解耦 Drupal 实例 URL 并追加 API 前缀 /ce-api 更新 Nuxt 配置中的 baseURL 设置，例如 https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api

许可证

MIT 许可证

鸣谢

开发由 drunomics [email protected] 赞助。