WWW::A9Toolbar 0.01

WWW::A9Toolbar is a class to allow perl to access the a9.com toolbar.

SYNOPSIS

use WWW::A9Toolbar;
my $a9 = WWW::A9Toolbar->new( { email => my@email.address,
password => mya9password,
connect => 1 } );
my @bookmarks = $a9->find_bookmarks({ title => qr/searchtext/ });

my $newbookmark = $a9->add_bookmark({ title => My Bookmark,
url => http://mybookmark.com,
type => url });

The WWW::A9Toolbar class implements the functions provided by the a9.com toolbar and interface. The toolbar allows a9.com users to view their a9.com bookmarks, remove and edit them. It also allows annotating of URLs via the diary entry textfield.
So far this module supports the following methods:

METHODS

new (constructor)
my $a9 = WWW::A9Toolbar->new( { email => my@email.address,
password => mya9password,
connect => 1 } );

The new constructor creates and returns a WWW::A9Toolbar object, it should be passed the a9 login credentials as a hashref. Optionally, if connect => 1 is passed to the constructor, it will also connect to the service.

connect (method)

$a9->connect();

Connect to the a9.com service, using the credentials supplied to the new constructor. Returns true on success.

customer_id (method)

my $id = $a9->customer_id();

Returns the users current customer-id, which is unique for each connection to the a9.com service.

scan_cookies (method)

$a9->scan_cookies();

Extracts the data from the cookies. Not much use at the moment.
get_userdata (method)

my $userdata = $a9->get_userdata();

Fetches the user data for this account, returns a hashref containing the users nickname, the date they agreed to the terms of use, their uniquekey and a list of columns they have set in their a9.com preferences.

get_bookmarks (method)

my @bookmarks = $a9->get_bookmarks({ since => time() - 3600 });

Returns all the bookmarks saved with a9.com. Optionally causes the module to refetch all bookmarks created since the given epoch time. The data returned is a list of hashrefs, each containing the fields:

guid - A unique ID for the bookmark
parentguid - A unique ID for the bookmarks parent folder, 0 if it is at the top level.
ordinal - A real number used for sorting the bookmarks. (99999 for deleted items)
bmtype - The item type, "folder" or "url".
title - The title of the URL or Folder.
url - The url of a url type bookmark, empty for a folder.
shortannotation - A note added to the bookmark, via the diary functions.
timestamp - The time that this bookmark was created, in miliseconds.
deleted - "true" for deleted items, "false" otherwise.

find_bookmarks (method)

my @bookmarks = $a9->find_bookmarks({ title => qr/mytitle/,
url => qr/myurl/ });
A function to filter the bookmarks, looking for items that match the given regular expressions. At least one of title or url must be supplied.

add_bookmark (method)

my $newbookmark = $a9->add_bookmark({ title => My Title,
url => http://foo.com,
type => url,
parent => $parentitem,
before => $beforeitem });

Create a new bookmark on a9.com. The completed bookmark will be returned, with the fields all filled in, as per the get_bookmarks() method. The type can be set to either "folder" or "url". The parent item should be a previousl fetched bookmark folder object. The before item should be a previously fetched bookmark object that this new bookmark will be placed before (i.e. it will get a lower ordinal, a9.com sorts its display in ascending ordinal order).

delete_bookmark (method)

$a9->delete_bookmark([$bookmark,$bookmark2]);

Sets the passed in list of bookmarks (arrayref), as deleted. Returns 1 on success, warns which items it could not delete on failure. The items passed in should be previously fetched bookmark objects.

get_diary_entries (method)

## Not implemented yet.

add_diary_entry (method)

$a9->add_diary_entry({url => http://foo.com,
text => This is the foo.com website,
title => Foo Com });

Annotate a url using the given text. The url does not have to be a bookmarked url. The annotation will be returned in the shortannotation field of the bookmark when fetched with get_bookmarks().

remove_diary_entry (method)

$a9->remove_diary_entry({ url => http://foo.com });

Remove a previously created annotation. The result of this is a redirect (302) if it succeeds, and thus is hard to check.