/ 
XML-Loy-0.52
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.

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

Creates 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 of 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 $entry->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.

Returns the entry node.

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://sojolicious.example/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://sojolicious.example/#12345');
print $atom->id;

Sets or returns the unique identifier of the Atom object.

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

# Get link elements
print $atom->link('related')->[0]->attr('href');

Adds link information to the Atom object or returns it. Accepts for retrieval the relation type and for setting the relation type followed by the reference, or multiple pairs as attributes of the link. If no relation attribute is given, the default relation is related.

Returns the link element on adding and a collection of matching link elements on retrieval.

$atom->logo('http://sojolicious.example/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.sojolicious.example/'
});
$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-2021, Nils Diewald.

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