78 lines
2.1 KiB
Plaintext
78 lines
2.1 KiB
Plaintext
@title Adding New CSS and JS
|
|
@group developer
|
|
|
|
Explains how to add new CSS and JS files to Phabricator.
|
|
|
|
= Overview =
|
|
|
|
Phabricator uses a system called **Celerity** to manage static resources. If you
|
|
are a current or former Facebook employee, Celerity is based on the Haste system
|
|
used at Facebook and generally behaves similarly.
|
|
|
|
= Adding a New File =
|
|
|
|
To add a new CSS or JS file, create it in an appropriate location in
|
|
##webroot/rsrc/css/## or ##webroot/rsrc/js/## inside your ##phabricator/##
|
|
directory.
|
|
|
|
Each file must ##@provides## itself as a component, declared in a header
|
|
comment:
|
|
|
|
LANG=css
|
|
/**
|
|
* @provides duck-styles-css
|
|
*/
|
|
|
|
.duck-header {
|
|
font-size: 9001px;
|
|
}
|
|
|
|
Note that this comment must be a Javadoc-style comment, not just any comment.
|
|
|
|
If your component depends on other components (which is common in JS but
|
|
rare and inadvisable in CSS), declare then with ##@requires##:
|
|
|
|
LANG=js
|
|
/**
|
|
* @requires javelin-stratcom
|
|
* @provides duck
|
|
*/
|
|
|
|
/**
|
|
* Put class documentation here, NOT in the header block.
|
|
*/
|
|
JX.install('Duck', {
|
|
...
|
|
});
|
|
|
|
Then rebuild the Celerity map (see the next section).
|
|
|
|
= Changing an Existing File =
|
|
|
|
When you add, move or remove a file, or change the contents of existing JS or
|
|
CSS file, you should rebuild the Celerity map:
|
|
|
|
phabricator/ $ ./scripts/celerity_mapper.php ./webroot
|
|
|
|
If you've only changed file content things will generally work even if you
|
|
don't, but they might start not working as well in the future if you skip this
|
|
step.
|
|
|
|
= Including a File =
|
|
|
|
To include a CSS or JS file in a page, use
|
|
@{function:require_celerity_resource}:
|
|
|
|
require_celerity_resource('duck-style-css');
|
|
require_celerity_resource('duck');
|
|
|
|
If your map is up to date, the resource should now be included correctly when
|
|
the page is rendered.
|
|
|
|
You should place this call as close to the code which actually uses the resource
|
|
as possible, i.e. **not** at the top of your Controller. The idea is that you
|
|
should @{function:require_celerity_resource} a resource only if you are actually
|
|
using it on a specific rendering of the page, not just because some views of the
|
|
page might require it.
|
|
|