PLG getItemInfo - Revision history

LWC: /* Additional properties */ =

2009-06-01T15:28:41Z

‎Additional properties: =

LWC: Deleted linebreaks and fixed order and added others

2009-06-01T15:28:07Z

Deleted linebreaks and fixed order and added others

Dirk: The plugin is now official - updated text to reflect that (no change in the actual API)

2009-05-31T19:00:34Z

The plugin is now official - updated text to reflect that (no change in the actual API)

Dirk: Added category

2009-02-05T16:18:40Z

Added category

Dirk: Corrected description of $uid = 0 and its current behavior

2008-12-22T15:17:12Z

Corrected description of $uid = 0 and its current behavior

Dirk: Additional properties

2008-12-10T11:54:58Z

Additional properties

Dirk: quick definition of "property"

2008-12-10T10:30:14Z

quick definition of "property"

Dirk: Started documenting the proposed extensions

2008-12-10T10:19:46Z

Started documenting the proposed extensions

Dirk: Started documentation of PLG_getItemInfo

2008-12-10T09:46:38Z

Started documentation of PLG_getItemInfo

New page

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

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 version 1.4.0-1.5.1:

<code>function PLG_getItemInfo($type, $id, $what)</code>

* <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>$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:
** '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

@@ Line 66: / Line 66: @@
 )</pre>
-== Additional properties ==
+=== 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.

@@ Line 4: / Line 4: @@
 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 =
@@ Line 25: / Line 24: @@
 <pre>array('http://www.example.com/article.php/welcome', 'Welcome to Geeklog!');</pre>
 For properties not supported by the plugin, an empty string will be returned.
 = Extended API =
@@ Line 32: / Line 30: @@
 <pre>function PLG_getItemInfo($type, $id, $what, $uid = 0, $options = array())</pre>
 == User ID ($uid) ==
@@ Line 39: / Line 47: @@
 * 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.
 == Options ($options) ==
@@ Line 71: / Line 75: @@
 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]]

@@ Line 1: / Line 1: @@
 = 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).
@@ Line 8: / Line 8: @@
 = 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>
@@ Line 27: / Line 27: @@
-= Proposed API Extension =
+= Extended API =
-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 outlined below.
+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>
@@ Line 37: / Line 35: @@
 == User ID ($uid) ==
-Currently, the API does not allow for access control. All operations are performed with the access control of the current user. 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> - use the permissions of the current user. 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.

← Older revision		Revision as of 16:18, 5 February 2009
Line 73:		Line 73:

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

@@ Line 37: / Line 37: @@
 == 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.
+Currently, the API does not allow for access control. All operations are performed with the access control of the current user. With the proposed $uid parameter, it would be 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 current implementation.
 * For a <code>$uid > 0</code>, only items that are accessible to that user should be returned.

@@ 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>$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. We will call these key/value pairs ''properties'' from now on.<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
 ** 'title' - the item's title or subject
@@ Line 29: / Line 29: @@
 = 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 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 outlined below.
 The proposed new API would look like this:
@@ Line 48: / Line 48: @@
 == Options ($options) ==
-''TBD''
+''reserved for future extensions''
 == 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(
      array(
@@ Line 63: / Line 63: @@
+     )
 )</pre>