From deac6e85cc87507459e5b0757d8e9fa0231c2831 Mon Sep 17 00:00:00 2001
From: epriestley <epriestley@phabricator.com>
Date: Fri, 4 Mar 2011 14:15:59 -0800
Subject: [PATCH] Basic doc for adding/updating Celerity CSS/JS.

Summary:

Test Plan:

Reviewers:

CC:
---
 .divinerconfig                         |  2 +-
 src/docs/adding_new_css_and_js.diviner | 77 ++++++++++++++++++++++++++
 2 files changed, 78 insertions(+), 1 deletion(-)
 create mode 100644 src/docs/adding_new_css_and_js.diviner

diff --git a/.divinerconfig b/.divinerconfig
index 88c73c168f..b5c38d4aed 100644
--- a/.divinerconfig
+++ b/.divinerconfig
@@ -6,7 +6,7 @@
     "install" : "Installing",
     "config" : "Configuration",
     "userguide" : "Application User Guides",
-
+    "developer" : "Phabricator Developer Guides",
     "differential" : "Differential (Code Review)",
     "diffusion" : "Diffusion (Repository Browser)",
     "maniphest" : "Maniphest (Task Tracking)",
diff --git a/src/docs/adding_new_css_and_js.diviner b/src/docs/adding_new_css_and_js.diviner
new file mode 100644
index 0000000000..f5ee9ef8e0
--- /dev/null
+++ b/src/docs/adding_new_css_and_js.diviner
@@ -0,0 +1,77 @@
+@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.
+