{"id":15628423,"url":"https://github.com/garyjones/gamajo-template-loader","last_synced_at":"2025-04-09T04:04:30.124Z","repository":{"id":12399581,"uuid":"15052647","full_name":"GaryJones/Gamajo-Template-Loader","owner":"GaryJones","description":"A class to copy into your WordPress plugin, to allow loading template parts with fallback through the child theme \u003e parent theme \u003e plugin.","archived":false,"fork":false,"pushed_at":"2024-04-12T23:53:40.000Z","size":73,"stargazers_count":296,"open_issues_count":6,"forks_count":62,"subscribers_count":16,"default_branch":"develop","last_synced_at":"2025-04-02T02:13:59.162Z","etag":null,"topics":["template","wordpress","wordpress-plugin"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GaryJones.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-12-09T16:31:46.000Z","updated_at":"2025-02-13T12:45:27.000Z","dependencies_parsed_at":"2024-06-18T14:01:53.816Z","dependency_job_id":"a081e5cf-73bc-4cb7-840a-ce63ecd2a491","html_url":"https://github.com/GaryJones/Gamajo-Template-Loader","commit_stats":{"total_commits":57,"total_committers":20,"mean_commits":2.85,"dds":0.6842105263157895,"last_synced_commit":"417361be27c60ab153c0e23ae5494c4e24fbb42f"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaryJones%2FGamajo-Template-Loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaryJones%2FGamajo-Template-Loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaryJones%2FGamajo-Template-Loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GaryJones%2FGamajo-Template-Loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GaryJones","download_url":"https://codeload.github.com/GaryJones/Gamajo-Template-Loader/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247974715,"owners_count":21026742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["template","wordpress","wordpress-plugin"],"created_at":"2024-10-03T10:22:32.490Z","updated_at":"2025-04-09T04:04:30.082Z","avatar_url":"https://github.com/GaryJones.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gamajo Template Loader\n\n[![Code Climate](https://codeclimate.com/github/GaryJones/Gamajo-Template-Loader/badges/gpa.svg)](https://codeclimate.com/github/GaryJones/Gamajo-Template-Loader)\n\nA class to copy into your WordPress plugin, to allow loading template parts with fallback through the child theme \u003e parent theme \u003e plugin.\n\n## Description\n\nEasy 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.\n\nThe `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.\n\n## Installation\n\nThis isn't a WordPress plugin on its own, so the usual instructions don't apply. Instead:\n\n### Manually install class\n1. 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.\n\nor:\n\n### Install class via Composer\n1. Tell Composer to install this class as a dependency: `composer require gamajo/template-loader`\n2. Recommended: Install the Mozart package: `composer require coenjacobs/mozart --dev` and [configure it](https://github.com/coenjacobs/mozart#configuration).\n3. The class is now renamed to use your own prefix, to prevent collisions with other plugins bundling this class.\n\n## Implement class\n1. Create a new file, such as `class-your-plugin-template-loader.php`, in the same directory.\n2. 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.\n3. Override the class properties to suit your plugin. You could also override the `get_templates_dir()` method if it isn't right for you.\n4. 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.\n\n  ~~~php\n  // Template loader instantiated elsewhere, such as the main plugin file.\n  $meal_planner_template_loader = new Meal_Planner_Template_Loader();\n  ~~~\n* 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.\n\n  ~~~php\n  $meal_planner_template_loader-\u003eget_template_part( 'recipe' );\n  ~~~\n* 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.\n\n  ~~~php\n  $data = array( 'foo' =\u003e 'bar', 'baz' =\u003e 'boom' );\n  $meal_planner_template_loader\n      -\u003eset_template_data( $data )\n      -\u003eget_template_part( 'recipe' );\n  ~~~\n  \n  The value of `bar` is now available inside the recipe template as `$data-\u003efoo`.\n  \n  If you wish to use a different variable name, add a second parameter to `set_template_data()`:\n\n  ~~~php\n  $data = array( 'foo' =\u003e 'bar', 'baz' =\u003e 'boom' );\n  $meal_planner_template_loader\n      -\u003eset_template_data( $data, 'context' )\n      -\u003eget_template_part( 'recipe', 'ingredients' );\n  ~~~\n  \n  The value of `bar` is now available inside the recipe template as `$context-\u003efoo`.\n\n  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`.\n\n* You can also pass the template loader object into the template as well:\n  ~~~php\n  $template_loader = new Your_Template_Loader();\n  $template_loader-\u003eset_template_data(\n      array(\n\t\t      'template_loader' =\u003e $template_loader,\n    \t\t  // Optional other data as needed.\n\t    )\n  );\n  ~~~\n  Then in the template you can use:\n  ~~~php\n  $data-\u003etemplate_loader-\u003eget_template_part( 'recipe' );\n  ~~~\n### Meal Planner Example Class\n\n```php\n\u003c?php\n/**\n * Meal Planner\n *\n * @package   Meal_Planner\n * @author    Gary Jones\n * @link      http://example.com/meal-planner\n * @copyright 2013 Gary Jones\n * @license   GPL-2.0+\n */\n\nif ( ! class_exists( 'Gamajo_Template_Loader' ) ) {\n  require plugin_dir_path( __FILE__ ) . 'class-gamajo-template-loader.php';\n}\n\n/**\n * Template loader for Meal Planner.\n *\n * Only need to specify class properties here.\n *\n * @package Meal_Planner\n * @author  Gary Jones\n */\nclass Meal_Planner_Template_Loader extends Gamajo_Template_Loader {\n  /**\n   * Prefix for filter names.\n   *\n   * @since 1.0.0\n   *\n   * @var string\n   */\n  protected $filter_prefix = 'meal_planner';\n\n  /**\n   * Directory name where custom templates for this plugin should be found in the theme.\n   *\n   * @since 1.0.0\n   *\n   * @var string\n   */\n  protected $theme_template_directory = 'meal-planner';\n\n  /**\n   * Reference to the root directory path of this plugin.\n   *\n   * Can either be a defined constant, or a relative reference from where the subclass lives.\n   *\n   * In this case, `MEAL_PLANNER_PLUGIN_DIR` would be defined in the root plugin file as:\n   *\n   * ~~~\n   * define( 'MEAL_PLANNER_PLUGIN_DIR', plugin_dir_path( __FILE__ ) );\n   * ~~~\n   *\n   * @since 1.0.0\n   *\n   * @var string\n   */\n  protected $plugin_directory = MEAL_PLANNER_PLUGIN_DIR;\n\n  /**\n   * Directory name where templates are found in this plugin.\n   *\n   * Can either be a defined constant, or a relative reference from where the subclass lives.\n   *\n   * e.g. 'templates' or 'includes/templates', etc.\n   *\n   * @since 1.1.0\n   *\n   * @var string\n   */\n  protected $plugin_template_directory = 'templates';\n}\n```\n\n## Usage Example\n\nThe [Cue](https://github.com/AudioTheme/cue) plugin from [AudioTheme](http://audiotheme.com/) uses this class. Starting at [https://github.com/AudioTheme/cue/tree/develop/includes](https://github.com/AudioTheme/cue/tree/develop/includes), it has this class in the vendor directory, then the required subclass of my class in the `class-cue-template-loader.php` file, which sets a few basic properties. It also has a template in [https://github.com/AudioTheme/cue/tree/develop/templates](https://github.com/AudioTheme/cue/tree/develop/templates).\n\nIf you wanted the playlist to have different markup for your theme, you'd copy `templates/playlist.php` to `wp-content/themes/{your-active-theme}/cue/playlist.php` and do whatever changes you wanted. WordPress will look for that file first, before then checking a parent theme location (if your active theme is a child theme), before falling back to the default template that comes with the Cue plugin.\n\n## Change Log\n\nSee the [change log](CHANGELOG.md).\n\n## License\n\n[GPL 2.0 or later](LICENSE).\n\n## Contributions\n\nContributions are welcome - fork, fix and send pull requests against the `develop` branch please.\n\n## Credits\n\nBuilt by [Gary Jones](https://twitter.com/GaryJ)  \nCopyright 2013 [Gary Jones](https://garyjones.io)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaryjones%2Fgamajo-template-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgaryjones%2Fgamajo-template-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgaryjones%2Fgamajo-template-loader/lists"}