gmazzap / ajax-template-part
Like get_template_part(), but AJAX powered.
Installs: 148
Dependents: 0
Suggesters: 0
Security: 0
Stars: 53
Watchers: 7
Forks: 9
Type:wordpress-plugin
Requires
- php: >=5.5
- composer/installers: ~1.0
- tedivm/stash: ~0.14.0
This package is auto-updated.
Last update: 2024-10-26 14:32:49 UTC
README
This plugin adds ajax_template_part()
function to WordPress.
It works like get_template_part()
,
but ajax powered.
#What does "ajax powered" mean?
When files containing ajax_template_part()
calls are loaded by WordPress, required
templates are not loaded immediately, only when entire page is loaded, an ajax request is sent to
server to get all the templates required, and related content is pushed in right place.
First question is:
Why should I run 2 HTTP requests (the regular one plus the ajax one) to show my template, when using
get_template_part()
I run only one?
Two reasons:
1. Quick response
Templates may require some time to be rendered. Let's imagine a loop.php
template
that shows a set of posts, each containing a shortcode that renders things dynamically.
Requiring that template using standard way will slow down page loading. However, sometimes
may be desirable to give a quick response to user that lands to the page and defer the loading
of slow things (maybe showing a loading UI).
That is possibly more useful to render "secondary" contents: e.g. load a post content as soon as possible, while a section with related posts, ads or stuff alike are loaded via ajax in meanwhile.
2. Cache
ajax_template_part()
embed a powerful cache system: all the contents loaded via ajax
are cached. That means that using this single, core-alike function is possible to implement
a deferred fragment cache system, without having to change existing code, to use additional libraries
or to setup anything.
More on plugin cache system later in this page.
#Requirements
- PHP 5.4+
- WordPress 3.9+
- Composer to install
#Installation
The plugin is a Composer package and can be installed in plugin directory via:
composer create-project gmazzap/ajax-template-part --no-dev
#How to use
ajax_template_part()
works just like get_template_part()
Accepts 2 arguments:
$slug
The slug name for the generic template (required)$name
The name of the specialized template (optional)
e.g. if the function is called like so:
ajax_template_part( 'content' );
it will look for content.php
, first in child theme folder (if any), then in parent theme.
If called like so:
ajax_template_part( 'content', 'page' );
it will load via ajax the first that exists among, in order:
content-page.php
in child themecontent-page.php
in parent themecontent.php
in child themecontent.php
in parent theme
Show content while loading
By default, where the function is called inside containing template, nothing appear until the ajax template is not loaded. However, is possible to show something: a spinner image, a loading message, default text..
That can be done in 2 ways:
- via filter
- using the
ajax_template_part_content()
function.
Via filter
Plugin provides the filter "ajax_template_loading_content"
and whatever is returned by hooking
callbacks is used as temporary content until required template is loaded.
Using this technique is possible to use a different contents for different calls thanks to the fact
that hooking callbacks receive 4 arguments
- the current content, that is an empty string, by default
- the "name" of the template required, that is 1st argument passed to function
- the "slug" of the template required, that is 2nd argument passed to function
- current main query object
Via ajax_template_part_content()
This function works in a pretty similar way to ajax_template_part()
, but takes 3 arguments:
whatever is passed as 1st argument is shown as temporary content, the other 2 arguments are the same
of ajax_template_part()
.
Note that content passed to this function is not filtered using "ajax_template_loading_content"
hook.
Temporary container class
When a temporary content is set, via filter or using ajax_template_part_content()
, it is added wrapped
inside a <div>
tag.
Is possible to set HTML class attribute for this container using
"ajax_template_loading_class"
filter hook.
Callbacks hooking this filter receive same 4 arguments passed by "ajax_template_loading_content"
.
Note that <div>
container is always added to page, even when no temporary content is used, but
by default it is hidden using in-line CSS, but using "ajax_template_loading_class"
filter, is
possible to add classes to the <div>
and so be able to style it via CSS: among other things is possible
to use a loader image by setting it as background image CSS property of a class
added via this filter.
Nested calls
If in template loaded using ajax_template_part()
there are additional calls to same function,
nested templates are loaded as expected, and in the same ajax request: don't expect
another ajax request triggered when parent ajax-required template as been loaded.
That applies in the exact manner to any get_template_part()
call inside ajax loaded templates.
Stay safe
To put ajax_template_part()
calls in your templates makes your site require this plugin is
installed, and active, otherwise you'll get fatal error because of function not declared.
To avoid such problems, e.g. if you deactivate plugin by accident, can be a good idea put this on top
of your functions.php
:
if ( ! function_exists( 'ajax_template_part' ) ) { function ajax_template_part( $name = '', $slug = '' ) { return get_template_part( $name, $slug ); } } if ( ! function_exists( 'ajax_template_part_content' ) ) { function ajax_template_part_content( $content = '', $name = '', $slug = '' ) { return get_template_part( $name, $slug ); } }
In this way your theme will gracefully degrade to get_template_part
if plugin is not active for
any reason.
Cache
Ajax template loading and content generation may be heavy, so plugin needs a way to cache them.
Cache is active by default when the constant WP_DEBUG
is set to FALSE
, this should be a pretty
common way to turn it on for production and off in locale / development environments.
However, using the "ajax_template_cache"
filter is possible to customize when enable or disable caching.
Only argument this hook passes to hooking callbacks is the current cache status and have to return
a boolean: TRUE
means cache active.
This plugin can work with different types of caches:
- if in the system is installed an external object cache, then this plugin will use that, nothing is left to do.
- if no external object cache is in use, this plugin uses Stash to cache data. This library can make use of different "drivers": FileSystem, APC, Memcached, Redis... By default plugin uses FileSystem driver and no configuration is required to use that. However is possible to use any supported driver, if system has the requirements.
Use an alternative cache driver
To use a different driver there are 2 filters available:
"ajax_template_cache_driver"
: hooking callback must return the fully qualified name of the class to use, one among:Stash\Driver\Sqlite
Stash\Driver\Memcache
Stash\Driver\APC
Stash\Driver\Redis
Stash\Driver\Composite
please refer to Stash documentation for details.
"ajax_template_{$driver}_driver_conf"
is the filter to be used to configure the chosen driver. Hooking callback must return the configuration array, see Stash documentation for details.
As example, configuration to use Memcache driver should be something like this:
add_filter( 'ajax_template_cache_driver', function() { return '\Stash\Driver\Memcache'; }); add_filter( "ajax_template_memcache_driver_conf", function() { return [ 'servers' => ['127.0.0.1', '11211'] ]; });
Cache expiration
By default contents are cached for 1 hour. Consider that if content (e.g. posts) is updated and the old content is cached, updated content will not be shown until cache expires.
Is possible to change default expiration time using "ajax_template_cache_ttl"
filter hook.
Hooking callbacks receives and have to return cache "time to live" value in seconds.
Note that setting a value under 30 seconds will be skipped and default will be used.
If you need to disable cache don't use this filter but "ajax_template_cache"
or set WP_DEBUG
to true
(not recommended for production, highly recommended for development environments).
#License
This plugin is released under MIT license.