=encoding utf8

=head1 NAME

Google::Merchant - provide Google shop with product info

=head1 INHERITANCE

 Google::Merchant
   is a XML::Compile::Cache
   is a XML::Compile::Schema
   is a XML::Compile

 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.

See L<documentation in base class|XML::Compile::Cache/"DESCRIPTION">.
 
=head1 METHODS

See L<documentation in base class|XML::Compile::Cache/"METHODS">.
 
=head2 Constructors

See L<documentation in base class|XML::Compile::Cache/"Constructors">.
 
=over 4

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

 -Option            --Defined in          --Default
  allow_undeclared    XML::Compile::Cache   <false>
  any_element         XML::Compile::Cache   'SKIP_ALL'
  block_namespace     XML::Compile::Schema  []
  hook                XML::Compile::Schema  undef
  hooks               XML::Compile::Schema  []
  ignore_unused_tags  XML::Compile::Schema  <false>
  key_rewrite         XML::Compile::Schema  []
  opts_readers        XML::Compile::Cache   []
  opts_rw             XML::Compile::Cache   []
  opts_writers        XML::Compile::Cache   []
  parser_options      XML::Compile          <many>
  prefixes            XML::Compile::Cache   <smart>
  schema_dirs         XML::Compile          undef
  string_format                             'HTML'
  title                                     <required>
  typemap             XML::Compile::Cache   {}
  website                                   <required>
  xsi_type            XML::Compile::Cache   {}

=over 2

=item allow_undeclared => BOOLEAN

=item any_element => CODE|'TAKE_ALL'|'SKIP_ALL'|'ATTEMPT'|'SLOPPY'

=item block_namespace => NAMESPACE|TYPE|HASH|CODE|ARRAY

=item hook => ARRAY-WITH-HOOKDATA | HOOK

=item hooks => ARRAY-OF-HOOK

=item ignore_unused_tags => BOOLEAN|REGEXP

=item key_rewrite => HASH|CODE|ARRAY-of-HASH-and-CODE

=item opts_readers => HASH|ARRAY-of-PAIRS

=item opts_rw => HASH|ARRAY-of-PAIRS

=item opts_writers => HASH|ARRAY-of-PAIRS

=item parser_options => HASH|ARRAY

=item prefixes => HASH|ARRAY-of-PAIRS

=item schema_dirs => DIRECTORY|ARRAY-OF-DIRECTORIES

=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 typemap => HASH|ARRAY

=item website => URI

=item xsi_type => HASH|ARRAY

=back

=back

=head2 Accessors

See L<documentation in base class|XML::Compile::Cache/"Accessors">.
 
=over 4

=item $obj-E<gt>B<addHook>(HOOKDATA|HOOK|undef)

See L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<addHooks>(HOOK, [HOOK, ...])

See L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<addKeyRewrite>(PREDEF|CODE|HASH, ...)

See L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<addSchemaDirs>(DIRECTORIES|FILENAME)

=item Google::Merchant-E<gt>B<addSchemaDirs>(DIRECTORIES|FILENAME)

See L<XML::Compile/"Accessors">

=item $obj-E<gt>B<addSchemas>(XML, OPTIONS)

See L<XML::Compile::Schema/"Accessors">

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

See L<XML::Compile::Schema/"Accessors">

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

See L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<allowUndeclared>([BOOLEAN])

See L<XML::Compile::Cache/"Accessors">

=item $obj-E<gt>B<anyElement>('ATTEMPT'|'SLOPPY'|'SKIP_ALL'|'TAKE_ALL'|CODE)

See L<XML::Compile::Cache/"Accessors">

=item $obj-E<gt>B<blockNamespace>(NAMESPACE|TYPE|HASH|CODE|ARRAY)

See L<XML::Compile::Schema/"Accessors">

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

See L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<typemap>([HASH|ARRAY|PAIRS])

See L<XML::Compile::Cache/"Accessors">

=item $obj-E<gt>B<useSchema>(SCHEMA, [SCHEMA])

See L<XML::Compile::Schema/"Accessors">

=item $obj-E<gt>B<xsiType>([HASH|ARRAY|LIST])

See L<XML::Compile::Cache/"Accessors">

=back

=head2 Prefix management

See L<documentation in base class|XML::Compile::Cache/"Prefix management">.
 
=over 4

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

See L<XML::Compile::Cache/"Prefix management">

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

See L<XML::Compile::Cache/"Prefix management">

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

See L<XML::Compile::Cache/"Prefix management">

=item $obj-E<gt>B<prefixed>(TYPE|(NAMESPACE,LOCAL))

See L<XML::Compile::Cache/"Prefix management">

=item $obj-E<gt>B<prefixes>([PAIRS|ARRAY|HASH])

See L<XML::Compile::Cache/"Prefix management">

=back

=head2 Compilers

See L<documentation in base class|XML::Compile::Cache/"Compilers">.
 
=over 4

=item $obj-E<gt>B<addCompileOptions>(['READERS'|'WRITERS'|'RW'], OPTIONS)

See L<XML::Compile::Cache/"Compilers">

=item $obj-E<gt>B<compile>(('READER'|'WRITER'), TYPE, OPTIONS)

See L<XML::Compile::Schema/"Compilers">

=item $obj-E<gt>B<compileAll>(['READERS'|'WRITERS'|'RW', [NAMESPACE]])

See L<XML::Compile::Cache/"Compilers">

=item $obj-E<gt>B<dataToXML>(NODE|REF-XML-STRING|XML-STRING|FILENAME|FILEHANDLE|KNOWN)

=item Google::Merchant-E<gt>B<dataToXML>(NODE|REF-XML-STRING|XML-STRING|FILENAME|FILEHANDLE|KNOWN)

See L<XML::Compile/"Compilers">

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

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

See L<XML::Compile/"Compilers">

=item $obj-E<gt>B<reader>(TYPE|NAME, OPTIONS)

See L<XML::Compile::Cache/"Compilers">

=item $obj-E<gt>B<template>('XML'|'PERL'|'TREE', ELEMENT, OPTIONS)

See L<XML::Compile::Schema/"Compilers">

=item $obj-E<gt>B<writer>(TYPE|NAME)

See L<XML::Compile::Cache/"Compilers">

=back

=head2 Administration

See L<documentation in base class|XML::Compile::Cache/"Administration">.
 
=over 4

=item $obj-E<gt>B<declare>('READER'|'WRITER'|'RW', TYPE|ARRAY-of-TYPES, OPTIONS)

See L<XML::Compile::Cache/"Administration">

=item $obj-E<gt>B<doesExtend>(EXTTYPE, BASETYPE)

See L<XML::Compile::Schema/"Administration">

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

See L<XML::Compile::Schema/"Administration">

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

See L<XML::Compile::Cache/"Administration">

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

=item Google::Merchant-E<gt>B<findSchemaFile>(FILENAME)

See L<XML::Compile/"Administration">

=item $obj-E<gt>B<importDefinitions>(XMLDATA, OPTIONS)

See L<XML::Compile::Schema/"Administration">

=item $obj-E<gt>B<knownNamespace>(NAMESPACE|PAIRS)

=item Google::Merchant-E<gt>B<knownNamespace>(NAMESPACE|PAIRS)

See L<XML::Compile/"Administration">

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

See L<XML::Compile::Schema/"Administration">

=item $obj-E<gt>B<printIndex>([FILEHANDLE], OPTIONS)

See L<XML::Compile::Cache/"Administration">

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

See L<XML::Compile::Schema/"Administration">

=item $obj-E<gt>B<walkTree>(NODE, CODE)

See L<XML::Compile/"Administration">

=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

See L<documentation in base class|XML::Compile::Cache/"DETAILS">.
 
=head2 Comparison

See L<documentation in base class|XML::Compile::Cache/"Comparison">.
 
=head2 Collecting definitions

See L<documentation in base class|XML::Compile::Cache/"Collecting definitions">.
 
=head2 Addressing components

See L<documentation in base class|XML::Compile::Cache/"Addressing components">.
 
=head2 Representing data-structures

See L<documentation in base class|XML::Compile::Cache/"Representing data-structures">.
 
=head2 Schema hooks

See L<documentation in base class|XML::Compile::Cache/"Schema hooks">.
 
=head2 Typemaps

See L<documentation in base class|XML::Compile::Cache/"Typemaps">.
 
=head2 Handling xsi:type

See L<documentation in base class|XML::Compile::Cache/"Handling xsi:type">.
 
=head2 Key rewrite

See L<documentation in base class|XML::Compile::Cache/"Key rewrite">.
 
=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'
               , _    => '<">'
               }
    );

=head1 DESCRIPTIONS

See L<documentation in base class|XML::Compile::Cache/"DESCRIPTIONS">.
 
=head1 SEE ALSO

This module is part of Google-Merchant distribution version 0.10,
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>,
L<XML::eXistDB>,
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>

