MyStuff plugin (0.2)

(c)2004 Matt Burns <http://www.matt.blis.co.uk>

How to use the MyStuff plugin for WordPress 1.2
===============================================



Installation
============

Read INSTALL.txt supplied with this archive.



Getting started
===============

A basic usage of the MyStuff plugin could look something like this:

<?php
// create a 'my_stuff' instance
$my_stuff = new my_stuff();
// OPTIONAL - set-up a referrer link
$my_stuff->set_link_referrer('www.amazon.co.uk','affiliate_no');
// add the categories I want to display (function call still to be
// documented)
$my_stuff->add_stuff('books', 'Currently Reading:', false, 5);
$my_stuff->add_stuff('books', 'Recently Read:', true, 5);
$my_stuff->add_stuff('music', 'Listening To:');
$my_stuff->add_stuff('films', 'Recently Watched:');
// display my stuff!
$my_stuff->display();
?>

Check further down for more details and explanations on the parameters
passed to each of these methods in the section 'my_stuff class API'.



my_stuff class API
==================

The my_stuff class API has 6 methods:

 * my_stuff::add_stuff($category, $label, $complete, $limit)
 * my_stuff::set_list_type($list)
 * my_stuff::set_title_element($element)
 * my_stuff::set_limit($limit)
 * my_stuff::display()
 * my_stuff::set_link_referrer($referrer_site, $referrer_id)

The following methods are deprecated:
 * my_stuff::set_amazon_id($affiliate_id, $affiliate_site)
   Use my_stuff::set_link_referrer() instead



add_stuff($category, $label[[, $complete], $limit])
-----------------------------------------------

The my_stuff::add_stuff() method defines the order and appearance of
the groups of items that appear in the My Stuff lists.

$category (string):
  Matches one of the categories in the database.

$label (string):
  A label bound to the individual list.

$complete (boolean | NULL):
  If this is true, will only display items marked as complete in
  the category.
  If this is false, will only display items not marked as complete
  in the category.
  If this is null, will display *all* items in the category, regardless
  if they are complete or not.
  Default is NULL.

$limit (integer):
  Limits the number of items to display (ordered by date added).
  Default is 10.

e.g. the code:

$my_stuff->add_stuff("books", "Books I've Yet To Read:", false, 10);

will create a list of your stuff (maximum of 10 items) in the "books" category
with a label of "Books I've Yet To Read" where those items don't have the
completed option checked.

$my_stuff->add_stuff("restaurants", "Restaurants:", null, 5);

will create a list of the last 5 items in the "restaurants" category, whether they are marked as "completed" (visited) or not (yet to visit).


set_list_type($list)
--------------------

Sets the list format.

$list (string):
  "ul":
    display lists as unordered lists
  "ol":
    display lists as ordered lists
  "div":
    display lists as div elements

set_title_element($element)
---------------------------

Defines the HTML element used as the header of a list.

$element ($string):
  The HTML element (without angle brackets/chevrons)
  (e.g. "h2") to use as the header for a list.


set_limit()
-----------------

The my_stuff::set_limit() sets a global limit to the number of
entries in each list.

$limit (integer):
  Limits the number of items to display (ordered by date added).
  Default is 10.


display()
---------

The my_stuff::display() method should be called last, and triggers the
display of the lists.



set_amazon_id($affiliate_id, $affiliate_site)
---------------------------------------------

THIS METHOD IS DEPRECATED, USE set_link_referrer() instead

THIS METHOD MAY BE REMOVED FROM FUTURE VERSIONS

MyStuff can provide links to the amazon.co.uk (currently untested
with other amazon sites) site.  If you have an Amazon affiliate/
associate ID, you can also use this to promote traffic through your
account.

$affiliate_id (string):
  Your amazon.co.uk (or other) affiliate/associate ID.  Replace with ""
  if you don't have one, and just want to provide links.

$affiliate_id (string):
  The Amazon site you want to use as the link target.  Use the domain
  name only (e.g. "amazon.co.uk") don't enter "http://" or "www." or
  a trailing slash.

Note: links to amazon.co.uk will only work if the affilate site AND
      the ASIN/ISBN is set.



Ideas for Your Own Stuff
========================

You can use this to maintain a list of anything and everything that you
want to keep track of, e.g.:

 * Books (read/unread)
 * CDs that are in your current rotation
 * Movies you've seen recently
 * Things to do/have done
 * Places to go
 * Cigarettes smoked (if you're trying to quit like me)
 * Coffees drunk (if you're trying to cut down)
 * Carbs eaten (if you're on a low-carb diet)

I'm sure you can think up loads of other stuff to add!



Known Limitations:
==================

 * only tested with amazon.co.uk, other amazon or affiliate sites
   may or may not work as-is.
 * Amazon sites must be in the form "www.amazon.co.uk"



Stuff To Do:
============

 * Add descriptions for the links (for more information)
 * JavaScript export for inserting into other sites (e.g. LiveJournal)
 * Test this with other Amazon sites
 * Do a sanity check on referred URLs just in case they contain
   "http://" or "www" or a trailing slash.
 * Add other (known) affiliate systems (suggestions welcome)

Other ideas are welcome, although I can't guarantee I'll add them!



Bug Reports, Usage and Other Comments
=====================================

If you find a bug, begin using this plugin, have difficulty installing
or using the plugin or have any other comment, I'd be happy to hear
from you.  Feel free to leave a comment on my WordPress blog:

http://www.matt.blis.co.uk/archives/category/programming/plugins/my-stuff/

Happy listing!

Matt