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