Field instances are used to represent extension parameters.
A Field can read and write XML
representations of values, generate HTML representations of values,
or present HTML forms that permit the user to update the value of
the field. There are several classes derived from
Field that you can use in extension classes.
If none of those classes satisfy your needs, you can create a new
class derived from Field.
A Field may have a title, which is used
when presenting the Field to the user. The
title need not be a valid Python identifier. For example, the
RSHTarget class has a host
parameter whose title is Remote Host Name.
When accessing an instance of this class, the
programmer refers to self.host. In the GUI,
however, the user will see the value presented as Remote
Host Name.
A Field may have an associated
description, which is a longer explanation of the
Field and its purpose. This information is
presented to the user by the GUI.
A Field may have a default value. The
default value is used if no argument is provided for the
field when the extension is initialized.
This example code from RSHTarget shows
how a Field is constructed:
remote_shell = qm.fields.TextField(
title="Remote Shell Program",
description="""The path to the remote shell program.
The name of the program that can be used to create a
remote shell. This program must accept the same command
line arguments as the 'rsh' program.""",
default_value="ssh")
See the internal documentation for Field
for complete interface documentation.
QMTest comes with several useful field classes:
IntegerField stores integers.
TextField stores strings.
EnumerationField stores one of a
set of (statically determined) possible values.
ChoiceField stores one of a
set of (dynamically determined) possible values.
BooleanField stores a boolean value.
TimeField stores a date and time.
AttachmentField stores arbitrary
data.
SetField stores multiple values of the
same type.
TupleField stores a fixed number of other fields.
Before writing any code, you should decide what kind of data
your field class will store. For example, will your field class
store arbitrary strings? Or only strings that match a particular
regular expression? Or will your field class store images? Once
you have decided this question, you can write the
Validate function for your field class. This
function checks an input value (a Python object) for validity.
Validate can return a modified version of the
value. For example, if the field stores strings, you could choose
to accept an integer as an input to Validate
and convert the integer to a string before returning it.
The FormatValueAsHtml function produces
an HTML representation of the value. You must define this function
so that the GUI can display the value of the field. The
style parameter indicates how the value
should be displayed. If the style is new or
edit, the HTML representation returned should be
a form that the user can use to set the value. If the user does
not modify the form, ParseFormValue should
yield the value that was provided to
FormatValueAsHtml.
The MakeDomNodeForValue and
GetValueFromDomNode functions convert values
to and from XML format. The FormatValueAsText
and ParseTextValue functions convert to and
from plain text. As with FormatValueAsHtml
and ParseFormValue, these pairs of functions
should be inverses of one another.
The ParseTextValue,
ParseFormValue, and
GetValueFromDomNode functions should use
Validate to check that the values produced are
permitted by the Field. In this way,
derived classes that want to restrict the set of valid values, but
are otherwise content to use the base class functionality, need
only provide a new implementation of
Validate.
All of the functions which read and write
Field values may raise exceptions if they
cannot complete their tasks. The caller of the
Field is responsible for handling the
exception if it occurs.