主题结构(可参考osr-style)

目录结构

  2. - theme-name # 为你的主题名称, 可自定义
  3. | - pages    # 存放html页面的目录, 名称必须是pages.
  4.   | - about-us
  5.     | - index.html
  6.     ...
  7.   | - contcat
  8.     | - index.html
  9.     | - weixin.html
  10.     ...
  12.   | - login.html
  13.   | - index.html
  14.   ...
  15. | - static  # 存放其他静态文件的目录, 名称必须是static.
  16.   | - css
  17.   | - js
  18.   ...
  20. | - conf.yaml　# 主题配置文件
  21. | - init_setting.json　# 主题初始化数据文件
  22. | - readme.md　# 主题介绍

结构解释

  • theme-name主题主目录, 名称可自定义

  • theme-name目录下的pages和static两个目录名称不可自定义

  • pages下是自定义区, 可根据自己的需求设计路由

  • static下主页用于存放css, js ,img等静态文件

路由

pages目录下的所有html文件的 "路由" 都和目录结构层次一样, 路由从pages下的第一级目录开始.

路由上无需带上".html"后缀. 比如需要访问theme-name/pages/contcat/weixin.html, 路由则是/contcat/weixin.

如果路由只写到目录层(未写到具体文件名), 则会响应此目录下的index.html文件.如果该目录下无index.html文件, 则响应404

比如：访问路由为/about-us和/about-us/index都会响应同一个about-us/index.html文件

conf.yaml 使用说明(格式)

  2. # 主题名必须和主题主目录一致
  3. theme_name: Your theme's name
  4. author: Allen Woo
  5. theme_uri: yoursite.com
  6. introduce: 这里是主题的简单介绍
  7. cover_path: static/sys_imgs/cover.png
  8. version: v0.1
  9. license: BSD-2

init_setting.json 初始化配置文件

此配置文件可以用于初始化主题的设置，每个主题独立拥有一份设置

配置是一个json文件, 格式与参数

  2. [
  3.     {
  4.         name: <str>
  5.         type: <str>
  6.         category: <str>
  7.         title: <str>
  8.         link: <str>
  9.         switch: <int:0 or 1>
  10.         code_type: <str:'html' or 'json'>
  11.         code: <str or json>
  12.         text: <str>
  13.         text_html: <str>
  14.     }
  15. ]

示范

  2. [{
  3.         "name": "about_us",
  4.         "category": "文本信息",
  5.         "type": "text",
  6.         "link":"",
  7.         "code_type":"html",
  8.         "code":"",
  9.         ""
  10.         "text": "这里展示关于我们信息",
  11.         "title": "关于我们"
  12.     },
  13.     {
  14.         "name": "contact",
  15.         "category": "文本信息",
  16.         "type": "text",
  17.         "text": "Email:xxx@xxx.com",
  18.         "title": "联系"
  19.     },
  20.     {
  21.         "name": "contact",
  22.         "category": "文本信息",
  23.         "type": "image",
  24.         "text": "Email:xxx@xxx.com",
  25.         "title": "联系"
  26.     },
  27.     {
  28.         "name": "photo-page-nav",
  29.         "category": "Photo导航",
  30.         "type": "text",
  31.         "link": "",
  32.         "title": "Photo页面导航",
  33.         "code":["城市","风光"],
  34.         "code_type":"json",
  35.         "text_html": "导航是[多媒体>图库]中的任一[分类名称]",
  36.         "text": "导航是[多媒体>图库]中的任一[分类名称]"
  37.     },
  38.     {
  39.         "name": "display_tag",
  40.         "category": "首页展示",
  41.         "type": "text",
  42.         "title": "Home页面文章Tags展示开关, 不需要展示则关闭开关",
  43.         "switch":1,
  44.         "link": "",
  45.         "text": "管理端->主题展示设置->图文里添加或修改，删除"
  46.     }
  47. ]

全局变量

全局变量 g

  • 在html中使用osroom提供的全局变量 g 可以获取站点的一些公开设置与数据(使用方法见模板引擎Jinjia2)

全局遍历current_user

  • 在html中使用osroom提供的全局变量cureent_user(提供当前用户的一些可公布信息与方法), 使用方法见模板引擎Jinjia2

current_user 提供的方法有

  2. # 判断当前用户是否已验证登录
  3. current_user.is_authenticated
  5. # 判断当前用户是否是匿名用户(未登录用户)
  6. current_user.is_anonymous
  9. # 判断用户是否拥有某个权限
  10. current_user.can()
  11. 已登录用户可用
  12. 参数：
  13. 　permissions:<int>, 权限值
  16. # 判断当前用户是否拥有某些page路由的权限
  17. current_user.page_permission_check()
  18. 已登录用户可用
  19. 参数：
  20. 　urls:<array>,
  21. 使用示范:
  22.     current_user.page_permission_check(['/account', '/account/email'])
  25. # 判断当前用户是否是网站工作人员
  26. current_user.is_staff
  27. 已登录用户可用
  29. # 判断当前用户是否是激活用户
  30. current_user.is_active
  31. 已登录用户可用
  34. # 获取当前用户的角色名称
  35. current_user.get_role_name()
  36. 已登录用户可用

current_user提供的用户信息有(获取以下信息前请判断用户是否登录)

  1. current_user.id
  2. current_user.str_id
  3. current_user.username
  4. current_user.email
  5. current_user.mphone_num
  6. current_user.custom_domain
  7. current_user.gender
  8. current_user.avatar_url
  9. current_user.role_id
  10. current_user.active
  11. current_user.is_delete
  12. current_user.create_at
  13. current_user.update_at
  14. current_user.editor
  15. current_user.jwt_login_time
  16. current_user.user_info

　注意

  • 以上全局变量只适合在OSROOM主题上使用, 未经过OSROOM系统的html等, 可以调用API: /api/global来获取全局数据了.
  2. API: /api/global
  3. 获取当前全局数据,包括站点的公开设置, 当前登录用户的基本可公开信息.

模板引擎Jinjia2使用

  • 使用模板引擎可以将数据渲染在html中

示范1: 获取全局变量g

  2. <!--获取site配置的LOGO路由-->
  3. <img class="osr-logo" src="{{g.site_global.site_config.LOGO_IMG_URL}}" alt="Logo">
  5. <!--想知道g会包含哪些数据可以将它在html页面中全部显示出来,如下-->
  6. {{ g }}
  8. <!--想知道网站的全局数据site_global,如下-->
  9. {{ g.site_global }}
  11. <!--这样也可以,如下-->
  12. <script>
  14. var current_lang = '{{g.site_global.language.current}}';
  15. alert(current_lang);
  17. </script>

示范2: 获取cureent_user

  2. <!--判断是否已登录-->
  4. {% if current_user.is_authenticated %}
  5.     <a>
  6.         <img class="osr-img-circle-b" src="{{current_user.avatar_url}}" alt="User Avatar"/>
  7.     </a>
  9. {% else %}
  10.     <a href="/sign-in">
  11.         登录
  12.     </a>
  14. {% endif %}
  17. <!--又比如. 选择使用网站名还是Logo-->
  18. <a href="/">
  19. {% if g.site_global.site_config.MB_LOGO_DISPLAY == "logo" %}
  21.     <img src="{{g.site_global.site_config.LOGO_IMG_URL}}" alt="Logo"/>
  23. {% else %}
  25.     <strong>{{g.site_global.site_config.APP_NAME}}</strong>
  27. {% endif %}
  28. </a>

更多的Jinjia2的语法

  • 了解了OSROOM提供的相关信息后就可以开发自己的主题了, 当然你要先去学习下Jinjia2使用.

docs.jinkan.org/docs/jinja2

其他公共数据

  • 最后我们要通过Api获取和提交其他数据,比如登录, 注册, 发表等, 具体有哪些Api请看Api文档

主题设置数据

这里要强调的是一个多媒体数据获取API:

/api/global/theme-data/display

  • 主题的很多设置可以在Admin管理的主题展示设置中设置

  • 比如图片设置页面中: 127.0.0.1/osr-admin/theme-setting/display/image

例子:

在管理的主题展示设置中上传3张图片, 比如名称改为home-carousel-1, home-carousel-1, home-rec1-1那么我可以使用api 获取这两张图片信息, 展示在html页面中

var conditions = [
     {
        type:"image",
        name_regex:"home-carousel-[0-9]+",
        result_key:"home_carousel"
     },
     {
        type:"image",
        name_regex:"home-rec1-[0-9]+",
        result_key:"rec_1"
     }
];
var d ={
    conditions:JSON.stringify(conditions)

}

// js请求api
var result = $.request("GET","/api/global/theme-data/display", d);
result.then(function (r) {
    var carousel = r.data.medias.home_carousel;
    var rec_1 = r.data.medias.rec_1;
});
  • /api/global/theme-data/display的具体使用方式可以见api文档, 以下文档不一定是最新的
/api/global/theme-data/display　调用说明
GET:
    1.获取主题展示用的多媒体数据
    conditions:<array:dict>, Such as:[{'type':<str>, 'names':<array>, 'name_regex':''}]
        说明:
            type-可以是"text", "image", "video", "audio"
            names-数组,指定要获取数据的name
            name_regex-字符串,获取匹配此正则的media,如果为空值，则不使用正则匹配(空置包括null, None,False, "")
            注意:name 与name_regex不能同时使用,当name_regex非空时，查询自动忽略names
        使用示例：前提在管理端多媒体中存在的内容
        如:首页轮播图片和获取”关于我们“页面的文字内容
        [
            {"type":"image", "names":["home-carousel-1", "home_carousel-2"]},
            {"type":"text", "names":["about-me"]},
            {"type":"image", "name_regex":"test-[0-9]+"}
        ]

多语言翻译

标记文本

在html中标记要翻译的文本, 示范:

  • 使用{{_()}}标记

<div>
{{_('这里是需要翻译的文本')}}
</div>

提取文本

提取文本使用osroom下的翻译提取脚本具体请看transations_tool提取

工具文档


# 获取提取工具帮助文档(osroom根目录下)
python tools/transations/transations_tool.py -h

步骤:每个步骤操作请看transations_tool.py -h 文档

  • 1.初始化语言目录(注意: 第一次提取前使用)

  • 2.update: 更新内容（提取最新的文本）

  • 3.翻译.po文本, 在语言目录(初始化后会自动建立)下, 比如osroom/apps/transations/theme/en_US/LC_MESSAGES/messages.po

  • 4.发布翻译

如果无需翻译, 就无需使用此工具

End 后续再补充