NAME
Web::DataService::Configuration::Format - how to configure output formats
SYNOPSIS
This page describes the role that output formats play in the Web::DataService framework, and how to configure them. It includes a list of the attributes that you can use to define them.
FORMAT DEFINITIONS
Each data service must define one or more output formats. These are defined using the define_format method of a data service object. This must be be done at data service startup time before any nodes are defined, so that the default_format and allow_format node attributes can be interpreted properly. Each format definition configures one of the available serialization modules.
Predefined formats
The format names listed below are predefined by Web::DataService and can be activated simply by specifying a hashref with the appropriate name attribute. For example, the following call will enable the formats 'json' and 'txt' with all of their default attribute values and documentation strings.
$ds->define_format(
{ name => 'json' },
{ name => 'txt' });You can override any of these attribute values and documentation strings by specifying them explicitly. The example code directory contains documentation files for each of these formats, which you can copy into your own application directory and modify as you see fit. However, you must explicitly define the corresponding data service nodes yourself or else the documentation pages will not be available. The corresponding call for this example would be:
$ds->define_node(
{ path => 'formats',
title => 'Output formats' },
{ path => 'formats/json',
title => 'JSON format' },
{ path => 'formats/txt',
title => 'Plain text format' });See the next section for descriptions of the various attributes.
json
This format serializes operation results using JSON (JavaScript Object Notation). It sets the content type of the response to "application/json", and its default documentation node is "formats/json". The module used is Web::DataService::Plugins::JSON.
txt
This format serializes operation results as lines of comma-separated values separated by the specified linebreak sequence. Its content type is "text/plain", and its default documentation node is "formats/txt". The module used is Web::DataService::Plugins::Text.
csv
This format is identical to "txt", except that it sets the content type of the response to "text/csv" and sets the content disposition to "attachment".
tsv
This format serializes operation results as lines of tab-separated values separated by the specified linebreak sequence. Its content type is "text/tab-separated-values", and its disposition is "attachment". Its default documentation node is "formats/txt". The module used is Web::DataService::Plugins::Text.
FORMAT ATTRIBUTES
With the exception of name, each of the following attributes is optional for predefined formats. Those which are required for custom (i.e. not predefined) formats are noted below.
name
Each format defined for a given data service must have a unique name. This name can be used as the value of the node attributes allow_format and default_format, and is matched either to the URL path suffix or to the value of the special parameter "format" depending upon which data service features are enabled. This attribute is required for all format definitions.
title
The value of this attribute is used as the format's title in all generated documentation. It defaults to the name.
content_type
The value of this attribute specifies the HTTP content type that will be reported in the response message. It is required for all custom format definitions.
disposition
If this attribute is given the value 'attachment', then any response generated with this format will be returned with a "content-disposition" header indicating that it should be saved to disk. However, if the special parameter "save" is active and a request includes that parameter with the value "no", then this attribute will be overridden for that request.
The value of this attribute defaults to 'inline' if not specified.
module
The value of this attribute must be the name of a Perl module implementing this format. This module will be automatically loaded via require. You must specify this attribute when defining a custom format, and then include a module with the corresponding name in the appropriate library directory.
doc_node
The value of this attribute specifies the path of a data service node which will provide documentation about this format. You must define the node with a separate call to define_node.
doc_string
You can set this attribute either directly or by including one or more documentation strings after each format definition hash in the call to define_format. This value will be used in any auto-generated format lists in the documentation pages.
default_vocab
The value of this attribute must be the name of an already-defined vocabulary. This vocabulary will be used when rendering responses in this format, unless overridden by the special parameter vocab. It defaults to 'null', which simply uses the underlying field names from the backend data store.
uses_header
The special parameter header will only be enabled if at least one enabled output format uses it. If you are defining a custom format that includes an optional header, you should give this attribute a true value. All of the Text builtin formats set this by default.
encode_as_text
If this attribute is given a true value, then the output of this format will be encoded in the output character set (specified by the 'charset' attribute in the application configuration file) before being sent. This attribute is required because the foundation framework Dancer only encodes output if its content type matches /(x(?:ht)?ml|text|json|javascript)/. If you are defining a custom format whose content is character data but whose content type does not match this regexp, you must set this attribute to true.
If you are defining a custom format for binary data, then you should not set this attribute. A good example would be a format such as 'png', which would be used with binary image data. This kind of format should be used only with operation methods that read binary data from the backend or from a file and send it using the data_result method without doing anything in the method code that would cause perl to apply Character semantics to the data.
disabled
If this attribute is given a true value, then any request that selects this format will get an HTTP 415 error response ("Invalid media type") just as if an undefined format was requested. This format can still be used as a value of the node attribute allow_format. You can use this to create a placeholder for a format that is not fully implemented yet, or to temporarily disable a format. Disabled formats will not appear in any auto-generated documentation lists.
undocumented
If this attribute is given a true value, the format will be available to be selected in the usual way, but it will never appear in any auto-generated documentation list.
AUTHOR
mmcclenn "at" cpan.org
BUGS
Please report any bugs or feature requests to bug-web-dataservice at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Web-DataService. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
COPYRIGHT & LICENSE
Copyright 2014 Michael McClennen, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.