Form Fields are utility clases provided for allowing easy communication of modules and administration interface.
It helps to define the administration level forms that will be used to manage different modules (service providers, services, authenticators, transports, ...)
All modules that needs to be presented to admin users, use UserInterface as one of their base class.
Think that not all interfaces needed by different modules need a direct representation at administration interface level, (for example, UserDeployment do not need to be managed by administrators, nor publications, both corresponding to service modules).
This class contains the representations of fields needed by UDS modules and administation interface.
This contains fields types, that modules uses to make a form and interact with users.
The use of this provided fields are as follows:
The Module is descendant of “BaseModule”, which also is inherited from this class.
At class level, we declare the fields needed to interact with the user, as this example:
class AuthModule(Authenticator):
# ...
# Other initializations
# ...
users = gui.EditableList(label = 'Users', tooltip = 'Select users',
order = 1, values = ['user1', 'user2', 'user3', 'user4'])
passw = gui.Password(label='Pass', length=32, tooltip='Password',
order = 2, required = True, defValue = '12345')
# ...
# more fields
# ...
At class instantiation, this data is extracted and processed, so the admin can access this form to let users create new instances of this module.
This represents a check box field, with values “true” and “false”
The values of parameters are inherited from InputField
The valid values for this defvalue are: “true” and “false” (as strings)
Example usage:
# Declares an check box field, with label "Use SSL", order 3, # tooltip "If checked, will use a ssl connection", default value # unchecked (not included, so it's empty, so it's not true :-)) ssl = gui.CheckBoxField(label = _('Use SSL'), order = 3, tooltip = _('If checked, will use a ssl connection'))
This represents a simple combo box with single selection.
The values of parameters are inherited from InputField
ChoiceField needs a function to provide values inside it.
We specify the values via “values” option this way:
Example:
choices = gui.ChoiceField(label="choices", values = [ {'id':'1', 'text':'Text 1'}, {'id':'xxx', 'text':'Text 2'}])You can specify a multi valuated field via id-values, or a single-valued field via id-value
We can override choice values at UserInterface derived class constructor or initGui using setValues
There is an extra option available for this kind of field:
- fills: This options is a dictionary that contains this fields:
- ‘callbackName’ : Callback name for invocation via the specific
method xml-rpc. This name is a name we assign to this callback, and is used to locate the method when callback is invoked from admin interface.
‘function’ : Function to execute.
This funtion receives one parameter, that is a dictionary with all parameters (that, in time, are fields names) that we have requested.
The expected return value for this callback is an array of dictionaries with fields and values to set, as example show below shows.
- ‘parameters’ : Array of field names to pass back to server so
it can obtain the results.
Of course, this fields must be part of the module.
Example:
choice1 = gui.ChoiceField(label="Choice 1", values = ...., fills = { 'target': 'choice2', 'callback': fncValues, 'parameters': ['choice1', 'name']} ) choice2 = ghui.ChoiceField(label="Choice 2")Here is a more detailed explanation, using the VC service module as sample.
class VCHelpers(object): # ... # other stuff # ... @staticmethod def getMachines(parameters): # ...initialization and other stuff... if parameters['resourcePool'] != '': # ... do stuff ... data = [ { 'name' : 'machine', 'values' : 'xxxxxx' } ] return data class ModuleVC(services.Service) # ... # stuff # ... resourcePool = gui.ChoiceField( label=_("Resource Pool"), rdonly = False, order = 5, fills = { 'callbackName' : 'vcFillMachinesFromResource', 'function' : VCHelpers.getMachines, 'parameters' : ['vc', 'ev', 'resourcePool'] }, tooltip = _('Resource Pool containing base machine'), required = True ) machine = gui.ChoiceField(label = _("Base Machine"), order = 6, tooltip = _('Base machine for this service'), required = True ) vc = gui.HiddenField() ev = gui.HiddenField() # ....
Editables list are lists of editable elements (i.e., a list of IPs, macs, names, etcc) treated as simple strings with no id
The struct used to pass values is an array of strings, i.e. [‘1’, ‘2’, ‘test’, ‘bebito’, ...]
This list don’t have “selected” items, so its defvalue field is simply ignored.
We only nee to pass in “label” and, maybe, “values” to set default content for the list.
Keep in mind that this is an user editable list, so the user can insert values and/or import values from files, so by default it will probably have no content at all.
Example usage:
# ipList = gui.EditableList(label=_('List of IPS'))
This represents a hidden field. It is not displayed to the user. It use is for keeping info at form needed by module, but not editable by user (i.e., one service can keep info about the parent provider in hiddens)
The values of parameres are inherited from InputField
These are almost the same as TextFields, but they do not get displayed for user interaction.
Example usage:
# Declares an empty hidden field hidden = gui.HiddenField()After that, at initGui method of module, we can store a value inside using setDefValue as shown here:
def initGui(self): # always set defValue using self, cause we only want to store # value for current instance self.hidden.setDefValue(self.parent().serialize())
Class representing an simple input field. This class is not directly usable, must be used by any inherited class (fields all of them) All fields are inherited from this one
Any other paremeter needed is indicated in the corresponding field class.
Also a value field is available, so you can get/set the form field value. This property expects always an string, no matter what kind of field it is.
Take into account also that “value” has precedence over “defValue”, so if you use both, the used one will be “value”. This is valid for all form fields.
Returns the dictionary with the description of this item. We copy it, cause we need to translate the label and tooltip fields and don’t want to alter original values.
Multichoices are list of items that are multi-selectable.
“defvalue” is expresed as a comma separated list of ids
This class do not have callback support, as ChoiceField does.
The values is an array of dictionaries, in the form [ { ‘id’ : ‘a’, ‘text’: b }, ... ]
Example usage:
# Declares a multiple choices field, with label "Datastores", that is editable, with 5 rows for displaying # data at most in user interface, 8th in order, that is required and has tooltip "Datastores where to put incrementals", # this field is required and has 2 selectable items: "datastore0" with id "0" and "datastore1" with id "1" datastores = gui.MultiChoiceField(label = _("Datastores"), rdonly = False, rows = 5, order = 8, tooltip = _('Datastores where to put incrementals'), required = True, values = [ {'id': '0', 'text': 'datastore0' }, {'id': '1', 'text': 'datastore1' } ] )
This represents a numeric field. It apears with an spin up/down button.
The values of parameres are inherited from InputField
Additionally to standard parameters, the length parameter indicates the max number of digits (0-9 values).
Example usage:
# Declares an numeric form field, with max value of 99999, label # "Port", that is required, # with tooltip "Port (usually 443)" and order 1 num = gui.NumericField(length=5, label = _('Port'), defvalue = '443', order = 1, tooltip = _('Port (usually 443)'), required = True)
This represents a password field. It appears with “*” at input, so the contents is not displayed
The values of parameres are inherited from InputField
Additionally to standard parameters, the length parameter is a recommended one for this kind of field.
Example usage:
# Declares an text form field, with label "Password", # tooltip "Password of the user", that is required, # with max length of 32 chars and order = 2, and is # editable after creation. passw = gui.PasswordField(lenth=32, label = _('Password'), order = 4, tooltip = _('Password of the user'), required = True)
This represents a text field.
The values of parameters are inherited from InputField
Additionally to standard parameters, the length parameter is a recommended one for this kind of field.
You can specify that this is a multiline text box with multiline parameter. If it exists, and is greater than 1, indicates how much lines will be used to display field. (Max number is 8)
Example usage:
# Declares an text form field, with label "Host", tooltip # "Host name for this module", that is required, # with max length of 64 chars and order = 1, and is editable # after creation. host = gui.TextField(length=64, label = _('Host'), order = 1, tooltip = _('Host name for this module'), required = True) # Declares an text form field, with label "Other", # tooltip "Other info", that is not required, that is not # required and that is not editable after creation. other = gui.TextField(length=64, label = _('Other'), order = 1, tooltip = _('Other info'), rdonly = True)