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


Generated: Mon Sep 28 01:01:32 2020 Cross-referenced by PHPXref 0.7.1