/ 
Google-Merchant-0.13
/ Google::Merchant

NAME

Google::Merchant - provide Google shop with product info

INHERITANCE

Google::Merchant is extended by
  Google::Merchant::AtomFeed

SYNOPSIS

my $feed = Google::Merchant::AtomFeed->new
  ( title   => 'My Webshop'
  , website => 'https://webshop.example.org'
  , string_format => 'TEXT'
  );

$feed->addItem
  ( # feed fields
    title   => 'washing machine'
  , webpage => "$website/EAN1234.html"

    # google base fields
  , id      => 'EAN1234'
  , price   => '12.34 EUR'
  );

$feed->write($filename);

DESCRIPTION

With the Merchant interface, shop-owners inform Google which products they have for sale. Read the documentation at Google

Google provides two XML syntaxes to denote product information (and a few other formats). This distribution can be used to produce files in the correct syntax. On the moment, only the feed of Atoms are implemented, although RSS should not be too hard to add. An attempt is made to hide the difference between the two in the here provided interface.

This module can not read merchant files. As you will also discover in the examples shown by Google: they do not use the schema themselves, nearly all examples will fail validation! Especially, the strict order of elements in a sequence is ignored by Google's examples.

METHODS

Constructors

Google::Merchant->new(OPTIONS)
-Option       --Default
 string_format  'HTML'
 title          <required>
 website        <required>
string_format => 'TEXT'|'HTML'|'XHTML'

How are your text strings formatted by default? Google itself does not specify the content of the string elements (elements of type stringAttrValueType -which isn't an attribute type!) However, we do need to diffentiate between strings which already have entities encoded or not. HTML encoded strings are included as CDATA if they contain an ampersand '&'.

title => STRING
website => URI

Accessors

$obj->feed()
$obj->schemas()

Items

$obj->addItem(OPTIONS)

The list of available OPTIONS is huge: all the fields which can be included in the atom. Not only a few which are RSS/Atom specific (see extension) but also dozens of fields specified by Google.

$obj->stringFormat()

Returns the default text format.

Feed handling

$obj->write(FILENAME, OPTIONS)
-Option  --Default
 beautify  0
 doc       <created internally>
 gzip      <undef>
beautify => 0|1|2

XML::LibXML output format parameter.

doc => XML::LibXML::Document object
gzip => 0..8

Libxml2 (the library which is used by XML::LibXML) can be compiled with gzip support. A higher compression factor may result in a smaller output file.

DETAILS

Item fields

The RSS interface defines an 'Item', and Google uses that term as well to describe product listings. The Atom interface refers to these as 'Entry' elements.

The Atom interface defines 12 fields, of which Google only uses three: the title, link, and summary. To reduce the gap between the Atom and RSS interface, you pass these three values via parameters title, webpage, and description respectively.

Google defined a huge list of parameters for any product. Look in the examples/ directory of this module for the template which lists the fields and explains their limitations. Most of these fields are described on the 'feed specification' on the google support website.

$feed->addItem
  ( # feed fields
    title       => 'washing machine'
  , webpage     => "$website/EAN1234.html"
  , description => "Best you can buy"

    # google base fields
  , id      => 'EAN1234'
  );

$feed->write($filename);

string values

String values (elements of type g:stringAttrValueType) can either be represented as HTML/XHTML or (plain) TEXT. This difference minor but crucial: when HTML is passed as TEXT, you may get double encoding of entities. For instance, '&quot;' may become '&amp;quot;'.

Set the best default with new(string_format). Now, per field you may diverge from the default:

my $feed = Google::Merchant::AtomFeed->new
  ( ...
  , string_format => 'HTML'
  );

$feed->addItem
  ( ...
  , brand => '&gt;&quot;&lt'     # default, here HTML
  , isbn  => { type => 'TEXT'    # overrule default
             , _    => '<">'
             }
  );

custom fields

When you want custom fields, you have to build elements by hand. These elements must be in the NS_GOOGLE_CUSTOM namespace, and use the same $doc element as the writer.

use Google::Merchant::Util ':ns10';

my $doc    = XML::LibXML::Document->new('1.0', 'UTF-8');
my $profit = $doc->createElementNS(NS_GOOGLE_CUSTOM10, 'profit', '10.5 EUR');
$profit->setAttribute(elementType => 'floatUnit');

$feed->addItem
  ( ...
  , 'c:profit' => $profit
  );

$feed->writer($fn, doc => $doc);

When your custom extensions, you can implement it nicer. I will not explain that here until someone needs it ;-)

SEE ALSO

This module is part of Google-Merchant distribution version 0.13, built on May 21, 2013. Website: http://perl.overmeer.net/xml-compile/.

COPYRIGHTS

Copyrights 2013 on the perl code and the related documentation by [Mark Overmeer] for StudioSV, The Netherlands. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html