Template API

The Autoloader API not only autoloads classes, interfaces, and traits, but also has templating API to load template files.

This provides more flexibility to developers for locating template files irrespective of the project type, either plugin or theme.

Default Path

Autoloader::default_path() method sets the default path for locating the template file. It will be used to locate both template as well as template-parts.

• By default, the path will be set to templates/thewebsolver/.
• A filter with tag-name tws_default_tempate_path_{$project_dirname} is applied to the default path. This way you can define your templating structure for the default path. Let's say your project name is Awesome Project. Applying the filter, you can set the default path to project-templates/awesome/.
• Default paths are passed to WordPress locate_template API to search in the following priority:
  • Child-theme directory: {$path_to}/themes/child-theme/{Autoloader::default_path()}.
  • Parent-theme directory: {$path_to}/themes/parent-theme/{Autoloader::default_path()}.

Locate Template

Autoloader::locate() method will locate the template file for inclusion.

It accepts three parameters.

• $template_name - (Required) The template file name (eg. content-main.php).
• $template_path - (Optional) The template file path where $template_name is located. If this is not given, then defaults to Autoloader::default_path().
• $default_path - (Optional) The fallback default path where $template_name is located. If this is not given, then defaults to {$project_root_path}/templates/.

Considering all of the above parameters, possible template structures, and their loading priority will be:

• Child-theme directory: {$path_to}/themes/child-theme/{$template_path}/{$template_name}.
• Child-theme directory: {$path_to}/themes/child-theme/{Autoloader::default_path()/{$template_name} (if $template_path not given).
• Parent-theme directory: {$path_to}/themes/parent-theme/{$template_path}/{$template_name}.
• Parent-theme directory: {$path_to}/themes/parent-theme/{Autoloader::default_path()/{$template_name} (if $template_path not given).
• Project directory: {$project_root_path}/templates/{$template_name} (considering $project is a plugin and template file could not be located in theme).

A filter with tag-name tws_locate_template_file_{$project_dirname} is applied to the located template file. 3 parameters are passed to the filter callback function:

• $template - The located template file with its located path (if located at all). This must be the return value after applying a filter.
• $template_name - The same parameter passed to this method.
• $template_path - The same parameter passed to this method.

Get Template

Autoloader::template() method will load the template file.

• Internally, the template file is located using Autoloader::locate().
• If the template file could not be located (if it doesn't exist), a log message will be printed to debug the log file using the WordPress function _doing_it_wrong.

It accepts four parameters.

• $template_name - (Required) The template file name (eg. content-main.php).
• $args - (Optional) The template args. These will be extracted using the PHP extract() function and can be used inside the located template file.
• $template_path - (Optional) Passed as argument to Autoloader::locate().
• $default_path - (Optional) Passed as argument to Autoloader::locate().

At last, it will be included using the PHP include expression.

This method is an alternative to WordPress's locate_template API.

Get Template Part

Autoloader::template_part() method will load the template file parts that can be used multiple times across various template files and/or locations.

It accepts three parameters:

• $slug - (Required) The slug name for the generic template.
• $name - (Optional) The name of the specialized template.
• $args - (Optional) The template args. These will be extracted using the PHP extract() function and can be used inside the located template part file.

As a fallback path when the template part is not found inside the theme, it will be {$project_rootpath}/template-parts.

A filter with tag-name tws_locate_template_path_{$project_dirname} is applied to the fallback path. 3 parameters are passed to the filter callback function:

• $fallback_path - The fallback path. This must be the return value after applying a filter.
• $template_path - The template part path located inside the theme, if any.
• $args - The same parameter passed to this method.

Considering all of the above parameters, possible template part structures, and their loading priority will be:

• Child-theme directory: {$path_to}/themes/child-theme/{Autoloader::default_path()}/{$slug}-{$name}.php.
• Child-theme directory: {$path_to}/themes/child-theme/{Autoloader::default_path()}/{$slug}.php.
• Parent-theme directory: {$path_to}/themes/parent-theme/{Autoloader::default_path()}/{$slug}-{$name}.php.
• Parent-theme directory: {$path_to}/themes/parent-theme/{Autoloader::default_path()}/{$slug}.php.
• Project directory: {$fallback_path}/{$slug}-{$name}.php.
• Project directory: {$fallback_path}/template-parts/{$slug}.php.

The final located template part file goes through another filter with tag-name tws_locate_template_part_{$project_dirname}. 3 parameters are passed to the filter callback function:

• $located_template_file - The located template part file from above-mentioned loading priority. This must be the return value after applying a filter.
• $slug - The same parameter passed to this method.
• $name - The same parameter passed to this method.

At last, it will be included using the PHP include expression.

This method is an alternative to WordPress's get_template_part API.