Edit1 What are Forms?
A form is an object that defines a user interface for viewing and editing objects belonging to a particular class. Each form is bound to a class and can only be used to view and edit objects that belong to that class. Forms are used by the IssueNet client to display and edit individual objects. For example, when the user double clicks on an object in a list, the IssueNet client locates the appropriate form for that object and opens it. The form designer in the Architect is used to create and edit forms.
Edit1.1 Plug-in/Form Type
The plug-in and form type properties of the form determine the underlying .NET class used for the form. The underlying .NET class determines the type of form instances that are created. It can be thought of as a template for the form, because it provides a basis or starting point for customizing the form. The default form type is ObjectFormBase, which is a blank form. Other form types are derived from ObjectFormBase such as MasterDetailForm and IssueForm. When creating a new form, you can choose any available form type as a starting point. For example, you might create a form for editing issues that is bound to ObjectFormBase instead of IssueForm if you wanted to start with a blank form instead of the stock IssueForm.
The plug-in and form type properties of a form allow users to create their own compiled .NET forms and use them in IssueNet. This is useful in cases where users need to use a control that is not included in the IssueNet form designer. It is also very useful for creating reusable form templates that are used as the basis of several similar forms.
Edit1.2 Class Binding
Each form must be bound to a class of objects. The class binding determines the type of objects that the form can display and edit. Controls on the form can bind to the properties of the class.
Edit1.3 Condition
A condition can be associated with a form in order to determine when the form should be available to the user. The condition can test any variable maintained by the session. For example, you can associate a condition with a form that tests the group membership of $(CurrentUserID) so that the form is only available to users belonging to a particular group. The condition can also test any property of the object that is being opened (i.e. double-clicked), which is assigned to the variable $(CurrentObject). For example, you can have a unique form for editing issues that are in a status of “New”.
Edit1.4 Layout
The form layout specifies the appearance of the form. The layout determines which controls appear on the form, the properties controls are bound to, and their appearance and behavior. The form designer in the Architect provides a What You See is What You Get (WYSIWYG) user interface for editing the form layout. Controls can be dragged and dropped onto the form and their properties can be set using a property editor.
Edit1.5 Script
Each form can have a script associated with it. The script can handle events that are fired by the form and controls on the form. Scripts are used to customize the behavior of the form in response to events that occur when the user is editing the form.
Edit2 Creating and Editing Forms Overview
The Layout tab in the IssueNet form designer provides a WYSIWYG environment for designing the appearance of forms as well as the class property loaded by each control. This section is designed to help you master the fundamentals of IssueNet designing form layouts.
A comprehensive discussion of all the available form and control properties is beyond the scope of this document, however, because the IssueNet form layout environment is based on the form layout environment used in Visual Studio .NET, the Visual Studio documentation can serve as an additional reference and guide for many tools and techniques available in the IssueNet layout environment.
The three basic design tools are:
- The Form Toolbox- The Form Tool box lists the controls IssueNet provides for form design. To add a control to a form, drag and drop the control from the list onto the region of the form where you want to locate it.
- The Layout tab-The Layout tab allows you to select a form element you want to edit, allows you to re-size form elements, and allows you to position elements on the form.
- The Form Properties pane-The Form Properties pane allows you to set the properties for the selected form element in the layout tab.
Edit2.1 Adding a Control to a Form
There are many different controls you can add to a form and even more properties of a form and its controls you can edit in the form designer. However, the most common operation is adding a control to a form and binding the control to a class property to make that property available to users when they use the form.
The first step is to drag the correct type of control onto the form by selecting the control in the Form Toolbox and dragging it onto the form layout to the location you want it to have. You will want to select the control type based on the type of property you want to bind the control to. For example, if the property you intend to bind the control to is a string you will want to select a text box control, time stamp text editor control, or a masked edit control. If the property is linked to an item list such as Issue Status, you will want to select a combo box control.
Once you have added the control to the form you can begin to edit its properties in the Form Properties pane. The most important property you will want to set is the Member Name property in Form Properties pane. This property determines which class property the control is bound to. The available class properties are based on the class the form is bound to in the Class Binding field of the General tab. Once you have added a control and set the member name, users will be able see the control and view and set the value of the property when they load the form.
Keep in mind that some controls featured in the Form Tool box are not bound to a class property. The Button control, for example, is designed to be used in conjunction with forms scripts and is never associated with a class property.
Edit2.2 Adding Form Labels
Once you have added a control to a form, it is common to add a label to identify the control on the form. To add a label to a form you drag it to the form from the Form Toolbox and resize it as you would any other control.
Once you have added the label the text displayed to the user will need to be set. You can set a text value by placing an entry in the Text property located in the Form Properties pane. This property is useful for viewing the display of the label as you design the form, and can be used for the value displayed when the form is loaded by a user. However, a more reliable method is setting the label to display the display name of the class property it represents. By setting the display value of the label to the display the display value of the class property, the label will always use the correct value even if the display name of the property is changed either locally or as part of a class override. As a result, this method is more reliable and reduces form maintenance if class definitions change.
To set a label to display the display value of a class property, set the “Member Binding property of the label to Display Value and set the Member Name property to the name of the class property you want the label to represent. For example, if you want a label to display the display name of the property Status, you would simply set the Member Binding to Display Value and select Status from the Member Binding list.
Edit2.3 Adding and Removing Tabs
Every form has a form type set in the General tab which defines the basic form layout. Many form types are a tabbed style which allows you to add controls on multiple tabbed sections. You can use the form designer to add and remove tabs from tabbed from types.
To add a tab, select an existing tab label or click in the horizontal region where the tab label are aligned, and click on the Add Tab link at the bottom of the Form Properties pane. To remove a tab, select the tab label and click on the Remove Tab button at the bottom of the Form Properties pane.
Edit3 Forms Best Practices
When designing a from layout there are several control properties and best practices that can greatly simplify the form design process, prevent simple mistakes, and allow you to take full advantage of the of the features of the forms designer – particularly if you are not an experienced user of a standard forms design environment. The purpose of this section is to familiarize you with the most common and useful form design features and best practices you should keep in mind as you create and modify forms.
Edit3.1 Using Controls for Large Text Fields
There are two controls that can be used for text entries that exceed a single line. For simple text entry fields the Text Box control can be used with the Multiline property set to true. However, the Text Box control does not offer options for time stamps, protected text, and does not produce a scroll bar for entries that exceed the size of the control – users must use the keyboard or mouse within the box to scroll.
For the options to use timestamps and protected text as well as a scroll bar, use the TimeStampTextEditor control. By setting the TimeStampTemplate property to a value such as the default; “FROM: $(CurrentContactID->FormattedName) DATE: $(LocalNow) $(LocalTimeZone)” and setting the TimeStampEnabled property to true, you can have a time stamp in this format placed before all text entries. By setting the ProtectedTextEnabled option to true, the control will convert to a split control where the bottom half allows new entries to be added and the top half displays previous entries in a read only format.
Edit3.2 Setting Default Values
Most controls allow setting a default value by setting a Text or EditText property. Although this is a useful method for setting default values for each form, it is often more useful to set a default value by editing the default value property of the class property the control will be bound to. Setting default values on the class property as opposed to the form, ensures that all forms that have that property will always have the same default value and reduce maintenance when class properties change. However, if setting a default value for a specific form is desired, the Text and EditText properties may be the correct choice.
Edit3.3 Setting the Empty Item Property
In some instances it is useful to provide a combo box which allows the user to set the value to nothing. For example, if a field for issue Severity is optional it makes sense to allow a user to set the value to nothing even if a value has been previously selected. Similarly, if you are adding a combo to a search form you always want to allow the user to set a previous selected value to nothing in order to widen their search criteria. To allow a combo box to be set to nothing, set the IncludeEmptyItem property to true and set any desired text as the empty item label in the EmptyItemName property.
Edit3.4 Setting the Drop Down Style to Allow User Defined Entries in Combo Boxes
In some instances it is useful to provide a combo box which provides a user with a list of choices but also allows them to enter their own text in the control. Enable a combo box control for this type of use, set the DropDownStyle property of the ComboBox control to DropDown from the default value DropDownList.
Edit3.5 Setting the Anchor Property for Proper Form Layout
If a control added to a form does not maintain the desired position, particularly when the form is re-sized, try adjusting the Anchor property of the control. This property and the Docking property control how a control resizes itself and moves on the form. There are many different way to set these properties. However, a good guide is to select an existing control on the form and copy those settings.
Edit3.6 Setting Useful Control Names
When designing a form is it useful to change the default name property to a value that will allow you to easily identify the control. For example, when adding combo box for a property named “Frequency” change the default control name of “ComboBox” to something like “cbFrequency”. Intuitive control names make form scripts much easier to create and maintain since it is the control name which allow you identify it in the script and the script editor fields which help you pick controls and control properties.
Edit4 Additional Resources