DESCRIPTION

This module provides a basic framework for creating and maintaining RDF Site Summary (RSS) files. This distribution also contains many examples that allow you to generate HTML from an RSS, convert between 0.9, 0.91, and 1.0 version, and other nifty things. This might be helpful if you want to include news feeds on your Web site from sources like Slashdot and Freshmeat or if you want to syndicate your own content.

XML::RSS currently supports 0.9, 0.91, and 1.0 versions of RSS. See http://backend.userland.com/rss091 for information on RSS 0.91. See http://www.purplepages.ie/RSS/netscape/rss0.90.html for RSS 0.9. See http://web.resource.org/rss/1.0/ for RSS 1.0.

RSS was originally developed by Netscape as the format for Netscape Netcenter channels, however, many Web sites have since adopted it as a simple syndication format. With the advent of RSS 1.0, users are now able to syndication many different kinds of content including news headlines, threaded messages, products catalogs, etc.

METHODS

Constructor for XML::RSS. It returns a reference to an XML::RSS object. You may also pass the RSS version and the XML encoding to use. The default version is 1.0. The default encoding is UTF-8. You may also specify the output format regardless of the input version. This comes in handy when you want to convert RSS between versions. The XML::RSS modules will convert between any of the formats. If you set <encode_output> XML::RSS will make sure to encode any entities in generated RSS. This is now on by default.

You can also pass an optional URL to an XSL stylesheet that can be used to output an <?xsl-stylesheet ... ?> meta-tag in the header that will allow some browsers to render the RSS file as HTML.

You can also set encode_cb to a reference to a subroutine that will encode the output in a custom way. This subroutine accepts two parameters: a reference to the XML::RSS::Private::Output::Base-derived object (which should normally not concern you) and the text to encode. It should return the text to encode. If not set, then the module will encode using its custom encoding routine.

xml:base will set an xml:base property as per

http://www.w3.org/TR/xmlbase/

Note that in order to encode properly, you need to handle "CDATA" sections properly. Look at XML::RSS::Private::Output::Base's _default_encode() method for how to do it properly.

Channel information is required in RSS. The title cannot be more the 40 characters, the link 500, and the description 500 when outputting RSS 0.9. title, link, and description, are required for RSS 1.0. language is required for RSS 0.91. The other parameters are optional for RSS 0.91 and 1.0.

To retrieve the values of the channel, pass the name of the value (title, link, or description) as the first and only argument like so:

Adding an image is not required. url is the URL of the image, link is the URL the image is linked to. title, url, and link parameters are required if you are going to use an image in your RSS file. The remaining image elements are used in RSS 0.91 or optionally imported into RSS 1.0 via the rss091 namespace.

The method for retrieving the values for the image is the same as it is for channel().

parse ($string, \%options)

Parses an RDF Site Summary which is passed into parse() as the first parameter. Returns the instance of the object so one can say $rss->parse($string)->other_method().

See the add_module() method for instructions on automatically adding modules as a string is parsed.

%options is a list of options that specify how parsing is to be done. The available options are:

allow_multiple

Takes an array ref of names which indicates which elements should be allowed to have multiple occurrences. So, for example, to parse feeds with multiple enclosures

$rss->parse($xml, { allow_multiple => ['enclosure'] });

hashrefs_instead_of_strings

If true, then some items (so far "description") will become hash-references instead of strings (with a content key containing their content , if they have XML attributes. Without this key, the attributes will be ignored and there will only be a string. Thus, specifying this option may break compatibility.

modules_as_arrays

This option when true, will parse the modules key-value-pairs as an arrayref of { el => $key_name, value => $value, } hash-refs to gracefully handle duplicate items (see below). It will not affect the known modules such as dc ("Dublin Core").

parsefile ($file, \%options)

Same as parse() except it parses a file rather than a string.

See the add_module() method for instructions on automatically adding modules as a string is parsed.

save ($file)

Saves the RSS to a specified file.

skipDays (day => $day)

Populates the skipDays element with the day $day.

skipHours (hour => $hour)

Populates the skipHours element, with the hour $hour.

strict ($boolean)

If it's set to 1, it will adhere to the lengths as specified by Netscape Netcenter requirements. It's set to 0 by default. Use it if the RSS file you're generating is for Netcenter. strict will only work for RSS 0.9 and 0.91. Do not use it for RSS 1.0.

This RSS element is also optional. Using it allows users to submit a Query to a program on a Web server via an HTML form. name is the HTML form name and link is the URL to the program. Content is submitted using the GET method.

Access to the textinput values is the same as channel() and image().

add_module(prefix=>$prefix, uri=>$uri)

Adds a module namespace declaration to the XML::RSS object, allowing you to add modularity outside of the standard RSS 1.0 modules. At present, the standard modules Dublin Core (dc) and Syndication (syn) are predefined for your convenience. The Taxonomy (taxo) module is also internally supported.

The modules are stored in the hash %{$obj->{'modules'}} where $obj is a reference to an XML::RSS object.

If you want to automatically add modules that the parser finds in namespaces, set the $XML::RSS::AUTO_ADD variable to a true value. By default the value is false. (N.B. AUTO_ADD only updates the %{$obj->{'modules'}} hash. It does not provide the other benefits of using add_module.)

Adding items from these modules in XML::RSS is as simple as adding other attributes such as title, link, and description. The only difference is the compartmentalization of their key/value paris in a second-level hash.

For elements of the Dublin Core module, use the key 'dc'. For elements of the Syndication module, 'syn'. For elements of the Taxonomy module, 'taxo'. These are the prefixes used in the RSS XML document itself. They are associated with appropriate URI-based namespaces:

Dublin Core elements may occur in channel, image, item(s), and textinput -- albeit uncomming to find them under image and textinput. Syndication elements are limited to the channel element. Taxonomy elements can occur in the channel or item elements.

Access to module elements after parsing an RSS 1.0 document using XML::RSS is via either the prefix or namespace URI for your convenience.

XML::RSS also has support for "non-standard" RSS 1.0 modularization at the channel, image, item, and textinput levels. Parsing an RSS document grabs any elements of other namespaces which might appear. XML::RSS also allows the inclusion of arbitrary namespaces and associated elements when building RSS documents.

For example, to add elements of a made-up "My" module, first declare the namespace by associating a prefix with a URI: