[Summary view] [Print] [Text view]

   1  @title Adding New CSS and JS
   2  @group developer
   3  
   4  Explains how to add new CSS and JS files to Phabricator.
   5  
   6  = Overview =
   7  
   8  Phabricator uses a system called **Celerity** to manage static resources. If you
   9  are a current or former Facebook employee, Celerity is based on the Haste system
  10  used at Facebook and generally behaves similarly.
  11  
  12  This document is intended for Phabricator developers and contributors. This
  13  process will not work correctly for third-party code, plugins, or extensions.
  14  
  15  = Adding a New File =
  16  
  17  To add a new CSS or JS file, create it in an appropriate location in
  18  `webroot/rsrc/css/` or `webroot/rsrc/js/` inside your `phabricator/`
  19  directory.
  20  
  21  Each file must ##@provides## itself as a component, declared in a header
  22  comment:
  23  
  24    LANG=css
  25    /**
  26     * @provides duck-styles-css
  27     */
  28  
  29    .duck-header {
  30      font-size: 9001px;
  31    }
  32  
  33  Note that this comment must be a Javadoc-style comment, not just any comment.
  34  
  35  If your component depends on other components (which is common in JS but
  36  rare and inadvisable in CSS), declare then with `@requires`:
  37  
  38    LANG=js
  39    /**
  40     * @requires javelin-stratcom
  41     * @provides duck
  42     */
  43  
  44    /**
  45     * Put class documentation here, NOT in the header block.
  46     */
  47    JX.install('Duck', {
  48      ...
  49    });
  50  
  51  Then rebuild the Celerity map (see the next section).
  52  
  53  = Changing an Existing File =
  54  
  55  When you add, move or remove a file, or change the contents of existing JS or
  56  CSS file, you should rebuild the Celerity map:
  57  
  58    phabricator/ $ ./bin/celerity map
  59  
  60  If you've only changed file content things will generally work even if you
  61  don't, but they might start not working as well in the future if you skip this
  62  step.
  63  
  64  The generated file `resources/celerity/map.php` causes merge conflicts
  65  quite often. They can be resolved by running the Celerity mapper. You can
  66  automate this process by running:
  67  
  68    phabricator/ $ ./scripts/celerity/install_merge.sh
  69  
  70  This will install Git merge driver which will run when a conflict in this file
  71  occurs.
  72  
  73  = Including a File =
  74  
  75  To include a CSS or JS file in a page, use
  76  @{function:require_celerity_resource}:
  77  
  78    require_celerity_resource('duck-style-css');
  79    require_celerity_resource('duck');
  80  
  81  If your map is up to date, the resource should now be included correctly when
  82  the page is rendered.
  83  
  84  You should place this call as close to the code which actually uses the resource
  85  as possible, i.e. **not** at the top of your Controller. The idea is that you
  86  should @{function:require_celerity_resource} a resource only if you are actually
  87  using it on a specific rendering of the page, not just because some views of the
  88  page might require it.
  89  
  90  = Next Steps =
  91  
  92  Continue by:
  93  
  94    - reading about Javascript-specific guidelines in @{article:Javascript Coding
  95      Standards}; or
  96    - reading about CSS-specific guidelines and features in @{article:CSS Coding
  97      Standards}.