[Summary view] [Print] [Text view]

   1  @title Celerity Technical Documentation
   2  @group celerity
   3  
   4  Technical overview of the Celerity system.
   5  
   6  = Overview =
   7  
   8  Celerity is a static resource (CSS and JS) management system, which handles:
   9  
  10    - Keeping track of which resources a page needs.
  11    - Generating URIs for the browser to access resources.
  12    - Managing dependencies between resources.
  13    - Packaging resources into fewer HTTP requests for performance.
  14    - Preprocessing resources (e.g., stripping comments and whitespace).
  15    - Delivering resources and managing resource cache lifetimes.
  16    - Interfacing with the client to manage resources.
  17  
  18  Celerity is an outgrowth of the //Haste// system at Facebook. You can find more
  19  information about Celerity here:
  20  
  21    - @{article:Things You Should Do Soon: Static Resources} describes the history
  22      and context of the system and the problems it solves.
  23    - @{article:Adding New CSS and JS} provides a developer guide to using
  24      Celerity.
  25  
  26  = Class Relationships =
  27  
  28  Celerity's primary API is @{function:require_celerity_resource}, which marks a
  29  resource for inclusion when a response is rendered (e.g., when the HTML page is
  30  generated, or when the response to an Ajax request is built). For instance, if
  31  you use a CSS class like "widget-view", you must ensure the appropriate CSS is
  32  included by calling ##require_celerity_resource('widget-view-css')## (or
  33  similar), at your use site.
  34  
  35  This function uses @{class:CelerityAPI} to access the active
  36  @{class:CelerityStaticResourceResponse} and tells it that it needs to include
  37  the resource later, when the response actually gets built. (This layer of
  38  indirection provides future-proofing against certain complex situations Facebook
  39  eventually encountered).
  40  
  41  When the time comes to render the response, the page renderer uses
  42  @{class:CelerityAPI} to access the active
  43  @{class:CelerityStaticResourceResponse} and requests that it render out
  44  appropriate references to CSS and JS resources. It uses
  45  @{class:CelerityResourceMap} to determine the dependencies for the requested
  46  resources (so you only have to explicitly include what you're actually using,
  47  and not all of its dependencies) and any packaging rules (so it may be able to
  48  generate fewer resource requests, improving performance). It then generates
  49  `<script />` and `<link />` references to these resources.
  50  
  51  These references point at ##/res/## URIs, which are handled by
  52  @{class:CelerityResourceController}. It responds to these requests and delivers
  53  the relevant resources and packages, managing cache lifetimes and handling any
  54  neessary preprocessing. It uses @{class:CelerityResourceMap} to locate resources
  55  and read packaging rules.
  56  
  57  The dependency and packaging maps are generated by ##bin/celerity map##,
  58  which updates ##resources/celerity/map.php##.
  59  
  60  @{class:CelerityStaticResourceResponse} also manages some Javelin information,
  61  and @{function:celerity_generate_unique_node_id} uses this metadata to provide
  62  a better uniqueness guarantee when generating unique node IDs.