README

WordPress module to add custom ( page and post type ) templates with plugins.

Installation

❗ Minimum requirements

PHP: 5.6

➖ Install with composer

Run the following in your terminal to install wp-templater with Composer.

composer require jozoor/wp-templater

As wp-templater uses PSR-4 autoloading you will need to use Composers autoloader. Below is a basic example of getting started with the class, though your setup maybe different depending on how you are using composer, this example below show you simple usage of create new post type:

require_once __DIR__ . '/vendor/autoload.php';

use JO\Module\Templater\Templater;

See Composers basic usage guide for details on working Composer and autoloading.

➖ Download the module and include it manually

If you don't using composer and want to to include the library manually, you can do that, this example below show you simple usage of create new post type:

/**
 * load main file
 */

require_once __DIR__ . '/wp-templater/src/Templater.php';

use JO\Module\Templater\Templater;

Features

In this module/package i improved the @source class PageTemplater created by wpexplorer, which i added this features:

handle class methods and added new functionality.
you can now define your 'Templater' $settings and $templates outside the class.
- @see Setup Templater
you can override final custom template file using filter outside the class
- @see Templater.php
create composer package.
support any post type custom template.

Usage

use JO\Module\Templater\Templater;

/**
 * How to use Templater
 */

// we should add our new Templater inside action hook
add_action('plugins_loaded', 'load_templater');

function load_templater()
{

    // setup our templater
    $my_templater = new Templater(
        array(
            // YOUR_PLUGIN_DIR or plugin_dir_path(__FILE__)
            'plugin_directory'          => plugin_dir_path(__FILE__),
            // should end with _ > prefix_
            'plugin_prefix'             => 'plugin_prefix_',
            // templates directory inside your plugin
            'plugin_template_directory' => 'templates',
        )
    );


    // add our new custom templates
    $my_templater->add(

        // array of available templates
        array(

            /**
             * default usage:
             * 'post_type_name' => array(
             *      'template_file.php' => 'template_name',
             *      or
             *      'path/to/template_file.php' => 'template_name',
             * ),
             *
             * Note: all this files should be inside your 
             * 'plugin_template_directory' => 'templates',
             * so this is parent directory > 'templates/path/template_file.php'
             */
            
            // add 'post' type custom templates
            'post' => array(
                // just file without any sub folders
                'post-template.php' => 'Post Custom Template',
                // with sub folders
                'path/to/post-template.php' => 'Post Custom Template',
            ),

            // add 'page' type custom templates
            'page' => array(
                // just file without any sub folders
                'page-template.php' => 'Page Custom Template',
                // with sub folders
                'path/to/page-template.php' => 'Page Custom Template',
            ),

            // add 'custom_post_type' type custom templates, for ex: product
            'product' => array(
                // just file without any sub folders
                'product-template.php' => 'Product Custom Template',
                // with sub folders
                'path/to/product-template.php' => 'Product Custom Template',
            ),

            // ..etc

            /**
             * Note: you can name your template file anything you like
             * i mean you shouldn't add post type name in template name, like
             * 'post-template.php' < this just for show you examples
             */

            /**
             * Note: why we separated templates in the top by 'post types' ?
             * because we need this when working on any WP version 4.7 and later
             * which custom templates supported post types, but for WP version 
             * 4.6 and older, all this templates will be merged, because we
             * working on 'page' enough, not like WP version 4.7 and later,
             * which we add templates only for exact post type.
             */

        )

    // here we actually will add all this new templates.
    )->register();

}


/**
 * How to override final custom template file in themes or plugins
 */

add_filter('plugin_prefix_override_plugin_custom_template', 'override_plugin_custom_template');

function override_plugin_custom_template($template_file)
{

    // add another template file here
    $template_file = plugin_dir_path(__FILE__) . 'templates/my_override_template.php';

    // or do whatever .. 

    // return new updated template or default template 
    return $template_file;

}

Author

Mohamed Abd Elhalim

site
twitter

jozoor / wp-templater

Maintainers

Details