=head1 NAME Web::DataService::Configuration::Output - how to configure output blocks =head1 SYNOPSIS This page describes the role that output blocks 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. =head1 OUTPUT BLOCK DEFINITIONS Each data service may define one or more groups of output elements, called "output blocks". These are defined by calling the L method of a data service object. These output elements specify which data fields should be included in the result, how they should be labeled, and how they should be processed. The first argument to C must be a string that provides the name of the output block. This must be unique among all of the output blocks defined for this data service. The remaining elements must be either hashrefs or strings: the hashrefs define the individual elements of the block, and the strings provide documentation. For example: $ds->define_block( 'basic' => { output => 'name' }, "The name of the state", { output => 'abbrev' }, "The standard abbreviation for the state", { output => 'region' }, "The region of the country in which the state is located", { output => 'pop2010' }, "The population of the state in 2010"); This call defines an output block called 'basic', with four elements. Each of these elements represent output fields. When a data service request is handled, the data service operation method is expected to construct and execute the appropriate query and then pass back a either a list of output records (as a listref whose elements are hashes) or a DBI statement handle from which the output records can be retrieved. Each of the output records will be processed and included in the data service result according to the list of output blocks that have been selected for this request, as interpreted by the serialization routine corresponding to the selected output format. There are four categories of output elements, listed below. Each category is defined by the presence of a hash key corresponding to the element type. Each element must contain exactly one of these keys, or else an error will be thrown at startup time. =over =item output An "output" element specifies a single data field to be included in a data service result. The value of the key C gives the internal name of this field, generally, the name by which the field is known to the backend data store. Other keys may be used to specify the name under which this field will be included in the result, and yet other keys can be used to specify conditions under which this it will or will not be included in the result. This is the only kind of element that is required in order to produce data service output; the others are there for the convenience of the application programmer. =item set A "process" element indicates a processing step to be carried out on the data before it is included in the result. The value of the key C specifies which field's value is to be altered. =item select A "select" element specifies a list of strings that can be retrieved by the various data service operation methods and used to construct queries on the backend data store. Use of this element is optional. The value of the key C. For example: { select => 'a.foo, b.bar', tables => 'a, b' } This element adds the values 'a.foo' and 'b.bar' to the "select list" and 'a' and 'b' to the "tables list". The data service operation methods that you write can then query the request object to obtain either a list or a hash of the unique select values and a hash of the unique table values. This element was designed with SQL in mind, but you can use it in any way that makes sense in constructing queries for the backend data system regardless of whether or not it is based on SQL. The idea is that your operation methods can use this mechanism to get a list of the fields and tables (or equivalent constructs) necessary for satisfying all of the output blocks that have been selected for this particular query. In this way, a single operation method can satisfy a wide variety of requests. You can use any of the following attributes in defining a select element: =head3 select This attribute is required, and we recommend that you always specify it first in order to make clear the element type. The value can be either a string or an array of strings. In the first case, it will be split on the pattern C. From your data service operation subroutines, you can call any of the relevant methods of the request object (C, C, C) to retrieve the list of all the C except that you retrieve the values by calling C. In most cases, it will make sense to list all of the unique tables (or equivalent constructs, depending upon the backend data system you are using) used by the elements listed in the value of the attribute C