NAME
Web::DataService::Configuration::Vocabulary - how to configure output vocabularies
SYNOPSIS
This page describes the role that output vocabularies 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.
VOCABULARY DEFINITIONS
Each data service may define one or more vocabularies. These are defined using the define_vocab method of a data service object. This must be be done at data service startup time before any formats are defined, so that the default_vocab attribute can be interpreted properly. These vocabularies can be used, for many purposes, including:
to express the data service output according to some well-known standard
to create shortened field names and values in order to reduce the size of the response messages
A vocabulary is selected for each request as follows. Each output format has a default vocabulary, and the vocabulary corresponding to the selected output format will always be used unless explicitly overridden. If the special parameter vocab is active, and if it is included in the request with a valid value, then that vocabulary is used regardless of the format.
A vocabulary named 'null' is always available unless you explicitly disable it. You do not need to call define_vocab to make it active, unlike with the predefined formats. This vocabulary expresses results using the underlying field names used by the backend data store. If you do not wish this vocabulary to be available for selection, you can explicitly disable it as follows:
$ds->define_vocab({ name => 'null', disabled => 1 });The actual names that make up the vocabulary are specified when defining output blocks. For example, if you have defined a vocabulary named "foo", then any output fields you subsequently define may contain the attribute "foo_name" whose value will be used as the field name in any output rendered with vocabulary "foo". If no such attribute is specified, then that field will be omitted from the output when vocabulary "foo" is selected. You can also include processing rules with an "if_vocab" value of "foo", which will be activated only when this vocabulary is selected. In this way, you can transform both the field names and values as appropriate for this vocabulary, and skip output values that cannot be expressed in that vocabulary.
VOCABULARY ATTRIBUTES
With the exception of name, each of these attributes is optional.
name
Each vocabulary defined for a given data service must have a unique name. This name can be used as the value of the format attribute default_vocab, and the processing rule attributes if_vocab and not_vocab.
In addition, suppose you have defined a vocabulary named "foo". You can then include the attribute foo_name in any of your field definitions. This is how you actually populate the vocabulary.
title
The value of this attribute is used as the vocabulary's title in documentation pages. It defaults to the name.
doc_node
The value of this attribute specifies the path of a data service node which will provide documentation about this vocabulary. You must define the node with a separate call to define_node.
use_field_names
If this attribute is given a true value, then the underlying field names used by the backend data store will be used by this vocabulary. It is automatically set to true for the predefined vocabulary 'null'.
doc_string
You can set this attribute either directly or by including one or more documentation strings after the format attribute hash in the call to define_format. This value will be used in any auto-generated vocabulary lists in the documentation pages.
disabled
If this attribute is given a true value, then any request that selects it will get an HTTP 400 error ("parameter error"). In addition, this vocabulary may not be the value of the format attribute default_vocab. You can use this to create a placeholder for a vocabulary that is not fully implemented yet, or to temporarily disable a vocabulary. Disabled vocabularies will never appear in any auto-generated documentation list.
undocumented
If this attribute is given a true value, the vocabulary will be available for selection 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.