Difference between revisions of "PLG getItemInfo"

From GeeklogWiki
Jump to: navigation, search
(Started documenting the proposed extensions)
m (Additional properties: =)
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
= Introduction =
 
= Introduction =
  
<code>PLG_getItemInfo</code> was introduced in Geeklog 1.4.0. It is used internally as part of the implementation of Trackbacks and Pingbacks.
+
<code>PLG_getItemInfo</code> was introduced in Geeklog 1.4.0 and used internally as part of the implementation of Trackbacks and Pingbacks. The API was [[#Extended_API|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).
 
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 =
 
= Original API =
  
The API, as implemented in Geeklog versions 1.4.0 - 1.5.1:
+
The API, as implemented in Geeklog versions 1.4.0 - 1.5.2:
  
 
<pre>function PLG_getItemInfo($type, $id, $what)</pre>
 
<pre>function PLG_getItemInfo($type, $id, $what)</pre>
Line 14: Line 13:
 
* <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 properties are defined:
 
** '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
Line 26: Line 25:
 
For properties not supported by the plugin, an empty string will be returned.
 
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.
 +
 +
<pre>function PLG_getItemInfo($type, $id, $what, $uid = 0, $options = array())</pre>
  
= Proposed API Extension =
+
== Plugin type ($type) ==
 +
This includes 'article' for stories.
  
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.
+
== Item ID ($id) ==
  
The proposed new API would look like this:
+
When requesting information for more than one item, the <code>$id</code> parameter is not needed. In this case, it should be set to <tt>'*'</tt> (a single asterisk character). This indicates to the plugin, that information for more than one item is requested.
  
<pre>function PLG_getItemInfo($type, $id, $what, $uid = 0, $options = array())</pre>
+
==Which properties ($what)==
 +
A comma-separated list of item properties.
  
 
== User ID ($uid) ==
 
== 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.
+
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: <code>$uid == 0</code> should be handled as if no access control is required. This is for backward-compatibility with the current implementation.
+
* Default: <code>$uid == 0</code> - use the permissions of the current user. This is for backward-compatibility with the original API.
 
* For a <code>$uid > 0</code>, only items that are accessible to that user should be returned.
 
* For a <code>$uid > 0</code>, only items that are accessible to that user should be returned.
 
== Item ID ($id) ==
 
 
When requesting information for more than one item, the <code>$id</code> parameter is not needed. In this case, it should be set to <tt>'*'</tt> (a single asterisk character). This indicates to the plugin, that information for more than one item is requested.
 
  
 
== Options ($options) ==
 
== Options ($options) ==
  
''TBD''
+
''reserved for future extensions''
  
 
== Return values ==
 
== 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 <code>$what = 'url,something-unknown,title'</code>:
+
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 <code>$what = 'url,something-unknown,title'</code>:
 
<pre>array(
 
<pre>array(
 
     array(
 
     array(
Line 63: Line 65:
 
     )
 
     )
 
)</pre>
 
)</pre>
 +
 +
=== 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.
 +
 +
[[Category:Plugin Development]]

Latest 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.