Dicop::Item::Template - an object defining Dicop::Item subclasses
use Dicop::Request::Template push @templates, Dicop::Item::Template->new ( class => 'Dicop::Item::Subclass', fields => "name => { maxlen => 128, def => 'some name' }", );
perl5.8.3, Dicop::Base, Dicop::Item, Dicop::Event
Exports nothing.
Templates are stored as text in a file, and are read upon startup to provide descriptions and rules for objects. They are used to check objects for being valid, as well as to restrict user input, construct automatically forms for objects to be added or edited.
Each template carries a list of valid fields for items of the class that the template is valid for, stored under fields.
fields
Each of these fields can have some properties that describe that field, for instance the default value, the maximum length etc.
In addition, the template knows the class of objects it belongs to, some help and descriptions etc.
{ class = Dicop::Item::SubSubSubclass help = "Some help text" description = "Some description text" fields => { name => { def => 'name', maxlen => 128, editable => 1, help => 'The name of the object', type => 'string' }, description => { maxlen => 256, editable => 1, help => 'A short description of the object/item', type => 'string', }, my_type => { selector => 'radiobutton', editable => 1, help => 'Select the type', type => 'int', addrank => 1, addindend => 1, editrank => 2, editindend => 0, valid => { 2 => 'Foo bar type', 5 => 'frobnozle', }, sort => 'name', }, my_int => { min => 1, max => 3, def => 2, help => 'a number between 1 and 3', }, my_virtual => { min => 1, max => 3, def => 2, editlen => 3, virtual => 2, }, include = "##include_someform.inc##" } fake_keys = "foobar" }
Here is the list of known keys for each template:
The class this template applies to. Example: 'Dicop::Item::Subclass'
A short description of this class.
A short help text that will appear when editing/adding objects of this class.
A commata seperated list of fake key names. See fields below.
A hash containing all the valid fields. See below for a list of "valid properties for each field".
Special code that should be inserted last on an add form.
Each field (see fields above) has a list of properties. Here follows an overview of all valid properties and a short description of their meaning:
The rank of this field on the add form. Fields with a low rank will be shown first, higher ranks later. Fields with no rank count will be shown last, in the order as determined by sorting their name.
The indend level of this field on the add form. Default is either the editindend or 0. Values of 0..3 work best.
A hash with additional options that should be selctable by the user on an add form.
addoption => { 0 => 'Add a new case', }
This would add a new selectable option named "Add a new case" with the value "0" to the list of allowed values when adding something.
The field can be changed, but is not automatically put on the edit form. This is for the support for extra fields, e.g. that sometimes are on the form, and sometimes not.
The default value for this field.
A short description of the field. When not defined, help is used instead. Since help is presented on the forms, description can be used to overwrite the description for the auto-doc feature.
help
description
If true, this field is editable and will appear on edit forms for this object type.
The indend level of this field on the edit form. Default is 0. Values of 0..3 work best.
A hash with additional options that should be selctable by the user on an edit form.
editoption => { 0 => 'Discard', }
This would add a new selectable option named "Discard" with the value "0" to the list of allowed values when editing something.
The rank of this field when creating an edit form. Lowest ranks come first, and all fields without any rank are added last, sorted by their name.
The rank of this field on the change/edit form. Fields with a low rank will be shown first, higher ranks later. Fields with no rank count will be shown last, in the order as determined by sorting their name.
filter => 'type_simple',
Defines a filter field name and a filter string, seperated by _. The field name of the item must match the filter string, or otherwise the item is not included in option lists on forms. The sample filter above would, for instance, only allow objects when $item->{type} eq 'simple'.
_
$item->{type} eq 'simple'
A short help text that describes the field.
min => 1,
The minimum value of the field. If set, it will be made sure that the value is at least min. Set min only for integer types!
min
max => 10,
The maximum value of the field. If set, it will be made sure that the value is not bigger than max. Set max only for integer types!
max
The maximum length in bytes of the contents of this field.
The name that will appear of forms without the trailing ':', e.g.:
name => 'Passwort'
If true, the field will not appear on add forms.
If true, the a little 'refresh' (refresh this form) button will appear next to this input field.
This will add '_refresh' to the selector name (see below).
selector
selector => 'radio',
The selector to use to build the entry form for the user. Usually this is autodetermined depending on type (see below), but can be overridden here. Valid selectors depend on the templates that are available (editfield_radio.inc must be available if selector = 'radio'>), but some examples are below:
type
editfield_radio.inc
selector =
radio only one button active at a time select a dropdown box of selections, only one at a time check checkbox(es) that allow multiple selections
If set, the given a list of items (either via valid or like case_id) will be sorted on their strings (e.g. the things the user can select via the dropdown box).
The type. Here is a list of currently valid types:
string for general strings, numbers etc int for integers float for floats file a file (or an string) Fields of this type will carry a 'Browse' button on add/edit forms dir like file, but the user can select a directory time time in seconds since 1970 foo_id ID of an object of type 'foo' Class::Name an object of the class 'Class::Name' (this type is determined by the '::'!)
If unsure, use type 'string'.
Specifiy a list of valid values for that field. There are three ways to accomplish that:
A scalar:
valid => 'some_method_that_returns_an_array_ref',
The method named must return either an array ref or a hash ref. These arrays or hashes are build like the two other examples below.
The second way is a hash with a list of keys that map valid values for this field to their descriptions for a form:
valid => { 3 => 'Running', 4 => 'Solved', 6 => 'Suspended' }
This would allow the user to select between the three settings 'Running', 'Solved' and 'Suspended' and nothing else. The selection will be in a list box and only one of the options can be selected at any time.
The third way is an array ref like this:
valid => [ 0, bit0 => 'Sunshine', 1, bit1 => 'Rain', 2, bit2 => 'Clouds', ],
With this, multiple checkboxes will be used to let the user select each option on its own. The first column is the bit number, the second the name of the checkbox that will appear on the edit form, and the last is the text the user will actually see beside each checkbox.
In short:
A hash will let the user select only one item at a time. By default this is a dropdown list, but this can be overriden with selector (see above).
An array will let the user select multiple items together. Per default this will be a list of checkboxes.
If true, makes the field virtual, e.g. it is not present in the object. This is usefull for fields that only appear on the add form. Without 'virtual', the field would be included in fields() and thus the code replacing it in templates would try to access a no-longer existing field.
Get/set error message. Returns empty string in case of no error.
my $class = $template->class();
Return the class of objects this template belongs to.
my $include_text = $template->include();
Return text to be included into form.
my $description = $template->description();
Return a short description for all objects that are defined by this template.
my $help_text = $template->help();
Return a short help text that helps the user when adding this object.
$template->init_object ($object);
Init fields in that object with default values.
$template->check_field ($object, $fieldname);
Check field in an object after a change to still conform to rules, modifying it if neccessary.
$template->construct_field ($object, $fieldname);
Turn field from text string into references to object.
my @changeable_fields = $template->editable_fields();
Returns a list of all fields that are changeable, but should not appear automatically on the edit form.
my @edit_form_fields = $template->editable_fields();
Returns a list of all fields that are editable and must appear on the edit form.
my @add_fields = $template->addable_fields();
Returns a list of all fields that the user must fill in to add an object defined by this template.
my @fields = $template->fields();
Returns a list of all fields that the template has.
my @fields = $template->fields_of_type('bool');
Returns a list of all fields that match the given type.
$field = $template->field('somefieldname');
Teturn a field as a hash containing things like { type => 'string', minlen => 1, }.
{ type => 'string', minlen => 1, }
None known yet.
(c) Bundesamt fuer Sicherheit in der Informationstechnik 1998-2006
DiCoP is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.
See http://www.bsi.de/ for more information.
To install Dicop::Base, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dicop::Base
CPAN shell
perl -MCPAN -e shell install Dicop::Base
For more information on module installation, please visit the detailed CPAN module installation guide.