NAME

AmphetaDesk::MyChannels - Access and maintenance of the user's subscriptions

SYNOPSIS

    # load or import channel subscriptions.
    load_my_channels;                       # default location.
    load_my_channels("/path/to/file");      # existing OPML file.
    load_my_channels($string_with_opml);    # existing OPML string.
    import_my_channels("/path/to/file");    # add file to existing.
    import_my_channels($string_with_opml);  # add string to existing.
    save_my_channels;                       # save to default location.
    save_my_channels("/path/to/file");      # save to specified file.

    # add or delete from subscriptions.
    add_url($url);   # add a url to the user's subscriptions.
    del_url($url);   # delete a url from the user's subscriptions.

    # get or set subscription data.
    $channel_title = get_my_channels_data($url, "title");
    set_my_channels_data($url, "title", "I Am A New Title");
    update_my_channels_data($url, $parsed_channel_xml);

    # returns complete channel data, sorted by title.
    my @array = get_my_sorted_channels("title", "data"); 

    # returns a list of URLs, sorted by last downloaded.
    my @array = get_my_sorted_channels("date_downloaded", "reversed_urls");

    # random utilities.
    check_for_duplicate_url($url);                 # does it exist?
    check_for_duplicate_filename($filename);       # does it exist?
    $count = count_my_channels();                  # return totals.
    $filename = create_channel_filename($title);   # create filename.
    download_my_channels();                        # get new data.
    remove_old_channel_files();                    # delete leftovers.

DESCRIPTION

This package is probably the most important - it carries all of the various functions that are used to create and interact with the user's subscription list (which is stored in OPML format - see an example below). By default, the subscription list defaults to a number of standard entries, but this is constantly tweaked and modified as AmphetaDesk usage continues.

A default OPML file looks similar to:

   <?xml version="1.0"?>
   <opml>
     <body>

       <outline description="Lengthy description here."
                title="Reuters Health eLine"
                filename="reutershealtheline.xml"
                xmlurl="http://www.reutershealth.com/eline.rss"
                htmlurl="http://www.reutershealth.com"
                date_downloaded="2003-04-22 09:12:23"
                date_added="2002-03-01 00:00:00"
                email="editor@reutershealth.com" />

       <outline description="Lengthy description here."
                title="ResearchBuzz"
                filename="researchbuzz.xml"
                xmlurl="http://www.researchbuzz.com/researchbuzz.rss"
                htmlurl="http://www.researchbuzz.com"
                date_downloaded="2003-04-21 20:18:02"
                date_added="2002-03-01 00:00:00"
                email="" />

     </body>
   </opml>

Each channel subscription gets one outline element, with an unlimited set of attributes - the entries you see above are what AmphetaDesk reads and supports natively. Realize, however, that if AmphetaDesk imports another OPML file that has attributes not defined above, AmphetaDesk will do its best to keep those attributes around forever and without modification. This facilitates interoperability, as well as enhances the control of plugins to add new per-channel metadata.

METHODS

add_url($url): This routine downloads the passed $url and creates an entry for the user's subscription file based on the data it sees within. After saving the RSS file, it saves the subscription list immediately. Returns 1, as we don't properly do anything when there's a failure. Multiple urls can be specified if they are seperated by ",http://" or a newline.

check_for_duplicate_filename($filename)
check_for_duplicate_url($url): These routines merely check to see if the $filename or $url already exist in the currently subscribed channels. If so, we return happily with a 1. If not, then we return 0, suggesting that it's a-ok to proceed.

count_my_channels: This routine counts the number of channels currently subscribed and returns the result. No muss, no fuss. Wheeeeee. My comments own j00.

create_channel_filename($title): This routine looks at $title and creates a semi-unique filename, chalking on ".xml" to the end, and returns the creation. It checks for duplicates with check_for_duplicate_filename, and if that filename already exist, it'll append a random 4 digit number to the filename it returns.

del_url($url): This routine takes a look at the passed channel url and sees if there is a matching one in our in memory subscription list. If there is, then we delete that one out of there, and resave our channels file. Multiple urls can be specified if they are seperated by ",http://" or a newline. This routine always returns 1, since we don't properly inform about non-existence.

download_my_channels: This routine takes a look at our loaded subscription list and downloads each one to our local storage directory, assuming it meets a number of time-based prerequisities. It will sort the subscriptions by oldest modified channel before downloading (which has very little benefit whatsoever). This routine always returns happily.

get_my_channels_data($url, "title")
set_my_channels_data($url, "title", "A New Title"): These routines get or set values associated with a subscription's RSS URL. get_setting accepts the RSS URL and the name of the attribute who's value you want. If the setting exists, the value is returned. If it doesn't, undef is returned instead. set_my_channels_data accepts three inputs, the first being the RSS URL of the subscription you want to change, then the attribute you want to change, and finally, the value you want to change the attribute to. Upon successful completion, set_ returns the value you pass it.

get_my_sorted_channels("sort_by", "type_of_data_returned"): This routine goes through our currently stored subscription list in and returns an array based on how the data should be sorted as well as how the data is returned. Sorting can be done on ANY attribute stored in the OPML file, and the returned array could be sorted normally or reversed, and could contain either URLs of the channels, or hashes of the data for the specific channel. Some examples of use:

load_my_channels
import_my_channels: This routine reads the passed info (which could be NULL, a $filepath, or a $string containing OPML data). If a null is passed to load_, we'll use the default location of the myChannels.opml. A file path or string will be loaded/merged into the current in-memory representation of the user's subscriptions, and then a modified subscription list will be written to disk. This routine always returns 1.

remove_old_channel_files: A clean up routine run at the beginning of each Ampheta start that will remove any extra files that are no longer needed (channels, etc.). This really shouldn't be necessary anymore, but can occur with third party modification of the myChannels.opml without regard for deleting orphaned / stored channel data. Returns 0 if the directory can't be opened, or 1 if everything went just peachy.

save_my_channels: This routine merely takes the current in memory subscription list, extracts the channel information that should be saved, and then dumps it to the data directory (or a passed $filepath). Returns 1 if the save went dandy, and 0 if it didn't.

update_my_channels_data($url, $parsed_xml_data): This routine looks at the $parsed_xml_data and uses it to update the OPML information for our passed $url. This routine is typically called with the data returned from a load_my_channel routine (which indicates a successful parse). Incidentally, this is called for every successful parse that we do, so that we'll always have the latest info in our subscription list. Returns 0 if the $url can't be found, and 1 for everything else.

AUTHOR

Morbus Iff, <morbus@disobey.com>

COPYRIGHT AND LICENSE