Differential D25007 Diff 21 src/docs/contributor/adding_new_css_and_js.diviner

Changeset View

Standalone View

src/docs/contributor/adding_new_css_and_js.diviner

	@title Adding New CSS and JS			@title Adding New CSS and JS
	@group developer			@group developer

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

	= Overview =			= Overview =

	Phabricator uses a system called Celerity to manage static resources. If you			Phorge uses a system called Celerity to manage static resources.
	are a current or former Facebook employee, Celerity is based on the Haste system
	used at Facebook and generally behaves similarly.

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

	= Adding a New File =			= Adding a New File =

	To add a new CSS or JS file, create it in an appropriate location in			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/`			`webroot/rsrc/css/` or `webroot/rsrc/js/` inside your `phorge/`
	directory.			directory.

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

	LANG=css			LANG=css
	/**			/**
	* @provides duck-styles-css			* @provides duck-styles-css
	*/			*/
	Show All 22 Lines

	Then rebuild the Celerity map (see the next section).			Then rebuild the Celerity map (see the next section).

	= Changing an Existing File =			= Changing an Existing File =

	When you add, move or remove a file, or change the contents of existing JS or			When you add, move or remove a file, or change the contents of existing JS or
	CSS file, you should rebuild the Celerity map:			CSS file, you should rebuild the Celerity map:

	phabricator/ $ ./bin/celerity map			phorge/ $ ./bin/celerity map

	If you've only changed file content things will generally work even if you			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			don't, but they might start not working as well in the future if you skip this
	step.			step.

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

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

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

	= Including a File =			= Including a File =

	To include a CSS or JS file in a page, use			To include a CSS or JS file in a page, use
	@{function:require_celerity_resource}:			@{function:require_celerity_resource}:
	Show All 21 Lines