diff --git a/docs/source/practices/frontend.rst b/docs/source/practices/frontend.rst new file mode 100644 index 0000000..f85f58c --- /dev/null +++ b/docs/source/practices/frontend.rst @@ -0,0 +1,79 @@ +前端页面编写 +======================== + +Pear Admin Flask 并没有实现前后端分离,因为存在部分页面的数据是直接通过模板渲染的方式直接渲染在 HTML 中的。但我们将展示给用户浏览器里的页面都称为前端。 + +公用模板文件 +-------------------- + +项目使用 Flask 搭建,其所有模板文件均存放在 `templates` 文件夹中。公用模板文件保存在 `templates/system/common` ,分别是: + +* header.html -- 头部包含文件,包含了后台页面通用的 css 文件 +* footer.html -- 页脚包含文件,包含了后台页面通用的 js 文件 + +在写后台内嵌页面时,可以参考下面的模板: + +.. code-block:: html + + + + + 这是标题 + {% include 'system/common/header.html' %} + + + + + + + + {% include 'system/common/footer.html' %} + + + +.. note:: + + 需要注意的是,`header.html` 和 `footer.html` 包含了主题色和夜间模式切换的脚本,如果不想包含这两个文件的话, + 还想进行主题色和夜间模式切换可能需要自行添加脚本。(可以参考这两个文件中的内容) + +正确的后台页面嵌入方式 +----------------------- + +Pear Admin Layui 主项目更新之后,提供了 组件式嵌入(_component) 和 iframe嵌入(_iframe) 两种方式。在编写前端页面时, +不同的嵌入方式有所不同,各有优劣。 + +对于组件式嵌入,可以提供更良好的用户体验,如果页面不存在则会弹出 404 提示信息,对于iframe嵌入,则会直接打开(即使不存在)。 + +.. important:: + **使用组件式嵌入时,上述的参考模板不在需要包含 header.html 和 footer.html 文件,如果包含这两个文件会直接影响到后台框架页面的排版和脚本调用!** + +经过测试,组件式嵌入仅适合于唯一且静态的页面,不建议在其中 **添加事件绑定的脚本** ,因为组件式嵌入会将页面内容直接嵌入 div 元素中, +并动态执行脚本,但是执行的脚本绑定的事件并不会因为页面关闭而销毁。简单说明就是,假设脚本中存在计时器,计时器不会在组件式嵌入的页面销毁之后而销毁。 + +所以在 Pear Admin Flask 项目中,仅首页(后台数据统计页面)和个人资料页面使用组件式嵌入,其余均使用iframe嵌入。 + +关于主题色和夜间模式 +----------------------- + +如果开发的是后台管理页面,主题色和夜间模式是必要的,这样可以增加观感。 +Pear Admin Layui 的控制主题色逻辑是通过设置全局的 css 属性:`--global-primary-color` + +比如对于 `.layui-btn` : + +.. code-block:: css + + .layui-btn { + background-color: var(--global-primary-color); + } + +所以,如果您添加了自定义元素,并想要其跟随主题色变化,请确保引用了 `--global-primary-color` 属性。 + +对于夜间模式,本质上就是修改 body 的 class ,使其添加上 `pear-admin-dark` ,比如 `.layui-btn` 的夜间模式 css 为: + +.. code-block:: css + + .pear-admin-dark .layui-btn { + color: #ffffff; + border-color: #4C4D4F; + } + diff --git a/docs/source/practices/index.rst b/docs/source/practices/index.rst index 7b9d61f..94e78c2 100644 --- a/docs/source/practices/index.rst +++ b/docs/source/practices/index.rst @@ -6,4 +6,5 @@ :maxdepth: 1 plugin - trick \ No newline at end of file + trick + frontend \ No newline at end of file diff --git a/docs/source/practices/plugin.rst b/docs/source/practices/plugin.rst index d74d15f..8716732 100644 --- a/docs/source/practices/plugin.rst +++ b/docs/source/practices/plugin.rst @@ -69,7 +69,7 @@ "plugin_description": "一个测试的插件。" } -这个 JSON 文件中,记录了基本的插件名称与插件版本,以及插件的介绍,请确保一个插件至少包含上述的三个字段,因为这三个字段会被项目所读取并在加载成功之后展示在控制台。 +这个 JSON 文件中,记录了基本的插件名称与插件版本,以及插件的介绍。**在更新之后,此文件可以不存在,插件的名称默认为文件夹名。** 编写插件入口 ------------------- @@ -126,4 +126,9 @@ 注意不要直接在 `__init__.py` 的 `event_init` 函数外直接写存在阻塞的代码,不然项目 Flask 将不能初始化完成。 +.. note:: + 在编写插件的前端模板(template)时,请尽量将模板文件放在项目根目录的 `templates` 文件中,这样可以保持良好的项目架构。 + 当然另一种做法是像 helloworld 插件那样,直接放在插件目录的 templates 中,但是一定要做好模板名称的区分, + 因为 flask 默认找模板行为是从根目录开始找的,如果根目录 templates 和插件目录的 templates 中存在的模板重名, + 则会优先使用根目录 templates 的模板文件。 \ No newline at end of file diff --git a/plugins/helloworld/__init__.json b/plugins/helloworld/__init__.json deleted file mode 100644 index 1373e2d..0000000 --- a/plugins/helloworld/__init__.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "plugin_name": "Hello World", - "plugin_version": "1.0.0.1", - "plugin_description": "一个测试的插件。" -} \ No newline at end of file