=pod

=head1 NAME

Hyper::Manual::Control::Setup - How to create new controls

=head1 DESCRIPTION

To create a new control element, for a service usecase, the following files
are required:

=over

=item * etc/Hyper/Control/Container/$service/$usecase.ini

Defines the components and steps a control consists of.
See L<usecase.ini|usecase.ini>.

=item * var/Hyper/Control/Container/$service/usecase.htm

Template for displaying the usecase. See <template.htm|template.htm>

=item * var/Hyper/Control/Container/$service/labels.ini

Labels configuration file for the service. See <labels.ini|labels.ini>

=back

After creating these files, classes are generated by a
Hyper::Generator::Control::Container run.

You may also use L<generate-control.pl|generate-control.pl> to create the
control classes.

=head1 FILES

=head2 usecase.ini

usecase.ini is the control container definition file. It consists of the
following sections:

=head3 [global]

Global settings.

Valid keys are:

=over

=item * attributes

Multi-Value field. All values specified will be included as object attributes
in the control container. get_$name and set_$name methods will be generated,
too.

=back

=head3 [Control]

Define the controls for this container here. To define a control, add
a [Control Name] subsection. Controls may have the following attributes:

=over

=item * class

The implementation class of the control with Hyper::Control stripped of in
. notation.

Examples:

 Primitive.PAccountSelect  (expands to Hyper::Control::Primitive::PAccountSelect)
 Base.BCheckBox            (expands to Hyper::Control::Base::BCheckBox)

=item * template

Template to use (if any).

=item * validators

Validators to use (if any).

=item * group_validators

Group validators to use. Group validators are used for validating groups
of fields - like name and given name for a "full name" control container.

Group validators return OK if, and only if, all single validators grouped
together into a group validator return OK.

Group validators return all error messages of all single validators grouped
together (if any).

When validating groups of fields, group validators are recommended for
usability.

=back

Example:

 [Control cSelectURAAccount]
 class=Base.BSelectList
 template=SelectAccount.htc

=head3 [Step]

Define the steps for the container here.

For every Step, place a [Step Name] section here.

Steps may include the following attributes:

=over

=item * controls

A list of controls. Only controls defined in the same file may be used here.

=item * action

Actions to perform for this control. For the grammar of action definitions,
see L<Hyper::Generator::Control::ContainerFlow>

=item * params

=back

For transitions, place a [Step Name Next_Name] subsection here.

=head2 template.htm

=head2 labels.ini

labels.ini is a UNIX-Style ini file defining the label namespaces used
in the service's templates.

It contains a section C<[global]> for namespaces required in all service
templates.

For every usecase template, a section named like the template (without
suffix) may be specified.

In all sections, namespaces may be specified by the key C<namespace>.
C<namespace> is a multi-value field, so you may set more than one namespace
by heredocs.

 ; global settings for all templates in this directory
 ; namespace: label namespace
 [global]
 namespace=GlobalData

 ; global setting may be overridden on a per-file base.
 ;[CSelectPerson]
 ;namespace=<<EON
 ;GlobalData
 ;SpecialNamespace
 ;EON

=head1 AUTHOR

 Martin Kutter <kutterma@users.sourceforge.net>

=head1 COPYING


=head1 Repository information

 $ID: $

 $LastChangedDate: $
 $LastChangedRevision: $
 $LastChangedBy: $

 $HeadURL: $

=cut
