Revision as of 10:30, 10 December 2008

Introduction

PLG_getItemInfo was introduced in Geeklog 1.4.0. It is used internally as part of the implementation of Trackbacks and Pingbacks.

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.1:

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 keywords are supported:
  • '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.

Proposed API Extension

The idea behind this proposed extension of the API 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 outlines below.

The proposed new API would look like this:

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

User ID ($uid)

Currently, the API does not allow for access control. With the proposed $uid parameter, it would be possible to request items that are only visible to a specific user.

• Default: $uid == 0 should be handled as if no access control is required. This is for backward-compatibility with the current implementation.
• For a $uid > 0, only items that are accessible to that user should be returned.

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.

Options ($options)

TBD

Return values

When returning more than one entry, the return value is supposed to be an array of arrays. The properties should be returned using PHP's associative arrays using key/value pairs instead of relying on the order or properties. Properties that are not supported 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'
    )
)