button

Available options

acclabel, activated, active, bgcolor, border, borderinfo, coordinates, data, datagroup, enclosuresettings (enclose button only), focused, fontcolor, fontinfo, format, gradient, help, image, imagemode, itemlocation, itemnext, itemprevious, justify, keypress, linespacing, mouseover, next, printbgcolor, printfontcolor, printvisible, signature, signatureimage, signdatagroups, signdetails, signer, signformat, signgroups, signinstances, signitemrefs, signitems, signnamespaces, signoptionrefs, signoptions, signnamespaces, signpagerefs, size, transmitformat, transmititemrefs, transmititems, transmitnamespaces, transmitoptionrefs, transmitoptions, transmitpagerefs, type, url, value, visible, xformsenabled, xformsreadonly, xformsrequired, xformsvalid, xforms:submit, xforms:trigger, xforms:upload

Examples

Submit button

Buttons that trigger form processing requests must have a type option setting of submit or done. The definition for such a button might look like this:

   <button sid="submit_button">
      <value>Process Form</value>
      <fontinfo>
         <fontname>Helvetica</fontname>
         <size>18</size>
         <effect>bold</effect>
         <effect>italic</effect>
      </fontinfo>
      <type>done</type>
      <url>http://www.ibm.server.com/cgi-bin/formProcessor</url>
   </button>

Enclosure button

This button encloses an external file in the form. The action to enclose a file is enclose. The datagroup option identifies the list of datagroups, or folders, in which the user can store the enclosed file. An enclose button might take the following form:

   <button sid="enclose_button">
      <value>Enclose File</value>
      <fontinfo>
         <fontname>Helvetica</fontname>
         <size>18</size>
         <effect>bold</effect>
         <effect>italic</effect>
      </fontinfo>
      <type>enclose</type>
      <datagroup>
         <datagroupref>Images_Asia</datagroupref>
         <datagroupref>Images_Eur</datagroupref>
         <datagroupref>Images_SAmer</datagroupref>
      </datagroup>
   </button>

This button will allow users to enclose files into one of three datagroups (folders): Images_Asia, Images_Eur, Images_SAmer.

Usage details

1. The text displayed by the button is defined by: the value option if given and not empty; otherwise, the xforms:label if the button contains an XForms option.
2. To define an image for a button, either use the mediatype="image/*" attribute setting on the xforms:output option or use the XFDL image option.
3. When setting the size option of a button, the height and width of the button is based on the average character size for the font in use (set with the fontinfo option).
4. If you set the width for a button, but not the height, then the button will automatically grow to accommodate the text within the given width. In other words, the text will wrap to fit within the width specified, and the height will increase to accommodate the text.
5. If a button's image option points to a data item that does not exist or contains no data, then the button will display its value option instead.
6. If a button's image option points to a data item that dynamically changes its mimedata (but not its item sid), then the button will update the image it displays. For information on how to update an image by enclosing a new one, see the data option description.
7. The format option is available in buttons in order to force users to sign forms before submitting them.
8. If a button of type enclose, extract, display, or remove contains both a datagroup and a data option, the data option takes precedence.
9. There are two steps to making a signature button mandatory:
   • Assign the following elements to the format option: string and mandatory.
   • Set the button's value equal to the button's signer option setting.
   • Setting the format to mandatory specifies that the button must have a value setting that is not empty before the user submits the form. Equating the value to the setting of the signer option ensures that the only way a button's value is set is if somebody uses it to sign the form. (The signer option stores the identity of the person who signed the form using the button.)
   • If a button that wraps an xforms:trigger option has a type of anything other than select, the xforms:trigger is overridden.

Usage details: Signature buttons

1. A signature button is the means by which the user can sign a form. To make a button a signature button, set its type to signature.
2. A signature button can be set up to sign the whole form or just part of it by setting up filters on the signature, using the signdatagroups, signgroups, signitemrefs, signitems, signnamespaces, signoptionrefs, and signoptions options.
   Note: It is recommended that the triggeritem and coordinates options should be filtered out. These options change when a submission is triggered or when a user clicks an image button, respectively. Filtering out parts of the form that a subsequent user will change, including subsequent signatures and signature buttons and custom options that might change, should also be taken into consideration.
3. Signature buttons allow users to do the following:
   • Sign the form or portion of the form the button specifies.
   • Delete their signatures (a signature can be deleted only by the user whose signature it is, and if the signature is currently valid and not signed by some other signature).
   • View the signature and view the XFDL text of what the signature applies to.
4. All option references, calculations, and other formulas in any signed portion of a form are frozen once they have been signed. Their setting will be valued at the setting they contained at the moment when the signature was created. If the user deletes the signature, however, then the formulas will become unfrozen, and will change dynamically as normal.
5. Review the Usage details section in the signitemrefs, signoptionrefs, signnamespaces, and signdatagroups filters, and avoid using the other advanced filters unless a thorough security review has been performed.

   The usual options for other buttons (i.e. size, image, value) can also be used with signature buttons.