nuxtjs-drupal-ce - Nuxt Drupal Custom Elements 连接器
通过 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
。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
已弃用的选项
以下选项已弃用,仅用于提高向后兼容性。
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 版本中受支持,但在 2.x 版本中已删除
addVueCompiler
:如果您想在运行时渲染自定义元素标记,则这是必要的;即使用 'markup' 内容格式。相反,可以通过 Nuxt 配置启用 vue 运行时编译器,请参阅 此处。axios
:传递给drupal-ce
axios 实例的选项。请改用fetchOptions
。
开发
- 克隆此仓库。
- 使用
npm install
安装依赖项。 - 运行
npm run dev:prepare
以生成类型存根。 - 使用
npm run dev
在开发模式下启动 playground。 - 使用 Lupus Decoupled Drupal 实例 URL 更新 Nuxt 配置文件中的 baseURL 设置,并附加 API 前缀 /ce-api,例如
https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api
在 StackBlitz 上运行
- 在 StackBlitz 上启动它
- 使用 Lupus Decoupled Drupal 实例 URL 更新 Nuxt 配置文件中的 baseURL 设置,并附加 API 前缀 /ce-api,例如
https://8080-shaal-drupalpod-8m3z0ms7mb6.ws-eu67.gitpod.io/ce-api
许可证
鸣谢
开发由 drunomics 赞助 hello@drunomics.com