=encoding utf8

=head1 NAME

Google::Merchant - provide Google shop with product info

=head1 INHERITANCE

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

=head1 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);

=head1 DESCRIPTION

With the Merchant interface, shop-owners inform Google which products
they have for sale.  Read the
L<documentation at Google|http://support.google.com/merchants/>

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.  But there are a
few other bugs as well.  Also, many used elements are not in the schema.
This is repared by this module.

=head1 METHODS

=head2 Constructors

=over 4

=item Google::Merchant-E<gt>B<new>(OPTIONS)

 -Option       --Default
  string_format  'HTML'
  title          <required>
  website        <required>

=over 2

=item 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 '&'.

=item title => STRING

=item website => URI

=back

=back

=head2 Accessors

=over 4

=item $obj-E<gt>B<feed>()

=item $obj-E<gt>B<schemas>()

=back

=head2 Items

=over 4

=item $obj-E<gt>B<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.

=item $obj-E<gt>B<stringFormat>()

Returns the default text format.

=back

=head2 Feed handling

=over 4

=item $obj-E<gt>B<write>(FILENAME, OPTIONS)

 -Option  --Default
  beautify  0
  doc       <created internally>
  gzip      <undef>

=over 2

=item beautify => 0|1|2

XML::LibXML output format parameter.

=item doc => XML::LibXML::Document object

=item 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.

=back

=back

=head1 DETAILS

=head2 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 C<title>, C<link>, and C<summary>.  To reduce the gap between the
Atom and RSS interface, you pass these three values via parameters
C<title>, C<webpage>, and C<description> respectively.

Google defined a huge list of parameters for any product.  Look in the
C<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);

=head3 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 L<new(string_format)|Google::Merchant/"Constructors">.  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
               , _    => '<">'
               }
    );

=head3 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
C<$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 ;-)

=head1 SEE ALSO

This module is part of Google-Merchant distribution version 0.14,
built on May 28, 2013. Website: F<http://perl.overmeer.net/xml-compile/>.

=head1 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 F<http://www.perl.com/perl/misc/Artistic.html>