1 |
|
2 | Firedoc Themes
|
3 | --------------
|
4 |
|
5 | ## Commands
|
6 |
|
7 | The following commands let you can manage firedoc themes locally.
|
8 |
|
9 | #### Install
|
10 |
|
11 | ```
|
12 | firedoc-theme install url [--name name]
|
13 | ```
|
14 |
|
15 | #### Uninstall
|
16 |
|
17 | ```
|
18 | firedoc-theme uninstall [name]
|
19 | ```
|
20 |
|
21 | #### Clear
|
22 |
|
23 | ```
|
24 | firedoc-theme clear
|
25 | ```
|
26 |
|
27 | ## How to create a theme for firedoc
|
28 |
|
29 | #### Distrubution
|
30 |
|
31 | The complete firedoc theme distrubution should be the below:
|
32 |
|
33 | ```
|
34 | themes/default/
|
35 | ├── assets
|
36 | │ ├── css
|
37 | │ ├── favicon.png
|
38 | │ ├── img
|
39 | │ ├── index.html
|
40 | │ ├── js
|
41 | │ └── vendor
|
42 | ├── i18n
|
43 | │ ├── en.json
|
44 | │ └── zh.json
|
45 | ├── layouts
|
46 | │ ├── main.handlebars
|
47 | │ └── xhr.handlebars
|
48 | ├── partials
|
49 | │ ├── attrs.handlebars
|
50 | │ ├── class-tree.handlebars
|
51 | │ ├── classes.handlebars
|
52 | │ ├── enums.handlebars
|
53 | │ ├── events.handlebars
|
54 | │ ├── files.handlebars
|
55 | │ ├── index.handlebars
|
56 | │ ├── items-index.handlebars
|
57 | │ ├── method.handlebars
|
58 | │ ├── module.handlebars
|
59 | │ ├── options.handlebars
|
60 | │ ├── props.handlebars
|
61 | │ └── sidebar.handlebars
|
62 | ├── locals.js
|
63 | └── theme.json
|
64 | ```
|
65 |
|
66 | The next, we will walk them as detailed as possible.
|
67 |
|
68 | 1. The directory "layouts" stores the skelton layout file.
|
69 | 2. The directory "partials" stores the detailed templates for `modules`, `classes` and other templates used by the former.
|
70 | 3. The directory "assets" stores the static resources like scripts, css files and fonts.
|
71 | 4. The directory "i18n" stores the i18n resources for templates, naming as `{lang}.json`.
|
72 | 5. The file `locals.js` is used to support a programable for theme developer, it is expected to export a function, which could rewrite the locals for templates variables.
|
73 |
|
74 | #### Template Context
|
75 |
|
76 | By default, all templates should have the ability to access to the following variables in his template context:
|
77 |
|
78 | ```
|
79 | {
|
80 | globals: {
|
81 | classes: [ /* all classes */ ],
|
82 | modules: [ /* all modules */ ]
|
83 | },
|
84 | i18n: {
|
85 | /* Just for i18n templates object
|
86 | }
|
87 | }
|
88 | ```
|
89 |
|
90 | But as in some special templates, the firedoc would make some shortcuts for the corresponding template:
|
91 |
|
92 | - `module`: the `module` template would be directly called at firedoc itself to generate `modules/*.html` to `dest` path, so that to simplify this spec, firedoc attaches the corresponding `module` object to the current context.
|
93 | - `classes`: the `classes` template would be directly called at firedoc itself to generate `classes/*.html` to `dest` path, so that to simplify this spec, firedoc attaches the corresponding `class` object to the current context.
|
94 |
|
95 | #### Use i18n
|
96 |
|
97 | The i18n in firedoc theme template just looks like add a map variable `i18n` into template `locals`, and the firedoc will depends on the `--lang` option's value to decide what file under `i18n` would be used. The complete example are at [themes/default](default/i18n).
|
98 |
|
99 | At template, we just can use i18n map by the below super simple way:
|
100 |
|
101 | ```html
|
102 | <p>{{i18n.EXAMPLE_I18N_TEXT}}</p>
|
103 | ```
|
104 |
|
105 | #### Programable Theme
|
106 |
|
107 | Sometimes, theme-maker might want a way to implement a new feature without any help from firedoc, so the `locals.js` would help the themer. Here is an example:
|
108 |
|
109 | ```js
|
110 | module.exports = function (modules, classes, locals) {
|
111 | // TODO
|
112 | };
|
113 | ```
|
114 |
|
115 | Then you could work with `modules`, `classes` and `locals` that you want, like if you want to add a timestamp for all classes:
|
116 |
|
117 | ```js
|
118 | module.exports = function (modules, _, _) {
|
119 | modules.forEach(function (mod) {
|
120 | mod.timestamp = Date.now();
|
121 | });
|
122 | }
|
123 | ```
|
124 |
|
125 | The result for the programming is that you can use the `timestamp` at `module` template:
|
126 |
|
127 | ```html
|
128 | Timestamp: {{timestamp}}
|
129 | ```
|