[Summary view] [Print] [Text view]

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