PHPackages                             gamajo/template-loader - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Templating & Views](/categories/templating)
4. /
5. gamajo/template-loader

ActiveLibrary[Templating & Views](/categories/templating)

gamajo/template-loader
======================

A class for your WordPress plugin, to allow loading template parts with fallback through the child theme > parent theme > plugin

1.3.1(7y ago)29849.6k↓39.9%59[4 issues](https://github.com/GaryJones/Gamajo-Template-Loader/issues)[1 PRs](https://github.com/GaryJones/Gamajo-Template-Loader/pulls)5GPL-2.0-or-laterPHPPHP >=5.2.4

Since Mar 26Pushed 2y ago16 watchersCompare

[ Source](https://github.com/GaryJones/Gamajo-Template-Loader)[ Packagist](https://packagist.org/packages/gamajo/template-loader)[ Docs](https://github.com/GaryJones/Gamajo-Template-Loader)[ RSS](/packages/gamajo-template-loader/feed)WikiDiscussions develop Synced 2d ago

READMEChangelog (5)Dependencies (5)Versions (5)Used By (5)

Gamajo Template Loader
======================

[](#gamajo-template-loader)

[![Code Climate](https://camo.githubusercontent.com/4b0495dd32aa3ae77dbf313c424037cc56449541553a287da0b812a5169120db/68747470733a2f2f636f6465636c696d6174652e636f6d2f6769746875622f476172794a6f6e65732f47616d616a6f2d54656d706c6174652d4c6f616465722f6261646765732f6770612e737667)](https://codeclimate.com/github/GaryJones/Gamajo-Template-Loader)

A class to copy into your WordPress plugin, to allow loading template parts with fallback through the child theme > parent theme > plugin.

Description
-----------

[](#description)

Easy Digital Downloads, WooCommerce, and Events Calendar plugins, amongst others, allow you to add files to your theme to override the default templates that come with the plugin. As a developer, adding this convenience in to your own plugin can be a little tricky.

The `get_template_part()` function in WordPress was never really designed with plugins in mind, since it relies on `locate_template()` which only checks child and parent themes. So we can add in a final fallback that uses the templates in the plugin, we have to use a custom `locate_template()` function, and a custom `get_template_part()` function. The solution here just wraps them up as a class for convenience.

Installation
------------

[](#installation)

This isn't a WordPress plugin on its own, so the usual instructions don't apply. Instead:

### Manually install class

[](#manually-install-class)

1. Copy [`class-gamajo-template-loader.php`](class-gamajo-template-loader.php) into your plugin. It can be into a file in the plugin root, or better, an `includes` directory.

or:

### Install class via Composer

[](#install-class-via-composer)

1. Tell Composer to install this class as a dependency: `composer require gamajo/template-loader`
2. Recommended: Install the Mozart package: `composer require coenjacobs/mozart --dev` and [configure it](https://github.com/coenjacobs/mozart#configuration).
3. The class is now renamed to use your own prefix, to prevent collisions with other plugins bundling this class.

Implement class
---------------

[](#implement-class)

1. Create a new file, such as `class-your-plugin-template-loader.php`, in the same directory.
2. Create a class in that file that extends `Gamajo_Template_Loader` (or the new prefixed name, if you installed via Composer/Mozart). You can see the Meal Planner Template Loader example class below as a starting point if it helps.
3. Override the class properties to suit your plugin. You could also override the `get_templates_dir()` method if it isn't right for you.
4. You can now instantiate your custom template loader class, and use it to call the `get_template_part()` method. This could be within a shortcode callback, or something you want theme developers to include in their files.

```
// Template loader instantiated elsewhere, such as the main plugin file.
$meal_planner_template_loader = new Meal_Planner_Template_Loader();
```

- Use it to call the `get_template_part()` method. This could be within a shortcode callback, or something you want theme developers to include in their files.

    ```
    $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()`. `set_template_data()` returns the loader object to allow for method chaining.

    ```
    $data = array( 'foo' => 'bar', 'baz' => 'boom' );
    $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`.

    If you wish to use a different variable name, add a second parameter to `set_template_data()`:

    ```
    $data = array( 'foo' => 'bar', 'baz' => 'boom' );
    $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`.

    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`.
- You can also pass the template loader object into the template as well:

    ```
    $template_loader = new Your_Template_Loader();
    $template_loader->set_template_data(
        array(
      	      'template_loader' => $template_loader,
      		  // Optional other data as needed.
          )
    );
    ```

    Then in the template you can use:

    ```
    $data->template_loader->get_template_part( 'recipe' );
    ```

### Meal Planner Example Class

[](#meal-planner-example-class)

```