Documentation 1.0

Documentation: 1.04.6
Documentation 1.0 – Term and Category Based Posts Widget

Version

“Term and Category Based Posts Widget”

All 1.0.x releases (The minor x version number means patch versions)

Server Requirements

  • PHP version 5.3 and above
  • WordPress version 4.0 and above

Preface

There are many aspects to the widget you can control including which posts will be displayed in it and some styling to the way they are displayed.

Since there are many options to control, in order to ease keep the admin area in a reasonable height we have divided the options into “panels” in which related options are being grouped together. You can open (expose the options) and close (hide them) by clicking the title of the panel.
Except for the visual effects, changing the options behaves exactly like it behaves in any other wordpress widget, both in the widgets admin screen and in the costumizer.

Title

title

Here you can find options to control what is displayed above the widget, AKA its title. You can either not dsplay a title at all, display some simple text, or display a link to the relevant category page.

The specific options are

  • Title: The text that is being displayed as the title
  • Title Link URL: If not empty the title will become a link to the URL specified here
  • Hide title: If selected no title will be displayed, no matter what the other options are.

Filter

filter

Here you can control which posts will be displayed in the widget. You can control their number and the sort criteria by which they are selected and displayed.

The options are:

  • Tags, categories, and other terms: For each public taxonomy which is defined in the site (categories and tags for blog style site, product categories and attributes if you have woocommerce, etc) a selection/menu box is displayed in which you can select posts from which selected terms of those taxonomies (i.e. specific categories, specific tgs etc) will be displayed.
    To be displayed a post has to be associated with any of the selected terms. This means that if you select category A and tag B, posts which are in category A will be displayed even if they are not in tag B, and vice versa. Of course posts that are both in category A and tag B will be displayed as well
    If you do not care about filtering by a specific taxonomy, you can set it to “Any“. This will cause that taxonomy to be ignored for filtering, and posts that are associated with any terms in it, or not associated at all, will be displayed based only on the other filtering criteria.
    usage: Clicking on the input area will open a drop down menu from which you can select the terms to filter by. You can also add them by writing their name and the drop down will adjust dynamically to show relevant matching terms. To remove a term, just click on the small”x” to the left of the term name.
  • Post Types: For each public “post type” which is defined in the site (posts and pages on a simple site, products if you have woocommerce, etc) a selection/menu box is displayed in which you can select posts from which post type will be displayed.
    Unlike the term filtering, to be displayed a post has to belong to any of the selected post types. Posts which do not belong to any of them will not be displayed.
    If you do not care about filtering by post types, you can set it to “Any“.
    usage: Clicking on the input area will open a drop down menu from which you can select the post types to filter by. You can also add them by writing their name and the drop down will adjust dynamically to show relevant matching post types. To remove a post type, just click on the small”x” to the left of the post type name.
  • Authors: On a site with many authors a selection/menu box is displayed in which you can select posts from which author will be displayed. This is not being displayed at all if there is only one author at the site.
    Unlike the term filtering, to be displayed a post has to belong to any of the selected authors. Posts which do not belong to any of them will not be displayed.
    If you do not care about filtering by authors, you can set it to “Any“.
    usage: Clicking on the input area will open a drop down menu from which you can select the author (by his display name) to filter by. You can also add them by writing their name and the drop down will adjust dynamically to show relevant matching authors. To remove an author, just click on the small”x” to the left of the author name.
  • Number of posts to show: The number of posts that will be displayed in the widget.
  • Show: The sort criteria used to select which posts out of all the posts associated with the category are actually going to be displayed. It also controls the display order.
    Sort options are:

    • Latest: Posts are sorted by their publish time. When selected The posts will be displayed from latest to oldest
    • Have more Comments: Post are sorted by the number of comment they have. The posts with more comment are displayed first
    • Random: No sort at all, posts are randomly picked to be displayed on every new page load.
      Note: Sometimes this option is useful which is why we provide it, but it is more resource demanding, and when using any type of page caching, you will get randomness only when the page cache is regenerated and not with every page load.
  • Exclude current post: If selected, when the widget is displayed on a post which matches all other criteria, the post itself will not be displayed as part of the widget. This behavior is useful if you use the widget to direct users to other posts, and displaying a link to the post the user is already on, is a waste of space.
  • Exclude posts which have no thumbnail: If selected, posts without a thumbnail/featured image will not be displayed. This is useful if you enable the display of thumbnails, and want to avoid style mismatches where some posts are displayed with and some without thumbnails. This is really just a stop gap measure, and it is much better to make sure all relevant posts have featured image.

Style

style

Here you can control the style effects applied to the list of posts, you can go traditional with a simple list, or for a slider effects

  • Style: The general style applied to the list. Can be any of
    • Simple: The posts will be displayed as a simple list
    • Vertical News Ticker: The posts will be displayed in a sliding “news ticker” style. To control the behavior of this specific style you will have the following options:
      • Direction: Controls the direction in wich the sliding happens. Can be either “Up” or “Down”
      • Time for transition: The time it will take to scroll through all of the post.
      • Number of displayed items: The number of posts that will be visible on the screen at any given time. Obviously this should probably be lees the the max number of posts configured in the filter panel.

Thumbnails

thumbs

Here you can control how thumbnails are being displayed

Options are:

  • Show post thumbnail: If selected a thumbnail based on the featured image of the post will be displayed.
  • Show thumbnails above text: If selected the thumbnail will be displayed above the text describing the post, if not selected it will be display to the left of it (on right to left sites, on the right).
  • Thumbnail dimensions (in pixels): You should set here The dimension of the thumbnail in pixels. It is best to set both dimensions but if you set only one the system will try to figure out the other.
    Important notes on how images are made to fit the place

    • When an image is uploaded, WordPress generates automatically several versions of them in smaller dimensions. The widget will select the one which is closest to the requested dimension and use it. If the match is not exact the browser will be instructed to stretch the image to fit the area.
    • In view of the previous point, you might want to use a plugin, or any any other appropriate tool, to instruct WordPress to generate images in the requested size (and then maybe run any plugin that regenerates them to make sure you have them for older posts as well). The motivation is mostly to avoid using big pictures to save bandwidth.
    • Starting with WordPress version 4.4 images will be responsive. When possible, the widget will give the browser several images instead of one, and the context in which they should be preferred, for example an image for “normal” displays and an higher quality image for retina displays.
  • Crop bigger thumbnails around the center: When selected the browser will be instructed to crop images which are bigger then the requested dimensions around their center in order to make them fit the dimensions, instead of stretching the images
  • Animation on mouse hover: Set visual effect to happen when the user is hovering a thumbnail. The possible effect are:
    • Darker: The thumbnail image will get a darker tone to it.
    • Brighter: The thumbnail image will get a brighter tone to it.
    • Zoom In: The thumbnail image will be zoomed into.

Post details

details

Here You can control what text will appear as part of the post description

The options are:

  • Hide post titles: When selected the post title will not be displayed
  • Show post excerpt: When selected, the post excerpt will be displayed
  • Excerpt length (in words): If the excerpt is displayed, this can be used to control the number of words in the excerpt. If the excerpt have more words in it then the specified limit, a “read more” kind of text will be added to the end of it
  • Excerpt ‘more’ text: The text to be used with the “read more” text being displayed when the excerpt limit is smaller then the excerpt size
  • Show post date: If selected the date in which the post was published will be added to the post description
  • Date format: The format of the date maybe any combination described on this page
  • Make widget date link: If selected the date will be a link to the post
  • Show number of comments: If selected the number of comments to the post will be appended to the post description
  • Show post author: If selected the name of the author of the post will be appended to the post description

General

general

Here you can set some miscellaneous options

Options are:

  • Disable the built-in CSS for this widget: If selected no CSS will be added automatically to style the specific widget. Any styling will have to be done by adding your own CSS rules.
  • Hide widget if there are no matching posts: If selected, when there are no posts in the category (or none have thumbnail, if the hide posts without thumbnail option is selected), The widget will not be displayed at all, which in practical terms means that the title and footer will not show.

Footer

footer

Here you can set how the footer of the widget looks

Options are:

  • Footer link URL: When non empty the footer text will be turned into a link, linking to the URL specified here
  • Footer link text: If not empty a link to the relevant category page will be displayed in the footer, with the text being used as the anchor text of the link.