在过去的几年里,我们一直在使用故事书在Sitecore SXA主题发展。它为我们提供了一些关键的特性,帮助加速我们的前端开发(美联储)工作流程:
- 节点与热模块开发环境重载(HMR)
- 不依赖Sitecore断开连接的环境
- a11y社区附加援助web可访问性()测试
- 动态文档文档附件
除了以上开发经验优势,利用故事书也为联邦政府提供了一致的工作流项目之间移动基于CMS的Sitecore之外,例如Episerver。
本文将讨论以下主题:
我们将开始一个新的SXA主题,但如果你希望完成的故事书种子,请访问Github回购。它仅仅包含了相关的故事书文件简化下降到任何项目。
第1部分。什么是故事书
在组织自己的话说:
故事书是一个开源工具开发UI组件在隔离反应,Vue,角等等。它使建筑惊人的ui组织和高效。
故事书安装到一个项目添加一个本地节点。js开发沙箱,允许开发人员创建、测试和文档组件的隔离。
当启动故事书UI, Sitecore调查局可以测试Sass和JS后导入Sitecore (SXA)或捆绑到一个服务器。传统项目往往涉及一系列令人眼花缭乱的HTML文件中引用一些或全部的资产来源。故事书让这一致和增加开发人员的经验和各种官方插件以及访问整个社区的开源插件。让我们看看故事书添加到一个SXA主题。
第2部分。设置SXA主题的故事书
现在我们已经掌握故事书是什么以及为什么使用它,让我们探索将它添加到你的SXA主题。
下面的例子是在假设你工作在传统SXA主题。的目录结构是你,但是你可能需要更新的引用/进口根据您的偏好。
目录结构:
主题/├──- /│├──scriban /│└──元数据。json├──杯/├──sass /├──脚本/├──来源├──风格├──包。json└──README.md
-
- 你package.json添加以下附件:
/ /包。json{“脚本”:{“开发”:“start-storybook - p 6006 - s公共”},“依赖性”:{“prop-types”:“^ 15.7.2”、“反应”:“^ 17.0.1”、“react-dom”:“^”17.0.1},“devDependencies”: {“@babel / preset-react”:“^ 7.10.4”、“@storybook / addon-a11y”:“^ 6.1.14”、“@storybook / addon-actions”:“^ 6.1.14”、“@storybook / addon-essentials”:“^ 6.1.14”、“@storybook / addon-links”:“^ 6.1.14”、“@storybook /插件”:“^ 6.1.14”、“@storybook / node-logger”:“^ 6.1.14”、“@storybook /反应”:“^ 6.1.14”、“@storybook /主题”:“^ 6.1.14”、“babel-loader”:“^ 8.2.2”、“core-js”:“^ 3.8.3”、“css-loader”:“^ 5.0.1”、“file-loader”:“^ 6.2.0”、“html-loader”:“^ 1.3.2”、“sass-loader”:“^大家”,“style-loader”:“^ 2.0.0”、“webpack”:“^ 4.44.2”、“webpack-cli”:“^”3.3.12}}npm安装
使用上面的命令安装的依赖关系
- 更新你的巴别塔配置包括以下:
{“巴别塔”:{“预设”:[“@babel / env”、“@babel / preset-react”]}} - 创建一个.storybook文件夹在您的目录下面的文件和内容:
主题/├──.storybook /│├──主要。js│└──预览。js└──……
/ /主要。js const path =要求(“路径”);模块。出口={“故事”:[' . . / src / * * / * .stories .@ (js | jsx) /故事/配置文件都位于],“插件”:[/ /添加必要的插件项目‘@storybook / addon-links’,‘@storybook / addon-essentials’,‘@storybook / addon-a11y’), / /自定义配置webpackFinal webpack:异步(配置,{configType}) = > {config.module.rules.push({测试:/ \。(js | jsx) /美元,排除:/ node_modules /用途:‘babel-loader’,,});config.module.rules.push({测试:/ \。scss /美元,使用:[‘style-loader’,‘css-loader’,‘sass-loader’,),排除:/ node_modules /});config.module.rules.push({测试:/ \。(woff | woff2 |测试结束| ttf |传递)/美元,使用:“file-loader”,包括:路径。解决(__dirname“. . /”)});config.module.rules.push({测试:/ \。(html | cshtml | scriban) /美元,使用:“html-loader”,包括:路径。解决(__dirname“. . /”)});返回配置;}},/ /预览。js / /空现在离开,我们将讨论导入主题在后续部分资产
- 创建您的第一个故事,主题根,创建一个src /目录并创建一个名为example.stories的文件内。js包含以下内容:
主题/├──……├──src /│└──故事/│└──example.stories。js└──……
/ /进口依赖进口的反应从“反应”;/ /故事元数据导出默认{标题:“测试”,/ /配置文件夹结构故事书UI};/ /一个故事(作为反应功能组件)/ /可以有多个故事在文件出口const标准= ()= > (< div >哟!< / div >)请注意:在步骤3中,我们添加了一条线,将故事书自动导入任何配置文件与.stories主题/ src /结束。js,所以你不需要手动导入任何文件的故事
- 运行故事书——这一切都设置正确,你现在应该可以打开任何终端,运行以下命令(先前添加到包中。json在步骤1):
npm运行开发
- 你package.json添加以下附件:
浏览器应该开放http://localhost: 6006用下面的
故事书启动并运行,让我们将注意力转向定制故事书的主题。
第3部分。定制为您的品牌故事书的主题
你可以定制各种UI通过部分故事书主题API。,您可以更改字体,风格,背景颜色,标志和图标。在本节中,我们将着眼于改变标志代表网站的品牌。
故事书将主题从.storybook API定制名为manager.js的文件/文件夹。更新的主要标志和图标,创建该文件包含以下内容:
主题/├──.storybook /│├──主要。js│├──经理。js / /添加这个文件│└──预览。js└──……
/ /经理。js从@storybook /插件的进口{插件};从“@storybook进口{创建}/主题/创建的;const主题=创建({基地:“光”,brandTitle:“故事书| Perficient’, brandUrl:“//www.feisu365.com/”,品牌形象:’。/ perficient-logo。svg "});插件。setConfig({主题});
注意:上面的图片路径是相对于主题/公共文件夹,因为它被配置为静态目录package.json的“脚本”一节。我们将讨论处理静态内容在以后的部分。
与定制补充说,停止并重新启动服务器,看故事书的变化
查看更多关于主题的故事书文档的定制选项。
第4部分。使用公共资产
简单的故事书使处理静态的资产。在包。json“脚本”一节,命令结尾- s标志与目录的位置(公共)。参考图片、字体等,将它们添加到公共目录,并通过路径引用它们相对于该目录,例如主题/公共/图片/标志。svg可以参考以下路径:
< img src = "图片/标志。png " alt = " alt文本在这里" / >
我们发现,模仿Sitecore媒体库路径是有助于解决url。
第5部分。处理SCSS和JS在故事书
不难处理SXA主题Scss和JS,但有一些问题。本节将向您展示如何导入你的源文件和解决全局变量错误。
SCSS在故事书
在第二节(上图),我们创建了一个空的预演。js文件.storybook /文件夹。这个文件是为全球JS和SCSS资产导入您的项目。我们将使用这所有的主题Sass导入到我们的项目。要做到这一点,就创建一个.scss文件和导入所需的所有样式。我们也获取必要的optimized.min。css文件(从Sitecore)并将它们添加到网格src文件夹,等等。
JS的故事书
进口组件JS故事中主要做文件,我们将看一看下面的一个例子。全球JS资产(如第三方库)可以被导入到预览。js文件。
工作与SXA组件JS故事书需要两个主要步骤:
- 全球XA对象创建和导入。这是需要为了模拟XA组件初始化组件的暴露api。模拟出来,创建一个xa-mock。js文件的src文件夹下面的代码。你可以导入这个全球预览。js文件。
/ / xa-mock。js全球。XA ={组件:{},注册(){}}; - 导入和初始化一个组件内部文件的故事。因为故事书是建立在最重要的反应,每个故事都功能组件。为了正确地初始化组件绑定到DOM元素,您需要执行init函数内部useEffect()反应钩。这将确保DOM完成渲染(反应)之前你想绑定事件处理程序等。让我们来看看下面一个简单的例子。
/ /主题/资源/组件。js XA.component.myComponent =(() = >{使用严格的;const api ={初始化:假的,init(){如果(this.initialized){返回;其他}{const btn = document.querySelector (# btn);btn。addEventListener(“点击”,()= >{警报(“工作! !”);});}}}返回api;})();XA。register('my-component', XA.component.myComponent);/ /主题/ src /故事/ Test.stories。js / /进口useEffect钩进口反应,从“反应”{useEffect};/ /导入组件导入“. . / . . /资源/组件”;/ /故事元数据导出默认{标题:“测试”,};出口const标准= ()= > {/ / useEffect用钩来初始化组件useEffect (() = > {XA.component.myComponent.init ();},[]);返回(< div > <按钮id = " btn " > < /按钮> < / div >点击我)}你可以看到,我们只需要导入useEffect()反应钩和调用它里面的故事组件来init()我们的XA组件。这将确保反应呈现()方法被称为我们的DOM内容已完成渲染。关于反应钩子的更多信息,请参阅文档。
在本节中,我们看到有一个小设置为了使用XA组件代码里面的故事书。第一次几次后,它将成为第二天性,或者至少一个模板复制/粘贴
之前,我们来看一个实际开发工作流程,让我们看看如何使用html标记或.scriban文件作为你的故事书的故事。
第6部分。使用模板代码
写作中的所有标记JSX语法有时会令人不快,特别是当复制并粘贴到一个剃须刀文件或一块scriban Sitecore内容树。(我经常忘记更改类名类)。幸运的是,我们可以编写模板代码.scriban或. html文件并将它们导入我们的故事。
与按钮的处理程序在上面的例子中,我们可以重构:
< !——/ - / scriban /测试/默认主题。scriban - - > <按钮id = " btn " > < /按钮>点击我
/ /主题/ src /故事/ Test.stories。js进口反应,从“反应”{useEffect};导入“. . / . . /资源/组件”;/ /导入模板const testScriban =要求(“. . / . . /——/ scriban /测试/ default.scriban ') / /故事元数据导出默认{标题:“测试”,};出口const标准= ()= > {useEffect (() = > {XA.component.myComponent.init ();},[]);/ /渲染dangerouslySetInnerHTML返回(< div dangerouslySetInnerHTML = {{__html: testScriban}} / >)}
应该渲染和工作完全按照它之前。区别在于,我们提取模板代码的格式,可以接近它将如何被Sitecore。一个关于使用scriban文件我们继续之前的注意事项:scriban语法不能解析通过节点,由于没有node-supported解析器。我们选择使用这种格式作为前端开发和Sitecore之间的合同模板实现。
在最后的部分中,我们将讨论一个实际的开发工作流程。
第7部分。开发工作流程和结论
现在,我们有一个更好的理解什么是故事书,如何把它变成我们的主题,以及如何使用它来处理主题文件和标记,让我们讨论一个典型的工作流。
由于前端开发现在断开Sitecore允许更快速发展,Sitecore开发人员可以专注于开发模板和效果图,前端开发人员专注于构建主题资产/风格/ JS。集成需要标记添加到Sitecore:要么.cshtml, .scriban或SSR反应组件。这一步将是一个手动过程,但标记从故事书将提供指南。我们发现它有助于认为它是契约优先的开发,并有义务在标记。
的手动过程之间移动标记成Sitecore并保持模板代码同步Sitecore和故事书很麻烦,我们仍然看到净减少。此外,我们看到一个真正的好处与故事书它提供开发文档。此外,故事书提供命令导出静态版本的网站,可以部署到一个托管服务器。最后,几个DSM(如Invision)集成点到故事书来提高合作设计和开发。
