features.api.php 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476
  1. <?php
  2. /**
  3. * Main info hook that features uses to determine what components are provided
  4. * by the implementing module.
  5. *
  6. * @return array
  7. * An array of components, keyed by the component name. Each component can
  8. * define several keys:
  9. *
  10. * 'file': Optional path to a file to include which contains the rest
  11. * of the features API hooks for this module.
  12. *
  13. * 'default_hook': The defaults hook for your component that is called
  14. * when the cache of default components is generated. Examples include
  15. * hook_views_default_views() or hook_context_default_contexts().
  16. *
  17. * 'default_file': The file-writing behavior to use when exporting this
  18. * component. May be one of 3 constant values:
  19. *
  20. * FEATURES_DEFAULTS_INCLUDED_COMMON: write hooks/components to
  21. * `.features.inc` with other components. This is the default behavior
  22. * if this key is not defined.
  23. *
  24. * FEATURES_DEFAULTS_INCLUDED: write hooks/components to a component-
  25. * specific include named automatically by features.
  26. *
  27. * FEATURES_DEFAULTS_CUSTOM: write hooks/components to a component-
  28. * specific include with a custom name provided. If your module provides
  29. * large amounts of code that should not be parsed often (only on specific
  30. * cache clears/rebuilds, for example) you should use the 2nd or 3rd
  31. * options to split your component into its own include.
  32. *
  33. * 'default_filename': The filename to use when 'default_file' is set to
  34. * FEATURES_DEFAULTS_CUSTOM.
  35. *
  36. * 'feature_source': Boolean value for whether this component should be
  37. * offered as an option on the initial feature creation form.
  38. *
  39. * 'base': Optional. An alternative base key to use when calling features
  40. * hooks for this component. Can be used for features component types that
  41. * are declared "dynamically" or are part of a family of components.
  42. *
  43. * 'alter_type': What type of alter hook this hook uses. 'normal' is called
  44. * after the main hook is called. 'inline' is embeded within the default hook
  45. * and may not be implemented by some default hooks.
  46. * 'none' is no alter hook exists. Defaults to 'normal'
  47. *
  48. * 'alter_hook': What the name of the alter hook for this component is.
  49. * Do not include the '_alter' part. Defaults to 'default_hook'.
  50. */
  51. function hook_features_api() {
  52. return array(
  53. 'mycomponent' => array(
  54. 'default_hook' => 'mycomponent_defaults',
  55. 'default_file' => FEATURES_DEFAULTS_INCLUDED,
  56. 'feature_source' => TRUE,
  57. 'file' => drupal_get_path('module', 'mycomponent') . '/mycomponent.features.inc',
  58. ),
  59. );
  60. }
  61. /**
  62. * Component hook. The hook should be implemented using the name of the
  63. * component, not the module, eg. [component]_features_export() rather than
  64. * [module]_features_export().
  65. *
  66. * Process the export array for a given component. Implementations of this hook
  67. * have three key tasks:
  68. *
  69. * 1. Determine module dependencies for any of the components passed to it
  70. * e.g. the views implementation iterates over each views' handlers and
  71. * plugins to determine which modules need to be added as dependencies.
  72. *
  73. * 2. Correctly add components to the export array. In general this is usually
  74. * adding all of the items in $data to $export['features']['my_key'], but
  75. * can become more complicated if components are shared between features
  76. * or modules.
  77. *
  78. * 3. Delegating further detection and export tasks to related or derivative
  79. * components.
  80. *
  81. * Each export processor can kickoff further export processors by returning a
  82. * keyed array (aka the "pipe") where the key is the next export processor hook
  83. * to call and the value is an array to be passed to that processor's $data
  84. * argument. This allows an export process to start simply at a few objects:
  85. *
  86. * [context]
  87. *
  88. * And then branch out, delegating each component to its appropriate hook:
  89. *
  90. * [context]--------+------------+
  91. * | | |
  92. * [node] [block] [views]
  93. * |
  94. * [CCK]
  95. * |
  96. * [imagecache]
  97. *
  98. * @param array $data
  99. * An array of machine names for the component in question to be exported.
  100. * @param array &$export
  101. * By reference. An array of all components to be exported with a given
  102. * feature. Component objects that should be exported should be added to
  103. * this array.
  104. * @param string $module_name
  105. * The name of the feature module to be generated.
  106. * @return array
  107. * The pipe array of further processors that should be called.
  108. */
  109. function hook_features_export($data, &$export, $module_name) {
  110. // The following is the simplest implementation of a straight object export
  111. // with no further export processors called.
  112. foreach ($data as $component) {
  113. $export['features']['mycomponent'][$component] = $component;
  114. }
  115. return array();
  116. }
  117. /**
  118. * Component hook. The hook should be implemented using the name of the
  119. * component, not the module, eg. [component]_features_export() rather than
  120. * [module]_features_export().
  121. *
  122. * List all objects for a component that may be exported.
  123. *
  124. * @return array
  125. * A keyed array of items, suitable for use with a FormAPI select or
  126. * checkboxes element.
  127. */
  128. function hook_features_export_options() {
  129. $options = array();
  130. foreach (mycomponent_load() as $mycomponent) {
  131. $options[$mycomponent->name] = $mycomponent->title;
  132. }
  133. return $options;
  134. }
  135. /**
  136. * Component hook. The hook should be implemented using the name of the
  137. * component, not the module, eg. [component]_features_export() rather than
  138. * [module]_features_export().
  139. *
  140. * Render one or more component objects to code.
  141. *
  142. * @param string $module_name
  143. * The name of the feature module to be exported.
  144. * @param array $data
  145. * An array of machine name identifiers for the objects to be rendered.
  146. * @param array $export
  147. * The full export array of the current feature being exported. This is only
  148. * passed when hook_features_export_render() is invoked for an actual feature
  149. * update or recreate, not during state checks or other operations.
  150. * @return array
  151. * An associative array of rendered PHP code where the key is the name of the
  152. * hook that should wrap the PHP code. The hook should not include the name
  153. * of the module, e.g. the key for `hook_example` should simply be `example`
  154. * The values in the array can also be in the form of an associative array
  155. * with the required key of 'code' and optional key of 'args', if 'args' need
  156. * to be added to the hook.
  157. */
  158. function hook_features_export_render($module_name, $data, $export = NULL) {
  159. $code = array();
  160. $code[] = '$mycomponents = array();';
  161. foreach ($data as $name) {
  162. $code[] = " \$mycomponents['{$name}'] = " . features_var_export(mycomponent_load($name)) .";";
  163. }
  164. $code[] = "return \$mycomponents;";
  165. $code = implode("\n", $code);
  166. return array('mycomponent_defaults' => $code);
  167. }
  168. /**
  169. * Component hook. The hook should be implemented using the name of the
  170. * component, not the module, eg. [component]_features_export() rather than
  171. * [module]_features_export().
  172. *
  173. * Revert all component objects for a given feature module.
  174. *
  175. * @param string $module_name
  176. * The name of the feature module whose components should be reverted.
  177. * @return boolean
  178. * TRUE or FALSE for whether the components were successfully reverted.
  179. * NOTE: This return value is no longer used in the latest Features so
  180. * modules should no longer count on this value
  181. */
  182. function hook_features_revert($module_name) {
  183. $mycomponents = module_invoke($module_name, 'mycomponent_defaults');
  184. if (!empty($mycomponents)) {
  185. foreach ($mycomponents as $mycomponent) {
  186. mycomponent_delete($mycomponent);
  187. }
  188. }
  189. }
  190. /**
  191. * Component hook. The hook should be implemented using the name of the
  192. * component, not the module, eg. [component]_features_export() rather than
  193. * [module]_features_export().
  194. *
  195. * Rebuild all component objects for a given feature module. Should only be
  196. * implemented for 'faux-exportable' components.
  197. *
  198. * This hook is called at points where Features determines that it is safe
  199. * (ie. the feature is in state `FEATURES_REBUILDABLE`) for your module to
  200. * replace objects in the database with defaults that you collect from your
  201. * own defaults hook. See API.txt for how Features determines whether a
  202. * rebuild of components is possible.
  203. *
  204. * @param string $module_name
  205. * The name of the feature module whose components should be rebuilt.
  206. */
  207. function hook_features_rebuild($module_name) {
  208. $mycomponents = module_invoke($module_name, 'mycomponent_defaults');
  209. if (!empty($mycomponents)) {
  210. foreach ($mycomponents as $mycomponent) {
  211. mycomponent_save($mycomponent);
  212. }
  213. }
  214. }
  215. /**
  216. * Alter the final array of Component names to be exported, just prior to
  217. * the rendering of defaults. Allows modules a final say in whether or not
  218. * certain Components are exported (the Components' actual data, however,
  219. * cannot be altered by this hook).
  220. *
  221. * @param array &$export
  222. * By reference. An array of all component names to be exported with a given
  223. * feature.
  224. * @param array $module_name
  225. * The name of the feature module to be generated.
  226. */
  227. function hook_features_export_alter(&$export, $module_name) {
  228. // Example: do not allow the page content type to be exported, ever.
  229. if (!empty($export['features']['node']['page'])) {
  230. unset($export['features']['node']['page']);
  231. }
  232. }
  233. /**
  234. * Alter the pipe array for a given component. This hook should be implemented
  235. * with the name of the component type in place of `component` in the function
  236. * name, e.g. `features_pipe_views_alter()` will alter the pipe for the Views
  237. * component.
  238. *
  239. * @param array &$pipe
  240. * By reference. The pipe array of further processors that should be called.
  241. * @param array $data
  242. * An array of machine names for the component in question to be exported.
  243. * @param array &$export
  244. * By reference. An array of all components to be exported with a given
  245. * feature.
  246. */
  247. function hook_features_pipe_COMPONENT_alter(&$pipe, $data, $export) {
  248. if (in_array($data, 'my-node-type')) {
  249. $pipe['dependencies'][] = 'mymodule';
  250. }
  251. }
  252. /**
  253. * Alter the pipe array for a given component.
  254. *
  255. * @param array &$pipe
  256. * By reference. The pipe array of further processors that should be called.
  257. * @param array $data
  258. * An array of machine names for the component in question to be exported.
  259. * @param array &$export
  260. * By reference. An array of all components to be exported with a given
  261. * feature.
  262. *
  263. * The component being exported is contained in $export['component'].
  264. * The module being exported contained in $export['module_name'].
  265. */
  266. function hook_features_pipe_alter(&$pipe, $data, $export) {
  267. if ($export['component'] == 'node' && in_array($data, 'my-node-type')) {
  268. $pipe['dependencies'][] = 'mymodule';
  269. }
  270. }
  271. /**
  272. * @defgroup features_component_alter_hooks Feature's component alter hooks
  273. * @{
  274. * Hooks to modify components defined by other features. These come in the form
  275. * hook_COMPONENT_alter where COMPONENT is the default_hook declared by any of
  276. * components within features.
  277. *
  278. * CTools also has a variety of hook_FOO_alters.
  279. *
  280. * Note: While views is a component of features, it declares it's own alter
  281. * function which takes a similar form:
  282. * hook_views_default_views_alter(&$views)
  283. */
  284. /**
  285. * Alter the default fields right before they are cached into the database.
  286. *
  287. * @param &$fields
  288. * By reference. The fields that have been declared by another feature.
  289. */
  290. function hook_field_default_fields_alter(&$fields) {
  291. }
  292. /**
  293. * Alter the default fieldgroup groups right before they are cached into the
  294. * database.
  295. *
  296. * @param &$groups
  297. * By reference. The fieldgroup groups that have been declared by another
  298. * feature.
  299. */
  300. function hook_fieldgroup_default_groups_alter(&$groups) {
  301. }
  302. /**
  303. * Alter the default filter formats right before they are cached into the
  304. * database.
  305. *
  306. * @param &$formats
  307. * By reference. The formats that have been declared by another feature.
  308. */
  309. function hook_filter_default_formats_alter(&$formats) {
  310. }
  311. /**
  312. * Alter the default menus right before they are cached into the database.
  313. *
  314. * @param &$menus
  315. * By reference. The menus that have been declared by another feature.
  316. */
  317. function hook_menu_default_menu_custom_alter(&$menus) {
  318. }
  319. /**
  320. * Alter the default menu links right before they are cached into the database.
  321. *
  322. * @param &$links
  323. * By reference. The menu links that have been declared by another feature.
  324. */
  325. function hook_menu_default_menu_links_alter(&$links) {
  326. }
  327. /**
  328. * Alter the default menu items right before they are cached into the database.
  329. *
  330. * @param &$items
  331. * By reference. The menu items that have been declared by another feature.
  332. */
  333. function hook_menu_default_items_alter(&$items) {
  334. }
  335. /**
  336. * Alter the default vocabularies right before they are cached into the
  337. * database.
  338. *
  339. * @param &$vocabularies
  340. * By reference. The vocabularies that have been declared by another feature.
  341. */
  342. function hook_taxonomy_default_vocabularies_alter(&$vocabularies) {
  343. }
  344. /**
  345. * Alter the default permissions right before they are cached into the
  346. * database.
  347. *
  348. * @param &$permissions
  349. * By reference. The permissions that have been declared by another feature.
  350. */
  351. function hook_user_default_permissions_alter(&$permissions) {
  352. }
  353. /**
  354. * Alter the default roles right before they are cached into the database.
  355. *
  356. * @param &$roles
  357. * By reference. The roles that have been declared by another feature.
  358. */
  359. function hook_user_default_roles_alter(&$roles) {
  360. }
  361. /**
  362. * @}
  363. */
  364. /**
  365. * @defgroup features_module_hooks Feature module hooks
  366. * @{
  367. * Hooks invoked on Feature modules when that module is enabled, disabled,
  368. * rebuilt, or reverted. These are ONLY invoked on the Features module on
  369. * which these actions are taken.
  370. */
  371. /**
  372. * Feature module hook. Invoked on a Feature module before that module is
  373. * reverted.
  374. *
  375. * @param $component
  376. * String name of the component that is about to be reverted.
  377. */
  378. function hook_pre_features_revert($component) {
  379. }
  380. /**
  381. * Feature module hook. Invoked on a Feature module after that module is
  382. * reverted.
  383. *
  384. * @param $component
  385. * String name of the component that has just been reverted.
  386. */
  387. function hook_post_features_revert($component) {
  388. }
  389. /**
  390. * Feature module hook. Invoked on a Feature module before that module is
  391. * rebuilt.
  392. *
  393. * @param $component
  394. * String name of the component that is about to be rebuilt.
  395. */
  396. function hook_pre_features_rebuild($component) {
  397. }
  398. /**
  399. * Feature module hook. Invoked on a Feature module after that module is
  400. * rebuilt.
  401. *
  402. * @param $component
  403. * String name of the component that has just been rebuilt.
  404. */
  405. function hook_post_features_rebuild($component) {
  406. }
  407. /**
  408. * Feature module hook. Invoked on a Feature module before that module is
  409. * disabled.
  410. *
  411. * @param $component
  412. * String name of the component that is about to be disabled.
  413. */
  414. function hook_pre_features_disable_feature($component) {
  415. }
  416. /**
  417. * Feature module hook. Invoked on a Feature module after that module is
  418. * disabled.
  419. *
  420. * @param $component
  421. * String name of the component that has just been disabled.
  422. */
  423. function hook_post_features_disable_feature($component) {
  424. }
  425. /**
  426. * Feature module hook. Invoked on a Feature module before that module is
  427. * enabled.
  428. *
  429. * @param $component
  430. * String name of the component that is about to be enabled.
  431. */
  432. function hook_pre_features_enable_feature($component) {
  433. }
  434. /**
  435. * Feature module hook. Invoked on a Feature module after that module is
  436. * enabled.
  437. *
  438. * @param $component
  439. * String name of the component that has just been enabled.
  440. */
  441. function hook_post_features_enable_feature($component) {
  442. }
  443. /**
  444. * @}
  445. */