通过 100+ 个技巧学习 Nuxt！
55.5K

drupal-ce
nuxtjs-drupal-ce

通过 Lupus 自定义元素渲染器将 Nuxt 与 Drupal 连接起来
1.2K 下载
25 个星标
v2.1.2
fagofago
maximilianmikusmaximilianmikus
TurtlBbxTurtlBbx

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

npm versionnpm downloadscicodecovLicense

通过 Lupus 自定义元素渲染器连接 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 解耦 Drupal 配合良好 - 在这种情况下，设置 drupalBaseUrl 就足以开始使用了。

  1. 搭建初始文件。搭建完成后，根据需要编辑它们。
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 进行渲染。

命名建议

我们建议使用 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。如果设置，则使用提供的 URL 的源设置 drupalBaseUrl。

错误处理

该模块为 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 解耦 Drupal 实例 URL 更新 Nuxt 配置中的 baseURL 设置，并附加 API 前缀 /ce-api，例如 https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api

在 StackBlitz 上运行

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

许可证

MIT 许可证

鸣谢

由 drunomics 赞助开发 [email protected]