Adding New CSS and JS

Phorge Contributor Documentation (Developer Guides)

Explains how to add new CSS and JS files to Phorge.

Overview

Phorge uses a system called Celerity to manage static resources.

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 phorge/ directory.

Each file must @provides itself as a component, declared in a header comment:

/**
 * @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:

/**
 * @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:

phorge/ $ ./bin/celerity map

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.

The generated file resources/celerity/map.php causes merge conflicts quite often. They can be resolved by running the Celerity mapper. You can automate this process by running:

phorge/ $ ./scripts/celerity/install_merge.sh

This will install Git merge driver which will run when a conflict in this file occurs.

Including a File

To include a CSS or JS file in a page, use 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 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.

Next Steps

Continue by:

• reading about Javascript-specific guidelines in Javascript Coding Standards; or
• reading about CSS-specific guidelines and features in CSS Coding Standards.