/ 
Dancer2-Serializer-XML-0.06
River stage zero No dependents
/ Dancer2::Serializer::XML

NAME

Dancer2::Serializer::XML - serializer for handling XML data

SYNOPSIS

set serializer => 'XML';

# Send an XML string to the caller
get '/xml/get_example' => sub {
   return { foo => 'one', bar => 'two' }
}

# Parse an XML string sent by the caller
put '/xml/from_body' => sub {
   debug request->data();	# Contains the deserialised Perl object
   return template 'ok';
};

DESCRIPTION

This module is a plugin for the Web application frmaework Dancer2, and allows it to serialise Perl objects into XML, and deserialise XML into Perl objects. It uses XML::Simple under the covers.

STATUS

Alpha, but it works for me. Reports of success are gratefully received.

METHODS

serialize

Serialize a data structure to an XML structure. Called automatically by Dancer2.

deserialize

Deserialize an XML structure to a data structure. Called automatically by Dancer2.

content_type

Returns the string 'application/xml'

CONFIGURATION

The default behaviour of this module is the default behaviour of XML::Simple - nothing is overridden, which creates backwards compatability with Dancer::Serializer::XML. Every option that XML::Simple supports is also supported by this module.

You can control options for serialization and deserialization separately. See the examples below.

Configuration in code

To configure the serializer in a route, do this:

   get '/xml/example' => sub {
      my $self = shift;
      $self->{'serializer_engine'}->{'xml_options'}->{'serialize'}->
                                                  {'RootName'} = 'data';
      return { foo => 'one', bar => 'two' }
   }

Which will produce this:

<data bar="two" foo="one" />

You can pass a reference to a hash to configure multiple things:

$self->{'serializer_engine'}->{'xml_options'}->{'serialize'} = 
                               { RootName => 'data', KeyAttr => [] };

To configure the deserializer, do similarly:

put '/from_body' => sub {
   my $self = shift;
   $self->{'serializer_engine'}->{'xml_options'}->{'deserialize'}->
                                                    {'KeepRoot'} = 1;
   return template 'ok';
};

etc. See below for the recommended configuration.

Configuration in config file

At this time there seems I cannot find a way for a Dancer2 serializer to directly access the configuration of a Dancer2 app. If you know it, please tell me. Until then, do this in your code:

get '/xml/example' => sub {
   my $self = shift;
   $self->{'serializer_engine'}->{'xml_options'} = 
                      $self->{'config'}->{'engines'}->{'serializer'};
   return { foo => 'one', bar => 'two' }
}

and put this in your config file:

engines:
   serializer:
     serialize:
        RootName: 'data'
        KeyAttr: []
     deserialize:
        KeepRoot: 1

BUT see "Recommended configuration".

For new code, these are the recommended settings for consistent behaviour. In code:

my $xml_options = { 'serialize' => { RootName => 'test',
									KeyAttr => []
									},
					'deserialize' => { ForceContent => 1,
									KeyAttr => [],
									ForceArray => 1,
									KeepRoot => 1
									}
					};

In config:

engines:
   serializer:
     serialize:
        AttrIndent: 1
        KeyAttr: []
     deserialize:
        ForceArray: 1
        KeyAttr: []
        ForceContent: 1
        KeepRoot: 1

SEE ALSO / EXAMPLES

XML::Simple

SOURCE / BUGS / CONTRIBUTIONS

GitHub

AUTHOR

Ian Gibbs, <igibbs@cpan.org> and Dancer Core Developers

COPYRIGHT AND LICENSE

Copyright (C) 2017 by Ian Gibbs and Copyright (C) 2010 by Alexis Sukrieh.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.