[Summary view] [Print] [Text view]

   1  <?php
   2  // $Id: plugins.inc,v 1.13.2.26 2010/07/25 18:59:12 merlinofchaos Exp $
   3  
   4  /**
   5   * @file
   6   *
   7   * Contains helper code for plugins and contexts.
   8   */
   9  
  10  /**
  11   * Determine if a pane is visible.
  12   *
  13   * @param $pane
  14   *   The pane object to test for access.
  15   * @param $display
  16   *   The display object containing the pane object to be tested.
  17   */
  18  function panels_pane_access($pane, $display) {
  19    ctools_include('context');
  20    return ctools_access($pane->access, $display->context);
  21  }
  22  
  23  /**
  24   * Get a list of panels available in the layout.
  25   */
  26  function panels_get_regions($layout, $display) {
  27    if (!empty($layout['panels function']) && function_exists($layout['panels function'])) {
  28      return $layout['panels function']($display, $display->layout_settings, $layout);
  29    }
  30    if (!empty($layout['panels'])) {
  31      return $layout['panels'];
  32    }
  33    return array();
  34  }
  35  
  36  /**
  37   * Get cached content for a given display and possibly pane.
  38   *
  39   * @return
  40   *   The cached content, or FALSE to indicate no cached content exists.
  41   */
  42  function panels_get_cached_content($display, $args, $context, $pane = NULL) {
  43    // Never use cache on a POST
  44    if (!empty($_POST)) {
  45      return FALSE;
  46    }
  47  
  48    $method = $pane ? $pane->cache['method'] : $display->cache['method'];
  49    $function = panels_plugin_get_function('cache', $method, 'cache get');
  50  
  51    if (!$function) {
  52      return FALSE;
  53    }
  54  
  55    $conf = $pane ? $pane->cache['settings'] : $display->cache['settings'];
  56    $cache = $function($conf, $display, $args, $context, $pane);
  57    if (empty($cache)) {
  58      return FALSE;
  59    }
  60  
  61    // restore it.
  62    $cache->restore();
  63    return $cache;
  64  }
  65  
  66  /**
  67   * Store cached content for a given display and possibly pane.
  68   */
  69  function panels_set_cached_content($cache, $display, $args, $context, $pane = NULL) {
  70    // Never use cache on a POST
  71    if (!empty($_POST)) {
  72      return FALSE;
  73    }
  74  
  75    $method = $pane ? $pane->cache['method'] : $display->cache['method'];
  76    $function = panels_plugin_get_function('cache', $method, 'cache set');
  77  
  78    if (!$function) {
  79      return FALSE;
  80    }
  81  
  82    $conf = $pane ? $pane->cache['settings'] : $display->cache['settings'];
  83  
  84    // snapshot it.
  85    $cache->cache();
  86    return $function($conf, $cache, $display, $args, $context, $pane);
  87  }
  88  
  89  /**
  90   * Clear all cached content for a display.
  91   */
  92  function panels_clear_cached_content($display) {
  93    // Figure out every method we might be using to cache content in this display:
  94    $methods = array();
  95    if (!empty($display->cache['method'])) {
  96      $methods[$display->cache['method']] = TRUE;
  97    }
  98  
  99    foreach ($display->content as $pane) {
 100      if (!empty($pane->cache['method'])) {
 101        $methods[$pane->cache['method']] = TRUE;
 102      }
 103    }
 104  
 105    foreach (array_keys($methods) as $method) {
 106      $function = panels_plugin_get_function('cache', $method, 'cache clear');
 107      if ($function) {
 108        $function($display);
 109      }
 110    }
 111  }
 112  
 113  /**
 114   * An object to hold caching information while it is happening.
 115   */
 116  class panels_cache_object {
 117    var $content = '';
 118    var $head = NULL;
 119    var $css = NULL;
 120    var $js = NULL;
 121    var $tokens = NULL;
 122    var $ready = FALSE;
 123  
 124    /**
 125     * When constructed, take a snapshot of our existing out of band data.
 126     */
 127    function panels_cache_object() {
 128      $this->head = drupal_set_html_head();
 129      $this->css = drupal_add_css();
 130      $this->tokens = ctools_set_page_token();
 131  
 132      foreach (array('header', 'footer') as $scope) {
 133        $this->js[$scope] = drupal_add_js(NULL, NULL, $scope);
 134      }
 135    }
 136  
 137    /**
 138     * Add content to the cache. This assumes a pure stream;
 139     * use set_content() if it's something else.
 140     */
 141    function add_content($content) {
 142      $this->content .= $content;
 143    }
 144  
 145    function set_content($content) {
 146      $this->content = $content;
 147    }
 148  
 149    /**
 150     * Set the object for storing. This overwrites.
 151     */
 152    function cache() {
 153      if ($this->ready) {
 154        return;
 155      }
 156  
 157      $this->ready = TRUE;
 158  
 159      // Simple replacement for head
 160      $this->head = str_replace($this->head, '', drupal_set_html_head());
 161  
 162      // Slightly less simple for CSS:
 163      $css = drupal_add_css();
 164      $start = $this->css;
 165      $this->css = array();
 166  
 167      foreach ($css as $media => $medias) {
 168        foreach ($medias as $type => $types) {
 169          foreach ($types as $path => $preprocess) {
 170            if (!isset($start[$media][$type][$path])) {
 171              $this->css[] = array($path, $type, $media, $preprocess);
 172            }
 173          }
 174        }
 175      }
 176  
 177      $js = array();
 178      // A little less simple for js
 179      foreach (array('header', 'footer') as $scope) {
 180        $js[$scope] = drupal_add_js(NULL, NULL, $scope);
 181      }
 182  
 183      $start = $this->js;
 184      $this->js = array();
 185  
 186      foreach ($js as $scope => $scopes) {
 187        foreach ($scopes as $type => $types) {
 188          foreach ($types as $id => $info) {
 189            if (!isset($start[$scope][$type][$id])) {
 190              switch ($type) {
 191                case 'setting':
 192                  $this->js[] = array($info, $type, $scope);
 193                  break;
 194  
 195                case 'inline':
 196                  $this->js[] = array($info['code'], $type, $scope, $info['defer']);
 197                  break;
 198  
 199                default:
 200                  $this->js[] = array($id, $type, $scope, $info['defer'], $info['cache']);
 201              }
 202            }
 203          }
 204        }
 205      }
 206  
 207      // And for tokens:
 208      $tokens = ctools_set_page_token();
 209      foreach ($this->tokens as $token => $argument) {
 210        if (isset($tokens[$token])) {
 211          unset($tokens);
 212        }
 213      }
 214  
 215      $this->tokens = $tokens;
 216    }
 217  
 218    /**
 219     * Restore out of band data saved to cache.
 220     */
 221    function restore() {
 222      if (!empty($this->head)) {
 223        drupal_set_html_head($this->head);
 224      }
 225      if (!empty($this->css)) {
 226        foreach ($this->css as $args) {
 227          call_user_func_array('drupal_add_css', $args);
 228        }
 229      }
 230      if (!empty($this->js)) {
 231        foreach ($this->js as $args) {
 232          call_user_func_array('drupal_add_js', $args);
 233        }
 234      }
 235  
 236      if (!empty($this->tokens)) {
 237        foreach ($this->tokens as $token => $key) {
 238          list($type, $argument) = $key;
 239          ctools_set_page_token($token, $type, $argument);
 240        }
 241      }
 242    }
 243  }
 244  
 245  /**
 246   * Get the title of a pane.
 247   *
 248   * @param $pane
 249   *   The $pane object.
 250   */
 251  function panels_get_pane_title(&$pane, $context = array(), $incoming_content = NULL) {
 252    ctools_include('content');
 253    return ctools_content_admin_title($pane->type, $pane->subtype, $pane->configuration, $context);
 254  }
 255  
 256  /**
 257   * Fetch metadata on a specific layout plugin.
 258   *
 259   * @param $layout
 260   *   Name of a panel layout. If the layout name contains a ':' this
 261   *   indicates that we need to separate the sublayout out and
 262   *   load it individually.
 263   *
 264   * @return
 265   *   An array with information about the requested panel layout.
 266   */
 267  function panels_get_layout($layout) {
 268    ctools_include('plugins');
 269    return ctools_get_plugins('panels', 'layouts', $layout);
 270  }
 271  
 272  /**
 273   * Fetch metadata for all layout plugins.
 274   *
 275   * @return
 276   *   An array of arrays with information about all available panel layouts.
 277   */
 278  function panels_get_layouts() {
 279    ctools_include('plugins');
 280    return ctools_get_plugins('panels', 'layouts');
 281  }
 282  
 283  /**
 284   * Fetch metadata for all layout plugins that provide builders.
 285   *
 286   * The layout builders allow reusable layouts be stored in the database and
 287   * exported. Since there are different methods, we are not limiting this
 288   * to just one plugin.
 289   *
 290   * @return
 291   *   An array of arrays with information about panel layouts with builders.
 292   */
 293  function panels_get_layout_builders() {
 294    ctools_include('plugins');
 295    $plugins = ctools_get_plugins('panels', 'layouts');
 296    $builders = array();
 297    foreach ($plugins as $name => $plugin) {
 298      if (!empty($plugin['builder'])) {
 299        $builders[$name] = $plugin;
 300      }
 301    }
 302  
 303    return $builders;
 304  }
 305  
 306  /**
 307   * Fetch metadata on a specific style plugin.
 308   *
 309   * @param $style
 310   *   Name of a panel style.
 311   *
 312   * @return
 313   *   An array with information about the requested panel style.
 314   */
 315  function panels_get_style($style) {
 316    ctools_include('plugins');
 317    return ctools_get_plugins('panels', 'styles', $style);
 318  }
 319  
 320  /**
 321   * Fetch metadata for all style plugins.
 322   *
 323   * @return
 324   *   An array of arrays with information about all available panel styles.
 325   */
 326  function panels_get_styles() {
 327    ctools_include('plugins');
 328    return ctools_get_plugins('panels', 'styles');
 329  }
 330  
 331  /**
 332   * Fetch metadata on a specific caching plugin.
 333   *
 334   * @param $cache
 335   *   Name of a panel cache.
 336   *
 337   * @return
 338   *   An array with information about the requested panel cache.
 339   */
 340  function panels_get_cache($cache) {
 341    ctools_include('plugins');
 342    return ctools_get_plugins('panels', 'cache', $cache);
 343  }
 344  
 345  /**
 346   * Fetch metadata for all context plugins.
 347   *
 348   * @return
 349   *   An array of arrays with information about all available panel caches.
 350   */
 351  function panels_get_caches() {
 352    ctools_include('plugins');
 353    return ctools_get_plugins('panels', 'cache');
 354  }
 355  
 356  /**
 357   * Fetch metadata on a specific display renderer plugin.
 358   *
 359   * @return
 360   *   An array of arrays with information about the requested panels display
 361   *   renderer.
 362   */
 363  function panels_get_display_renderer($renderer) {
 364    ctools_include('plugins');
 365    return ctools_get_plugins('panels', 'display_renderers', $renderer);
 366  }
 367  
 368  /**
 369   * Fetch metadata for all display renderer plugins.
 370   *
 371   * @return
 372   *   An array of arrays with information about all available panels display
 373   *   renderer.
 374   */
 375  function panels_get_display_renderers() {
 376    ctools_include('plugins');
 377    return ctools_get_plugins('panels', 'display_renderers');
 378  }
 379  
 380  /**
 381   * Get and initialize the class to handle rendering a display.
 382   *
 383   * @return
 384   *   Either the instantiated renderer or FALSE if one could not be found.
 385   */
 386  function panels_get_renderer_handler($plugin, &$display) {
 387    if (is_string($plugin)) {
 388      $plugin = panels_get_display_renderer($plugin);
 389    }
 390  
 391    $class = ctools_plugin_get_class($plugin, 'handler');
 392    if ($class) {
 393      $renderer = new $class();
 394      $renderer->init($plugin, $display);
 395      return $renderer;
 396    }
 397  
 398    return FALSE;
 399  }
 400  
 401  /**
 402   * Choose a renderer for a display based on a render pipeline setting.
 403   */
 404  function panels_get_renderer($pipeline_name, &$display) {
 405    // If operating in legacy mode, only the legacy renderer is available:
 406    if (variable_get('panels_legacy_rendering_mode', TRUE)) {
 407      return panels_get_renderer_handler('legacy', $display);
 408    }
 409  
 410    // Load the pipeline
 411    ctools_include('export');
 412    $pipeline = ctools_export_crud_load('panels_renderer_pipeline', $pipeline_name);
 413  
 414    // If we can't, or it has no renderers, default.
 415    if (!$pipeline || empty($pipeline->settings['renderers'])) {
 416      return panels_get_renderer_handler('standard', $display);
 417    }
 418  
 419    // Get contexts set on the pipeline:
 420    $contexts = array();
 421    if (!empty($pipeline->settings['contexts'])) {
 422      $contexts = ctools_context_load_contexts($pipeline->settings['context']);
 423    }
 424  
 425    // Cycle through our renderers and see.
 426    foreach ($pipeline->settings['renderers'] as $candidate) {
 427      // See if this passes selection criteria.
 428      if (!ctools_access($candidate['access'], $contexts)) {
 429        continue;
 430      }
 431  
 432      $renderer = panels_get_renderer_handler($candidate['renderer'], $display);
 433  
 434      if (!empty($candidate['options'])) {
 435        $renderer->set_options($candidate['options']);
 436      }
 437  
 438      return $renderer;
 439    }
 440  
 441    // Fall through. If no renderer is selected, use the standard renderer
 442    return panels_get_renderer_handler('standard', $display);
 443  }
 444  
 445  /**
 446   * Sort callback for sorting renderer pipelines.
 447   *
 448   * Sort first by weight, then by title.
 449   */
 450  function _panels_renderer_pipeline_sort($a, $b) {
 451    if ($a->weight == $b->weight) {
 452        if ($a->admin_title == $b->admin_title) {
 453          return 0;
 454        }
 455      return ($a->admin_title < $b->admin_title) ? -1 : 1;
 456    }
 457    return ($a->weight < $b->weight) ? -1 : 1;
 458  }
 459  
 460  /**
 461   * Get a list of available renderer pipelines.
 462   *
 463   * This can be used to form a select or radios widget by enabling
 464   * sorting. Descriptions are left in.
 465   */
 466  function panels_get_renderer_pipelines($sort = TRUE) {
 467    // If operating in legacy mode, only the legacy renderer is available:
 468    if (variable_get('panels_legacy_rendering_mode', TRUE)) {
 469      return array();
 470    }
 471  
 472    ctools_include('export');
 473    $pipelines = ctools_export_crud_load_all('panels_renderer_pipeline');
 474    if ($sort) {
 475      uasort($pipelines, '_panels_renderer_pipeline_sort');
 476    }
 477  
 478    return $pipelines;
 479  }
 480  
 481  /**
 482   * Get a function from a plugin, if it exists.
 483   *
 484   * @param $plugin
 485   *   The type of plugin
 486   * @param $which
 487   *   Either the loaded plugin object (or the same data in array form)
 488   *   or a string with the name of the desired the specific plugin.
 489   * @param $function_name
 490   *   The identifier of the function. For example, 'settings form'.
 491   *
 492   * @return
 493   *   The actual name of the function to call, or NULL if the function
 494   *   does not exist.
 495   */
 496  function panels_plugin_get_function($plugin, $which, $function_name) {
 497    ctools_include('plugins');
 498    if (is_object($which) || is_array($which)) {
 499      return ctools_plugin_get_function($which, $function_name);
 500    }
 501    else {
 502      return ctools_plugin_load_function('panels', $plugin, $which, $function_name);
 503    }
 504  
 505  }
 506  
 507  // @todo these are DEPRECATED and can probably be removed.
 508  // These are placeholders to prevent crashes from the former plugins
 509  class panels_required_context { function filter() { } };
 510  class panels_optional_context extends panels_required_context {};