List widget

What it does: Lets you insert listings of posts by category in a variety of formats.

In the same sort of way that individual posts can be added to the sidecolumns of a page, it’s also possible to insert listings of posts by category into any of the page columns. Typical listings could include:

  • the five most recent Archived Events in excerpt form
  • all Blog entries as titles, paginated to show ten at a time
  • a 1-item listing of the latest News

Set up with: Custom Field left-0-list, right-0-list etc, or shortcode_list.

Parameters: The values shown are examples only.

cat = 20 (REQUIRED)
type=excerpts (optional) default: titles
order=ASC (optional) default: DESC
show_posts=-1 (optional) default: 5
paginate=true (optional) default: false
heading=Recent news (optional) default: <no heading>
format=d (optional) default: <no adjustments>
status=future (optional) default: publish
style=boxed (optional) default: default

Notes: cat is the ID number of the post category you want to display. You can find the category ID number by going to the Categories page (accessed from the Posts page) and hovering over the appropriate category name: the ID number is at the end of the url that appears in your browser status bar.

type indicates how much of each post to display and can take the value: full, excerpts or titles.

order indicates whether to list the posts by ascending or descending date order and takes the value: ASC or DESC

show_posts indicates how many posts to list and takes an integer value (or -1, meaning display all). If the paginate parameter is true, show_posts indicates how many posts to display on the current sheet of the list.

heading specifies an <h2> heading to insert. Special characters (eg: apostrophes) should be preceded with a backslash: heading=Our organisation's history. In the shortcode version, uses underscores instead of spaces: heading=Our_organisation's_history.

format specifies various codes to modify how the post content is arranged. Eg: if format contains the character d, then the date is not output.

status is used mainly for Events listings. By setting status=future, only forthcoming events will be shown.

Adjusting the Publication Date: For many categories, the Publication Date is just that: the date on which you published the News item, Blog entry or whatever. However, for some other categories (eg: Events), hijacking the Publication Date is the simplest way of attaching the relevant Event date etc to the post, as well as ensuring that the posts are listed in the correct chronological order (rather than the order in which they were created).

The display of the date can be suppressed by setting parameter format=d.

The Descriptor: If the posts to be listed have a custom field called Descriptor, the (text) value of this field will be displayed within <p class='type'></p> tags between the date and the title. For Event posts, typical values for this field might be: Workshop, Forum, Consultation etc. Remember: the Descriptor custom field is attached to each of the posts, not the page on which the posts are listed. Go to Edit Post and set up custom field Descriptor with the appropriate text.

Required: For future events, functions.php may(?) need add_filter('the_posts', 'show_future_posts');