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]],
});
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,
EXPORTS
This module is implemented as a mixin and therefore exports the
functions "to_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".
TODO
It would be nice to have a "from_xml()" method. Patches most certainly
welcome.
SEE ALSO
Class::DBI, XML::Simple, perl.
AUTHOR
Casey West, .
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.