快速入门春松客服 v7 版本开发,Pugjs 介绍及使用注意事项 | Chatopera

春松客服:快速获得好用的开源智能客服系统

https://www.cskefu.com/
在这里插入图片描述

春松客服使用 Pugjs

春松客服 v7 版本自2021年2月10日发布至今,短短一个月,已经完成 2,000+ 次 Docker 镜像部署。 春松客服 v7 版引入 Pugjs 替换 Freemarker,用意是提升前端开发速度:使用 Freemarker 的前端代码,因为标签太多导致维护效率低。

v7 版本最终发布时,已经达到了完全替换的目的,Pugjs 的一些优点:

  • 简化代码:前端代码量减少 60%
  • 支持格式化: 在开发环境中,更容易自动排查错误和提示
  • 跟容易维护,增强可读性

以上三点为主要的优点,现在春松客服前端开发效率提升了至少 3 倍!

以下内容将围绕如何使用 Pugjs 为主,帮助春松客服开源社区用户可以快速入门新版本开发,定制智能客服系统。

Pugjs 例子

在正式介绍之前,先看一个例子:

//- template.pug
p #{name}的 Pug 代码!

例子来源:https://pugjs.org/zh-cn/api/getting-started.html

这就是一个 Pugjs 代码,Pugjs 是后端 HTML 渲染引擎,不同编程语言有兼容 Pugjs 的工具包,将 Pugjs 代码编译为 HTML 字符串。

春松客服 v7 使用的 Pugjs 渲染引擎实现是 pug4jhttps://github.com/neuland/pug4j

pug4j’s intention is to be able to process pug templates in Java without the need of a JavaScript environment, while being fully compatible with the original pug syntax.

春松客服 contact-center root POM:
在这里插入图片描述

Pugjs 语法

参考中文站点文档:
https://pugjs.org/zh-cn/language/attributes.html

该站点对 Pugjs 的基础知识介绍的非常详细。需要强调的是,重点要理解 unbufferedbuffered 的区别。

使用注意事项

接下来,假设你已经运行了一些 Pugjs 的小例子及看了 Pugjs 的语法文档。那么在春松客服中如何使用呢?
春松客服 Pugjs 的模板源码位置:
contact-center\app\src\main\resources\templates

在这里插入图片描述
.pug 结尾的文件都是 Pugjs 代码文件。

以下各点,有的是代码书写约定,有的是春松客服的设计,都属于注意事项。

判断模块

春松客服中,使用模块化加载,比如企业聊天CRMFacebook Messenger 渠道 都是独立的模块,在前端检查一个模块是否安装:

models?seq_contains("contacts") -> models.contains("contacts")

判断权限

春松客服中,每个登录用户,都依据角色权限显示或控制读写,在 Pugjs 模板中检查权限:

user?? && (user.roleAuthMap["A02"]??  || user.admin) -> user && (user.roleAuthMap["A02"] || user.admin)

使用 for 而不是 each

foreach 都可以进行遍历,为了更好的可读性,只使用 for
在这里插入图片描述
语法: https://pugjs.org/zh-cn/language/code.html

使用 unbuffered comment

Pugjs 中,注释应统一用 //- 这种,提升性能和减少不必要的信息。

在这里插入图片描述

根据条件赋予不同Class

Pugjs 中使用如下语法:
在这里插入图片描述

在行内,最前或最后如果有空格,不去掉

因为 Pugjs 处理空格有约定,在 Pug buffer 中,空格需要特别处理。

如果在一行的最前或最后,有空格,空格不去掉。比如

标签(空格1)(空格2)text(空格3) 

那么,这里空格1是规范,必须有,但是空格2空格3,如果有,则不要去掉,这是故意留的。

尤其是用格式化工具,不要被格式化规则去掉。

语法:https://pugjs.org/language/plain-text.html#whitespace-control

尽量使用 if !

在 pug 中,unless 等同于 if !,但是从习惯上,if ! 更方便阅读,并且占用的代码更少,所以,还是多用 if !.

在这里插入图片描述

阅读 pug4j 使用的动态语言

de.neuland.pug4j 中,可以直接写 JavaScript,但实际上,该语言和 JavaScript 有着一些区别,比如常用的 length 函数,在 pug4j 中对应的是 size,pug4j 使用的真正语言是 jexl

https://commons.apache.org/proper/commons-j/reference/syntax.html

标签属性,应尽量加入 , 分隔,, 可消除歧义, 规避错误

比如:

div(class='div-class' (click)='play()')

应写为:

div(class='div-class', (click)='play()')

语法:https://pugjs.org/language/attributes.html#quoted-attributes

IDEA 中开发 Pug 脚本

在 IDEA 中,打开任意 pug 文件,IDEA 提示安装插件,按照提示进行安装。

在这里插入图片描述

安装后,重启 IDEA。
在这里插入图片描述

格式化代码,快捷方式:

option + command + L

HTML 自动转化为 Pug 的工具

html2pug 转化工具
https://github.com/izolate/html2pug

转化后,检查,使用两列显示
在这里插入图片描述

使用 4 个空格作为缩进

春松客服中,Pugjs 文件使用 4 个空格缩进。
IDEA 中设置 Pug 如下:
在这里插入图片描述
设置如上,点击 “保存”。

IDEA 快捷方式

  • 减少缩进
    针对一行,减少一个前面的缩进。
Shift + Tab
  • 更新前端代码
Fn + Command + F9

Date 格式化

在春松客服中,有很多时间转化的需求,春松客服通过提供 filter 函数,统一为帮助类。
使用 pugHelper.formatDate(String pattern, Date value)

例如:

${user.lastlogintime?string("HH:mm:ss")} -> #{pugHelper.formatDate('HH:mm:ss', user.lastlogintime)}

pattern 语法和原来一致。

获得当前时间戳

pugHelper.currentTimeMillis()

字符串右对齐

使用 pugHelper.padRight(String input,String ch)

例如:

${((agentServicesAvg %(1000*60*60))/(1000*60))?string('00')} -> #{pugHelper.padRight(agentServicesAvg / (1000 * 60 * 60), "00")}

春松客服中的 layout

使用 extends 继承 layout 模板:

在这里插入图片描述
和原来用 freemarker 的关系:layout.pug 即原来的 tpl.html,content 即引用 tpl.html 的原 Freemarker 模版,其中,content 中也可以定义属于 body 的script。

script 模版标签处理

<script id="message_tpl" type="text/html"> 类型的标签是前端模版,不需要转换 pug.
在这里插入图片描述

处理方式:

1、内容比较长的单独创建 tpl文件,存放标签里的内容,不含标签

然后在pug里引用

在这里插入图片描述
在这里插入图片描述

2、内容比较短,不会影响IDE工作的

script#attributetext(type="text/html").
    <MeasureExpression>
    <SQL>
    (case when status = 'ready' then 1 else 0 end)
    </SQL>
    </MeasureExpression>

参考 contact-center/app/src/main/resources/templates/apps/agent/index.pug

Pugjs 文件书写导致格式化错误

格式化:
在这里插入图片描述

如果但一行写成 h1.site-h1(style='background-color:#FFFFFF;')= tagType.name + '标签' + '(' + userList.totalElements + ')',则会导致第二行格式化时,减少了一个单位的缩进。

使用下面则没有格式化问题

h1.site-h1(style='background-color:#FFFFFF;') #{tagType.name} 标签 (#{userList.totalElements})
   span(style='float:right;')

Pugjs 中使用 attributes 注意

Pug 文档里将的 https://pugjs.org/language/attributes.html

input(type='checkbox' checked=true && 'checked')  -转化为-> <input type="checkbox" checked="checked">

pug4j 不兼容,需要用如下句式:

input(type='checkbox' checked=(true ?'checked': false)) -->  <input type="checkbox" checked="checked">

不可复用的 mixin 放在文件最上面

这个 mixin 不太可能被其他页面使用的情况下,写在该页面内。
就写在前面,比 extend 优先级低。

在这里插入图片描述

生成 range

Pug 文档中 https://pugjs.org/zh-cn/language/code.html 有如下用法:
在这里插入图片描述

在 pug4j 的项目中不可用,会报错。需要改为:

  for x in pugHelper.range(1,24)

解决 Plug 文件编辑自动提示错误

如果在 Pugjs 中,IDEA 提示错误,但实际上不是语法错误,参考修改提示规则:
Jetbrains IDEA 中修正 Pugjs 文件编辑自动提示错误 | 春松客服
在这里插入图片描述

接下来

Pugjs 官网

Pugjs 中文站点

一山还有一山高,开源智能客服系统春松客服 v7 版本发布 | Chatopera

春松客服开发环境搭建

部署春松客服 v7 版本

Chatopera 研发团队 聊天机器人 机器学习 智能客服
https://www.chatopera.com 北京华夏春松科技有限公司:为企业交付智能客服系统、智能对话机器人、机器人客服、Chatbot。
已标记关键词 清除标记
相关推荐