NAME

Class::DBI::AsXML - Format CDBI Objects as XML

SYNOPSIS

  # As you do...
  package MyApp::User;
  use base qw[Class::DBI];
  
  __PACKAGE__->connection('dbi:SQLite:dbfile', '', '');
  __PACKAGE__->table(q[users]);
  __PACKAGE__->columns(Primary => 'id');
  __PACKAGE__->columns(Essential => qw[username password]);
  __PACKAGE__->columns(Others    => qw[email zip_code phone]);
  __PACKAGE__->has_a(pref => 'MyApp::Pref');

  # Enter XML Support!
  use Class::DBI::AsXML;
  __PACKAGE__->to_xml_columns([qw[username email zip_code]]);

  # Elsewhere...
  my $user = MyApp::User->retrieve(shift);
  my $user_and_prefs_xml = $user->to_xml(depth => 1);

  # Or... override defaults
  my $uname_pwd_xml = $user->to_xml( columns => {
      ref($user) => [qw[username password]],
  });
  
  # Create from XML
  my $new_user = MyApp::User->create_from_xml(<<__XML__);
  <user>
    <username>new_user</username>
    <password>new_pass</password>
    <email>&lt;casey@geeknest.com%gt;</email>
  </user>
  __XML__

DESCRIPTION

This software adds XML output support to Class::DBI based objects.

to_xml_columns

  Class->to_xml_columns([qw[columns to dump with xml]]);

This class method sets the default columns this class should dump when calling to_xml() on an object. The single parameter is a list reference with column names listed.

to_xml

  my $xml = $object->to_xml(
                columns => {
                    MyApp::User  => [ qw[username email zip_code] ],
                    MyApp::File  => [ qw[user filename size]      ],
                    MyApp::Pref  => [ MyApp::Pref->columns        ],
                },
                depth => 10,
                xml => {
                    NoAttr => 0,
                },
            );

All arguments are optional.

columns - A hash reference containing key/value pairs associating class names to a list of columns to dump as XML when the class is serialized. They keys are class names and values are list references containing column names, just as they'd be sent to to_xml_columns(). Passing a columns parameter to this instance method will override any defaults associated with this object. Failing that, to_xml_colunms() is checked and failing that, the Primary and Essential columns are dumped by default.

Each column requested for XML output will go through an attempt to be stringified. If the column value is an object with stringification overloaded (using overload) then it is stringified in that manner. If the column is an object and its interface supports either as_string() or as_text() methods, those method will be called and the results returned. Finally, if the value is defined then it is stringified and returned (this means references will become ugly). If the value is undefined then an empty string is used in its place.

depth - Depth to dump to. Depth of zero, the default, will not recurse. Column values are interogated to determine if they should be recursed down. If the column value is an object whose API supports the to_xml() method, then that method will be called and the resulting XML will be parsed via XMLin() from XML::Simple. The root node will not be kept when converting the XML back into a data structure.

xml - Hash reference of XML::Simple options. Change these only if you really know what you're doing. By default the following options are set.

  NoAttr   => 1,
  RootName => $self->moniker,
  XMLDecl  => 0,

create_from_xml

  my $new_user = MyApp::User->create_from_xml($xml);

Creates a new user from an XML document. The document is parsed with XMLin and the root node is thrown away. All information passed in to this method is ignored except the tags that match column names.

EXPORTS

This module is implemented as a mixin and therefore exports the functions to_xml, create_from_xml, and _to_xml_stringify into the caller's namespace. If you don't want these to be exported, then load this module using require.

SEE ALSO

Class::DBI, XML::Simple, perl.

AUTHOR

Casey West, <casey@geeknest.com>.

COPYRIGHT

  Copyright (c) 2005 Casey West.  All rights reserved.
  This module is free software; you can redistribute it and/or modify it
  under the same terms as Perl itself.