mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-15 11:22:40 +01:00
66 lines
3.1 KiB
Text
66 lines
3.1 KiB
Text
|
@title Celerity Technical Documentation
|
||
|
|
@group celerity
|
||
|
|
|
||
|
|
Technical overview of the Celerity system.
|
||
|
|
|
||
|
|
= Overview =
|
||
|
|
|
||
|
|
Celerity is a static resource (CSS and JS) management system, which handles:
|
||
|
|
|
||
|
|
- Keeping track of which resources a page needs.
|
||
|
|
- Generating URIs for the browser to access resources.
|
||
|
|
- Managing dependencies between resources.
|
||
|
|
- Packaging resources into fewer HTTP requests for performance.
|
||
|
|
- Preprocessing resources (e.g., stripping comments and whitespace).
|
||
|
|
- Delivering resources and managing resource cache lifetimes.
|
||
|
|
- Interfacing with the client to manage resources.
|
||
|
|
|
||
|
|
Celerity is an outgrowth of the //Haste// system at Facebook. You can find more
|
||
|
|
information about Celerity here:
|
||
|
|
|
||
|
|
- @{article:Things You Should Do Soon: Static Resources} describes the history
|
||
|
|
and context of the system and the problems it solves.
|
||
|
|
- @{article:Adding New CSS and JS} provides a developer guide to using
|
||
|
|
Celerity.
|
||
|
|
|
||
|
|
= Class Relationships =
|
||
|
|
|
||
|
|
Celerity's primary API is @{function:require_celerity_resource}, which marks a
|
||
|
|
resource for inclusion when a response is rendered (e.g., when the HTML page is
|
||
|
|
generated, or when the response to an Ajax request is built). For instance, if
|
||
|
|
you use a CSS class like "widget-view", you must ensure the appropriate CSS is
|
||
|
|
included by calling ##require_celerity_resource('widget-view-css')## (or
|
||
|
|
similar), at your use site.
|
||
|
|
|
||
|
|
This function uses @{class:CelerityAPI} to access the active
|
||
|
|
@{class:CelerityStaticResourceResponse} and tells it that it needs to include
|
||
|
|
the resource later, when the response actually gets built. (This layer of
|
||
|
|
indirection provides future-proofing against certain complex situations Facebook
|
||
|
|
eventually encountered).
|
||
|
|
|
||
|
|
When the time comes to render the response, the page renderer uses
|
||
|
|
@{class:CelerityAPI} to access the active
|
||
|
|
@{class:CelerityStaticResourceResponse} and requests that it render out
|
||
|
|
appropriate references to CSS and JS resources. It uses
|
||
|
|
@{class:CelerityResourceMap} to determine the dependencies for the requested
|
||
|
|
resources (so you only have to explicitly include what you're actually using,
|
||
|
|
and not all of its dependencies) and any packaging rules (so it may be able to
|
||
|
|
generate fewer resource requests, improving performance). It then generates
|
||
|
|
##<script />## and ##<link />## references to these resources.
|
||
|
|
|
||
|
|
These references point at ##/res/## URIs, which are handled by
|
||
|
|
@{class:CelerityResourceController}. It responds to these requests and delivers
|
||
|
|
the relevant resources and packages, managing cache lifetimes and handling any
|
||
|
|
neessary preprocessing. It uses @{class:CelerityResourceMap} to locate resources
|
||
|
|
and read packaging rules.
|
||
|
|
|
||
|
|
The dependency and packaging maps are generated by
|
||
|
|
##scripts/celerity_mapper.php##, which updates
|
||
|
|
##src/__celerity_resource_map__.php##. This file is automatically included and
|
||
|
|
just calls @{function:celerity_register_resource_map} with a large blob of
|
||
|
|
static data to populate @{class:CelerityResourceMap}.
|
||
|
|
|
||
|
|
@{class:CelerityStaticResourceResponse} also manages some Javelin information,
|
||
|
|
and @{function:celerity_generate_unique_node_id} uses this metadata to provide
|
||
|
|
a better uniqueness guarantee when generating unique node IDs.
|