NAME

WWW::A9Toolbar - A class to allow perl to access the a9.com toolbar.

VERSION

This documentation refers to version 0.01.

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' });

DESCRIPTION

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 it's 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.

DEPENDENCIES

Modules used, version dependencies, core yes/no

WWW::Mechanize

WWW::Mechanize::FormFiller

URI

URI::URL

URI::QueryParam

Net::DNS

XML::Simple

NOTES

Usage of this module implies an acceptance of the www.a9.com Terms Of Use.

TODO

Still missing are the search and search history functionality, fetching all diary entries, and fetching siteinfo data.

The hashrefs returned as bookmark "objects" could probably be more objectlike.

BUGS AND LIMITATIONS

None known currently, please email the author if you find any

AUTHOR

Jess Robinson castaway@desert-island.m.isar.de

LICENCE AND COPYRIGHT

Copyright (c) 2005, Jess Robinson castaway@desert-island.m.isar.de. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

cpanm WWW::A9Toolbar

perl -MCPAN -e shell
install WWW::A9Toolbar