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.

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:

class

The class this template applies to. Example: 'Dicop::Item::Subclass'

description

A short description of this class.

help

A short help text that will appear when editing/adding objects of this class.

fake_keys

A commata seperated list of fake key names. See fields below.

fields

A hash containing all the valid fields. See below for a list of valid properties for each field.

include

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:

addrank

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.

addindend

The indend level of this field on the add form. Default is either the editindend or 0. Values of 0..3 work best.

addoption

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.

changeable

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.

def

The default value for this field.

description

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.

editable

If true, this field is editable and will appear on edit forms for this object type.

editindend

The indend level of this field on the edit form. Default is 0. Values of 0..3 work best.

editoption

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.

editrank

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.

editlen

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

	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'.

help

A short help text that describes the field.

min

	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!

max

	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!

maxlen

The maximum length in bytes of the contents of this field.

name

The name that will appear of forms without the trailing ':', e.g.:

	name => 'Passwort'

noadd

If true, the field will not appear on add forms.

refresh

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:

	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

sort

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).

type

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'.

valid

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.

virtual

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.

error

Get/set error message. Returns empty string in case of no error.

class

	my $class = $template->class();

Return the class of objects this template belongs to.

include

	my $include_text = $template->include();

Return text to be included into form.

description

	my $description = $template->description();

Return a short description for all objects that are defined by this template.

help

	my $help_text = $template->help();

Return a short help text that helps the user when adding this object.

init_object

	$template->init_object ($object);

Init fields in that object with default values.

check_field

	$template->check_field ($object, $fieldname);

Check field in an object after a change to still conform to rules, modifying it if neccessary.

construct_field

	$template->construct_field ($object, $fieldname);

Turn field from text string into references to object.

changeable_fields

	my @changeable_fields = $template->editable_fields();

Returns a list of all fields that are changeable, but should not appear automatically on the edit form.

editable_fields

	my @edit_form_fields = $template->editable_fields();

Returns a list of all fields that are editable and must appear on the edit form.

addable_fields

	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.

fields

	my @fields = $template->fields();

Returns a list of all fields that the template has.

fields_of_type

	my @fields = $template->fields_of_type('bool');

Returns a list of all fields that match the given type.

field

	$field = $template->field('somefieldname');

Teturn a field as a hash containing things like { 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.