Merge branch 'develop'

* develop:
  1.3.0
  Make requested change
  Update change log
  Remove `array` casting from `set_template_data`
  Update readme to reflect method chaining in #30
  Update set/unset methods to return `$this` (for method-chaining)
  redoing: namespace get_template_part action hook
  Added a template cache to store previously located template paths. Added a custom data variable name cache so unset_template_data() can remove all custom references.

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [1.3.0] - 2017-03-24
+
+- Add prefixed get_template_part filter.
+- Add a template cache to store previously located template paths.
+- Add a custom data variable name cache, so `unset_template_data()` can remove all custom references.
+- Update `set_template_data()` and `unset_template_data()` to become fluent methods.
+- Remove array type hint from `set_template_data()` argument.
+- Update documentation.
+
 ## [1.2.0] - 2016-03-26
 
 - Support adding custom template data.
@@ -25,6 +36,7 @@
 
 - Initial release.
 
-[Unreleased]: https://github.com/GaryJones/Gamajo-Template-Loader/compare/1.2.0...HEAD
+[Unreleased]: https://github.com/GaryJones/Gamajo-Template-Loader/compare/1.3.0...HEAD
+[1.3.0]: https://github.com/GaryJones/Gamajo-Template-Loader/compare/1.2.0...1.3.0
 [1.2.0]: https://github.com/GaryJones/Gamajo-Template-Loader/compare/1.1.0...1.2.0
 [1.1.0]: https://github.com/GaryJones/Gamajo-Template-Loader/compare/1.0.0...1.1.0

README.md

@@ -29,25 +29,27 @@ This isn't a WordPress plugin on its own, so the usual instructions don't apply.
   ~~~php
   $meal_planner_template_loader->get_template_part( 'recipe' );
   ~~~
-* If you want to pass data to the template, call the `set_template_data()` method with an array before calling `get_template_part()`.
+* If you want to pass data to the template, call the `set_template_data()` method with an array before calling `get_template_part()`. `set_template_data()` returns the loader object to allow for method chaining.
 
   ~~~php
   $data = array( 'foo' => 'bar', 'baz' => 'boom' );
-  $meal_planner_template_loader->set_template_data( $data );
-  $meal_planner_template_loader->get_template_part( 'recipe' );
+  $meal_planner_template_loader
+      ->set_template_data( $data );
+      ->get_template_part( 'recipe' );
   ~~~
 
-  The value of `bar` is now available inside the recipe template as `$data['foo']`.
+  The value of `bar` is now available inside the recipe template as `$data->foo`.
 
   If you wish to use a different variable name, add a second parameter to `set_template_data()`:
 
   ~~~php
   $data = array( 'foo' => 'bar', 'baz' => 'boom' );
-  $meal_planner_template_loader->set_template_data( $data, 'context' );
-  $meal_planner_template_loader->get_template_part( 'recipe', 'ingredients' );
+  $meal_planner_template_loader
+      ->set_template_data( $data, 'context' )
+      ->get_template_part( 'recipe', 'ingredients' );
   ~~~
 
-  The value of `bar` is now available inside the recipe template as `$context['foo']`.
+  The value of `bar` is now available inside the recipe template as `$context->foo`.
 
   This will try to load up `wp-content/themes/my-theme/meal-planner/recipe-ingredients.php`, or `wp-content/themes/my-theme/meal-planner/recipe.php`, then fallback to `wp-content/plugins/meal-planner/templates/recipe-ingredients.php` or `wp-content/plugins/meal-planner/templates/recipe.php`.
 

class-gamajo-template-loader.php

@@ -7,7 +7,7 @@
  * @link      http://github.com/GaryJones/Gamajo-Template-Loader
  * @copyright 2013 Gary Jones
  * @license   GPL-2.0+
- * @version   1.2.0
+ * @version   1.3.0
  */
 
 if ( ! class_exists( 'Gamajo_Template_Loader' ) ) {
@@ -69,6 +69,24 @@ class Gamajo_Template_Loader {
 		 */
 		protected $plugin_template_directory = 'templates';
 
+		/**
+		 * Internal use only: Store located template paths.
+		 *
+		 * @var array
+		 */
+		private $template_path_cache = array();
+
+		/**
+		 * Internal use only: Store variable names used for template data.
+		 *
+		 * Means unset_template_data() can remove all custom references from $wp_query.
+		 *
+		 * Initialized to contain the default 'data'.
+		 *
+		 * @var array
+		 */
+		private $template_data_var_names = array('data');
+
 		/**
 		 * Clean up template data.
 		 *
@@ -92,6 +110,7 @@ public function __destruct() {
 		public function get_template_part( $slug, $name = null, $load = true ) {
 			// Execute code for this part.
 			do_action( 'get_template_part_' . $slug, $slug, $name );
+			do_action( $this->filter_prefix . '_get_template_part_' . $slug, $slug, $name );
 
 			// Get files names of templates, for given slug and name.
 			$templates = $this->get_template_file_names( $slug, $name );
@@ -110,14 +129,23 @@ public function get_template_part( $slug, $name = null, $load = true ) {
 		 *
 		 * @since 1.2.0
 		 *
-		 * @param array  $data     Custom data for the template.
+		 * @param mixed  $data     Custom data for the template.
 		 * @param string $var_name Optional. Variable under which the custom data is available in the template.
 		 *                         Default is 'data'.
+		 *
+		 * @return Gamajo_Template_Loader
 		 */
-		public function set_template_data( array $data, $var_name = 'data' ) {
+		public function set_template_data( $data, $var_name = 'data' ) {
 			global $wp_query;
 
 			$wp_query->query_vars[ $var_name ] = (object) $data;
+
+			// Add $var_name to custom variable store if not default value
+			if( $var_name !== 'data' ) {
+				$this->template_data_var_names[] = $var_name;
+			}
+
+			return $this;
 		}
 
 		/**
@@ -126,13 +154,23 @@ public function set_template_data( array $data, $var_name = 'data' ) {
 		 * Good to use once the final template part has been requested.
 		 *
 		 * @since 1.2.0
+		 *
+		 * @return Gamajo_Template_Loader
 		 */
 		public function unset_template_data() {
 			global $wp_query;
 
-			if ( isset( $wp_query->query_vars['data'] ) ) {
-				unset( $wp_query->query_vars['data'] );
+			// Remove any duplicates from the custom variable store
+			$custom_var_names = array_unique( $this->template_data_var_names );
+
+			// Remove each custom data reference from $wp_query
+			foreach ( $custom_var_names as $var ) {
+				if ( isset( $wp_query->query_vars[$var] ) ) {
+					unset( $wp_query->query_vars[$var] );
+				}
 			}
+
+			return $this;
 		}
 
 		/**
@@ -184,23 +222,35 @@ protected function get_template_file_names( $slug, $name ) {
 		 * @return string The template filename if one is located.
 		 */
 		public function locate_template( $template_names, $load = false, $require_once = true ) {
-			// No file found yet.
-			$located = false;
-
-			// Remove empty entries.
-			$template_names = array_filter( (array) $template_names );
-			$template_paths = $this->get_template_paths();
-
-			// Try to find a template file.
-			foreach ( $template_names as $template_name ) {
-				// Trim off any slashes from the template name.
-				$template_name = ltrim( $template_name, '/' );
-
-				// Try locating this template file by looping through the template paths.
-				foreach ( $template_paths as $template_path ) {
-					if ( file_exists( $template_path . $template_name ) ) {
-						$located = $template_path . $template_name;
-						break 2;
+
+			// Use $template_names as a cache key - either first element of array or the variable itself if it's a string
+			$cache_key = is_array( $template_names ) ? $template_names[0] : $template_names;
+
+			// If the key is in the cache array, we've already located this file.
+			if ( isset( $this->template_path_cache[$cache_key] ) ) {
+				$located = $this->template_path_cache[$cache_key];
+			} else {
+
+				// No file found yet.
+				$located = false;
+
+				// Remove empty entries.
+				$template_names = array_filter( (array) $template_names );
+				$template_paths = $this->get_template_paths();
+
+				// Try to find a template file.
+				foreach ( $template_names as $template_name ) {
+					// Trim off any slashes from the template name.
+					$template_name = ltrim( $template_name, '/' );
+
+					// Try locating this template file by looping through the template paths.
+					foreach ( $template_paths as $template_path ) {
+						if ( file_exists( $template_path . $template_name ) ) {
+							$located = $template_path . $template_name;
+							// Store the template path in the cache
+							$this->template_path_cache[$cache_key] = $located;
+							break 2;
+						}
 					}
 				}
 			}