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

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.

cpanm Dancer2::Serializer::XML

perl -MCPAN -e shell
install Dancer2::Serializer::XML