Bloomreach 反应 SDK

Bloomreach React SDK 提供了简化的无头集成 Bloomreach 内容 用于基于反应的应用程序。 此库与 页面模型 API 财务报告和审定财务报表 Bloomreach SPA SDK 软件 财务报告和审定财务报表 在Page Model上暴露出简化的宣示反应界面.

特征

• 页面组件;
• Bloomreach 组件;
• 管理内容按钮;
• 管理菜单按钮;
• 渲染道具模式支持;
• 反应服务器组件 支助;
• 下一个.js 应用路由器支持;
• 反应路由器 财务报告和审定财务报表 下一个路由 支助;
• 原生反应 支助;
• 酶 财务报告和审定财务报表 欢乐 支助.

开始

安装

让SDK进入你的项目 国家预防机制数字 :

npm install @bloomreach/react-sdk

还有 雅伦数字 :

yarn add @bloomreach/react-sdk

使用量

以下代码片段使一个简单的页面带有一个 横幅 组件.

import React from 'react';
import axios from 'axios';
import { BrComponent, BrPage, BrProps } from '@bloomreach/react-sdk';

function Banner({ component, page, mapping }: BrProps) {
  return <div>Banner: {component.getName()}</div>;
}

export default function App() {
  const configuration = { /* ... */ };

  return (
    <BrPage configuration={configuration} mapping={{ Banner }}>
      {({ page, mapping, component }) => (
        <>
          <header>
            {page && <Link to={page.getUrl('/')}>Home</Link>}
            <BrComponent path="menu" page={page} mapping={mapping} component={component}>
              <Menu page={page} mapping={mapping} />
            </BrComponent>
          </header>
          <section>
            <BrComponent path="main" page={page} mapping={mapping} component={component} />
          </section>
          <BrComponent path="footer" page={page} mapping={mapping} component={component}>
            <footer>
              <BrComponent page={page} mapping={mapping} component={component} />
            </footer>
          </BrComponent>
        </>
      )}
    </BrPage>
  );
}

如果包含 BrPage 的组件重新提交以防止不必要的请求到 Page Model API 中,则对配置对象进行纪念.

const location = useLocation();

const memoizedConfiguration = useMemo(() => {
  return buildConfiguration(`${location.pathname}${location.search}`, axios);
}, [location.pathname, location.search]);

<BrPage configuration={memoizedConfiguration} mapping={mapping}>
  ...

重要使用说明

单页/轮廓

只用一个 BrPage 每个页面或路由的组件. 这个 BrPage 组成部分旨在:

• 从 Page 模型 API 获取特定路径的页面模型
• 为内容更新设置 CMS 预览听众
• 通过渲染道具向所有儿童部件提供页面和绘图数据
• 管理完整页面状态

使用多个 BrPage 同页上的组件将引发冲突,不支持。 如果您需要制作不同的页面段落, 请使用 BrComponent 单人之内 BrPage 换句话说.

非阻塞渲染模式( NBRMODE)

非屏蔽渲染模式可用于减少应用程序在客户端完全加载的时间. 以 默认 NBRMODE 配置为 false 以避免打破现有设置。 设为 true 将启用 非阻塞渲染模式。 当模式激活时, BrPage 组件的子将开始安装, 同时 正在获取页面模型 。 这些孩子可能包含逻辑本身,可以查询一些外部API并使用 非屏蔽渲染模式将允许在请求页面模型的同时执行.

const fetchData = async () => {
  const data = await fetch('https://yourapi.com');
}

function MyComponent() {
  useEffect(() => {
    // This will run in parallel to fetching the PageModel from the Delivery API
    fetchData().catch(console.error);
  }, []);
  
  return `<div>Hello</div>`
}

export default function App() {
  const configuration = {
    /* ... */
    NBRMode: true,
  };

  return (
    <BrPage configuration={configuration} mapping={{ ... }}>
      <MyComponent/>
    </BrPage>
  );
}

React 服务器组件( RSC) 支持

支持编辑 经验经理,该页面和组件必须使用反应钩在客户端动态地进行. 因此,默认 BrPage 财务报告和审定财务报表 BrComponent 两者均作为客户部分执行。 然而,这种限制并不适用于现场,使用服务器组件使您的反应应用完全安全. 为支持这种使用 BrPageServer 财务报告和审定财务报表 BrComponentServer 组件从 @bloomreach/react-sdk/server 作为对应方提供一揽子服务.

使用量

要在您的反应应用程序中使用服务器组件, 只需替换所有发生 BrPage 财务报告和审定财务报表 BrComponent 与 BrPageServer 财务报告和审定财务报表 BrComponentServer 页:1 例如:

import React from 'react';
import axios from 'axios';
import { BrComponentServer, BrPageServer, BrProps } from '@bloomreach/react-sdk/server';

function Banner({ component, page, mapping }: BrProps) {
  return <div>Banner: {component.getName()}</div>;
}

export default function Page() {
  const configuration = { /* ... */ };

  return (
    <BrPageServer configuration={configuration} mapping={{ Banner }}>
      {({ page, mapping, component }) => (
        <>
          <header>
            {page && <Link to={page.getUrl('/')}>Home</Link>}
            <BrComponentServer path="menu" page={page} mapping={mapping} component={component}>
              <Menu page={page} mapping={mapping} />
            </BrComponentServer>
          </header>
          <section>
            <BrComponentServer path="main" page={page} mapping={mapping} component={component} />
          </section>
          <BrComponentServer path="footer" page={page} mapping={mapping} component={component}>
            <footer>
              <BrComponentServer page={page} mapping={mapping} component={component} />
            </footer>
          </BrComponentServer>
        </>
      )}
    </BrPageServer>
  );
}

[注]

• 服务器组件不会在经验管理器中正确工作(更多信息见下文).
• 依其性质, 您无法使用 NBRMODE 中的服务器组件 !
• 在服务器组件中不支持管理内容/Menu按钮. 因为他们只应该在经验经理公司.
• BrPageServer 财务报告和审定财务报表 BrComponentServer 具有与 BrPage 财务报告和审定财务报表 BrComponent分别是:.

混合服务器和客户端组件

在许多情况下,您希望您的反应应用程序同时在现场(使用服务器组件)和体验管理器(使用客户端组件)工作. 要做到这一点,最简单的方法是在您的应用程序中创建两个切入点,并检测使用 page.isPreview() 来自 spar-sdk 的函数。 下面是使用Next.js的示例:

页.tsx

import axios from 'axios';
import { initialize } from '@bloomreach/spa-sdk';
import BrxAppClient from '@/components/BrxAppClient';
import BrxAppServer from '@/components/BrxAppServer';

export default async function Page() {
  const configuration = { /* ... */ };

  const page = await initialize({
    ...configuration,
    httpClient: axios,
  });

  const pageModel = page.toJSON();
  if (configuration.NBRMode || page.isPreview()) {
    // Props passed to Client Components need to be serializable by React.
    return (
      <BrxAppClient configuration={configuration} pageModel={pageModel} />
    );
  }

  return (
    <BrxAppServer configuration={configuration} page={page} />
  );
}

BrxAppClient.tsx (英语)

'use client';

import React from 'react';
import axios from 'axios';
import { Banner } from './Banner';
import { Configuration, PageModel } from '@bloomreach/spa-sdk';
import { BrComponent, BrPage, BrProps } from '@bloomreach/react-sdk';

interface Props {
  configuration: Omit<Configuration, 'httpClient'>;
  pageModel: PageModel;
}

export default function BrxAppClient({configuration, pageModel}: Props) {
  const mapping = { Banner };

  return (
    <BrPage configuration={{ ...configuration, httpClient: axios }} mapping={mapping} page={pageModel}>
      {({ page, mapping: pageMapping, component }) => (
        <>
          <header>
            {page && <Link to={page.getUrl('/')}>Home</Link>}
            <BrComponent path="menu" page={page} mapping={pageMapping} component={component}>
              <Menu page={page} mapping={pageMapping} />
            </BrComponent>
          </header>
          <section>
            <BrComponent path="main" page={page} mapping={pageMapping} component={component} />
          </section>
          <BrComponent path="footer" page={page} mapping={pageMapping} component={component}>
            <footer>
              <BrComponent page={page} mapping={pageMapping} component={component} />
            </footer>
          </BrComponent>
        </>
      )}
    </BrPage>
  );
}

BrxAppServer.tsx (英语)

import React from 'react';
import axios from 'axios';
import { Banner } from './Banner';
import { Configuration, Page } from '@bloomreach/spa-sdk';
import { BrComponentServer, BrPageServer } from '@bloomreach/react-sdk/server';

interface Props {
  configuration: Omit<Configuration, 'httpClient'>;
  page: Page;
}

export default function BrxAppServer({configuration, page}: Props) {
  const mapping = { Banner };

  return (
    <BrPageServer configuration={{ ...configuration, httpClient: axios }} mapping={mapping} page={page}>
      {({ page: contextPage, mapping: pageMapping, component }) => (
        <>
          <header>
            {contextPage && <Link to={contextPage.getUrl('/')}>Home</Link>}
            <BrComponentServer path="menu" page={contextPage} mapping={pageMapping} component={component}>
              <Menu page={contextPage} mapping={pageMapping} />
            </BrComponentServer>
          </header>
          <section>
            <BrComponentServer path="main" page={contextPage} mapping={pageMapping} component={component} />
          </section>
          <BrComponentServer path="footer" page={contextPage} mapping={pageMapping} component={component}>
            <footer>
              <BrComponentServer page={contextPage} mapping={pageMapping} component={component} />
            </footer>
          </BrComponentServer>
        </>
      )}
    </BrPageServer>
  );
}

Banner.tsx 页面存档备份,存于互联网档案馆

import { BrProps } from '@bloomreach/react-sdk';

export default function Banner({ component, page, mapping }: BrProps) {
  return <div>Banner: {component.getName()}</div>;
}

[注]

• 你必须把 'use client' 客户端切入点组件开头处(BrxAppClient (见以上例子) 标记客户端模块的边界。 。 。 .
• 通常您不需要为您的映射组件写入单独的客户端/服务器组件( S)Banner (见以上例子)。 因为你的出入口部分已经标出边界 为了方便,你可以使用新的布尔地产 isClientComponent 从 BrProps 界面来检查您的组件是作为客户端还是服务器组件提供的.
• 如果您想要在您映射的组件中使用管理内容/ 菜单按钮, 请确保仅在组件交付客户端时才会提供 。 见 按钮 下节.
• 检查以下样本项目 examples/next 参考执行.

配置

这个 BrPage编号 :BrPageServer 组件支持您可用于自定义页面的多个选项 初始化。 这些选项将转交给 initialize 函数从 @bloomreach/spa-sdk。见 这里 联 合 国 sPA SDK Typedocs中的完整配置文档.

绘图

这个 BrPage编号 :BrPageServer 组件提供了将 React 组件与 brXM 链接的方法 这些。 它需要通过 mapping 属性,用于映射组件类型 及其代表.

这个 集装箱物品 可能会是 他们的标签.

import NewsList from "./components/NewsList";

return <BrPage mapping={{ "News List": NewsList }} />;

这个 集装箱 只能用他们的 类型, (中文(简体) ), 因此,你需要使用 常数 从 @bloomreach/spa-sdk默认情况下, 反应SDK提供了所有容器类型的执行,因为它是 定义 文档。 。 。 .

import { TYPE_CONTAINER_INLINE } from "@bloomreach/spa-sdk";
import MyInlineContainer from "./components/MyInlineContainer";

return <BrPage mapping={{ [TYPE_CONTAINER_INLINE]: MyInlineContainer }} />;

在集装箱部分内,集装箱物品可通过 children 属性。 这可用于重排或包装子元素.

export default function MyInlineContainer() {
  return (
    <div>
      {React.Children.map(props.children, (child) => (
        <span className="float-left">{child}</span>
      ))}
    </div>
  );
}

这个 构成部分 可以用他们的名字绘制地图。 对菜单组件映射很有用.

import Menu from "./components/Menu";

return <BrPage mapping={{ menu: Menu }} />;

默认情况下,未绘制地图的集装箱项目将用作警告 语句。 有一种选择可以推翻倒计时.

import { TYPE_CONTAINER_ITEM_UNDEFINED } from "@bloomreach/spa-sdk";
import Fallback from "./components/Fallback";

return <BrPage mapping={{ [TYPE_CONTAINER_ITEM_UNDEFINED]: Fallback }} />;

内置映射

还有另一种方式可以构成一个组成部分。 如果你需要显示 静态组件或抽象页面中的组件,可以使用内线 组件映射.

return (
  <BrComponent path="menu" page={page} mapping={mapping} component={component}>
    <Menu page={page} mapping={mapping} isClientComponent />
  </BrComponent>
);

或者,如果您正在使用服务器组件:

return (
  <BrComponentServer path="menu" page={page} mapping={mapping} component={component}>
    <Menu page={page} mapping={mapping} isClientComponent={false} />
  </BrComponentServer>
);

也可以指出该组成部分的儿童将在哪里 摆放.

return (
  <BrComponent path="footer" page={page} mapping={mapping} component={component}>
    <footer>
      <BrComponent page={page} mapping={mapping} />
    </footer>
  </BrComponent>
);

内部映射时的组件数据可以通过渲染道具访问.

return (
  <BrComponent path="footer" page={page} mapping={mapping} component={component}>
    {({ component: footerComponent }) => (
      <footer>
        &copy; {footerComponent.getName()}
        <BrComponent page={page} mapping={mapping} component={footerComponent} />
      </footer>
    )}
  </BrComponent>
);

或者通过传递组件数据作为道具.

export default function Menu({ component, page, mapping }) {
  return <ul>{component.getName()}</ul>;
}

按钮

• 建议添加 Css 风格 position: relative 切入按钮 因此,他们将正确定位在母容器组件内.

• 管理菜单按钮可使用 BrManageMenuButton 组件.

import React from "react";
import { Menu, Reference } from "@bloomreach/spa-sdk";
import { BrManageMenuButton, BrProps } from "@bloomreach/react-sdk";

interface MenuModels {
  menu: Reference;
}

export default function MenuComponent({ component, page, mapping }: BrProps) {
  const menuRef = component?.getModels<MenuModels>().menu;
  const menu = menuRef && page?.getContent<Menu>(menuRef);

  if (!menu) {
    return null;
  }

  return (
    <ul className={page?.isPreview() ? "has-edit-button" : ""}>
      {/* ... */}

      <BrManageMenuButton menu={menu} page={page} mapping={mapping} />
    </ul>
  );
}

• 管理内容按钮可使用 BrManageContentButton 非空组件 content 属性.

import React from "react";
import { Document, Reference } from "@bloomreach/spa-sdk";
import { BrManageContentButton, BrProps } from "@bloomreach/react-sdk";

interface BannerModels {
  document: Reference;
}

export default function Banner({ component, page, mapping }: BrProps) {
  const { document: documentRef } = component.getModels<BannerModels>();
  const document = documentRef && page.getContent<Document>(documentRef);

  return (
    <div className={page.isPreview() ? "has-edit-button" : ""}>
      {/* ... */}

      <BrManageContentButton
        content={document}
        documentTemplateQuery="new-banner-document"
        folderTemplateQuery="new-banner-folder"
        parameter="document"
        root="banners"
        relative
        page={page}
        mapping={mapping}
      />
    </div>
  );
}

• 添加新内容按钮可使用 BrManageContentButton 指令,但不传递内容实体.

import React from "react";
import { BrManageContentButton, BrProps } from "@bloomreach/react-sdk";

export default function News({ component, page, mapping }: BrProps) {
  // ...

  return (
    <div className={page.isPreview() ? "has-edit-button" : ""}>
      {/* ... */}

      <BrManageContentButton
        documentTemplateQuery="new-news-document"
        folderTemplateQuery="new-news-folder"
        root="news"
        page={page}
        mapping={mapping}
      />
    </div>
  );
}

• 如果您的组件能够作为服务器/客户端的组件来渲染, 请确保您的管理内容/菜单按钮只在客户端组件中提供 。 您可以通过检查 isClientComponent 属性。 例如:

import React from "react";
import { Document, Reference } from "@bloomreach/spa-sdk";
import { BrManageContentButton, BrProps } from "@bloomreach/react-sdk";

interface BannerModels {
  document: Reference;
}

export default function Banner({ component, page, mapping, isClientComponent }: BrProps) {
  const { document: documentRef } = component.getModels<BannerModels>();
  const document = documentRef && page.getContent<Document>(documentRef);

  return (
    <div className={page.isPreview() ? "has-edit-button" : ""}>
      {/* ... */}

      {isClientComponent &&
        <BrManageContentButton
          content={document}
          documentTemplateQuery="new-banner-document"
          folderTemplateQuery="new-banner-folder"
          parameter="document"
          root="banners"
          relative
          page={page}
          mapping={mapping}
        />
      }
    </div>
  );
}

原生反应

SDK 完全兼容 原生反应 但有一些最佳做法.

• 无法使用 <div> (原始内容存档于2018-09-31). React Industrial, and it is 建议使用 hst.nomarkup 后端的容器类型 配置 .

• 如果需要支持其他类型的集装箱,这些类型应当是: 在绘图中明显被压倒。 默认执行使用 HTML 报告所描述的实体 文档。 。 。 .

  import React from "react";
  import { View } from "react-native";
  import { TYPE_CONTAINER_BOX } from "@bloomreach/spa-sdk";
  
  function MyBoxContainer() {
    return (
      <View>
        {React.Children.map(props.children, (child) => (
          <View>{child}</View>
        ))}
      </View>
    );
  }
  
  export default function App() {
    return <BrPage mapping={{ [TYPE_CONTAINER_BOX]: MyBoxContainer }} />;
  }
  

• 逆向绘图应被推翻,以防止生产时出错 一个新组件类型从后端弹出, 因为默认执行是 返回纯文本节点.

  import React from "react";
  import { Text } from "react-native";
  import { TYPE_CONTAINER_ITEM_UNDEFINED } from "@bloomreach/spa-sdk";
  
  function Fallback({ component, page, mapping }) {
    return (
      page.isPreview() && (
        <Text>Component "{component.getType()}" is not defined.</Text>
      )
    );
  }
  
  export default function App() {
    return <BrPage mapping={{ [TYPE_CONTAINER_ITEM_UNDEFINED]: Fallback }} />;
  }
  

• 与 相关性 模块, (中文(简体) ), 应在申请中处理存储和传递的访客身份标识 边 这是 visitor 选项 配置 那个 启用不使用 cookie 的设置 .

  import React, { useEffect, useMemo, useRef } from "react";
  import { read, write } from "./storage";
  
  export default function App() {
    const ref = useRef(null);
    const configuration = {
      /* ... */
      visitor: read("visitor"),
    };
  
    const visitor =
      ref.current &&
      ref.current.state.page &&
      ref.current.state.page.getVisitor();
  
    useEffect(() => void visitor && write("visitor", visitor), [
      visitor && visitor.id,
    ]);
  
    return <BrPage ref={ref} configuration={configuration} />;
  }
  

许可证

原载 Apache 2.0 (英语) 执照.

参考文献

反应SDK正在使用 Bloomreach SPA SDK 软件 要交互 与 Bloomreach 内容.

BrPage/ BrPageServer 软件

这是页面模型的切入点 。 本构成部分要求和 初始化页面模型,然后向孩子提供页面和绘图数据 通过渲染道具模式。 该组件使页面根组件与 收到渲染函数.

编译员/编译员

本部分指出儿童或某些部分应放在何处. BrComponent编号 :BrComponentServer 可在内部使用 BrPage编号 :BrPageServer 或只绘制组件. 如果反应儿童被通过,那么他们就会被释放 作为。 。 。 . 否则,它将试图使所有儿童的成分循环.

Brmanage 按钮

此组件在打开链接内容的页面上设置按钮 文档编辑器或打开文档编辑器以创建新的编辑器。 按钮会 仅以预览模式显示.

Brmanage 梅努按钮

此组件在打开链接菜单的页面上设置按钮 菜单编辑器。 按钮仅以预览模式显示 .

BrProps 接口

所有映射组件应执行的基础接口以接收页面、映射和组件数据.

interface BrProps<T extends Component = Component> {
  component?: T;      // The brXM component instance
  page: Page;         // The current page (required)
  mapping: BrMapping; // Component mapping object (required)
  isClientComponent?: boolean // Whether the component is rendered as a client component
}