GUIXML widgets reference
When designing a new page layout using GUI XML, (as was done earlier in this tutorial as part of "Developing the Custom Module"), there are a number of available widgets. For the purposes of the GUI design for our demo module, only TextFields with their associated labels were required (refer back to Figure 22).
This section describes all the available widgets and their configuration when developing custom Java™ modules.
There are 8 widget types available for use in a Page Layout, as shown in Figure 63 below.
Figure 63. Available GUI Elements
Following is a table showing the various widgets and their configuration properties. There are some commonalities among the widgets. For example:
- name - The name is always required, and represents the name of the configuration parameter. This is the same name that you use to retrieve the parameter value in your module code. See example in Listing 2.
- required - I bet you can figure this one out.
- modes - This acts as a filter, and is a comma-separated listed of STS module modes that the module may operate in and use this parameter. The set of modes we are talking about is the set of operational modes that the module can be configured in when added to a module chain (i.e. validate,map,issue,exchange,other,authenticate,authorize). The console will only prompt for the parameter when the module is configured in a listed mode. For example it makes no sense to prompt for a "signature validation key" for a module that is in
issuemode. Similarly it doesn't make sense to prompt for a "signing key" for a module in
validatemode. The console only prompts for the parameters required for the mode the module is operating in.
Non-obvious properties for the widgets are described in detail in the table.
|Widget Type||Description||Configurable Properties||Configuration Notes|
|TextField||Text input box that allows users to enter text on a single line.||name*|
The valueType for a text field is not currently used, but the intent is to eventually use it for validating entry. For now we recommend you set it to |
The multivalued attribute allows a
The password attribute determines if the characters on the display are replaced with *. There are two main differences between using this and a PasswordField widget. First, the value is stored in plaintext when using a
The displayWidth attribute is an integer that controls the default width of the input string. The default is 60 and is suitable for most purposes.
The displayValue attribute allows you to pre-populate the text field with a default value.
The issuerField attribute is a special attribute that is used internally by TFIM to occasionally hide a text field attribute from the display when collecting parameter information in wizards. For example the issuer attribute for generating SAML assertions is generally defaulted to the Identity Provider ID, and for simplifying the amount of data collected it is not prompted for during wizard federation creation. It is not recommended that you use this field for your own token modules.
|TextArea||Text input area that allows the user to enter large amounts of text across multiple lines.||name*|
|This is a multi-line text entry field. You can distinguish the lines in your code by looking at the |
|CheckBox||A check box (tick box) that represents an option to the user. The user is permitted to make multiple selections from a number of options.||name*|
|The checked attribute determines if the checkbox is pre-selected as checked.|
|KeyIdentifierInput||Allows the user to enter a key identifier. A key identifier represents a public or private key, and consists of a keystore, plus the label of the key within that keystore.||name*|
This complex widget consists of a set of components which allow you to pick a key. It looks something like this:|
The enabledName attribute describes an optional configuration parameter name. If provided, the widget will display a checkbox to describe if the function associated with this key is enabled. If no enabledName value is provided, a key is to always be prompted for. If a value is provided, a checkbox will appear (like the example above which has the label "Really need a key?"). When the checkbox is selected, the entire rest of the key widget is enabled, when it is not selected, the rest of the key widget is disabled. The tricky part here is providing a label for the checkbox. This is done by adding a
Note that this ComponentLabel is in addition to the one which describes the label for the key identifier widget itself (defined as "My KeyID" above). To define the ComponentLabel for the actual key identifier widget, set the for: attribute of the ComponentLabel to keyidentifier, or just leave it blank.
The first element in the main portion of the key widget (labeled Keystore) is a drop-down list box of keystore names. This will be filtered based on the type of keys selected in the keyTypes parameter.
The keyTypes parameter is a comma-separated list of one or more of the following values:
The second element in the main portion of the key widget is for the Keystore Password, which is the password used to open the keystore you have selected.
The third element in the main portion of the key widget is the List Keys button, and the table which shows all the listed keys. The List Keys button should only be pressed after the password is entered, and the keys will only be listed if the password is correct. Each of the keys in the keystore which match the keyTypes filter will be shown.
The last part of the main portion of the key widget is actually a variable set of drop-down list boxes which permit you to select which portions of the key are included in the
For each attribute you will be prompted for one of the following values:
The checked attribute controls whether or not the main portion widget is enabled, and basically pre-checks the optional parameter defined by the checkedName attribute for enabling or disabling key selection. It doesn't make sense to set this attribute to false unless you are definitely including the enabledName attribute and want it to be disabled by default. A good example where TFIM uses this combination internally is enabling signatures for the TAM Credential module.
The only other attribute not yet mentioned is validateUseKeyInfoName. This is an advanced configuration parameter we do not recommend using in your own modules (leave it blank). This parameter again represents an optional configuration parameter name, which if provided, causes the key widget to prompt for an additional key selection options (not shown in our example) via a radio button group at the very top of the main part of the widget. The radio buttons allow you to select whether or not a key to be used for signature validation should come from the KeyInfo inside an XMLSignature element itself, or from a user-selected key from the widget (as shown in our example). If signature validation is done from KeyInfo information, then no key is selected from a keystore, and instead we prompt for an optional subject DN expression for allowable X509 certificates. The semantics of this property are very particular to TFIM internal API options for signature validation, and it is more likely that for your own module you would use a combination of other widgets to prompt for these style of options rather than this particular attribute of KeyIdentifierInput.
|ComboBox||A drop down list box containing a list of existing options that can be selected from.||name*|
|The editable attribute describes whether or not the user can put in their own text rather than selecting one of the built-in options. The widget allows you to add an Options element, and to this you add one or more child Option elements. Each Option has a display label and value.|
|TDIModuleInput||*For internal use only as part of the TDI mapping module.||name*|
|Do not use this widget in your own modules.|
|PasswordField||A pair of text input fields where the entered characters will be obfuscated so that they do not appear on the screen in clear text.||name*|
The displayWidth has the same meaning as for a TextField widget.
The widget will automatically prompt for the same value twice, and will validate that the input is the same for both entry fields. It will also automatically obfuscate the resulting value before storing it in configuration. When reading a password from configuration in your module code, it is necessary to call the method
|RadioButtonGroup||A radio button (option button) allows the user to choose one of a predefined set of options.||name*|
|A RadioButtons element is added to a RadioButtonGroup, and under that an ordered list of RadioButton elements are added to build the list of options. Each RadioButton has both a label and a value (as would be expected). The ordered list is zero-indexed, so setting the defaultButtonIndex to 0 will pre-select the first radio button.|
NOTE: * indicates a required field.