API.txt

   1
   2 Context 3.x API
   3 ---------------
   4 The following is an overview of using the Context API.
   5
   6
   7 The context static cache
   8 ------------------------
   9 Context provides a centralized set of API functions for setting and retrieving a
  10 static cache:
  11
  12     // Set a static cache value at [my_namspace][mykey]
  13     context_set('my_namespace', 'mykey', $value);
  14
  15     // Retrieve a static cache value at [my_namespace][mykey]
  16     context_get('my_namespace', 'mykey'); // $value
  17
  18     // Boolean for whether there is a value at [my_namespace][mykey]
  19     context_isset('my_namespace', 'mykey'); // TRUE
  20
  21 These are used internally by context but may also be used by other modules. Just
  22 do not use the namespace `context` unless you want to affect things that context
  23 is up to.
  24
  25
  26 Adding a condition or reaction plugin
  27 -------------------------------------
  28 Both context conditions and reactions utilize the CTools plugins API. In order
  29 to add a new condition or reaction for your module, follow these steps:
  30
  31 1. Implement `hook_context_plugins()` to define your plugins, classes, and class
  32   hierarchy.
  33
  34         function mymodule_context_plugins() {
  35           $plugins = array();
  36           $plugins['mymodule_context_condition_bar'] = array(
  37             'handler' => array(
  38               'path' => drupal_get_path('module', 'mymodule') .'/plugins',
  39               'file' => 'mymodule_context_condition_bar.inc',
  40               'class' => 'mymodule_context_condition_bar',
  41               'parent' => 'context_condition',
  42             ),
  43           );
  44           return $plugins;
  45         }
  46
  47 2. Implement `hook_context_registry()` to define your conditions and/or
  48   reactions and map them to plugins.
  49
  50         function mymodule_context_registry() {
  51           return array(
  52             'conditions' => array(
  53               'bar' => array(
  54                 'title' => t('Name of condition "bar"'),
  55                 'plugin' => 'mymodule_context_condition_bar',
  56               ),
  57             ),
  58           );
  59         }
  60
  61 3. Write your condition or reaction plugin class. It's best to look at one of
  62   the included plugins as a starting point.
  63
  64 4. Add in a Drupal integration point for your plugin. A node page condition
  65   plugin, for example, may be invoked from `hook_nodeapi()`.
  66
  67
  68 Replacing or extending existing plugins
  69 ---------------------------------------
  70 You can replace a condition or reaction plugin with your own plugin class using
  71 `hook_context_registry_alter()`:
  72
  73     function mymodule_context_registry_alter(&$registry) {
  74       if (!empty($registry['conditions']['node'])) {
  75         $registry['conditions']['node']['plugin'] = 'mymodule_context_condition_customnode';
  76       }
  77     }
  78
  79 This entry would swap out the default node condition plugin for a custom one
  80 provided by `mymodule`. Note that any replacement plugins must have an entry in
  81 `hook_context_plugins()`.