adding_new_css_and_js.diviner
No OneTemporary
Actions

Size

2 KB

Referenced Files

None

Subscribers

None

adding_new_css_and_js.diviner
View Options

	@title Adding New CSS and JS
	@group developer

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

	= Overview =

	Phorge uses a system called Celerity to manage static resources.

	(NOTE) This document is intended for Phorge developers and contributors. This
	process will not work correctly for third-party code, plugins, or extensions.

	= 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:

	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:

	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
	@{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.

	= Next Steps =

	Continue by:

	- reading about Javascript-specific guidelines in @{article:Javascript Coding
	Standards}; or
	- reading about CSS-specific guidelines and features in @{article:CSS Coding
	Standards}.

File Metadata

Mime Type: text/plain
Expires: Sun, Jan 19, 16:17 (2 w, 6 d ago)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 1126400
Default Alt Text: adding_new_css_and_js.diviner (2 KB)

adding_new_css_and_js.divinerNo OneTemporaryActions

adding_new_css_and_js.divinerView Options

File Metadata

Event Timeline

adding_new_css_and_js.diviner
No OneTemporary
Actions

adding_new_css_and_js.diviner
View Options