- Author: Scott Reilly
- Version: 3.0.1
- First released: 2010-09-27
- Last update: 2021-04-14
- Compatibility: WP 3.6 – 5.7.1
- Download: [ zip ]
- Description:
Facilitates injecting an array of posts into a WP query object as if queried. Particularly useful to allow use of standard template tags.
-
Extended Description
This plugin provides a function for use by developers who have their own code for fetching posts according to a given criteria and now want to make use of loop-aware template tags to display those posts.
WordPress’s template tags are intended to be used within ‘the loop’. The loop is managed by a WP_Query object which sets up various global variables and its own object variables for use by the various template tags. The primary purpose of a WP_Query object is to actually query the database for the posts that match the currently specified criteria. However, if you don’t need to query for posts since you already have them by some other means, you can still take advantage of the template tags by injecting those posts into the WP_Query via this plugin.
Depending on the template tags you are looking to use, or the logic you are hoping to employ within a loop, you may need to manually configure some of the query object’s variables.
Example:
<?php // Say we're in the sidebar // We've gotten some post objects on our own. $posts = c2c_get_random_posts( 5, '' ); // Inject the posts c2c_inject_query_posts( $posts ); // Now let's display them via template tags: if ( have_posts() ) : while ( have_posts() ) : the_post(); ?> <li><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title_attribute(); ?>"><?php the_title(); ?></a></li> <?php endwhile;?> <?php endif; ?>
Links: Plugin Homepage | Plugin Directory Page | GitHub | Author Homepage
Template Tags
The plugin provides one template tag for use in your theme templates, functions.php, or plugins.
Functions
<?php function c2c_inject_query_posts( $posts, $args = array() ) ?>
Injects an array of posts into a query object as if that query object had obtained those posts via a query.
Arguments
-
$posts
(array)
Array of posts to inject into the query object. -
$args
(array)
Optional. Associative array of configuration options. Available options:-
$config
(array)
Associative array of query object variables to directly set, and their values. -
$query_obj
(WP_Query|null)
The query object to modify. If null, then the global wp_query object will be used. Pass a string or non-zero integer to have a new query object created and used. -
$preserve_query_obj
(bool)
Should the query object be kept as-is prior to injecting posts? Default is false. If false, then the object is re-initialized/reset before post injection. -
$cache_posts
(bool)
Update the posts in cache? Default is true.
-
Examples
-
(See Description section for an additional example.)
-
Similar to previous example, for WP 3.0+
Hooks
The plugin is further customizable via two hooks. Such code should ideally be put into a mu-plugin or site-specific plugin (which is beyond the scope of this readme to explain).
inject_query_posts_preserve_query_obj (filter)
The ‘inject_query_posts_preserve_query_obj’ filter allows you override the value of the
$preserve_query_obj
argument passed to the function. This is not typical usage for most users.Arguments:
- $preserve_query_obj (bool) : Boolean indicating if the query object was set to be preserved or not
- $query_obj (WP_Query object) : The WP_Query object passed to the
c2c_inject_query_posts()
- $posts (array) : The posts being injected into the WP_Query object
- $config (array) : Query object variables to directly set, and their values.
Example:
/** * Always preserve the condition of the WP_Query object passed ot Inject Query Posts. * * @param bool $preserve_query_obj The default preservation value as passed to the function. * @param WP_Query $query_obj The query object. * @param array $posts The posts being injected. * @param array $config Associative array of query object variables to directly set, and their values. * @return bool */ function my_preserve_query_obj( $preserve_query_obj, $query_obj, $posts, $config ) { return true; } add_filter( 'inject_query_posts_preserve_query_obj', 'my_preserve_query_obj', 10, 4 );
c2c_inject_query_posts (filter)
The ‘c2c_inject_query_posts’ filter allows you to use an alternative approach to safely invoke
c2c_inject_query_posts()
in such a way that if the plugin were deactivated or deleted, then your calls to the function won’t cause errors in your site.Arguments:
- The same arguments as
c2c_inject_query_posts()
Example:
Instead of:
<?php echo c2c_inject_query_posts( $posts, array( 'is_search' => true ) ); ?>
Do:
<?php echo apply_filters( 'c2c_inject_query_posts', $posts, array( 'is_search' => true ) ); ?>
Find out more at the plugin’s WordPress Plugin Repository page.
-
Installation
- Install via the built-in WordPress plugin installer. Or download and unzip
inject-query-posts.zip
inside the plugins directory for your site (typicallywp-content/plugins/
) - Activate the plugin through the ‘Plugins’ admin menu in WordPress
- Use the
c2c_inject_query_posts()
function to inject an array of posts into a WP query object. Specify the posts array as the first argument. Configure the query object by passing an array as the second argument. If specifying a WP query object, pass it as the third object; if not specified then the global wp_query object will be assumed.
- Install via the built-in WordPress plugin installer. Or download and unzip
-
Release Log
3.0.1 (2021-04-13)
- Change: Note compatibility through WP 5.7+
- Change: Update copyright date (2021)
3.0 (2020-08-14)
- This significant release changes argument handling (while retaining backward compatibility), removes long-deprecated
inject_query_posts()
, changes unit test file structure, improves inline documentation, adds TODO.md file, and notes compatibility through WP 5.5+.
Details:
- New: Add TODO.md and move existing TODO list from top of main plugin file into it
- New: Add inline documentation for
inject_query_posts_preserve_query_obj
filter - Change: Consolidate multiple arguments for
c2c_inject_query_posts()
into an array- Change: Replace second and subsequent args with
$args
, a configuration array - Note: Legacy (pre-3.0) syntax is still supported, so existing code won’t break
- Change: Replace second and subsequent args with
- Change: Ensure use of post objects after the incoming posts have been mapped as such
- Change: Remove long-deprecated
inject_query_posts()
- Change: Cast first argument to
inject_query_posts_preserve_query_obj
filter as bool - Change: Move
inject_query_posts_preserve_query_obj
filter until after a query object has been obtained - Change: Restructure unit test file structure
- Change: Note compatibility through WP 5.5+
- Change: Add and update some inline documentation
2.2.9 (2020-05-01)
- Change: Use HTTPS for link to WP SVN repository in bin script for configuring unit tests
- Change: Note compatibility through WP 5.4+
- Change: Update links to coffee2code.com to be HTTPS
-
Copyright & Disclaimer
Copyright © 2010-2021 by Scott Reilly (aka coffee2code)This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -
Discussion / Support
Have any questions, comments, or suggestions? Please provide them via the plugin’s WordPress.org support forum. I’ll do my best to reply in a timely fashion and help as best I can.
Unfortunately, I cannot provide guaranteed support, nor do I provide support via any other means.
Was this plugin useful useful to you? Consider giving it a rating. If you’re inclined to give it a poor rating, please first post to the support forum to give me a chance to address or explain the situation.
Categories
One reply on “Inject Query Posts”
[…] Inject Query Posts von Scott Reilly injektiert ein Feld mir Postings in ein WordPress Query Object. Das Plungin ist kompatibel mit WordPress 2.3+, 2.5+, 2.6+, 2.7+. Bookmarks setzen: Diese Icons verlinken auf Bookmark Dienste bei denen Nutzer neue Inhalte finden und mit anderen teilen können. […]