src/docs/tech/celerity.diviner

   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 necessary 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.