Issue #2187889 by colan: Use empty string as default value if there isn't one.
[project/context.git] / 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. Create a Drupal integration point for your plugin. A node page condition
65   plugin, for example, may be invoked from `hook_node_view()`. Typically a
66   Drupal integration point for a condition uses a Drupal hook to trigger
67   tests that determine whether context conditions are met for one or more
68   plug-ins. For example, this is how the context module itself uses
69   hook_init():
70
71         function context_init() {
72           if ($plugin = context_get_plugin('condition', 'path')) {
73             $plugin->execute();
74           }
75           if ($plugin = context_get_plugin('condition', 'language')) {
76             global $language;
77             $plugin->execute($language->language);
78           }
79           if ($plugin = context_get_plugin('condition', 'user')) {
80             global $user;
81             $plugin->execute($user);
82           }
83         }
84
85   This function first instantiates the Context module's path condition
86   plugin (filename context_condition_path.inc in the plugins directory),
87   and then uses that plugin's execute() method. The execute() method
88   determine whether any path conditions are met and, if so, it activates
89   the contexts that match those conditions. After setting contexts based
90   path conditions, the context_init() function then does the same thing
91   with the Context module's language and user condition plugins.
92
93 Replacing or extending existing plugins
94 ---------------------------------------
95 You can replace a condition or reaction plugin with your own plugin class using
96 `hook_context_registry_alter()`:
97
98     function mymodule_context_registry_alter(&$registry) {
99       if (!empty($registry['conditions']['node'])) {
100         $registry['conditions']['node']['plugin'] = 'mymodule_context_condition_customnode';
101       }
102     }
103
104 This entry would swap out the default node condition plugin for a custom one
105 provided by `mymodule`. Note that any replacement plugins must have an entry in
106 `hook_context_plugins()`.