/ 
XML-Loy-0.04
River stage one • 4 direct dependents • 4 total dependents
/ XML::Loy::Atom

NAME

XML::Loy::Atom - Atom Syndication Format Extension

SYNOPSIS

# Create new Atom feed
my $feed = XML::Loy::Atom->new('feed');

# Add new author
$feed->author(
  name => 'Sheldon Cooper',
  uri => 'https://en.wikipedia.org/wiki/Sheldon_Cooper'
);

# Set title
$feed->title('Bazinga!');

# Set current time for publishing
$feed->published(time);

# Add new entry
my $entry = $feed->entry(id => 'first');

for ($entry) {
  $_->title('Welcome');
  $_->summary('My first post');

  # Add content
  my $content = $_->content(
    xhtml => '<p>First para</p>'
  );

  # Use XML::Loy methods
  $content->add(p => 'Second para')
          ->comment('My second paragraph');
};

# Get summary of first entry
print $feed->entry('first')->summary->all_text;
# My first post

# Pretty print
print $feed->to_pretty_xml;

# <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
# <feed xmlns="http://www.w3.org/2005/Atom">
#   <author>
#     <name>Sheldon Cooper</name>
#     <uri>https://en.wikipedia.org/wiki/Sheldon_Cooper</uri>
#   </author>
#   <title xml:space="preserve">Bazinga!</title>
#   <published>2013-03-07T17:51:25Z</published>
#   <entry xml:id="first">
#     <id>first</id>
#     <title xml:space="preserve">Welcome</title>
#     <summary xml:space="preserve">My first post</summary>
#     <div xmlns="http://www.w3.org/1999/xhtml">
#       <p>First para</p>
#
#       <!-- My second paragraph -->
#       <p>Second para</p>
#     </div>
#   </entry>
# </feed>

DESCRIPTION

XML::Loy::Atom is a base class or extension for XML::Loy and provides several functions for the work with the Atom Syndication Format as described in RFC4287.

This code may help you to create your own XML::Loy extensions.

This module is an early release! There may be significant changes in the future.

METHODS

XML::Loy::Atom inherits all methods from XML::Loy and implements the following new ones.

new_person

my $person = $atom->new_person(
  name => 'Bender',
  uri  => 'acct:bender@example.org'
);

Returns a new person construction. Accepts a hash with element descriptions.

new_text

my $text = $atom->new_text('This is a test');
my $text = $atom->new_text( xhtml => 'This is a <strong>test</strong>!');
my $text = $atom->new_text(
  type    => 'xhtml',
  content => 'This is a <strong>test</strong>!'
);

Creates a new text construct. Accepts either a simple string (of type text), a tupel with the first argument being the media type and the second argument being the content, or a hash with the parameters type, content or src (and others). There are three predefined type values:

  • text for textual data

  • html for HTML data

  • xhtml for XHTML data

xhtml data is automatically wrapped in a namespaced div element (see RFC4287, Section 3.1 for further details).

author

my $person = $atom->new_person(
  name => 'Bender',
  uri  => 'acct:bender@example.org'
);
my $author = $atom->author($person);

print $atom->author->[0]->at('name')->text;

Adds author information to the Atom object or returns it. Accepts a person construct (see new_person) or the parameters accepted by new_person.

Returns a collection of author nodes.

category

$atom->category('world');

print $atom->category->[0];

Adds category information to the Atom object or returns it. Accepts either a hash for attributes (with, e.g., term and label) or one string representing the category's term.

Returns a collection of category terms.

content

my $text = $atom->new_text(
  type    => 'xhtml',
  content => '<p>This is a <strong>test</strong>!</p>'
);

my $entry = $atom->entry(id => 'entry_1');

$entry->content($text);
$entry->content('This is a test!');

print $atom->content->all_text;

Sets content information to the Atom object or returns it. Accepts a text construct (see new_text) or the parameters accepted by new_text. Returns the content node or, on construction of an xhtml object, the wrapped div node.

contributor

my $person = $atom->new_person(
  name => 'Bender',
  uri  => 'acct:bender@example.org'
);
my $contributor = $atom->contributor($person);

print $atom->contributor->[0]->at('name')->text;

Adds contributor information to the Atom object or returns it. Accepts a person construct (see new_person) or the parameters accepted by new_person.

Returns a collection of contributor nodes.

entry

# Add entry as a hash of attributes
my $entry = $atom->entry(
  id      => 'entry_id_1',
  summary => 'My first entry'
);

# Get entry by id
my $entry = $atom->entry('entry_id_1');

Adds an entry to the Atom feed or returns one. Accepts a hash of simple entry information for adding or an id for retrieval.

generator

$atom->generator('XML-Loy-Atom');
print $atom->generator;

Sets generator information of the feed or returns it as a text string.

icon

$atom->icon('http://sojolicio.us/favicon.ico');
print $atom->icon;

Sets icon url of the feed or returns it as a text string. The image should be suitable for a small representation size and have an aspect ratio of 1:1.

id

$atom->id('http://sojolicio.us/#12345');
print $atom->id;

Sets or returns the unique identifier of the Atom object.

$atom->link(related => 'http://sojolicio.us/#12345');
$atom->link(
  rel  => 'self',
  href => 'http://sojolicio.us/#12345'
);

# Get link elements
$atom->link('related');

Adds link information to the Atom object. Accepts either one scalar as a reference of a related link, a pair of scalars for the relational type and the reference, or multiple hashes for the attributes of the link. If no relation attribute is given, the default relation is 'related'.

$atom->logo('http://sojolicio.us/sojolicious.png');
print $atom->logo;

Sets logo url of the feed or returns it as a text string. The image should have an aspect ratio of 2:1.

published

$atom->published('1312311456');
$atom->published('2011-08-30T16:16:40Z');

# Set current time
$atom->published(time);

print $atom->published->to_string;

Sets the publishing date of the Atom object or returns the publishing date as a XML::Loy::Date::RFC3339 object. Accepts all valid parameters of XML::Loy::Date::RFC3339::new.

This method is experimental and may return another object with a different API!

rights

$atom->rights('Public Domain');
print $atom->rights->all_text;

Sets legal information of the Atom object or returns it. Accepts a text construct (see new_text) or the parameters accepted by new_text. Returns the rights node or, on construction of an xhtml object, the wrapped div node.

source

my $source = $atom->entry('my_id')->source({
  'xml:base' => 'http://source.sojolicio.us/'
});
$source->author(name => 'Zoidberg');

print $atom->entry('my_id')
      ->source
      ->author->[0]->at('name')->all_text;

Sets or returns the source information of an atom entry. Expects for setting a hash reference (at least empty) of the attributes of the source. Returns the source node.

subtitle

my $text = $atom->new_text(
  type => 'text',
  content => 'This is a subtitle!'
);

$atom->subtitle($text);
$atom->subtitle('This is a subtitle!');

print $atom->subtitle->all_text;

Sets subtitle information to the Atom feed or returns it. Accepts a text construct (see new_text) or the parameters accepted by new_text. Returns the subtitle node or, on construction of an xhtml object, the wrapped div node.

summary

my $text = $atom->new_text(
  type => 'text',
  content => 'This is a summary!'
);

$atom->summary($text);
$atom->summary('This is a summary!');

print $atom->summary->all_text;

Sets summary information to the Atom entry or returns it. Accepts a text construct (see new_text) or the parameters accepted by new_text. Returns the summary node or, on construction of an xhtml object, the wrapped div node.

title

my $text = $atom->new_text(
  type => 'text',
  content => 'This is a title!'
);

$atom->title($text);
$atom->title('This is a title!');

print $atom->title->all_text;

Sets title information to the Atom object or returns it. Accepts a text construct (see new_text) or the parameters accepted by new_text. Returns the title node or, on construction of an xhtml object, the wrapped div node.

updated

$atom->updated('1312311456');
$atom->updated('2011-08-30T16:16:40Z');

# Set current time
$atom->updated(time);

print $atom->updated->to_string;

Sets the date of the last update of the Atom object or returns it as a XML::Loy::Date::RFC3339 object. Accepts all valid parameters of XML::Loy::Date::RFC3339's new.

This method is experimental and may return another object with a different API!

MIME-TYPES

When loaded as a base class, XML::Loy::Atom makes the mime-type application/atom+xml available.

DEPENDENCIES

Mojolicious.

AVAILABILITY

https://github.com/Akron/XML-Loy

COPYRIGHT AND LICENSE

Copyright (C) 2011-2013, Nils Diewald.

This program is free software, you can redistribute it and/or modify it under the same terms as Perl.