Difference between revisions of "PLG getItemInfo"
(Started documenting the proposed extensions) |
m (quick definition of "property") |
||
Line 14: | Line 14: | ||
* <code>$type</code> 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. | * <code>$type</code> 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. | ||
* <code>$id</code> is the ID of the item we are requesting information about, e.g. the story ID (sid), link ID (lid), etc. | * <code>$id</code> is the ID of the item we are requesting information about, e.g. the story ID (sid), link ID (lid), etc. | ||
− | * <code>$what</code> is a comma-separated list of keywords indicating the information we are requesting for the specified item.<br>Currently, the following keywords are supported: | + | * <code>$what</code> 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.<br>Currently, the following keywords are supported: |
** 'url' - the complete URL of the item | ** 'url' - the complete URL of the item | ||
** 'title' - the item's title or subject | ** 'title' - the item's title or subject |
Revision as of 10:30, 10 December 2008
Contents
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' ) )