Revision as of 15:28, 1 June 2009

Introduction

PLG_getItemInfo was introduced in Geeklog 1.4.0 and used internally as part of the implementation of Trackbacks and Pingbacks. The API was extended in Geeklog 1.6.0 for use by the XMLSitemap Plugin.

The basic idea for this function is to request information for an item that is under a plugin's control (where, in this case, the list of "plugins" also includes Geeklog's built-in articles).

Original API

The API, as implemented in Geeklog versions 1.4.0 - 1.5.2:

function PLG_getItemInfo($type, $id, $what)

• $type is the type of plugin we want to request information from. This is the internal name of the plugin, e.g. 'links' for the Links plugin. Additionally, 'article' can be used to request information for stories.
• $id is the ID of the item we are requesting information about, e.g. the story ID (sid), link ID (lid), etc.
• $what is a comma-separated list of keywords indicating the information we are requesting for the specified item. We will call these key/value pairs properties from now on.
  Currently, the following properties are defined:
  • 'url' - the complete URL of the item
  • 'title' - the item's title or subject
  • 'excerpt' - a short description of the item
  • 'description' - the full description of the item, e.g. the article text

The function returns an array of strings of the requested information, in the order defined by the $what parameter, e.g. for

PLG_getItemInfo('article', 'welcome', 'url,title');

it would return information about the default story on a fresh install of Geeklog:

array('http://www.example.com/article.php/welcome', 'Welcome to Geeklog!');

For properties not supported by the plugin, an empty string will be returned.

Extended API

The idea behind this extended API (as of Geeklog 1.6.0) is to allow Geeklog and other plugins to request a list of items and information about those items at the same time. The extensions are designed to be backward-compatible, as outlined below.

function PLG_getItemInfo($type, $id, $what, $uid = 0, $options = array())

Plugin type ($type)

This includes 'article' for stories.

Item ID ($id)

When requesting information for more than one item, the $id parameter is not needed. In this case, it should be set to '*' (a single asterisk character). This indicates to the plugin, that information for more than one item is requested.

Which properties ($what)

A comma-separated list of item properties.

User ID ($uid)

The original API did not allow for access control. All operations were performed with the access control of the current user. With the $uid parameter, it is now possible to request items that are only visible to a specific user.

• Default: $uid == 0 - use the permissions of the current user. This is for backward-compatibility with the original API.
• For a $uid > 0, only items that are accessible to that user should be returned.

Options ($options)

reserved for future extensions

Return values

When returning more than one entry, the return value is supposed to be an array of arrays (even if it only contains one entry). The properties should be returned using PHP's associative arrays using key/value pairs instead of relying on the order of properties. Properties that are not supported or available will not be set in the returned arrays, e.g. for $what = 'url,something-unknown,title':

array(
    array(
        'url' => 'http://www.example.com/article.php/welcome',
        'title' => 'Welcome to Geeklog!'
    ),
    array(
        'url' => 'http://www.example.com/article.php/about',
        'title' => 'About this site'
    )
)

Additional properties

• 'id' - an item's ID. Obviously, when requesting information about more than one item, we also need the IDs of those items to tell them apart.
• 'date-created' - date when the item was created, as a Unix timestamp.
• 'date-modified' - date when the item was last modified, as a Unix timestamp.

Note: Plugins that only have one of either 'date-created' or 'date-modified' should only return that information (i.e. do not return a modified date when it's really the item's creation date). Plugins that do not keep any date information should, obviously, not return any either.

Unknown properties should be silently ignored. This will allow for future extensions as well as for using properties that are only supported by some plugins.