root / drupal7 / sites / all / modules / diff / diff.api.php @ 661d64c9
1 |
<?php
|
---|---|
2 |
|
3 |
/**
|
4 |
* @file
|
5 |
* Hooks provided by the diff module.
|
6 |
*/
|
7 |
|
8 |
/**
|
9 |
* @addtogroup hooks
|
10 |
* @{
|
11 |
*/
|
12 |
|
13 |
/**
|
14 |
* Allow modules to provide a comparison about entity properties.
|
15 |
*
|
16 |
* @param object $old_entity
|
17 |
* The older entity revision.
|
18 |
*
|
19 |
* @param object $new_entity
|
20 |
* The newer entity revision.
|
21 |
*
|
22 |
* @param array $context
|
23 |
* An associative array containing:
|
24 |
* - entity_type: The entity type; e.g., 'node' or 'user'.
|
25 |
* - old_entity: The older entity.
|
26 |
* - new_entity: The newer entity.
|
27 |
* - view_mode: The view mode to use. Defaults to FALSE. If no view mode is
|
28 |
* given, the recommended fallback view mode is 'default'.
|
29 |
* - states: An array of view states. These could be one of:
|
30 |
* - raw: The raw value of the diff, the classic 7.x-2.x view.
|
31 |
* - rendered: The rendered HTML as determined by the view mode. Only
|
32 |
* return markup for this state if the value is normally shown
|
33 |
* by this view mode. The user will most likely be able to see
|
34 |
* the raw or raw_plain state, so this is optional.
|
35 |
*
|
36 |
* The rendering state is a work in progress.
|
37 |
*
|
38 |
* Conditionally, you can get these states, but setting these will override
|
39 |
* the user selectable markdown method.
|
40 |
*
|
41 |
* - raw_plain: As raw, but text should be markdowned.
|
42 |
* - rendered_plain: As rendered, but text should be markdowned.
|
43 |
*
|
44 |
* @return array
|
45 |
* An associative array of values keyed by the entity property.
|
46 |
*
|
47 |
* This is effectively an unnested Form API-like structure.
|
48 |
*
|
49 |
* States are returned as follows:
|
50 |
*
|
51 |
* $results['line'] = array(
|
52 |
* '#name' => t('Line'),
|
53 |
* '#states' => array(
|
54 |
* 'raw' => array(
|
55 |
* '#old' => '<p class="line">This was the old line number [tag].</p>',
|
56 |
* '#new' => '<p class="line">This is the new line [tag].</p>',
|
57 |
* ),
|
58 |
* 'rendered' => array(
|
59 |
* '#old' => '<p class="line">This was the old line number <span class="line-number">57</span>.</p>',
|
60 |
* '#new' => '<p class="line">This is the new line <span class="line-number">57</span>.</p>',
|
61 |
* ),
|
62 |
* ),
|
63 |
* );
|
64 |
*
|
65 |
* For backwards compatibility, no changes are required to support states,
|
66 |
* but it is recommended to provide a better UI for end users.
|
67 |
*
|
68 |
* For example, the following example is equivalent to returning the raw
|
69 |
* state from the example above.
|
70 |
*
|
71 |
* $results['line'] = array(
|
72 |
* '#name' => t('Line'),
|
73 |
* '#old' => '<p class="line">This was the old line number [tag].</p>',
|
74 |
* '#new' => '<p class="line">This is the new line [tag].</p>',
|
75 |
* );
|
76 |
*/
|
77 |
function hook_entity_diff($old_entity, $new_entity, $context) { |
78 |
$results = array(); |
79 |
|
80 |
if ($context['entity_type'] == 'node') { |
81 |
$type = node_type_get_type($new_entity); |
82 |
$results['title'] = array( |
83 |
'#name' => $type->title_label, |
84 |
'#old' => array($old_entity->title), |
85 |
'#new' => array($new_entity->title), |
86 |
'#weight' => -5, |
87 |
'#settings' => array( |
88 |
'show_header' => FALSE, |
89 |
), |
90 |
); |
91 |
} |
92 |
|
93 |
return $results; |
94 |
} |
95 |
|
96 |
/**
|
97 |
* Allow modules to alter a comparison about entities.
|
98 |
*
|
99 |
* @param array $entity_diffs
|
100 |
* An array of entity differences.
|
101 |
* @param array $context
|
102 |
* An associative array containing:
|
103 |
* - entity_type: The entity type; e.g., 'node' or 'user'.
|
104 |
* - old_entity: The older entity.
|
105 |
* - new_entity: The newer entity.
|
106 |
* - view_mode: The view mode to use. Defaults to FALSE.
|
107 |
*
|
108 |
* @see hook_entity_diff()
|
109 |
*/
|
110 |
function hook_entity_diff_alter(&$entity_diffs, $context) { |
111 |
} |
112 |
|
113 |
/**
|
114 |
* Callback to the module that defined the field to prepare items comparison.
|
115 |
*
|
116 |
* This allows the module to alter all items prior to rendering the comparative
|
117 |
* values. It is mainly used to bulk load entities to reduce overheads
|
118 |
* associated with loading entities individually.
|
119 |
*
|
120 |
* @param array $old_items
|
121 |
* An array of field items from the older revision.
|
122 |
* @param array $new_items
|
123 |
* An array of field items from the newer revision.
|
124 |
* @param array $context
|
125 |
* An associative array containing:
|
126 |
* - entity_type: The entity type; e.g., 'node' or 'user'.
|
127 |
* - bundle: The bundle name.
|
128 |
* - field: The field that the items belong to.
|
129 |
* - instance: The instance that the items belong to.
|
130 |
* - language: The language associated with $items.
|
131 |
* - old_entity: The older entity.
|
132 |
* - new_entity: The newer entity.
|
133 |
*
|
134 |
* @see MODULE_field_diff_view()
|
135 |
*/
|
136 |
function MODULE_field_diff_view_prepare(&$old_items, &$new_items, $context) { |
137 |
$fids = array(); |
138 |
foreach (array_merge_recursive($old_items, $new_items) as $info) { |
139 |
$fids[$info['fid']] = $info['fid']; |
140 |
} |
141 |
// A single load is much faster than individual loads.
|
142 |
$files = file_load_multiple($fids); |
143 |
|
144 |
// For ease of processing, store a reference of the entity on the item array.
|
145 |
foreach ($old_items as $delta => $info) { |
146 |
$old_items[$delta]['file'] = isset($files[$info['fid']]) ? $files[$info['fid']] : NULL; |
147 |
} |
148 |
foreach ($new_items as $delta => $info) { |
149 |
$new_items[$delta]['file'] = isset($files[$info['fid']]) ? $files[$info['fid']] : NULL; |
150 |
} |
151 |
} |
152 |
|
153 |
/**
|
154 |
* Callback to the module that defined the field to generate items comparisons.
|
155 |
*
|
156 |
* @param array $items
|
157 |
* An array of field items from the entity.
|
158 |
* @param array $context
|
159 |
* An associative array containing:
|
160 |
* - entity: The entity being compared.
|
161 |
* - entity_type: The entity type; e.g., 'node' or 'user'.
|
162 |
* - bundle: The bundle name.
|
163 |
* - field: The field that the items belong to.
|
164 |
* - instance: The instance that the items belong to.
|
165 |
* - language: The language associated with $items.
|
166 |
* - old_entity: The older entity.
|
167 |
* - new_entity: The newer entity.
|
168 |
*
|
169 |
* @see MODULE_field_diff_view_prepare()
|
170 |
*/
|
171 |
function MODULE_field_diff_view($items, $context) { |
172 |
$diff_items = array(); |
173 |
foreach ($items as $delta => $item) { |
174 |
if (isset($item['file'])) { |
175 |
$diff_items[$delta] = $item['file']->filename . ' [fid: ' . $item['fid'] . ']'; |
176 |
} |
177 |
} |
178 |
|
179 |
return $diff_items; |
180 |
} |
181 |
|
182 |
/**
|
183 |
* Allow other modules to interact with MODULE_field_diff_view_prepare().
|
184 |
*
|
185 |
* @param array $old_items
|
186 |
* An array of field items from the older revision.
|
187 |
* @param array $new_items
|
188 |
* An array of field items from the newer revision.
|
189 |
* @param array $context
|
190 |
* An associative array containing:
|
191 |
* - entity_type: The entity type; e.g., 'node' or 'user'.
|
192 |
* - bundle: The bundle name.
|
193 |
* - field: The field that the items belong to.
|
194 |
* - instance: The instance that the items belong to.
|
195 |
* - language: The language associated with $items.
|
196 |
* - old_entity: The older entity.
|
197 |
* - new_entity: The newer entity.
|
198 |
*
|
199 |
* @see MODULE_field_diff_view_prepare()
|
200 |
*/
|
201 |
function hook_field_diff_view_prepare_alter($old_items, $new_items, $context) { |
202 |
|
203 |
} |
204 |
|
205 |
/**
|
206 |
* Allow other modules to interact with MODULE_field_diff_view().
|
207 |
*
|
208 |
* @param array $values
|
209 |
* An array of field items from the entity ready for comparison.
|
210 |
* @param array $items
|
211 |
* An array of field items from the entity.
|
212 |
* @param array $context
|
213 |
* An associative array containing:
|
214 |
* - entity: The entity being compared.
|
215 |
* - entity_type: The entity type; e.g., 'node' or 'user'.
|
216 |
* - bundle: The bundle name.
|
217 |
* - field: The field that the items belong to.
|
218 |
* - instance: The instance that the items belong to.
|
219 |
* - language: The language associated with $items.
|
220 |
* - old_entity: The older entity.
|
221 |
* - new_entity: The newer entity.
|
222 |
*
|
223 |
* @see MODULE_field_diff_view()
|
224 |
*/
|
225 |
function hook_field_diff_view_alter($values, $items, $context) { |
226 |
|
227 |
} |
228 |
|
229 |
/**
|
230 |
* @} End of "addtogroup hooks".
|
231 |
*/
|