recaptime.dev
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Adding New CSS and JS
2@group developer
3
4Explains how to add new CSS and JS files to Phorge.
5
6= Overview =
7
8Phorge uses a system called **Celerity** to manage static resources.
9
10(NOTE) This document is intended for Phorge developers and contributors. This
11process will not work correctly for third-party code, plugins, or extensions.
12
13= Adding a New File =
14
15To add a new CSS or JS file, create it in an appropriate location in
16`webroot/rsrc/css/` or `webroot/rsrc/js/` inside your `phorge/`
17directory.
18
19Each file must `@provides` itself as a component, declared in a header comment:
20
21 LANG=css
22 /**
23 * @provides duck-styles-css
24 */
25
26 .duck-header {
27 font-size: 9001px;
28 }
29
30Note that this comment must be a Javadoc-style comment, not just any comment.
31
32If your component depends on other components (which is common in JS but
33rare and inadvisable in CSS), declare then with `@requires`:
34
35 LANG=js
36 /**
37 * @requires javelin-stratcom
38 * @provides duck
39 */
40
41 /**
42 * Put class documentation here, NOT in the header block.
43 */
44 JX.install('Duck', {
45 ...
46 });
47
48Then rebuild the Celerity map (see the next section).
49
50= Changing an Existing File =
51
52When you add, move or remove a file, or change the contents of existing JS or
53CSS file, you should rebuild the Celerity map:
54
55 phorge/ $ ./bin/celerity map
56
57If you've only changed file content things will generally work even if you
58don't, but they might start not working as well in the future if you skip this
59step.
60
61The generated file `resources/celerity/map.php` causes merge conflicts
62quite often. They can be resolved by running the Celerity mapper. You can
63automate this process by running:
64
65 phorge/ $ ./scripts/celerity/install_merge.sh
66
67This will install Git merge driver which will run when a conflict in this file
68occurs.
69
70= Including a File =
71
72To include a CSS or JS file in a page, use
73@{function:require_celerity_resource}:
74
75 require_celerity_resource('duck-style-css');
76 require_celerity_resource('duck');
77
78If your map is up to date, the resource should now be included correctly when
79the page is rendered.
80
81You should place this call as close to the code which actually uses the resource
82as possible, i.e. **not** at the top of your Controller. The idea is that you
83should @{function:require_celerity_resource} a resource only if you are actually
84using it on a specific rendering of the page, not just because some views of the
85page might require it.
86
87= Next Steps =
88
89Continue by:
90
91 - reading about Javascript-specific guidelines in @{article:Javascript Coding
92 Standards}; or
93 - reading about CSS-specific guidelines and features in @{article:CSS Coding
94 Standards}.