[Summary view] [Print] [Text view]

   1  <?php
   2  // $Id: export-ui.inc,v 1.1.2.9 2010/10/15 21:05:55 merlinofchaos Exp $
   3  
   4  /**
   5   * @file
   6   * Provide a tool for creating UIs for exportable objects.
   7   *
   8   * See Advanced Help for documentation.
   9   */
  10  /**
  11   * Implementation of hook_ctools_plugin_*.
  12   */
  13  function ctools_ctools_plugin_export_ui() {
  14    return array(
  15      'process' => 'ctools_export_ui_process',
  16    );
  17  }
  18  
  19  /**
  20   * Process an export-ui plugin to provide it with defaults.
  21   */
  22  function ctools_export_ui_process(&$plugin, $info) {
  23    ctools_include('export');
  24  
  25    $plugin += array(
  26      'has menu' => TRUE,
  27      'title' => $plugin['name'],
  28      'export' => array(),
  29      'allowed operations' => array(),
  30      'menu' => array(),
  31      'form' => array(),
  32      'strings' => array(),
  33      'list' => NULL,
  34      'access' => 'administer site configuration',
  35      'use advanced help' => FALSE,
  36      'advanced help' => array(),
  37    );
  38  
  39    // Provide CRUD access defaults based on the base 'access' setting:
  40    $plugin += array(
  41      'create access' => $plugin['access'],
  42      'delete access' => $plugin['access'],
  43    );
  44  
  45    if (empty($plugin['has menu'])) {
  46      return;
  47    }
  48  
  49    // The following keys are required and the plugin cannot be processed
  50    // without them.
  51    $keys = array(
  52      'title singular',
  53      'title plural',
  54      'title singular proper',
  55      'title plural proper',
  56      'schema',
  57    );
  58  
  59    foreach ($keys as $key) {
  60      if (empty($plugin[$key])) {
  61        drupal_set_message(t('The plugin definition of @plugin is missing the %key key.', array('%key' => $key, '@plugin' => $plugin['name'])), 'error');
  62      }
  63    }
  64  
  65    // If we're on the modules page and building a menu, there is a design flaw
  66    // in Drupal core that causes modules to be installed but the schema does
  67    // not become available until AFTER menu rebuild. This helps smooth that
  68    // out. This is a HACK but it should work:
  69    $schema = ctools_export_get_schema($plugin['schema']);
  70  
  71    if (!$schema && $_GET['q'] == 'admin/build/modules/list/confirm') {
  72      $schema = ctools_export_get_schema($plugin['schema'], TRUE);
  73    }
  74  
  75    if (empty($schema)) {
  76      // If we're updating the schema may not have been read yet, so don't report this error in that case.
  77      if (!defined('MAINTENANCE_MODE')) {
  78        drupal_set_message(t('The plugin definition of @plugin cannot locate schema %schema.', array('%schema' => $plugin['schema'], '@plugin' => $plugin['name'])), 'error');
  79      }
  80      return;
  81    }
  82  
  83    if (empty($schema['export'])) {
  84      drupal_set_message(t('The plugin definition of @plugin uses %schema, but it has no export section.', array('%schema' => $plugin['schema'], '@plugin' => $plugin['name'])), 'error');
  85      return;
  86    }
  87  
  88    $plugin['export'] += array(
  89      // Add the identifier key from the schema so we don't have to call
  90      // ctools_export_get_schema() just for that.
  91      'key' => $schema['export']['key'],
  92    );
  93  
  94    // Add some default fields that appear often in exports
  95    // If these use different keys they can easily be specified in the
  96    // $plugin.
  97  
  98    if (empty($plugin['export']['admin_title']) && !empty($schema['fields']['admin_title'])) {
  99      $plugin['export']['admin_title'] = 'admin_title';
 100    }
 101    if (empty($plugin['export']['admin_description']) && !empty($schema['fields']['admin_description'])) {
 102      $plugin['export']['admin_description'] = 'admin_description';
 103    }
 104  
 105    // Define allowed operations, and the name of the operations.
 106    $plugin['allowed operations'] += array(
 107      'edit'    => array('title' => t('Edit')),
 108      'enable'  => array('title' => t('Enable'), 'ajax' => TRUE, 'token' => TRUE),
 109      'disable' => array('title' => t('Disable'), 'ajax' => TRUE, 'token' => TRUE),
 110      'revert'  => array('title' => t('Revert')),
 111      'delete'  => array('title' => t('Delete')),
 112      'clone'   => array('title' => t('Clone')),
 113      'import'  => array('title' => t('Import')),
 114      'export'  => array('title' => t('Export')),
 115    );
 116  
 117    $plugin['menu'] += array(
 118      'menu item' => str_replace(' ', '-', $plugin['name']),
 119      'menu prefix' => 'admin/build',
 120      'menu title' => $plugin['title'],
 121      'menu description' => '',
 122    );
 123    $base_path = ctools_export_ui_plugin_base_path($plugin);
 124    $prefix_count = count(explode('/', $plugin['menu']['menu prefix']));
 125  
 126    $plugin['menu'] += array(
 127      // Default menu items that should be declared.
 128      'items' => array(),
 129    );
 130  
 131    $plugin['menu']['items'] += array(
 132      'list callback' => array(
 133        'path' => '',
 134        // Menu items are translated by the menu system.
 135        // TODO: We need more flexibility in title. The title of the admin page
 136        // is not necessarily the title of the object, plus we need
 137        // plural, singular, proper, not proper, etc.
 138        'title' => $plugin['menu']['menu title'],
 139        'description' => $plugin['menu']['menu description'],
 140        'page callback' => 'ctools_export_ui_switcher_page',
 141        'page arguments' => array($plugin['name'], 'list'),
 142        'access callback' => 'ctools_export_ui_task_access',
 143        'access arguments' => array($plugin['name'], 'list'),
 144        'type' => MENU_NORMAL_ITEM,
 145      ),
 146      'list' => array(
 147        'path' => 'list',
 148        'title' => 'List',
 149        'page callback' => 'ctools_export_ui_switcher_page',
 150        'page arguments' => array($plugin['name'], 'list'),
 151        'access callback' => 'ctools_export_ui_task_access',
 152        'access arguments' => array($plugin['name'], 'list'),
 153        'type' => MENU_DEFAULT_LOCAL_TASK,
 154        'weight' => -10,
 155      ),
 156      'add' => array(
 157        'path' => 'add',
 158        'title' => 'Add',
 159        'page callback' => 'ctools_export_ui_switcher_page',
 160        'page arguments' => array($plugin['name'], 'add'),
 161        'access callback' => 'ctools_export_ui_task_access',
 162        'access arguments' => array($plugin['name'], 'add'),
 163        'type' => MENU_LOCAL_TASK,
 164      ),
 165      'edit callback' => array(
 166        'path' => 'list/%ctools_export_ui',
 167        'page callback' => 'ctools_export_ui_switcher_page',
 168        'page arguments' => array($plugin['name'], 'edit', $prefix_count + 2),
 169        'load arguments' => array($plugin['name']),
 170        'access callback' => 'ctools_export_ui_task_access',
 171        'access arguments' => array($plugin['name'], 'edit', $prefix_count + 2),
 172        'type' => MENU_CALLBACK,
 173      ),
 174      'edit' => array(
 175        'path' => 'list/%ctools_export_ui/edit',
 176        'title' => 'Edit',
 177        'page callback' => 'ctools_export_ui_switcher_page',
 178        'page arguments' => array($plugin['name'], 'edit', $prefix_count + 2),
 179        'load arguments' => array($plugin['name']),
 180        'access callback' => 'ctools_export_ui_task_access',
 181        'access arguments' => array($plugin['name'], 'edit', $prefix_count + 2),
 182        'type' => MENU_DEFAULT_LOCAL_TASK,
 183      ),
 184    );
 185  
 186    if ($plugin['allowed operations']['import']) {
 187      $plugin['menu']['items'] += array(
 188        'import' => array(
 189          'path' => 'import',
 190          'title' => 'Import',
 191          'page callback' => 'ctools_export_ui_switcher_page',
 192          'page arguments' => array($plugin['name'], 'import'),
 193          'access callback' => 'ctools_export_ui_task_access',
 194          'access arguments' => array($plugin['name'], 'import'),
 195          'type' => MENU_LOCAL_TASK,
 196        ),
 197      );
 198    }
 199  
 200    if ($plugin['allowed operations']['export']) {
 201      $plugin['menu']['items'] += array(
 202        'export' => array(
 203          'path' => 'list/%ctools_export_ui/export',
 204          'title' => 'Export',
 205          'page callback' => 'ctools_export_ui_switcher_page',
 206          'page arguments' => array($plugin['name'], 'export', $prefix_count + 2),
 207          'load arguments' => array($plugin['name']),
 208          'access callback' => 'ctools_export_ui_task_access',
 209          'access arguments' => array($plugin['name'], 'export', $prefix_count + 2),
 210          'type' => MENU_LOCAL_TASK,
 211        ),
 212      );
 213    }
 214  
 215    if ($plugin['allowed operations']['revert']) {
 216      $plugin['menu']['items'] += array(
 217        'revert' => array(
 218          'path' => 'list/%ctools_export_ui/revert',
 219          'title' => 'Revert',
 220          'page callback' => 'ctools_export_ui_switcher_page',
 221          // Note: Yes, 'delete' op is correct.
 222          'page arguments' => array($plugin['name'], 'delete', $prefix_count + 2),
 223          'load arguments' => array($plugin['name']),
 224          'access callback' => 'ctools_export_ui_task_access',
 225          'access arguments' => array($plugin['name'], 'revert', $prefix_count + 2),
 226          'type' => MENU_CALLBACK,
 227        ),
 228      );
 229    }
 230  
 231    if ($plugin['allowed operations']['delete']) {
 232      $plugin['menu']['items'] += array(
 233        'delete' => array(
 234          'path' => 'list/%ctools_export_ui/delete',
 235          'title' => 'Delete',
 236          'page callback' => 'ctools_export_ui_switcher_page',
 237          'page arguments' => array($plugin['name'], 'delete', $prefix_count + 2),
 238          'load arguments' => array($plugin['name']),
 239          'access callback' => 'ctools_export_ui_task_access',
 240          'access arguments' => array($plugin['name'], 'delete', $prefix_count + 2),
 241          'type' => MENU_CALLBACK,
 242        ),
 243      );
 244    }
 245  
 246    if ($plugin['allowed operations']['clone']) {
 247      $plugin['menu']['items'] += array(
 248        'clone' => array(
 249          'path' => 'list/%ctools_export_ui/clone',
 250          'title' => 'Clone',
 251          'page callback' => 'ctools_export_ui_switcher_page',
 252          'page arguments' => array($plugin['name'], 'clone', $prefix_count + 2),
 253          'load arguments' => array($plugin['name']),
 254          'access callback' => 'ctools_export_ui_task_access',
 255          'access arguments' => array($plugin['name'], 'clone', $prefix_count + 2),
 256          'type' => MENU_CALLBACK,
 257        ),
 258      );
 259    }
 260  
 261    if ($plugin['allowed operations']['enable']) {
 262      $plugin['menu']['items'] += array(
 263        'enable' => array(
 264          'path' => 'list/%ctools_export_ui/enable',
 265          'title' => 'Enable',
 266          'page callback' => 'ctools_export_ui_switcher_page',
 267          'page arguments' => array($plugin['name'], 'enable', $prefix_count + 2),
 268          'load arguments' => array($plugin['name']),
 269          'access callback' => 'ctools_export_ui_task_access',
 270          'access arguments' => array($plugin['name'], 'enable', $prefix_count + 2),
 271          'type' => MENU_CALLBACK,
 272        ),
 273      );
 274    }
 275  
 276    if ($plugin['allowed operations']['disable']) {
 277      $plugin['menu']['items'] += array(
 278        'disable' => array(
 279          'path' => 'list/%ctools_export_ui/disable',
 280          'title' => 'Disable',
 281          'page callback' => 'ctools_export_ui_switcher_page',
 282          'page arguments' => array($plugin['name'], 'disable', $prefix_count + 2),
 283          'load arguments' => array($plugin['name']),
 284          'access callback' => 'ctools_export_ui_task_access',
 285          'access arguments' => array($plugin['name'], 'disable', $prefix_count + 2),
 286          'type' => MENU_CALLBACK,
 287        ),
 288      );
 289    }
 290  
 291    // Define some redirects that should happen after edit/add/clone operations.
 292    $plugin['redirect'] = array(
 293      'add' => $base_path,
 294      'clone' => $base_path,
 295      'edit' => $base_path,
 296      'import' => $base_path,
 297    );
 298  
 299    // Define form elements.
 300    $plugin['form'] += array(
 301      'settings' => function_exists($plugin['name'] . '_form') ? $plugin['name'] . '_form' : '',
 302      'validate' => function_exists($plugin['name'] . '_form_validate') ? $plugin['name'] . '_form_validate' : '',
 303      'submit' => function_exists($plugin['name'] . '_form_submit') ? $plugin['name'] . '_form_submit' : '',
 304    );
 305  
 306    // Define strings.
 307  
 308    // For all strings, %title may be filled in at a later time via str_replace
 309    // since we do not know the title now.
 310    $plugin['strings'] += array(
 311      'title' => array(),
 312      'confirmation' => array(),
 313      'help' => array(),
 314      'message' => array(),
 315      'advanced help' => array(),
 316    );
 317  
 318    // Strings used in drupal_set_title().
 319    $plugin['strings']['title'] += array(
 320      'add' => t('Add a new @plugin', array('@plugin' => $plugin['title singular'])),
 321      // The "%title" will be replaced in ctools_export_ui_form(), as in this
 322      // stage we dont have the specific exportable object.
 323      'edit' => t('Edit @plugin %title', array('@plugin' => $plugin['title singular'])),
 324      'clone' => t('Clone @plugin %title', array('@plugin' => $plugin['title singular'])),
 325  
 326      'import' => t('Import @plugin', array('@plugin' => $plugin['title singular'])),
 327      'export' => t('Export @plugin %title', array('@plugin' => $plugin['title singular'])),
 328    );
 329  
 330    // Strings used in confirmation pages.
 331    $plugin['strings']['confirmation'] += array(
 332      'revert' => array(),
 333      'delete' => array(),
 334      'add' => array(),
 335      'edit' => array(),
 336    );
 337  
 338    $plugin['strings']['confirmation']['revert'] += array(
 339      'question' => t('Are you sure you want to revert %title?'),
 340      'information' => t('This action will permanently remove any customizations made to this item.'),
 341      'success' => t('The item has been reverted.'),
 342    );
 343  
 344    $plugin['strings']['confirmation']['delete'] += array(
 345      'question' => t('Are you sure you want to delete %title?'),
 346      'information' => t('This action will permanently remove this item from your database..'),
 347      'success' => t('The item has been deleted.'),
 348    );
 349  
 350    $plugin['strings']['confirmation']['add'] += array(
 351      'success' => t('%title has been created.'),
 352      'fail' => t('%title could not be created.'),
 353    );
 354  
 355    $plugin['strings']['confirmation']['edit'] += array(
 356      'success' => t('%title has been updated.'),
 357      'fail' => t('%title could not be updated.'),
 358    );
 359  
 360    // Strings used in $forms.
 361    $plugin['strings']['help'] += array(
 362      'import' => t('You can import an exported definition by pasting the exported object code into the field below.'),
 363    );
 364  
 365    // Strings used in drupal_set_message().
 366    $plugin['strings']['message'] += array(
 367      'enable' => t('@plugin %title was enabled.', array('@plugin' => $plugin['title singular proper'])),
 368      'disable' => t('@plugin %title was disabled.', array('@plugin' => $plugin['title singular proper'])),
 369    );
 370  
 371    // Strings used if advanced help module is enabled.
 372  
 373  
 374    if (!empty($plugin['use advanced help'])) {
 375      if (module_exists('advanced_help')) {
 376        $plugin['advanced help'] += array(
 377          'enabled' => TRUE,
 378          'topic' => $plugin['module'],
 379          'module' => $plugin['module'],
 380        );
 381       }
 382       else {
 383          $plugin['advanced help'] += array(
 384            'enabled' => FALSE,
 385          );
 386       }
 387  
 388       // Get the module name.
 389       $info = drupal_parse_info_file(drupal_get_path('module', $plugin['module']) .'/'. $plugin['module'] .'.info');
 390       $plugin['strings']['advanced help'] += array(
 391         // The strings to show when the advanced help module is enabled or disabled.
 392         'enabled' => t('Learn more about the @module module.', array('@module' => $info['name'])),
 393         'disabled' => t('Learn more about the @module module by enabling the <a href="@path">Advanced help</a> module.', array('@module' => $info['name'], '@path' => 'http://drupal.org/project/advanced_help')),
 394       );
 395    }
 396  
 397  
 398  
 399  }
 400  
 401  /**
 402   * Get the class to handle creating a list of exportable items.
 403   *
 404   * If a plugin does not define a lister class at all, then the default
 405   * lister class will be used.
 406   *
 407   * @return
 408   *   Either the lister class or FALSE if one could not be had.
 409   */
 410  function ctools_export_ui_get_handler($plugin) {
 411    $cache = &ctools_static(__FUNCTION__, array());
 412    if (empty($cache[$plugin['name']])) {
 413      // If a list class is not specified by the plugin, fall back to the
 414      // default ctools_export_ui plugin instead.
 415      if (empty($plugin['handler'])) {
 416        $default = ctools_get_export_ui('ctools_export_ui');
 417        $class = ctools_plugin_get_class($default, 'handler');
 418      }
 419      else {
 420        $class = ctools_plugin_get_class($plugin, 'handler');
 421      }
 422  
 423      if ($class) {
 424        $cache[$plugin['name']] = new $class();
 425        $cache[$plugin['name']]->init($plugin);
 426      }
 427    }
 428    return !empty($cache[$plugin['name']]) ? $cache[$plugin['name']] : FALSE;
 429  }
 430  
 431  /**
 432   * Get the base path from a plugin.
 433   *
 434   * @param $plugin
 435   *   The plugin.
 436   *
 437   * @return
 438   *   The menu path to the plugin's list.
 439   */
 440  function ctools_export_ui_plugin_base_path($plugin) {
 441    return $plugin['menu']['menu prefix'] . '/' . $plugin['menu']['menu item'];
 442  }
 443  
 444  /**
 445   * Get the path to a specific menu item from a plugin.
 446   *
 447   * @param $plugin
 448   *   The plugin name.
 449   * @param $item_id
 450   *   The id in the menu items from the plugin.
 451   * @param $export_key
 452   *   The export key of the item being edited, if it exists.
 453   * @return
 454   *   The menu path to the plugin's list.
 455   */
 456  function ctools_export_ui_plugin_menu_path($plugin, $item_id, $export_key = NULL) {
 457    $path = $plugin['menu']['items'][$item_id]['path'];
 458    if ($export_key) {
 459      $path = str_replace('%ctools_export_ui', $export_key, $path);
 460    }
 461    return ctools_export_ui_plugin_base_path($plugin) . '/' . $path;
 462  }
 463  
 464  /**
 465   * Helper function to include CTools plugins and get an export-ui exportable.
 466   *
 467   * @param $plugin_name
 468   *   The plugin that should be laoded.
 469   */
 470  function ctools_get_export_ui($plugin_name) {
 471    ctools_include('plugins');
 472    return ctools_get_plugins('ctools', 'export_ui', $plugin_name);
 473  
 474  }
 475  
 476  /**
 477   * Helper function to include CTools plugins and get all export-ui exportables.
 478   */
 479  function ctools_get_export_uis() {
 480    ctools_include('plugins');
 481    return ctools_get_plugins('ctools', 'export_ui');
 482  }
 483  
 484  /**
 485   * Main page callback to manipulate exportables.
 486   *
 487   * This simply loads the object defined in the plugin and hands it off to
 488   * a method based upon the name of the operation in use. This can easily
 489   * be used to add more ops.
 490   */
 491  function ctools_export_ui_switcher_page($plugin_name, $op) {
 492    $args = func_get_args();
 493    $js = !empty($_REQUEST['ctools_ajax']);
 494  
 495    // Load the $plugin information
 496    $plugin = ctools_get_export_ui($plugin_name);
 497    $handler = ctools_export_ui_get_handler($plugin);
 498  
 499    if ($handler) {
 500      $method = $op . '_page';
 501      if (method_exists($handler, $method)) {
 502        // replace the first two arguments:
 503        $args[0] = $js;
 504        $args[1] = $_POST;
 505        return call_user_func_array(array($handler, $method), $args);
 506      }
 507    }
 508    else {
 509      return t('Configuration error. No handler found.');
 510    }
 511  }