The sections of an issue form

All issue forms consist of the following...

• A fixed collection of attributes, presented as on-screen entry fields, selection boxes, toggle switches, etc. (collectively known as widgets).
• Two text panes, free format text area, typically used to contain the initial definition of the issue to be resolved and the resolution.

The attributes, as well as the initial text which may appear in either of the two text panes, are controlled by a set of configuration files. These configuration files are typically defined and administered by a single person. and are discussed elsewhere in this manual.¹

An example of an issue form is shown below.

The attribute section

Attribute types

The attribute section² of an issue form should be extremely easy for a user to navigate, particularly with any prior exposure to a window-based GUI. In brief, the types of attributes which may be presented are...

• Text fields for the entry of a single line of textual information.
• Several types of widgets for choosing items from a fixed list of options. Some allow selection of only a single option at a time, while others allow the selection of a mixed subset of the presented options.
• A checkbox, which you can either set, or leave un-set.
• A state selector, which functions as a special purpose one-of-many type widget, typically employed for denoting the life-cycle state of an issue. This widget will always be initially presented with the first option chosen at the time a new issue is created.
• A date/time field. It is presented much like a text field widget, and although you are allowed to type directly into the field, most users prefer to work with the popup associated with it. By selecting the button to the left of the field, a panel similar to the one below will appear, offering a more controlled means of entering the data.
  
  
  

The Time pulldown menu includes some convenient shortcuts such as Tomorrow, One week from now, etc.

• A label. This provides form separators or information for the user to help identify the data to be entered.

Conditional attributes (sensitivity)

It is also possible that Razor has been configured to have some of the attributes (widgets) be conditionally grayed out, based on the settings of other attributes on the form. All of the data will still be available for inspection; having a field be insensitive only makes it so that it can not be modified. For example, once an issue has entered a certain state, you may want to prevent users from modifying its priority. See "Conditional attributes (sensitivity)" on page 204 for more details.

Rules and restrictions

A requirement imposed by Razor is that the first field on the issue form be a text field³, and that users actually supply some text such as a brief description of the issue. This string is what will is shown on the main display. Local conventions and administration may have additional soft and hard rules concerning what type of information you are encouraged to put on the form.

In this context, a "soft" rule is one purely of local convention. It is what you and your team members have agreed upon, but there is nothing programmatically enforcing your adherence. A "hard" rule is one which Razor will attempt to force you to follow. These are established through the optional attachment of shell scripts⁴ to the Ok/Apply buttons. If a user has violated a "hard" rule, then an additional error popup will appear with information about what the user may have done wrong.

If there is a STATE attribute on the issue form, new issues are always entered into the database in the first state. Also, although many issues can be viewed simultaneously, only one can be created or modified at a time.

Text panes

Working with text panes

Unlike the single line text fields which may be in the top of an issue form, these text sections⁵ are effectively of infinite length. You are free to expand on them and fill them out as you see fit. The normal paradigms of using the mouse to select the insertion point, etc. are honored.

Additionally, it is possible to define hot-keys to perform programmatic functions within a text pane, as well as control the functionality of certain key combinations such as ^U and ^E. This provides the opportunity for a great deal of customization in how you can enter information into a text pane.⁶

Including files into the text panes

New issue forms will appear with some collection of initial text, as defined by your site's configuration files. You are free to edit and add to whatever is already in those fields.⁷

Occasionally you may wish to include the contents of another file directly into one of the text panes. It may contain source code, an error log, or some other information you find useful. To facilitate this, a special extension to the text fields has been provided. By holding down the menu button on the mouse, a menu will appear allowing you to bring up the panel shown below.




After you've maneuvered to find the text file you want included, select either Ok or Apply at the bottom of the form. The contents of the selected file will be inserted directly into the text pane where you had last left the insertion point.

¹ See "Configuring the issues program" on page 204.
² See "Attribute types defined" on page 189.
³ The title field must contain at least one non-blank character. This is especially important if the first field is readonly, then it must be properly filled in with a preload script.
⁴ "Attaching scripts to buttons" on page 235 has a lot of detail in this regard.
⁵ Refer to "Options" on page 202 for more details on the types of controls available for text panes.
⁶ For more information, see "Special control over text widgets" on page 279
⁷ See "Pre-loading information into the text panes" on page 210.