Update README.md to include Plugin Documentation

README.md

@@ -40,6 +40,81 @@ LifePress can import items from your feeds either through Pseudo Cron (default)
 5. Copy your .htaccess, config.php and database.php and themes files back in.
 6. Quickly check in case there have been any changes to the above 3 files since last upgrade.
 
+## Plugins
+
+Plugins improve how LifePress imports data from different websites. LifePress is pretty good at automatically detecting images, video and tags, but when it can't a plugin can often fix that. Plugins are in `application/plugins`.
+
+There are two "hooks" - functions where we can manipulate feed data:
+
+* At import using `pre_db()` - before the item is put into the database.
+* At display using `pre_display()` - before the item is rendered in a user's browser.
+
+It's best to make your changes in `pre_display()` when possible, because `pre_db()` makes permanent changes to the data as it gets stored to the db. At import is suitable for making tweaks to data that we know we want to be permanent, like stripping out unwanted data, or setting certain items to "draft" status. At display is suitable for simple tweaks to the available data, like the youtube plugin setting `$item->item_data['video']` based on the youtube link in the item. 
+
+### Creating a plugin
+
+Plugin file names must be the website's url for the feed it was built for, replacing periods with an underscore. E.g. youtube.com plugin is `youtube_com.php`.
+
+```
+<?php if (!defined('BASEPATH')) exit('No direct script access allowed');
+
+class Youtube_com {
+  function pre_db($item)
+  {
+    $item->item_status = 'draft';
+    return $item;
+  }
+  
+  function pre_display($item)
+  {
+    $item->item_data['video'] = '<iframe width="640" height="360" src="' . $item->item_data['permalink'] . '"></iframe>';
+    return $item;
+  }
+}
+?>
+```
+
+Available item attributes are:
+
+```
+$item->item_status //status of item. "publish" by default, you can set to "draft"
+$item->item_date  //date of the item in unix timestamp
+$item->item_title //title of the item
+$item->item_permalink //permalink back to the origin of the item
+$item->item_content = //content of the item
+$item->item_name = //url-safe name of the item, created from the item title
+```
+
+#### Storing Custom Data
+
+Item objects also feature an `$item->item_data` array.  This can be used to store custom values.  It contains extra data about the item so be careful you do not overwrite anything you might want later.  Existing `item_data` values are:
+
+```
+$item->item_data['title'] //raw title before it was cleaned for $item->item_title
+$item->item_data['permalink'] //raw permalink of item
+$item->item_data['content'] //raw content
+$item->item_data['enclosures'] //data found in the item's rss "enclosure" section
+$item->item_data['categories'] //data found in the item's rss "categories" section  
+$item->item_data['tags'] //tags LifePress was able to associate with the item  
+$item->item_data['image'] //image that LifePress was able to associate with the item
+```
+
+You can store completely custom data by simply adding to the `item_data` array:
+
+```
+$item->item_data['foo'] = 'bar';
+```
+
+#### Easily Access Media In Your Themes
+
+LifePress' theme API has three functions for getting media:
+
+```
+$item->get_image()
+$item->get_video()
+$item->get_audio()
+```
+
 ## Contribute/Issues
 
 If you find a bug in LifePress please file an Issue. Make sure there isn't already an issue for that bug. Before you create a pull request please file an issue so the community can discuss the fix/enhancement and this way if the bug has already been fixed or is not plausible your not wasting your time.