Home » Docs » Classes » Class: Conductor_Widget_Query

Description

This is the foundation query class used in Conductor Widgets. It is used as a base class to initialize logic used for displaying content (output elements) within Conductor Widgets and it contains the structure/helper functions for querying content.

Developers should extend this class to create their own query functionality/logic (see examples below and Conductor_Widget_Default_Query).

Construct/Instantiation

Upon instantiation, arguments are processed and stored as properties on the class. Only valid arguments (variables existing on the class) are stored. All other arguments will not be stored.

After the arguments have been processed, if a Conductor Widget instance exists (via arguments), the query is run (Conductor_Widget_Query::query()).

Output element callback functions are hooked to the conductor_widget_display_content_{$this->number} action. Opening/closing wrapper and content wrapper element callback functions are also hooked (before and after sortable output elements).

By default, the opening wrapper element is hooked at priority of 1 and the opening content wrapper element is hooked at a priority of 2 (right after opening wrapper element). The closing content wrapper element is hooked at a priority of 999 and the closing wrapper element is hooked at priority of 1000 (right after closing content wrapper element).

By default, sortable output elements will always start at a priority of 10 and increase by 10 (i.e. 10, 20, 30, 40, 50, etc…). This allows for an almost infinite number of other elements to be added (hooked) between the default priorities. The default priority step size of 10 can be adjusted in the conductor_widget_admin_localize filter via the priority_step_size property.

The default Conductor Widget callback functions are hooked in this order:

  • Conductor_Widget_Query::conductor_widget_wrapper() – priority: 1
  • Conductor_Widget_Query::conductor_widget_content_wrapper() – priority: 2
  • Conductor_Widget_Query::conductor_widget_featured_image() – priority: 10
  • Conductor_Widget_Query::conductor_widget_post_title() – priority: 20
  • Conductor_Widget_Query::conductor_widget_author_byline() – priority: 30
  • Conductor_Widget_Query::conductor_widget_post_content() – priority: 40
  • Conductor_Widget_Query::conductor_widget_read_more() – priority: 50
  • Conductor_Widget_Query::conductor_widget_content_wrapper_close() – priority: 999
  • Conductor_Widget_Query::conductor_widget_wrapper_close() – priority: 1000

When an output element is hooked to the conductor_widget_display_content_{$this->number} action, Conductor_Widget_Query triggers both the conductor_widget_query_add_display_content and conductor_widget_query_add_display_content_{$widget_number} actions.

The Conductor_Widget_Query will first look for callback functions presented as an array, which are callable, on a class (can be any PHP class as long as the callback method exists) which isn’t and instance of the Conductor_Widget_Query class (i.e. an object-oriented approach).

If a valid callback function isn’t found there, it will then look for a callback function on itself (a function which matches the callback name within the Conductor_Widget_Query class).

Lastly, the logic will check to see if a stand-alone callback function (not within a PHP class) exists.

Note: By default, if Conductor_Widget_Query detects that an output element should not be visible/displayed, the output element will be ignored.

Note: By default, if Conductor_Widget_Query does not find a valid callable callback function, the output element will be ignored.

Note: By default, Conductor Widget callback functions are prefixed with conductor_widget_ (i.e. the featured_image output element callback function is: conductor_widget_featured_image). This value can be modified via the conductor_widget_query_callback_prefix filter.

Conductor_Widget_Query::query()

This function is meant to perform a query and return query results (optional).

Note: Developers must create their own version of this function in their custom Conductor Widget Query sub-class.

Conductor_Widget_Query::get_query()

This function returns the current query object (stored in Conductor_Widget_Query->query).

Conductor_Widget_Query::have_posts()

This function is meant to check if the current query has any posts.

Note: Developers must create their own version of this function in their custom Conductor Widget Query sub-class.

Conductor_Widget_Query::next_post()

This function is meant to advance the current query to the next post.

Note: Developers must create their own version of this function in their custom Conductor Widget Query sub-class.

Conductor_Widget_Query::the_post()

This function is meant to advance the current query to the next post and also setup global post variables.

Note: Developers must create their own version of this function in their custom Conductor Widget Query sub-class.

Conductor_Widget_Query::get_current_post()

This function is meant to get the current post object reference within the query.

Note: Developers must create their own version of this function in their custom Conductor Widget Query sub-class.

Conductor_Widget_Query::get_pagination_links()

This function is meant to get pagination links for the current query and output them.

Note: Developers must create their own version of this function in their custom Conductor Widget Query sub-class.

 

This class is instantiated when the Conductor_Widget::widget() function is called (when a Conductor Widget is displayed).

Technical Details

Resources

Examples

The following example demonstrates how to extend Conductor_Widget_Query and create custom logic for querying content.