Issue #2193179 by Elijah Lynn: Undefined index $form_state['clicked_button']['#id'].
[project/sps.git] / sps.plugins.api.php
1 <?php
2 /**
3 * @file
4 * SPS Plugins API Documentation.
5 *
6 * The sps module allows a set of plugins to expand what entities can be
7 * overridden in preview mode, and how those overrides should be chosen.
8 *
9 *
10 * Conditions are use for selecting which entity should be overridden, That info
11 * is then passed on to override controllers which store the data in meaningful
12 * ways. Finally the Reaction Use that data to change things in Drupal so the
13 * user may preview how overrides apply.
14 *
15 * .-----------------------------.
16 * | Condition Plugins |
17 * |-----------------------------|
18 * | Find what overrides |
19 * | should be in place |
20 * | when previewing a site |
21 * '-----------------------------'
22 * |
23 * |
24 * v
25 * .-----------------------------.
26 * | Override Controller Plugins |
27 * |-----------------------------|
28 * | Store Overrides In |
29 * | Ways for reactions |
30 * | to use them |
31 * '-----------------------------'
32 * |
33 * |
34 * v
35 * .-----------------------------.
36 * | Reaction Plugins |
37 * |-----------------------------|
38 * | Change what is displayed |
39 * | based on what is in the |
40 * | Override Controllers |
41 * '-----------------------------'
42 *
43 * There are two other Plugins Widgets and Overrides, This are used by
44 * Condition that use the BasicCondition class. Condition of this class
45 * search the plugin system for the correct widget and overrides to use @see
46 * hook_sps_condition_plugins()
47 */
48
49 /**
50 * Used to define Condition for the SPS System.
51 *
52 * The condition plugin is used to collect, store condition information, and
53 * then use that information to query what overrides should be in effect.
54 * There is a default class for conditions
55 * (Drupal\sps\Plugins\Condition\BasicCondition) which can be use in most
56 * case.
57 *
58 * The hook should return an array of plugin arrays keyed by the name of the
59 * condition. There are no required fields for condition plugins, if one is
60 * going to use the default value for class (which is
61 * Drupal\sps\plugins\Condition\BasicCondition) then the they should provide
62 * instance_settings with items for name, widget and title.
63 * if the class is stated it must be a class that implements
64 * Drupal\sps\plugins\ConditionInterface
65 *
66 * @see Drupal\sps\plugins\ConditionInterface
67 * @see Drupal\sps\plugins\Condition\BasicCondition
68 *
69 * There is one other key root_condition by default this is set to false. if
70 * it is set to TRUE then this condition will be excluded from use by the root
71 * condition sps implements (default_root_condition). This should be use if
72 * one is planing on replacing the default_root_condition.
73 *
74 * BasicCondition
75 *
76 * This base condition use widget and override plugins. The widget to use
77 * is passed in as a instance setting and the name is use to find all
78 * override plugins that should be used by the condition.
79 * .----------------------------.
80 * | date_condition |
81 * |----------------------------|
82 * | class : BasicCondition |
83 * | instance_settings : | .-----------------------------------.
84 * | widget : date_widget ------------------------> date_widget |
85 * | name : date_condition <------. |-----------------------------------|
86 * '----------------------------' | | class : Drupal\sps\...\DateWidget |
87 * | '-----------------------------------'
88 * |
89 * | .------------------------------------.
90 * | | ers_override |
91 * | |------------------------------------|
92 * | | class : Drupal\sps_ers\ERSOverride |
93 * '------condition : date_condition |
94 * '------------------------------------'
95 *
96 * @see hook_sps_widget_plugins
97 * @see Drupal\sps\Plugins\WidgetInterface
98 * @see hook_sps_override_plugins
99 * @see Drupal\sps\Plugins\OverrideInterface
100 */
101 function hook_sps_condition_plugins() {
102 return array(
103 'date_condition' => array(
104 'instance_settings' => array(
105 'name' => 'date_condition',
106 'widget' => 'date_widget',
107 'title' => 'Site as of ...',
108 ),
109 ),
110 );
111 }
112
113 /**
114 * Define Override Controller (override storage objects) for the SPS System
115 *
116 * The override controllers provide an interface for reaction plugins to access
117 * override information. Each plugin must say which api it implements and what
118 * class is used. There are two api and two plugins provided by sps.
119 *
120 * They system will only use one override controller per api key. The system
121 * first looks to a map table in the sps config, under the key
122 * SPS_CONFIG_OVERRIDE_CONTROLLER, then it finds the first plugin that
123 * implements a particular api.
124 *
125 * The two override controller provide by sps are the simple_cache and
126 * temp_table plugins they implement the controller_api simple_cache and
127 * mysql_table respectively. For more detail about then one can see there
128 * class or the interface they implement, but in general the simple_cache is a
129 * simple storing of the overrides in its internals, with methods for retrieving
130 * that data. The temp_table has methods for pushing the override data into a
131 * temp table, that can then be use in queries. for example of how this are
132 * used one can inspect the entity_load and entity_select_query_alter reactions
133 * respectively.
134 *
135 * @see Drupal\sps\Manager::getOverrideControllerMap()
136 * @see Drupal\sps\plugins\OverrideControllerInterface
137 * @see Drupal\sps\plugins\OverrideController\SimpleCacheOverrideControllerInterface
138 * @see Drupal\sps\plugins\OverrideController\TableOverrideStorageControllerInterface
139 */
140 function hook_sps_override_controller_plugins() {
141 return array(
142 'simple_cache' => array(
143 'class' => '\Drupal\sps\Plugins\OverrideController\SimpleCacheOverrideController',
144 'implements_controller_api' => 'simple_cache',
145 ),
146 'temp_table' => array(
147 'class' => '\Drupal\sps\Plugins\OverrideController\TempTableOverrideController',
148 'implements_controller_api' => 'mysql_table',
149 ),
150 );
151 }
152
153 /**
154 * Define Reactions for the SPS System.
155 *
156 * The reaction plugins use current override data to react to the fact that
157 * some entity values are overridden. Each reaction must specify what
158 * controller api in uses (see Override Controllers). Defining a reaction by
159 * it self will have no effect, one must also call the reaction using the
160 * managers react method. as an example the entity_select_query_alter reaction
161 * is call in sps_query_alter
162 *
163 * function sps_query_alter($query) {
164 * $data = new stdClass();
165 * $data->query=$query;
166 * sps_get_manager()->react('entity_select_query_alter', $data);
167 * }
168
169 * One should put all logic in to the react and not in to the hook use to call
170 * it. This why the manager can issue the the reaction should occur before
171 * calling any of that logic.
172 *
173 * @see Drupal\sps\Manager::react
174 *
175 * The class is a mandatory value in the plugin and should implement
176 * Drupal\sps\Plugins\ReactionInterface. Also the use_controller_api is
177 * mandatory, not if there are no override controllers that implement the api
178 * stated then the reaction will not be run.
179 *
180 * @see hook_sps_override_controller_plugins
181 * @see Drupal\sps\Plugins\ReactionInterface
182 */
183 function hook_sps_reaction_plugins() {
184 $reactions = array(
185 'entity_load' => array(
186 'class' => 'Drupal\sps\Plugins\Reaction\EntityLoadReaction',
187 'use_controller_api' => 'simple_cache',
188 'instance_settings' => array(),
189 ),
190 );
191 return $reactions;
192 }
193
194 /**
195 * Define Wddget plugins for use by sps conditions.
196 *
197 * Widget plugins are used by the BasicCondition class, they provide a widget
198 * to be used in the sps preview form, this includes validation and a
199 * transformation of the form data in to a array of data to be used by the
200 * condition.
201 *
202 * The class used should implement the Drupal\sps\Plugins\WidgetInterface
203 *
204 * @see Drupal\sps\Plugins\WidgetInterface
205 * @see hook_sps_condition_plugins()
206 */
207 function hook_sps_widget_plugins() {
208 return array(
209 'date_widget' => array(
210 'class' => 'Drupal\sps\Plugins\Widget\DateWidget',
211 'instance_settings' => array(
212 'title' => 'Preview Date',
213 ),
214 ),
215 );
216 }
217
218
219 /**
220 * Define Override Object for use by sps Conditions.
221 *
222 * Override Plugins do the heavy lifting for Conditions that use the
223 * BasicCondition Class. Each Override Plugin should say which condition should
224 * use it.
225 *
226 * @see Drupal\sps\Plugins\WidgetInterface
227 * @see hook_sps_condition_plugins()
228 */
229 function hook_sps_override_plugins() {
230 return array(
231 'ers_override' => array(
232 'class' => 'Drupal\sps_ers\ERSOverride',
233 'condition' => 'date_condition',
234 ),
235 );
236 }
237