Plugin overview

This plugin allows a blog administrator to set the order in which each item appears. Each item can be assigned an order number. When the blog form of the skinvar is used, the posts will be displayed in the order designated. Posts that are not given an order, are not shown when using the default form of the skinvar. An alternate form of the skinvar will display just the unordered posts ordered by post time. The skinvar also accepts an optional blogname parameter to display ordered posts from a different blog.

Additionally, a blog administator can set orders to categories in a blog for use with the categorylist form of this skinvar. A template can be designated, as well, to be used when displaying items in a given category when using the blog form of this skinvar. A category's items can also be excluded from the main page when using the blog form of this skinvar.

Requirements

This plugin should work on any system that meets the minimum requirements of Nucleus CMS v3.2 or higher, but may work on earlier versions as well. It requires PHP v 4.0.6 or higher. It has only been tested using MySQL version 4.1.16 and higher, but should theoretically work on all MySQL versions supported by Nucleus CMS 3.2+.

Upgrading

To upgrade to version 1.1 from version 1.0, simply copy the new files over the existing files.

Installation

The NP_Ordered plugin can be downloaded from here.

Download and extract the zip file. Copy the NP_Ordered.php file and the ordered directory to the nucleus/plugins directory.

Use the Nucleus Admin GUI to register the NP_Ordered plugin into Nucleus. Be sure to click the ‘Update subscription list’ button.

You will need to edit and save the plugin options before using the plugin. The options are described below.

Plugin Options

There are two options that control the operation of the Ordered plugin. These options are set from the ‘edit options’ link in the Plugin Admin area.

Plugin Options

SkinVars

These skinvars should be valid in all skin types except member, error, and imagepopup. The setnavigation skinvar is valid only in the Item Details skin part.

There are four forms of this skinvar — blog, categorylist, item, and setnavigation.

The blog form of the skinvar is used to replace the blog and otherblog skinvars. Its general form is as follows:

<%Ordered(blog,show,templatename,amount,category,blogname)%>
where:

The categorylist form of the skinvar is used to replace the categorylist skinvar. Its general form is as follows:

<%Ordered(categorylist,show,templatename,blogname)%>
where:

The item form of the skinvar is used to replace the item skinvar. Its general form is as follows:

<%Ordered(item,templatename)%>
where:

The setnavigation form of the skinvar is used to set the nextlink and prevlink to the proper values according to the sorting of the blog form of this skinvar. It should generally be placed in the head section of your skin about the first call to <%nextlink%> or <%prevlink%>. Its general form is as follows:

<%Ordered(setnavigation,show,amount,setcat)%>
where:

Usage

Use the item edit form or the plugin admin page to set the order of the items you wish to order. Then add the skinvar described above to your skins (usually the Main Index part) where you want the posts displayed. Will usually take the place of the <%blog(templatename,amount)%> skinvar.

Some usage examples are given below:

In your Category List template, use <%catiscurrent%>, to set the CSS class of the link for the current category like this: 

<a class="catcurr_<%catiscurrent%>" href="<%catlink%>" title="Category: <%catname%>"><%catname%></a>

There are lot's of ways to use this plugin to do things like sticky some important announcements or posts (like an About item), to order the items in a fairly static category, but leaving the other categories as dynamic, blog-like categories. The possibilities are endless, but most uses might require some clever uses of the <%if(category,catname,CategoryName)%> skinvar and tweaks in templates to get the desired affect. If anyone wants to submit examples use cases, I will be happy to include them in this document. Submit to the forum thread linked below.

The NP_Ordered plugin admin page allows blog administrators to manage item order and category order. In addition to ordering categories, blog administrators can set a template to be used to display items from each category when using the blog form of this skinvar. If no template is given, the template set in the blog form of the skinvar is used. Categories can also be set to not show on the main page when using the blog form of the skinvar.

API

A simple API method has been added so other plugins can get the ordered mysql results to manipulate as they please. It takes basically the same parameters as the skinvars, minus the unneeded templatename.

resource getQueryResult('blog',show,amount,category,blogname)

resource getQueryResult('categorylist',show,blogname)

Example of use. This outputs the catid of each category of the current blog then the itemid of each item in the order set by NP_Ordered 

/* example use of API function getQueryResult()*/
    $plugin =& $manager->getPlugin('NP_Ordered');
	$b =& $manager->getBlog(intval($blogid));
	$bname = $b->getShortName();
	$res = $plugin->getQueryResult('categorylist','all',$bname);
	while ($row = mysql_fetch_object($res)) {
		echo $row->catid."<br />";
	}
	echo "<br /><br />";
	$res = $plugin->getQueryResult('blog','all',10,'',$bname);
	while ($row = mysql_fetch_object($res)) {
		echo $row->itemid."<br />";
	}

The fields available for the categorylist lind are catid, catdesc, catname, myorder, mytemplate, myshowonmainpage, mysortcol. Where myorder is the order you set for the category, mytemplate is the template you set to use for that category, myshowonmainpage is 1 or 0 depending on how you set that category, and mysortcol is either 1 (is ordered) or 2 (is unordered).

The fields available for the blog kind are itemid, title, body, author, authorname, itime, more, authorid, authormail, authorurl, category, catid, closed, myorder, otemplate, ocnumber, mysortcol. Where myorder is the set order of the item, otemplate is the template set for that category, ocnumber is the set order of the item's category, and mysortcol is either 1 (is ordered) or 2 (is unordered).

Future Plans

Some added features under consideration, if there is interest, are the following:

Support and Bug reports

For additional support and/or bug reports please use this forum thread: http://forum.nucleuscms.org/viewtopic.php?t=14070

Version History