Advanced Usage
- The default options of the main function
- Filtering the output
- The "Get posts from taxonomy using custom field" option
- Using
nowas Custom field value when comparing dates
As of version 4.10.0, these are the default options of the main function pis_posts_in_sidebar():
$defaults = array(
// The custom container class.
'container_class' => '',
// The title of the widget.
'title' => esc_html__( 'Posts', 'posts-in-sidebar' ),
'title_link' => '',
'intro' => '',
// Posts retrieving.
'post_type' => 'post', // post, page, attachment, or any custom post type.
'post_type_multiple' => '', // A list of post types, comma separated.
'posts_id' => '', // Post/Pages IDs, comma separated.
'author' => '', // Author nicename.
'author_in' => '', // Author IDs.
'posts_by_comments' => false, // Boolean. An array of post IDs will be used.
'cat' => '', // Category slugs, comma separated.
'tag' => '', // Tag slugs, comma separated.
'post_parent_in' => '',
'post_format' => '',
'number' => get_option( 'posts_per_page' ),
'orderby' => 'date',
'order' => 'DESC',
'offset_number' => '',
'post_status' => 'publish',
'post_meta_key' => '',
'post_meta_val' => '',
/*
* The 's' (search) parameter must be not declared or must be empty
* otherwise it will break sticky posts.
*/
'search' => null,
'has_password' => 'null', // Fake content that will be converted later into real null/true/false.
'post_password' => '',
'ignore_sticky' => false,
/*
* This is the category of the single post
* where we'll get posts from.
*/
'get_from_same_cat' => false,
'number_same_cat' => '',
'title_same_cat' => '',
'sort_categories' => false,
'orderby_same_cat' => 'date',
'order_same_cat' => 'DESC',
'offset_same_cat' => '',
'search_same_cat' => false,
'post_type_same_cat' => 'post',
'ptm_sc' => '',
/*
* This is the tag of the single post
* where we'll get posts from.
*/
'get_from_same_tag' => false,
'number_same_tag' => '',
'title_same_tag' => '',
'sort_tags' => false,
'orderby_same_tag' => 'date',
'order_same_tag' => 'DESC',
'offset_same_tag' => '',
'search_same_tag' => false,
'post_type_same_tag' => 'post',
'ptm_st' => '',
/*
* This is the author of the single post
* where we'll get posts from.
*/
'get_from_same_author' => false,
'number_same_author' => '',
'title_same_author' => '',
'orderby_same_author' => 'date',
'order_same_author' => 'DESC',
'offset_same_author' => '',
'search_same_author' => false,
'post_type_same_author' => 'post',
'ptm_sa' => '',
/*
* This is the custom field
* to be used when on single post
*/
'get_from_custom_fld' => false,
's_custom_field_key' => '',
's_custom_field_tax' => '',
'number_custom_field' => '',
'title_custom_field' => '',
'orderby_custom_fld' => 'date',
'order_custom_fld' => 'DESC',
'offset_custom_fld' => '',
'search_same_cf' => false,
'post_type_same_cf' => 'post',
'ptm_scf' => '',
/*
* This is the post format of the single post
* where we'll get posts from.
*/
'get_from_same_post_format' => false,
'number_same_post_format' => '',
'title_same_post_format' => '',
'orderby_same_post_format' => 'date',
'order_same_post_format' => 'DESC',
'offset_same_post_format' => '',
'search_same_post_format' => false,
'post_type_same_post_format' => 'post',
'ptm_spf' => '',
/*
* Do not ignore other parameters when changing query on single posts.
*/
'dont_ignore_params' => false,
/*
* Get posts from the current category page.
*/
'get_from_cat_page' => false,
'number_cat_page' => '',
'offset_cat_page' => '',
'title_cat_page' => '',
'orderby_cat_page' => 'date',
'order_cat_page' => 'DESC',
'post_type_cat_page' => 'post',
'ptm_scp' => '',
/*
* Get posts from the current tag page.
*/
'get_from_tag_page' => false,
'number_tag_page' => '',
'offset_tag_page' => '',
'title_tag_page' => '',
'orderby_tag_page' => 'date',
'order_tag_page' => 'DESC',
'post_type_tag_page' => 'post',
'ptm_stp' => '',
/*
* Get posts from the current author page.
*/
'get_from_author_page' => false,
'number_author_page' => '',
'offset_author_page' => '',
'title_author_page' => '',
'orderby_author_page' => 'date',
'order_author_page' => 'DESC',
'post_type_author_page' => 'post',
'ptm_sap' => '',
/*
* Get posts from the current post format page.
*/
'get_from_post_format_page' => false,
'number_post_format_page' => '',
'offset_post_format_page' => '',
'title_post_format_page' => '',
'orderby_post_format_page' => 'date',
'order_post_format_page' => 'DESC',
'post_type_post_format_page' => 'post',
'ptm_spfp' => '',
/*
* Do not ignore other parameters when changing query on archive pages.
*/
'dont_ignore_params_page' => false,
// Taxonomies.
'relation' => '',
'taxonomy_aa' => '',
'field_aa' => '',
'terms_aa' => '',
'operator_aa' => '',
'relation_a' => '',
'taxonomy_ab' => '',
'field_ab' => '',
'terms_ab' => '',
'operator_ab' => '',
'taxonomy_ba' => '',
'field_ba' => '',
'terms_ba' => '',
'operator_ba' => '',
'relation_b' => '',
'taxonomy_bb' => '',
'field_bb' => '',
'terms_bb' => '',
'operator_bb' => '',
// Date query.
'date_year' => '',
'date_month' => '',
'date_week' => '',
'date_day' => '',
'date_hour' => '',
'date_minute' => '',
'date_second' => '',
'date_after_year' => '',
'date_after_month' => '',
'date_after_day' => '',
'date_before_year' => '',
'date_before_month' => '',
'date_before_day' => '',
'date_inclusive' => false,
'date_column' => '',
'date_after_dyn_num' => '',
'date_after_dyn_date' => '',
'date_before_dyn_num' => '',
'date_before_dyn_date' => '',
// Meta query.
'mq_relation' => '',
'mq_key_aa' => '',
'mq_value_aa' => '',
'mq_compare_aa' => '',
'mq_type_aa' => '',
'mq_relation_a' => '',
'mq_key_ab' => '',
'mq_value_ab' => '',
'mq_compare_ab' => '',
'mq_type_ab' => '',
'mq_key_ba' => '',
'mq_value_ba' => '',
'mq_compare_ba' => '',
'mq_type_ba' => '',
'mq_relation_b' => '',
'mq_key_bb' => '',
'mq_value_bb' => '',
'mq_compare_bb' => '',
'mq_type_bb' => '',
// Get posts from user login name.
'get_from_username' => false,
'use_categories' => false,
/*
* Do not ignore other parameters when changing query using current user login name.
*/
'dont_ignore_params_username'=> false,
// Posts exclusion.
'author_not_in' => '',
'exclude_current_post' => false,
'post_not_in' => '',
'cat_not_in' => '', // Category ID, comma separated.
'tag_not_in' => '', // Tag ID, comma separated.
'post_parent_not_in' => '',
// The title of the post.
'display_title' => true,
'link_on_title' => true,
'arrow' => false,
'title_length' => 0,
'title_length_unit' => 'words',
'title_hellipsis' => true,
'html_title_type_of' => 'p',
// The featured image of the post.
'display_image' => false,
'image_size' => 'thumbnail',
'image_align' => 'no_change',
'image_before_title' => false,
'image_link' => '',
'custom_image_url' => '',
'custom_img_no_thumb' => true,
'image_link_to_post' => true,
// The text of the post.
'excerpt' => 'excerpt',
'exc_length' => 20,
'exc_length_unit' => 'words',
'the_more' => esc_html__( 'Read more…', 'posts-in-sidebar' ),
'exc_arrow' => false,
// Author, date/time and comments.
'display_author' => false,
'author_text' => esc_html__( 'By', 'posts-in-sidebar' ),
'linkify_author' => false,
'gravatar_display' => false,
'gravatar_size' => 32,
'gravatar_default' => '',
'gravatar_position' => 'next_author',
'display_date' => false,
'date_text' => esc_html__( 'Published on', 'posts-in-sidebar' ),
'linkify_date' => false,
'display_time' => false,
'display_mod_date' => false,
'mod_date_text' => esc_html__( 'Modified on', 'posts-in-sidebar' ),
'linkify_mod_date' => false,
'display_mod_time' => false,
'comments' => false,
'comments_text' => esc_html__( 'Comments:', 'posts-in-sidebar' ),
'linkify_comments' => false,
'display_comm_num_only' => false,
'hide_zero_comments' => false,
'utility_sep' => '|',
'utility_after_title' => false,
'utility_before_title' => false,
// The categories of the post.
'categories' => false,
'categ_text' => esc_html__( 'Category:', 'posts-in-sidebar' ),
'categ_sep' => ',',
'categ_before_title' => false,
'categ_after_title' => false,
// The tags of the post.
'tags' => false,
'tags_text' => esc_html__( 'Tags:', 'posts-in-sidebar' ),
'hashtag' => '#',
'tag_sep' => '',
'tags_before_title' => false,
'tags_after_title' => false,
// The custom taxonomies of the post.
'display_custom_tax' => false,
'term_hashtag' => '',
'term_sep' => ',',
'ctaxs_before_title' => false,
'ctaxs_after_title' => false,
// The custom field.
'custom_field_all' => false,
'custom_field' => false,
'custom_field_txt' => '',
'meta' => '',
'custom_field_count' => '', // In characters.
'custom_field_hellip' => '…',
'custom_field_key' => false,
'custom_field_sep' => ':',
'cf_before_title' => false,
'cf_after_title' => false,
// The link to the archive.
'archive_link' => false,
'link_to' => 'category',
'tax_name' => '',
'tax_term_name' => '',
'auto_term_name' => false,
// translators: %s is the name of the taxonomy for the archive page link.
'archive_text' => esc_html__( 'Display all posts under %s', 'posts-in-sidebar' ),
// When no posts found.
'nopost_text' => esc_html__( 'No posts yet.', 'posts-in-sidebar' ),
'hide_widget' => false,
// Styles.
'margin_unit' => 'px',
'intro_margin' => null,
'title_margin' => null,
'side_image_margin' => null,
'bottom_image_margin' => null,
'excerpt_margin' => null,
'utility_margin' => null,
'categories_margin' => null,
'tags_margin' => null,
'terms_margin' => null,
'custom_field_margin' => null,
'archive_margin' => null,
'noposts_margin' => null,
'custom_styles' => '',
// Extras.
'list_element' => 'ul',
'remove_bullets' => false,
'add_wp_post_classes' => false,
// Cache.
'cached' => false,
'cache_time' => 3600,
'widget_id' => '',
// Debug.
'admin_only' => true,
'debug_query' => false,
'debug_params' => false,
'shortcode_id' => '',
);If you want to use the main function directly in your PHP files, you can use this form:
if ( function_exists( 'pis_posts_in_sidebar' ) ) {
$args = array(
'number' => 3,
'comments' => true,
// Add here the other options to change.
);
pis_posts_in_sidebar( $args );
}The output of Posts in Sidebar can be filtered (i.e. changed) in some points. There are multiple hooks for filters added in the code.
pis_intro_class
pis_ul_class
pis_li_class
pis_title_class
pis_title_link_class
pis_arrow_class
pis_excerpt_class
pis_thumbnail_link_class
pis_thumbnail_class
pis_arrow_class
pis_more_class
pis_utility_class
pis_author_class
pis_author_link_class
pis_separator_class
pis_date_class
pis_date_link_class
pis_comments_class
pis_categories_class
pis_tags_class
pis_archive_class
pis_archive_link_class
pis_nopost_class
pis_noposts_classTo add a class to the current class of an HTML element, use a function like this:
// Add this filter to each li
function li_class() {
$class = 'my-example-class';
return $class;
}
add_filter( 'pis_li_class', 'li_class' );This filter will add the class "my-example-class" to the default class of every li HTML element.
To add multiple classes to the current class of an HTML element, use a function like this:
function archive_class() {
$class = array( 'class-1', 'class-2', 'class-3' );
return $class;
}
add_filter( 'pis_categories_class', 'archive_class' );This function will add the classes class-1, class-2, class-3 to the class of the p HTML element of the categories section.
pis_classesTo remove all the classes at once, add this function:
function remove_all_classes() {
$class = '';
return $class;
}
add_filter( 'pis_classes', 'remove_all_classes' );To change all the classes at once, add this function:
function change_all_classes() {
$class = 'class="my-example-class"';
return $class;
}
add_filter( 'pis_classes', 'change_all_classes' );Be aware that all the classes of all the HTML elements generated by this plugin will be changed.
pis_categories_list
pis_tags_listFor example, to add a class to the categories and tags list, use this function:
function add_class_to_the_term_list( $list ) {
$list = str_replace( '<a href', '<a class="my-class" href', $list );
return $list;
}
add_filter( 'pis_categories_list', 'add_class_to_the_term_list' );
add_filter( 'pis_tags_list', 'add_class_to_the_term_list' );Changing the title of the widgets can be done using a filter. You can change the title of all the widgets of any plugin, or you can change the title of all the widgets of a specific plugin, or even the title of a specific instance of a plugin. Here is the code of these three situations.
These functions can be added in the functions.php file of your current theme
or, better, in a functions plugin (a plugin that collects the functions that
you want to use even when changing your theme) you have created for yourself.
This code will change the title of all the widgets of any plugin.
What this functions does: adds the string (all widgets) to the end of the title:
/**
* Change the title of all the widgets of any plugin.
*
* @param string $title The string with the input title.
* @return string $title The filtered title.
*/
function change_all_widget_titles( $title ) {
$title .= ' (all widgets)';
return $title;
}
add_filter( 'widget_title', 'change_all_widget_titles', 10, 1 );This code will change the title of all the widgets of a single plugin.
What this functions does: adds the string (all PiS widgets) to the end of the title:
/**
* Change the title of all the widgets of a specific plugin.
*
* @param string $title The string with the input title.
* @param array $instance Array of settings for the current widget.
* @param string $id_base The string with the id_base of the widget plugin.
* The param $id_base contains the base string,
* without the trailing number.
* @return string $title The filtered title.
*/
function change_title_specific_plugin( $title, $instance, $id_base ) {
if ( 'pis_posts_in_sidebar' === $id_base ) {
$title .= ' (all PiS widgets)';
}
return $title;
}
add_filter( 'widget_title', 'change_title_specific_plugin', 10, 3 );This code will change the title of a single widget of Posts in Sidebar plugin.
What this functions does: adds the string (a specific PiS widget) to the end of the title:
/**
* Change the title of a specific instance of a plugin.
*
* @param string $title The string with the input title.
* @param array $instance Array of settings for the current widget.
* @return string $title The filtered title.
*/
function change_title_specific_instance( $title, $instance ) {
if ( ! isset( $instance['widget_id'] ) ) {
return;
}
if ( 'pis_posts_in_sidebar-18' === $instance['widget_id'] ) {
$title .= ' (a specific PiS widget)';
}
return $title;
}
add_filter( 'widget_title', 'change_title_specific_instance', 10, 2 );As you know, the option "Get posts from current category" gets posts from the category of the main post, and works fine. If the single (main) post has more categories, the plugin can grab posts from only one category and it uses the category with key 0 in the array of categories.
This option has been introduced in order to let the user choose the category (or tag) where the plugin will get posts from.
To make this option in use, we'll use Custom fields. We'll create a custom field where the value is the slug or the ID of the post's taxonomy we like. In this way, when the single post is displayed, the plugin will show the post from that taxonomy.
These steps are necessary:
- Create a new custom field with a unique name across all the posts or only across the posts you want. The uniqueness is due to the fact that this name will be used in the widget.
- In every post of the site, that could have one or more categories, decide which category/tag of the post should be used to get posts from and write its slug or ID in the Custom field value. Make sure that the post is under that category/tag. Before making these changes, the user must decide if he want to use categories or tags.
- After having made this, create a widget of Posts in Sidebar activating the section "Get posts from taxonomy using custom field". Fill in the field for the custom field key and the type of taxonomy.
- Save the widget and test the results.
Custom field can contain any type of text, even a date, for example:
2020-01-01 01:10
or even:
2020-01-01
This is useful when the post, for example, contains an event and you want to store the event date as a value in a separate field. This lets you search posts based on that field, for example: give me all the posts that have an event date after 2020-01-01, or for example: give me all posts that have an event after today.
Let's say we have a series of posts, where we wrote about events. Each post speaks of an event. In a custom field we store the date of the event:
- key of the custom field:
date; - content of the custom field: the date of the event.
Now, we want to show in the sidebar those posts that have date as custom field key and the event is in the future (i.e., after now).
While it's simple to setup the formula for the first example (give me all the posts that have an event date after 2020-01-01), it was impossible to setup a dinamic date (today) for the second example (give me all posts that have an event after today).
Starting from 4.9.0, you can use the word now for the custom field value, if the custom field is a date.
For the example above (give me all posts that have an event after today) the setup is the following:
-
Custom field key A1: insert the key of the custom field, in this case
date; -
Custom field value: insert
nowand Posts in Sidebar will change it with the current date and time; -
Operator: choose
>(greater than); used in conjunction withnowmeans after now; -
Type: choose the type of custom field value; use
DATEwhen using a simple date (for example, 2019-10-27), orDATETIMEwhen using a date and a time (for example, 2019-10-27 22:45:00).
You can also sort the retrieved posts using the other options, for example:
A possible result could be the following:
