Jared Quinn

IT Consulting :: Design :: Events Management

subList - List Child Pages

Name: subList
Version: 3.1
License: GPL

Adds a post tag that lists the subpages below a specific page, allowing pages to include summaries of other pages. It features many options including recursive listing, customisable formatting, arbitary starting page and pre/post text to add.

Based on “List Subpages v1.0″ by Rob Miller, “SubList” takes Rob’s plugin one step further and introduces functionality I wanted for driving the dynamic indexes on this site.

Comments, Questions, Queries and Suggestions should all be made as comments on the “Download” page for the version you are currently using. It is recommended that you upgrade to the latest version before reporting any issues.

Installation Instructions

  • Install the plugin by placing it in your wp-content/plugins directory.
  • Activate the plugin in the Plugins section of the WordPress admin panel
  • Insert an appropriate tag into the page where you want the sublist to appear.

Upgrade Instructions

  • Replace the sublist.php script with the latest copy.
  • Upgrading to versions 2.3 and above, users may wish to enable compatibility mode so the old syntax of <!–subpages–> will continue to work.
  • If upgrading from version 3.0 change references to “sibList” to “subList” and use the start=”parent” option. The sibList calls were implemented in 3.0 but not kept.

Invoking the Plugin

Embedding inside a post/page

HTML Code can be inserted into your page or post (or anywhere else that is considered ‘the_content’) to invoke the Plugin; e.g.:

<sublist recurse=“on” />

or

<sublist recurse=“on” start=“parent”>formatstring</sublist>

Calling the plugin from Templates

When the plugin is used within a template or other php code, it can be called using the following php:

sublist(optionarray, bool);

Example:

subList( array(  format => ‘<li><a href="%link%" title="%title">%title</a></li>’,
                         start => “current” ), true );

To list page siblings, the following example can be used:

subList( array(  format=> ‘<li><a href="%link%" title="%title">%title</a></li>’,
                         start => “parent” ), true );

Compatibility Mode

The plugin by default, operates in compatibility mode1. This can be disabled by setting the SUBLIST_COMPATIBILITY_MODE definition to 0. You will want to disable this setting if you use subList alongside the original List Subpages plugin.

To invoke the plugin in compatibility mode, you can use the following syntax:

<!–subpages options–>
  • sibList is not supported in “compatibility” mode.
  • You cannot use compatibility mode in a template or other php code.

Options

The available options are:

  • pretext=”text” - text to prepend part of the list (defaults to <UL>)
  • posttext=”text” - text to postpent part of the list (defaults to <UL>)
  • notext=”text” - text to display if no sub/sibling pages are found by the plugin.
  • recurse=”on|off” - recurse multiple levels (defaults to ON). Not available in compatibility mode. (see below)
  • format=”format” - format string for formatting the list of sub pages (see below).
  • start = “current|parent|#” - specify the location to start from. Parent will start from the current page parent, current from the current page or an integer to specify a particular page number.



The following options are only available using compatibility mode:

  • no-recurse - deprecated, use recurse=”off”.

Format String

The format specification can include any HTML and the following tags:

  • %id% - post ID
  • %link% - permalink to the post
  • %title% - title of the post
  • %excerpt% - the excerpt of the post

Example:

<sublist start=“parent”>
  <li><a href=“%link%” title=“%title%”>%title%</a><br/>%excerpt%<br/></li>
</sublist>

Caveat

When this plugin is used in “compatibility mode” it may cause unexpected behaviour when Rob’s original “List SubPages” plugin is also installed. The new tagging system was introduced in version 2.3 to allow both plugins to co-exist peacefully.

History

  • Version 3.1
    • Dropped support for new tag “sibList” and function sibList in favour of using “subList” with a start=”parent” option (performs same function).
    • Added support for “notext” option to specify text to display when no matching pages are returned (thanks once again to Arun Kale for the suggestion).
  • Version 3.0
    • Added support for listing page siblings, thanks to a suggestion from Arun Kale.
    • Added new tag “sibList” as a method for invoking a default of listing sibling pages.
    • Added support for the start option.
  • Version 2.4
    • Fixed issues using new style tags where they were not correctly working on some formatting of the tag.
    • Fixed issue where draft and attachments where being displayed by the plugin when they shouldn’t have been.

Download

Footnotes

  1. Note: sibList is not supported in compatibility mode [↩]