[ Index ]

PHP Cross Reference of BuddyPress

title

Body

[close]

/src/bp-core/ -> bp-core-template-loader.php (source)

   1  <?php
   2  /**
   3   * BuddyPress Template Functions.
   4   *
   5   * This file contains functions necessary to mirror the WordPress core template
   6   * loading process. Many of those functions are not filterable, and even then
   7   * would not be robust enough to predict where BuddyPress templates might exist.
   8   *
   9   * @package BuddyPress
  10   * @subpackage TemplateFunctions
  11   * @since 1.7.0
  12   */
  13  
  14  // Exit if accessed directly.
  15  defined( 'ABSPATH' ) || exit;
  16  
  17  /**
  18   * Get a BuddyPress template part for display in a theme.
  19   *
  20   * @since 1.7.0
  21   *
  22   * @param string      $slug Template part slug. Used to generate filenames,
  23   *                          eg 'friends' for 'friends.php'.
  24   * @param string|null $name Optional. Template part name. Used to generate
  25   *                          secondary filenames, eg 'personal' for 'activity-personal.php'.
  26   * @return false|string Path to located template. See {@link bp_locate_template()}.
  27   */
  28  function bp_get_template_part( $slug, $name = null ) {
  29  
  30      /**
  31       * Fires at the start of bp_get_template_part().
  32       *
  33       * This is a variable hook that is dependent on the slug passed in.
  34       *
  35       * @since 1.7.0
  36       *
  37       * @param string $slug Template part slug requested.
  38       * @param string $name Template part name requested.
  39       */
  40      do_action( 'get_template_part_' . $slug, $slug, $name );
  41  
  42      // Setup possible parts.
  43      $templates = array();
  44      if ( isset( $name ) ) {
  45          $templates[] = $slug . '-' . $name . '.php';
  46      }
  47      $templates[] = $slug . '.php';
  48  
  49      /**
  50       * Filters the template parts to be loaded.
  51       *
  52       * @since 1.7.0
  53       *
  54       * @param array  $templates Array of templates located.
  55       * @param string $slug      Template part slug requested.
  56       * @param string $name      Template part name requested.
  57       */
  58      $templates = apply_filters( 'bp_get_template_part', $templates, $slug, $name );
  59  
  60      // Return the part that is found.
  61      return bp_locate_template( $templates, true, false );
  62  }
  63  
  64  /**
  65   * Get an asset template part.
  66   *
  67   * Basically the same as {@link bp_get_template_part()}, but with 'assets/'
  68   * prepended to the slug.
  69   *
  70   * @since 2.6.0
  71   *
  72   * @see bp_get_template_part() for full documentation.
  73   *
  74   * @param string      $slug Template slug.
  75   * @param string|null $name Template name.
  76   * @return false|string
  77   */
  78  function bp_get_asset_template_part( $slug, $name = null ) {
  79      return bp_get_template_part( "assets/{$slug}", $name );
  80  }
  81  
  82  /**
  83   * Retrieve the name of the highest priority template file that exists.
  84   *
  85   * Searches in the STYLESHEETPATH before TEMPLATEPATH so that themes which
  86   * inherit from a parent theme can just overload one file. If the template is
  87   * not found in either of those, it looks in the theme-compat folder last.
  88   *
  89   * @since 1.7.0
  90   *
  91   * @param string|array $template_names Template file(s) to search for, in order.
  92   * @param bool         $load           Optional. If true, the template file will be loaded when
  93   *                                     found. If false, the path will be returned. Default: false.
  94   * @param bool         $require_once   Optional. Whether to require_once or require. Has
  95   *                                     no effect if $load is false. Default: true.
  96   * @return string The template filename if one is located.
  97   */
  98  function bp_locate_template( $template_names, $load = false, $require_once = true ) {
  99  
 100      // Bail when there are no templates to locate
 101      if ( empty( $template_names ) ) {
 102          return false;
 103      }
 104  
 105      // No file found yet.
 106      $located            = false;
 107      $template_locations = bp_get_template_stack();
 108  
 109      // Try to find a template file.
 110      foreach ( (array) $template_names as $template_name ) {
 111  
 112          // Continue if template is empty.
 113          if ( empty( $template_name ) ) {
 114              continue;
 115          }
 116  
 117          // Trim off any slashes from the template name.
 118          $template_name  = ltrim( $template_name, '/' );
 119  
 120          // Loop through template stack.
 121          foreach ( (array) $template_locations as $template_location ) {
 122  
 123              // Continue if $template_location is empty.
 124              if ( empty( $template_location ) ) {
 125                  continue;
 126              }
 127  
 128              // Check child theme first.
 129              if ( file_exists( trailingslashit( $template_location ) . $template_name ) ) {
 130                  $located = trailingslashit( $template_location ) . $template_name;
 131                  break 2;
 132              }
 133          }
 134      }
 135  
 136      /**
 137       * This action exists only to follow the standard BuddyPress coding convention,
 138       * and should not be used to short-circuit any part of the template locator.
 139       *
 140       * If you want to override a specific template part, please either filter
 141       * 'bp_get_template_part' or add a new location to the template stack.
 142       */
 143      do_action( 'bp_locate_template', $located, $template_name, $template_names, $template_locations, $load, $require_once );
 144  
 145      /**
 146       * Filter here to allow/disallow template loading.
 147       *
 148       * @since 2.5.0
 149       *
 150       * @param bool $value True to load the template, false otherwise.
 151       */
 152      $load_template = (bool) apply_filters( 'bp_locate_template_and_load', true );
 153  
 154      if ( $load_template && $load && ! empty( $located ) ) {
 155          load_template( $located, $require_once );
 156      }
 157  
 158      return $located;
 159  }
 160  
 161  /**
 162   * Get file data of the highest priority asset that exists.
 163   *
 164   * Similar to {@link bp_locate_template()}, but for files like CSS and JS.
 165   *
 166   * @since 2.6.0
 167   *
 168   * @param string $filename Relative filename to search for.
 169   * @return false|array Array of asset data if one is located (includes absolute filepath and URI).
 170   *                     Boolean false on failure.
 171   */
 172  function bp_locate_template_asset( $filename ) {
 173      // Ensure assets can be located when running from /src/.
 174      if ( defined( 'BP_SOURCE_SUBDIRECTORY' ) && 'src' === BP_SOURCE_SUBDIRECTORY ) {
 175          $filename = str_replace( '.min', '', $filename );
 176      }
 177  
 178      // Use bp_locate_template() to find our asset.
 179      $located = bp_locate_template( $filename, false );
 180      if ( false === $located ) {
 181          return false;
 182      }
 183  
 184      // Set up data array.
 185      $data = array();
 186      $data['file'] = $data['uri'] = $located;
 187  
 188      $find = array(
 189          get_theme_root(),
 190          bp_get_theme_compat_dir()
 191      );
 192  
 193      $replace = array(
 194          get_theme_root_uri(),
 195          bp_get_theme_compat_url()
 196      );
 197  
 198      // Make sure URI path is relative to site URL.
 199      $data['uri'] = str_replace( $find, $replace, $data['uri'] );
 200  
 201      return $data;
 202  }
 203  
 204  /**
 205   * Register a new template stack location.
 206   *
 207   * This allows for templates to live in places beyond just the parent/child
 208   * relationship, to allow for custom template locations. Used in conjunction
 209   * with bp_locate_template(), this allows for easy template overrides.
 210   *
 211   * @since 1.7.0
 212   *
 213   * @param string $location_callback Callback function that returns the stack location.
 214   * @param int    $priority          Optional. The priority parameter as passed to
 215   *                                  add_filter(). Default: 10.
 216   * @return bool See {@link add_filter()}.
 217   */
 218  function bp_register_template_stack( $location_callback = '', $priority = 10 ) {
 219  
 220      // Bail if no location, or function/method is not callable.
 221      if ( empty( $location_callback ) || ! is_callable( $location_callback ) ) {
 222          return false;
 223      }
 224  
 225      // Add location callback to template stack.
 226      return add_filter( 'bp_template_stack', $location_callback, (int) $priority );
 227  }
 228  
 229  /**
 230   * Deregister a previously registered template stack location.
 231   *
 232   * @since 1.7.0
 233   *
 234   * @see bp_register_template_stack()
 235   *
 236   * @param string $location_callback Callback function that returns the stack location.
 237   * @param int    $priority          Optional. The priority parameter passed to
 238   *                                  {@link bp_register_template_stack()}. Default: 10.
 239   * @return bool See {@link remove_filter()}.
 240   */
 241  function bp_deregister_template_stack( $location_callback = '', $priority = 10 ) {
 242  
 243      // Bail if no location, or function/method is not callable.
 244      if ( empty( $location_callback ) || ! is_callable( $location_callback ) ) {
 245          return false;
 246      }
 247  
 248      // Add location callback to template stack.
 249      return remove_filter( 'bp_template_stack', $location_callback, (int) $priority );
 250  }
 251  
 252  /**
 253   * Get the "template stack", a list of registered directories where templates can be found.
 254   *
 255   * Calls the functions added to the 'bp_template_stack' filter hook, and return
 256   * an array of the template locations.
 257   *
 258   * @since 1.7.0
 259   *
 260   * @see bp_register_template_stack()
 261   *
 262   * @global array $wp_filter         Stores all of the filters.
 263   * @global array $merged_filters    Merges the filter hooks using this function.
 264   * @global array $wp_current_filter Stores the list of current filters with
 265   *                                  the current one last.
 266   * @return array The filtered value after all hooked functions are applied to it.
 267   */
 268  function bp_get_template_stack() {
 269      global $wp_filter, $merged_filters, $wp_current_filter;
 270  
 271      // Setup some default variables.
 272      $tag  = 'bp_template_stack';
 273      $args = $stack = array();
 274  
 275      // Add 'bp_template_stack' to the current filter array.
 276      $wp_current_filter[] = $tag;
 277  
 278      // Sort.
 279      if ( class_exists( 'WP_Hook' ) ) {
 280          $filter = $wp_filter[ $tag ]->callbacks;
 281      } else {
 282          $filter = &$wp_filter[ $tag ];
 283  
 284          if ( ! isset( $merged_filters[ $tag ] ) ) {
 285              ksort( $filter );
 286              $merged_filters[ $tag ] = true;
 287          }
 288      }
 289  
 290      // Ensure we're always at the beginning of the filter array.
 291      reset( $filter );
 292  
 293      // Loop through 'bp_template_stack' filters, and call callback functions.
 294      do {
 295          foreach( (array) current( $filter ) as $the_ ) {
 296              if ( ! is_null( $the_['function'] ) ) {
 297                  $args[1] = $stack;
 298                  $stack[] = call_user_func_array( $the_['function'], array_slice( $args, 1, (int) $the_['accepted_args'] ) );
 299              }
 300          }
 301      } while ( next( $filter ) !== false );
 302  
 303      // Remove 'bp_template_stack' from the current filter array.
 304      array_pop( $wp_current_filter );
 305  
 306      // Remove empties and duplicates.
 307      $stack = array_unique( array_filter( $stack ) );
 308  
 309      /**
 310       * Filters the "template stack" list of registered directories where templates can be found.
 311       *
 312       * @since 1.7.0
 313       *
 314       * @param array $stack Array of registered directories for template locations.
 315       */
 316      return (array) apply_filters( 'bp_get_template_stack', $stack ) ;
 317  }
 318  
 319  /**
 320   * Put a template part into an output buffer, and return it.
 321   *
 322   * @since 1.7.0
 323   *
 324   * @see bp_get_template_part() for a description of $slug and $name params.
 325   *
 326   * @param string      $slug See {@link bp_get_template_part()}.
 327   * @param string|null $name See {@link bp_get_template_part()}.
 328   * @param bool        $echo If true, template content will be echoed. If false,
 329   *                          returned. Default: true.
 330   * @return string|null If $echo, returns the template content.
 331   */
 332  function bp_buffer_template_part( $slug, $name = null, $echo = true ) {
 333      ob_start();
 334  
 335      // Remove 'bp_replace_the_content' filter to prevent infinite loops.
 336      remove_filter( 'the_content', 'bp_replace_the_content' );
 337  
 338      bp_get_template_part( $slug, $name );
 339  
 340      // Remove 'bp_replace_the_content' filter to prevent infinite loops.
 341      add_filter( 'the_content', 'bp_replace_the_content' );
 342  
 343      // Get the output buffer contents.
 344      $output = ob_get_clean();
 345  
 346      // Echo or return the output buffer contents.
 347      if ( true === $echo ) {
 348          echo $output;
 349      } else {
 350          return $output;
 351      }
 352  }
 353  
 354  /**
 355   * Retrieve the path to a template.
 356   *
 357   * Used to quickly retrieve the path of a template without including the file
 358   * extension. It will also check the parent theme and theme-compat theme with
 359   * the use of {@link bp_locate_template()}. Allows for more generic template
 360   * locations without the use of the other get_*_template() functions.
 361   *
 362   * @since 1.7.0
 363   *
 364   * @param string $type      Filename without extension.
 365   * @param array  $templates An optional list of template candidates.
 366   * @return string Full path to file.
 367   */
 368  function bp_get_query_template( $type, $templates = array() ) {
 369      $type = preg_replace( '|[^a-z0-9-]+|', '', $type );
 370  
 371      if ( empty( $templates ) ) {
 372          $templates = array( "{$type}.php" );
 373      }
 374  
 375      /**
 376       * Filters possible file paths to check for for a template.
 377       *
 378       * This is a variable filter based on the type passed into
 379       * bp_get_query_template.
 380       *
 381       * @since 1.7.0
 382       *
 383       * @param array $templates Array of template files already prepared.
 384       */
 385      $templates = apply_filters( "bp_get_{$type}_template", $templates );
 386  
 387      // Filter possible templates, try to match one, and set any BuddyPress theme
 388      // compat properties so they can be cross-checked later.
 389      $templates = bp_set_theme_compat_templates( $templates );
 390      $template  = bp_locate_template( $templates );
 391      $template  = bp_set_theme_compat_template( $template );
 392  
 393      /**
 394       * Filters the path to a template file.
 395       *
 396       * This is a variable filter based on the type passed into
 397       * bp_get_query_template.
 398       *
 399       * @since 1.7.0
 400       *
 401       * @param string $template Path to the most appropriate found template file.
 402       */
 403      return apply_filters( "bp_{$type}_template", $template );
 404  }
 405  
 406  /**
 407   * Get the possible subdirectories to check for templates in.
 408   *
 409   * @since 1.7.0
 410   *
 411   * @param array $templates Templates we are looking for.
 412   * @return array Possible subfolders to look in.
 413   */
 414  function bp_get_template_locations( $templates = array() ) {
 415      $locations = array(
 416          'buddypress',
 417          'community',
 418          ''
 419      );
 420  
 421      /**
 422       * Filters the possible subdirectories to check for templates in.
 423       *
 424       * @since 1.7.0
 425       *
 426       * @param array $locations Array of subfolders to look in.
 427       * @param array $templates Array of templates we are looking for.
 428       */
 429      return apply_filters( 'bp_get_template_locations', $locations, $templates );
 430  }
 431  
 432  /**
 433   * Add template locations to template files being searched for.
 434   *
 435   * @since 1.7.0
 436   *
 437   * @param array $stacks Array of template locations.
 438   * @return array Array of all template locations registered so far.
 439   */
 440  function bp_add_template_stack_locations( $stacks = array() ) {
 441      $retval = array();
 442  
 443      // Get alternate locations.
 444      $locations = bp_get_template_locations();
 445  
 446      // Loop through locations and stacks and combine.
 447      foreach ( (array) $stacks as $stack ) {
 448          foreach ( (array) $locations as $custom_location ) {
 449              $retval[] = untrailingslashit( trailingslashit( $stack ) . $custom_location );
 450          }
 451      }
 452  
 453      /**
 454       * Filters the template locations to template files being searched for.
 455       *
 456       * @since 1.7.0
 457       *
 458       * @param array $value  Array of all template locations registered so far.
 459       * @param array $stacks Array of template locations.
 460       */
 461      return apply_filters( 'bp_add_template_stack_locations', array_unique( $retval ), $stacks );
 462  }
 463  
 464  /**
 465   * Add checks for BuddyPress conditions to 'parse_query' action.
 466   *
 467   * @since 1.7.0
 468   *
 469   * @param WP_Query $posts_query WP_Query object.
 470   */
 471  function bp_parse_query( $posts_query ) {
 472  
 473      // Bail if $posts_query is not the main loop.
 474      if ( ! $posts_query->is_main_query() ) {
 475          return;
 476      }
 477  
 478      // Bail if filters are suppressed on this query.
 479      if ( true == $posts_query->get( 'suppress_filters' ) ) {
 480          return;
 481      }
 482  
 483      // Bail if in admin.
 484      if ( is_admin() ) {
 485          return;
 486      }
 487  
 488      /**
 489       * Fires at the end of the bp_parse_query function.
 490       *
 491       * Allow BuddyPress components to parse the main query.
 492       *
 493       * @since 1.7.0
 494       *
 495       * @param WP_Query $posts_query WP_Query instance. Passed by reference.
 496       */
 497      do_action_ref_array( 'bp_parse_query', array( &$posts_query ) );
 498  }
 499  
 500  /**
 501   * Possibly intercept the template being loaded.
 502   *
 503   * Listens to the 'template_include' filter and waits for any BuddyPress specific
 504   * template condition to be met. If one is met and the template file exists,
 505   * it will be used; otherwise.
 506   *
 507   * Note that the _edit() checks are ahead of their counterparts, to prevent them
 508   * from being stomped on accident.
 509   *
 510   * @since 1.7.0
 511   *
 512   * @param string $template The path to the template file that is being used.
 513   * @return string The path to the template file that is being used.
 514   */
 515  function bp_template_include_theme_supports( $template = '' ) {
 516  
 517      /**
 518       * Filters whether or not to override the template being loaded in parent/child themes.
 519       *
 520       * @since 1.7.0
 521       *
 522       * @param bool   $value    Whether or not there is a file override. Default false.
 523       * @param string $template The path to the template file that is being used.
 524       */
 525      $new_template = apply_filters( 'bp_get_root_template', false, $template );
 526  
 527      // A BuddyPress template file was located, so override the WordPress
 528      // template and use it to switch off BuddyPress's theme compatibility.
 529      if ( ! empty( $new_template ) ) {
 530          $template = bp_set_template_included( $new_template );
 531      }
 532  
 533      /**
 534       * Filters the final template being loaded in parent/child themes.
 535       *
 536       * @since 1.7.0
 537       *
 538       * @param string $template The path to the template file that is being used.
 539       */
 540      return apply_filters( 'bp_template_include_theme_supports', $template );
 541  }
 542  
 543  /**
 544   * Set the included template.
 545   *
 546   * @since 1.8.0
 547   *
 548   * @param mixed $template Default: false.
 549   * @return mixed False if empty. Template name if template included.
 550   */
 551  function bp_set_template_included( $template = false ) {
 552      buddypress()->theme_compat->found_template = $template;
 553  
 554      return buddypress()->theme_compat->found_template;
 555  }
 556  
 557  /**
 558   * Is a BuddyPress template being included?
 559   *
 560   * @since 1.8.0
 561   *
 562   * @return bool True if yes, false if no.
 563   */
 564  function bp_is_template_included() {
 565      return isset( buddypress()->theme_compat->found_template ) && buddypress()->theme_compat->found_template;
 566  }
 567  
 568  /**
 569   * Attempt to load a custom BP functions file, similar to each themes functions.php file.
 570   *
 571   * @since 1.7.0
 572   *
 573   * @global string $pagenow
 574   */
 575  function bp_load_theme_functions() {
 576      global $pagenow, $wp_query;
 577  
 578      // Do not load our custom BP functions file if theme compat is disabled.
 579      if ( ! bp_use_theme_compat_with_current_theme() ) {
 580          return;
 581      }
 582  
 583      // Do not include on BuddyPress deactivation.
 584      if ( bp_is_deactivation() ) {
 585          return;
 586      }
 587  
 588      // If the $wp_query global is empty (the main query has not been run,
 589      // or has been reset), load_template() will fail at setting certain
 590      // global values. This does not happen on a normal page load, but can
 591      // cause problems when running automated tests.
 592      if ( ! is_a( $wp_query, 'WP_Query' ) ) {
 593          return;
 594      }
 595  
 596      // Only include if not installing or if activating via wp-activate.php.
 597      if ( ! defined( 'WP_INSTALLING' ) || 'wp-activate.php' === $pagenow ) {
 598          bp_locate_template( 'buddypress-functions.php', true );
 599      }
 600  }
 601  
 602  /**
 603   * Get the templates to use as the endpoint for BuddyPress template parts.
 604   *
 605   * @since 1.7.0
 606   * @since 2.4.0 Added singular.php to stack
 607   *
 608   * @return string Possible root level wrapper template files.
 609   */
 610  function bp_get_theme_compat_templates() {
 611      return bp_get_query_template( 'buddypress', array(
 612          'plugin-buddypress.php',
 613          'buddypress.php',
 614          'community.php',
 615          'generic.php',
 616          'page.php',
 617          'single.php',
 618          'singular.php',
 619          'index.php'
 620      ) );
 621  }


Generated: Sat Dec 14 01:01:40 2019 Cross-referenced by PHPXref 0.7.1