Backend context object

2019-01-04 05:10:41

Cabloy-CMS uses ejs template engine for page rendering, a context object is created before rendering, and collects related data and methods for use in template files.

Context object structure

{
  ctx: [Object],
  site: [Object],
  require: [Function],
  url: [Function],
  css: [Function],
  js: [Function],
  env: [Function],
  text: [Function],
  util: {
    time: {
      now: [Function],
      today: [Function],
      formatDateTime: [Function],
      formatDate: [Function],
      formatTime: [Function]
    },
    formatDateTime: [Function]
  },
  article: [Object],
  _path: [String]
}
Name Type Instruction
ctx property Backend APIs and various resources can be invoked via ctx object
site property Site configuration information
require method Reference module
url method Construct an absolute link
css method Declare css files for final merging and minimization
js method Declare js files for final merging and minimization
env method Inject environment variables for frontend usage
text method Text internationalization
util property Tool function
article property Currently rendered article information
_path property Indicates the relative path of the current template file (relative to the directory intermediate)

Access backend resources

Backend APIs and various resources can be invoked via ctx object.

For example, in order to render the menu, you need to get the directory tree, you can do the following

const res = await ctx.performAction({
  method:'post',
  url: '/a/cms/category/tree',
  body: { language:site.language.current,hidden:0 },
});
const tree=res.list;

Reference module

In the .ejs file, you can also reference the module as in NodeJS.

// reference module in node_modules
const moment=require('moment');
// reference module in the project
const test=require('./test.js');

Absolute address

It is recommended that URL links of all resources in the page are rendered as absolute addresses.

// Relative to the website root directory
<%=url('assets/images/background.png')%>
// Relative to the current file
<%=url('./fonts/github/700i.woff')%>

Merge and minimize CSS, JS

During the rendering process, the CSS and JS files are declared at first and then merged and minimized at the end. A placeholder is provided in the rendering template, it will be replaced by the actual generated URL link.

Declare CSS, jS

// css
css('../assets/css/markdown/github.css.ejs');
css('../assets/css/article.css');
css('../assets/css/sidebar.css');
// js
js('../assets/js/lib/json2.min.js');
js('../assets/js/lib/bootbox.min.js');
js('../assets/js/util.js.ejs');
js('../assets/js/article.js.ejs');
js('../assets/js/sidebar.js.ejs');

If the referenced CSS, JS file suffix is .ejs, it will also be rendered as an ejs template.

Placeholder

// CSS file link placeholder
<link rel="stylesheet" href="_ _CSS_ _">
// JS file link placeholder
<script src="_ _JS_ _"></script>

Effects

<link rel="stylesheet" href="https://zhennann.me/assets/css/8d38154d198309325c0759a22213dbd6ff0b7edecd2f4868dc72311335ccbe25.css">
<script src="https://zhennann.me/assets/js/b17e06ccb536dee939d4b1deaa595436363a52769c210d74d6a77f011e0f6461.js"></script>

Inject environment parameters

In order to facilitate the flexible and rich functional logic of the frontend, some environmental parameters need to be injected into the frontend.

The backend declares environment parameters through env, which are finally merged into the frontend.

Similarly, placeholders also need to be provided on the frontend, replace to the actual generated environment parameters.

Declare env

env('index',{
  [_path]:data.index,
});

Placeholder

// ENV placeholder
_ _ENV_ _

Effects

<script type="text/javascript">
var env={
  "base": ...,
  "language": ...,
  "format": ...,
  "comment": ...,
  "site": ...,
  "index": {
    "main/index/index": 20
  }
};
</script>

Internationalization

If you need to apply themes and plugins to different languages, you need to internationalize the text resources used in them.

Because the theme and plugin are essentially EggBorn modules, you can use the internationalization mechanism provided by the EggBorn module directly.

For example, the plugin cms-pluginbase provides unlimited scrolling, if you need a Load error, try again reminder when load fails, you could probably try the following.

Define language resources

cms-pluginbase/backend/src/config/locale/zh-cn.js

module.exports = {
  'Load error, try again': '加载失败,请重试',
};

Use language resources

cms-pluginbase/backend/cms/plugin/assets/js/util.js.ejs

const $buttonTry = $('<button type="button" class="btn btn-warning btn-xs"><%=text("Load error, try again")%></button>');

Path indication: _path

A generic ejs template file may be referenced by multiple master ejs template files. With _path, you can know which master ejs template file is currently referenced in the generic ejs template file for different logical processing.



Comments: