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

  $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.

=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'
               , _    => '<">'
               }
    );

=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
    ( brand      => '&gt;&quot;&lt'     # default, here HTML
    , isbn       => { type => 'TEXT', _ => '<">' }
    , '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.11,
built on May 13, 2013. Website: F<http://perl.overmeer.net/xml-compile/>

Other distributions in this suite:
L<XML::Compile>,
L<XML::Compile::SOAP>,
L<XML::Compile::SOAP12>,
L<XML::Compile::SOAP::Daemon>,
L<XML::Compile::SOAP::WSA>,
L<XML::Compile::C14N>,
L<XML::Compile::WSS>,
L<XML::Compile::WSS::Signature>,
L<XML::Compile::Tester>,
L<XML::Compile::Cache>,
L<XML::Compile::Dumper>,
L<XML::Compile::RPC>,
L<XML::Rewrite>
and
L<XML::LibXML::Simple>.

Please post questions or ideas to the mailinglist at
F<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile> .
For live contact with other developers, visit the C<#xml-compile> channel
on C<irc.perl.org>.

=head1 LICENSE

Copyrights 2013 by [Mark Overmeer]. 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>

