docs/proposal-config.txt

   1
   2 Configuration
   3
   4 Configuration is documented on a per-use case: if a class uses a certain
   5 value from the configuration object, it has to define its name and what the
   6 value is used for.  This means decentralized configuration declarations that
   7 are nevertheless error checking and a centralized configuration object.
   8
   9 Directives are divided into namespaces, indicating the major portion of
  10 functionality they cover (although there may be overlaps).  Please consult
  11 the documentation in ConfigDef for more information on these namespaces.
  12
  13 Since configuration is dependant on context, internal classes require a
  14 configuration object to be passed as a parameter.  (They also require a
  15 Context object).
  16
  17 In relation to HTMLDefinition and CSSDefinition, there could be a special class
  18 of directives that influence the *construction* of the Definition object.
  19 A theoretical call pattern would look like:
  20
  21 1. Client calls Config->getHTMLDefinition()
  22 2. Config calls HTMLDefinition->createNew(this)
  23 3. HTMLDefinition constructs itself with base configuration
  24 4. HTMLDefinition calls Config->get('HTML')
  25 5. Config returns array of directives
  26 6. HTMLDefinition performs operations and changes specified by directives
  27 7. HTMLPurifier returns constructed definition
  28 8. Config caches definition so it doesn't have to be generated again
  29 9. Config returns definition
  30
  31 You could also override Config's copy of the definition with your own
  32 custom copy, which OVERRIDES all directives.  Only the base, vanilla copy
  33 is the Singleton, the object actually interfaced with is a operated-upon
  34 clone of that object.  Also, if an update to the directives would update
  35 the definition, you'd have to force reconstruction.
  36
  37 In practice, the pulling directives from the config object are
  38 solely need-based, and the flex points are littered throughout the
  39 setup() function.  Some sort of refactoring is likely in order. See
  40 ref-xhtml-1.1.txt for more info.