WordPress Portal

This is a library/plugin to ease complex themes development in WordPress. Its main feature is the custom The Loop creator, useful to manage complex and information-dense layouts, but it gives also many other functions to shortcut some common tasks.

It can be used:

  1. As a library, to ease complex themes development.
  2. As a plugin, to add any number of Widgets.

Currently supports WordPress 2.3+.
Use WPP version 0.5 for WordPress 2.1/2.2.

Usage as a Plugin

When you add WPP as a plugin you get a WordPress Portal widget that can extract a specific category from the WordPress database (like the wpp::foreach_post function described below).

The WordPress Widget configuration panel: title, category, limit and more

Using multiple widgets and multiple sidebars you can build complex websites: for example a homepage with sidebars and widgets can display a box with highlights, a box with a few news and the latest articles. For more complex usages you can still rely on WPP, using it as a library and generating more complex queries.

Usage as a Library

These are the functions usable once WPP has been included or plugged:

wpp::foreach_post($filter, $limit = null)
Creates a custom The Loop. Its first parameter could be either a raw string defining an SQL WHERE clause or an array where each key=>value pair becomes a string of key = 'value', joined with AND.
The good thing is that you can pass also: a page nicename (slug) or a category nicename (slug) and it will get all the matching content.
The filter parameter is just the LIMIT part of the query: write '3' and you'll get three posts, write '3,10' and you'll get ten posts starting from third.
wpp::get_posts($filter, $limit = null)
Same parameters as wpp::foreach_post(), but returns an array instead of creating a custom The Loop.
wpp::foreach_attachment($filter, $limit = null)
This functions behaves exactly like foreach_post, but it creates a custom The Loop on the attachments of a post. You can also filter them out by mime-type ("mime_type").
wpp::get_attachments($filter, $limit = null)
Same parameters as wpp::foreach_attachment(), but returns an array instead of creating a custom The Loop.
wpp::get_terms_recursive($ref, $levels = -1, $taxonomy = 'category')
Gets all the Term rows from the database, starting from the one matching the nicename (slug) passed as $ref and adding all its children.
The returned array is flat, not hierarchical.
The $levels parameters specify how deep it should recurse, by default it's unlimited.
wpp::in_category($nicename)
Usable only inside The Loop or The Loop custom.
It checks if the current post belongs to the category passed as nicename (slug).
wpp::is_term_child_of($child_term, $parent_term)
Checks if the $child_term is the same or a child of $parent_term.
wpp::get_post_custom($custom, $before = '', $after = '', $optid = 0)
Usable only inside The Loop or The Loop custom (without $optid).
Returns a specific post custom field.
It could wrap the results (using $before and $after) and could refer to a specific post (identified by the ID) using $optid.
wpp::get_page_content($nicename, $on_empty = "The page '%s' is empty.")
Gets a string with the content of the page identified by the nicename (slug).
It returns a customizable message if it's not found.
wpp::get_zone($key = null)
Returns an array containing zone type, zone id and if possible the matching Terms array.
array('type' => ..., 'id' => ..., 'terms' => array(...)).
The WP zone types are matching the is_* functions (i.e. is_page, is_single, ...), while the id is the unique identifier for that zone type (i.e. for pages and post, the post id; for categories the category nicename, ...).
The returned types are: page, post, author, search, category, date, tag, home.
wpp::is_admin($uid = 0)
Check if the current user is an Administrator.
Pass an user ID to check a specific user.
wpp::get_last_comments($size = 10, $id = 0)
Gets an array with the last 10 comments (use $size to specify how many).
Pass a post ID to retrieve the last $size posts from a specific post.
wpp::get_last_comments_grouped($size = 10)
Gets an array with the last 10 commented posts, each one with the last comment details.
wpp::get_pages_root()
Retrieves the top page in the current hierarchy of pages.
The hierarchy of pages starts with a root top page and goes down its children.
wpp::list_pages_of_section($arguments = '&title_li=')
Like wp_list_pages(), but it returns just the current hierarchy of pages.
This function is related to wpp::get_pages_root().

Examples

Custom The Loop, by Page, passing just its nicename (slug) and then using it inside the block with any The Loop function. 

while (wpp::foreach_post(array('page' => 'about'))) {
	echo the_content();
}

Custom The Loop, by Category, choosing all the posts from the 'blue' category (and all its sub-categories) and limiting to the top 5 entries sorted automatically by date.
Note the function wpp::in_category that is checking a different category: if 'azure' is a sub-category of 'blue', it will show also the custom field named 'color'. 

while (wpp::foreach_post(array('category' => 'blue'), 5)) {
	echo the_title();
	if (wpp::in_category('azure')) {
		echo wpp::get_post_custom('color');
	}
}

Get Posts, choosing all the posts from the 'corporate' category (and all its sub-categories) and limiting to the top 2 entries sorted automatically by date. 

$posts = wpp::get_posts(array('category' => 'corporate'), 2);
echo $posts[0]->post_content;
echo $posts[1]->post_content;

Virtual Pages, from anywhere in the code you can inject a new page at a specific relative URL, using the WordPress url rewrite feature (permalinks MUST be enabled).
This is a good way to develop a simple plugin APIs and custom panels with an high degree of flexibility.
Assuming the WordPress installation at "example.org" this example will add the virtual path located at "http://example.org/plugin-x/api/list", trying to load "customtemplate-1.php" from the template folder and if it isn't found it loads "customtemplate-2.php" from the plugin folder. You can have any number of fallbacks. 

wpp::add_virtual_page('plugin-x/api/list', array(
  get_template_directory() . "/customtemplate-1.php",
  dirname(__FILE__) . "/customtemplate-2.php"  
));

Custom The Loop for Attachments, allows loading the attachments for each post like they were normal posts. You can filter them also by mime-type.
This example will load all the posts from the "gallery" category and displays the first image associated with each post. 

while (wpp::foreach_post(array('category_name' => "gallery"), 10)) :
  while(wpp::foreach_attachment(array('mime_type' => 'image'), 1)) {
    $image = wp_get_attachment_image_src($post->ID, 'full');
    echo '<img src="' . $image[0] . '" />';
  }
}

Download

NOTE: this class can be used in two ways: included in a template or added as a plugin to get the Widgets. If it's included in the template, adding the plugin will upgrade the class (it loads the first one).

Changelog

0.9.1 (2009 03 27)
Virtual Pages: avoided WordPress auto-guessing of URL.
Virtual Pages: removed 404 flag.
0.9 (2009 03 26)
Widgets: if used as plugin it allows creation of unlimited WPP Widgets from administration panel.
Virtual Pages: support for pages injection (using WP url rewrite).
0.8 (2009 01 18)
Complete rewrite of foreach_post (now generalized, more WP-like, supports attachments).
0.7.1 (2008 05 15)
Improved foreach_post() support for The Loop structures using setup_postdata() WP internal function to handle initialization.
0.7 (2007 10 03)
Fixed in-file documentation errors.
0.7 (2007 09 29)
Changed WPP interface to static 'wpp' class. Usage as before, but statically called.
0.6 (2007 09 27)
Upgraded the library to WordPress 2.3, with a few improvements.
0.5 (2007 08 03)
First public release