Setting Dialog Control Properties

Description

Select each control in the Control Types list to display its Control Properties menu. There are many optional properties for each control. The default values for these properties produce a useable starting configuration for your dialog. This means that you can largely ignore these optional properties when you are learning to build dialogs or you expect to gradually refine your design in later revisions. A dialog component has few requirements. You are free to add and format controls (of any type) as you wish. The ((|#Data_Type|Data Type)) setting informs the page how to validate input to a control. It does not affect the type of data generated by a control, which is always "character" data.

Select the Control Type

The types of controls that you can place on a dialog are:

• ((|#AdvancedButton_Properties|Advanced button)) - a free form button that can set a variable's value or run a script

• Blurb - a static text control that does not have a heading

• ((|#Calendar_Properties|Calendar)) a monthly calendar

• ((|#CheckBox_Properties|Check box)) - allowing a selection from a list of values

• ((|#Custom_Control_Properties|Custom)) - allows you to define the content of the dialog cell with Xbasic and HTML

• ((|#DropDownBox_Properties|Drop Down Box)) - a list box that may appear as a list or combo box, and allowing a selection from a list of values, which is often retrieved from a table

• Heading - a static text control without a heading that spans the width of the dialog

• ((|#Hidden_Control_Properties|Hidden)) - a mechanism for creating and storing variables in the dialog component

• ((|#Label_Properties1|Label)) - a read-only control suitable for character, numeric, and date/time data

• ((|#Image_Properties|Image)) - displaying either embedded or linked images

• ((|#Link_Properties|Link)) - a hyperlink, which may open another page or select a record to display

• ((|#Lookup_Properties|Lookup)) - a variation on a textbox or textarea control that retrieves one or more field values from a grid

• ((|#RadioButton_Properties|Radio button)) - allowing a selection from a list of values

• ((|#Tab_Control_and_Tab_Pane_Properties|Tab Control)) - a control that allows you to selectively display and hide other controls

• ((|#TextArea_Properties|Text area)) - similar to a text box, but with multiple lines

• ((|#TextBox_Properties|Text box)) - an editable control suitable for character, numeric, and date/time data

Purpose

Action

Date field

To create a control appropriate for s a date, set the control type to "textbox" and then modify Date picker properties.

Image or image reference field

To display a picture, set the control type to "Image".

True/False choice

Set the control type of the field to check box and define its Choice properties.

Short list of choices

Set the control type of the field to radio button and define its Choice properties. Choices can be static or dynamic (retrieved from a table).

Long list of choices

Set the control type of the field to drop down list box and define its Choice properties. Choices can be static or dynamic (retrieved from a table).

Select the appropriate display format

An In-Line style overrides the formatting of the cascading style sheet. If you wanted the text to be bolded, or in a different font, point size, or color, this is where you would define the formatting. You may also want to define validation rules to improve the quality of user input. You may want to allow only certain users to see a field. To do this set a minimum user security level required before the field will display.

Control Settings

The following properties are available for all control types.

• Name

  Specifies the name of the control, which must be unique within the form.

  tmpl.Variable_Info
  .varname as C

• Scope

  Sets the "visibility" of the variable set by the control. The options are:

  tmpl.Variable_Info
  .scope as C

  • "Local" - Local variables can only be seen by this page.

  • "Session" - Session variables can be seen by other pages in your application.

• Control Type

  You may change the type of control.

  tmpl.Variable_Info
  .controltype as C

  • Options

  • AdvancedButton

  • CheckBox

  • DropDownBox

  • Image

  • Label

  • Link

  • RadioButton

  • TextArea

  • TextBox

  • Calendar

  • Custom

  • Hidden

  • Tab Control

  • Tab Pane

  • Blurb

  • Heading

• Data Type

  Specifies the type of data returned by the control. The data type only affects the way validation operations run. From the perspective of Xbasic scripts, all variables are of type character. The options are:

  tmpl.Variable_Info
  .type as C

  • Options

  • "Character"

  • "Numeric"

  • "Logical"

  • "Date"

  • "Time"

• Validation Rules

  Specifies rules for verifying that the user's input or selection is acceptable. Click the '...' icon to display the Field Validation dialog box.

  tmpl.Variable_Info.HasValidationRules as L
  tmpl.Variable_Info.ValidationSettings
   .Enable_ClientSideValidation as L
  .Validate_OnBlur as L
  .general.require_value as L
   .general.error_msg as C
   .text_format.lLetters as L
   .text_format.lDigits as L
   .text_format.lwhite space as L
   .text_format.lOther as L
   .text_format.lSpecial as L
   .text_format.use_simple_mask as L
   .text_format.simple_mask as C
   .text_format.regex as C
   .text_format.error_msg as C
   .text_format.place_holder as C
   .numeric_format.numeric_type as C
   .numeric_format.grouping as C
   .numeric_format.decimal as C
   .numeric_format.decimal_places as N
   .numeric_format.error_msg as C
   .logical_format.terms as C
   .logical_format.error_msg as C
   .data_length.lRequired as L
   .data_length.min_length as N
   .data_length.max_length as N
   .data_length.error_msg as C
   .data_value.expression_type as C
   .data_value.equality as C
   .data_value.value as C
   .data_value.value1 as C
   .data_value.value2 as C
   .data_value.expression as C
   .data_value.error_msg as C
   .xfile.source as C
   .xfile.dbf.table as C
   .xfile.dbf.field as C
   .xfile.validation_type as C
   .xfile.ado.cs as C
   .xfile.ado.connection_type as C
   .xfile.ado.table as C
   .xfile.ado.field as C
   .xfile.ado.access_fn as C
   .xfile.ado.use_saved_connection_string AS L
   .xfile.ado.saved_connection_string as C
   .xfile.error_msg as C

• Client side validation

  Specifies whether data in this control should be validated before the form is submitted.

  tmpl.Variable_Info
  .Enable_ClientSideValidation as L

• Initial Value

  Optionally, set an initial value for the control to display.

  tmpl.Variable_Info
   .InitialValue as C

• Calculated Field Expression

  Optionally, set an initial value for the control to display.

  tmpl.Variable_Info
   .InitialValue as C

Events

The server Validate event is available for all types of controls. The Validate event provides an opportunity to run a script at the server after the form has been submitted.

• Server

• Specify the Xbasic to run to when the form is submitted. Click the '...' icon to display the Server Events dialog box.

  events.server.validate = <<%code%
  ' code here
  %code%

Advanced Button Properties

An advanced button is device for running a script without submitting the form. The script is defined under the button's Events > Server property.

• Button Label

  The label of the button.

  tmpl.Variable_Info.controltype as C

• In-line Style

  Specify style attributes that override the settings inherited from the style sheet. Click '...' to display the Style Editor.

  tmpl.Variable_Info
   .AdvancedButton.InLineStyle as C

Blurb Properties

A blurb is a static text control similar to a label but without a heading.

• Text

  The label of the button.

  tmpl.Variable_Info
  .controltype as C

• In-line Style

  Specify style attributes that override the settings inherited from the style sheet. Click to display the Style Editor.

  tmpl.Variable_Info
   .AdvancedButton.InLineStyle as C

Calendar Properties

The Calendar control is a control that a user can place on a dialog component. The Calendar control always displays the calendar on the page. The calendar control can be read-only or set the value of a variable.

• Date format

  Specify the format in which date values are passed to the calendar control. e.g. mm/dd/yyyy.

  with tmpl.Variable_info
  .Calendar.DateFormat as C

• Read only

  Specify if the calendar control is for displaying date values only, or should it allow the user to also set date values. If the calendar control is read only, then the user cannot click on any of the days, and the buttons at the top of the control to change the year and month are hidden.

  with tmpl.Variable_info
  .Calendar.Readonly as L

• Switch year

  This property is available on if the Read only property is not set. If a date value has a two digit year, specify which year to switch from 1900 to 2000.

  with tmpl.Variable_info
  .Calendar.SwitchYear as N

• Combo boxes

  When enabled, displays the combo boxes for the year and month pickers.

  with tmpl.Variable_info
  			.Calendar.UseComboBoxes as L

• Low year

  Specifies the low year in the year picker.

  with tmpl.Variable_info
  .Calendar.LowYear as N

• High year

  Specifies the high year in the year picker.

  with tmpl.Variable_info
  .Calendar.HighYear as N

CheckBox Properties

Check boxes are appropriate when you want to set a True/False value into a logical field. The most important property for a check box control is the definition of its choices.

• Choices

  Specify the choices to display. Click '...' to display the Define Choices dialog box.

  tmpl.Variable_Info
  .CheckBox.Choices as C

• Dynamic choices from a .DBF table are defined by:

  tmpl.Variable_Info
  .CheckBox.Datasource as C
  .CheckBox.Table as C
  .CheckBox.DisplayValueField as C
  .CheckBox.StoredValueField as C
  .CheckBox.maxchoices as N
  .CheckBox.Filter as C

• Dynamic choices from a ADO/ODBC source are defined by:

  t mpl.Variable_Info
  .CheckBox.Datasource as C
  .CheckBox.ADO.ConnectionString as C
  .CheckBox.ADO.SQL as C
  .CheckBox.maxchoices as N

• Dynamic choices from a variable are defined by:

  t mpl.Variable_Info
  .CheckBox.Datasource as C
  .CheckBox.DataSourceVariableName as C

• Orientation

  Specifies the placement of buttons. The options are:

  tmpl.Variable_Info
  .CheckBox.Orientation as C

  • "Horizontal"

  • "Vertical"

• In-line Style

  Specify style attributes that override the settings inherited from the style sheet. Click '...' to display the Style Editor.

  tmpl.Variable_Info
  .CheckBox.InLineStyle as C

• Style control if error

  Indicate whether to change the style of the entry if there is an error.

  tmpl.Variable_Info
  .CheckBox.StyleFieldIfError as L

• In-line style for errors

  Specify style attributes that override the settings inherited from the style sheet when errors occur. Click '...' to display the Style Editor.

  tmpl.Variable_Info
  
  .CheckBox.ErrorInLineStyle as C

• Not in list rule

  If the current value in the variable does not match the list of choices in the control, how should the current value in the variable be changed. The options are:

  tmpl.Variable_Info
  				.CheckBox.NotInListRule as C

  • "First Entry"

  • "Null"

  • "Do Nothing"

Custom Control Properties

Custom controls are appropriate when you want display or calculate something beyond the abilities of a standard control.

• Definition

  Specify the HTML and Xbasic to display. Click '...' to display the Define Xbasic for Custom Control dialog box.

  tmpl.Variable_Info
  .CustomControlXbasic as C

Drop Down Box Properties

Drop Down Boxes are appropriate when you want to select a value from a large list of alternatives. The most important properties for a check box control is the definition of its choices and its height. A height of 1 produces a combo box. A height greater than 1 produces a list box. If you set the height to be more than 1 line, you can also set the multi-select allowed field to "Multiple". This allows the user to select more than one value to insert into the field. (Commas will separate the resulting selections.)

• Choices

  Specify the choices to display. Click '...' to display the Define Choices dialog box.

  tmpl.Variable_Info
  .DropDownBox.Choices as C

• Dynamic choices from a .DBF table are defined by:

  tmpl.Variable_Info
  
   .DropDownBox.Datasource as C
   .DropDownBox.Table as C
  .DropDownBox.DisplayValueField as C
  .DropDownBox.StoredValueField as C
   .DropDownBox.maxchoices as N
  .DropDownBox.Filter as C

• Dynamic choices from a ADO/ODBC source are defined by:

  t mpl.Variable_Info
  .DropDownBox.Datasource as C
  .DropDownBox.ADO.ConnectionString as C
  .DropDownBox.ADO.SQL as C
  .DropDownBox.maxchoices as N

• Dynamic choices from a variable are defined by:

  t mpl.Variable_Info
  .DropDownBox.Datasource as C
  .DropDownBox.DataSourceVariableName as C

• Height

  Specify the number of rows to display.

  t mpl.Variable_Info
  .DropDownBox.Size as N

• Multi-select

  If the number of rows is greater than 1, specify if the user may select more than one entry. The options are"

  tmpl.Variable_Info
  .DropdownBox.selectStyle as C

  • Single

  • Multiple

• In-line Style

  Specify style attributes that override the settings inherited from the style sheet. Click '...' to display the Style Editor.

  t mpl.Variable_Info
  .DropDownBox.InLineStyle as C

• Style control if error

  Indicate whether to change the style of the entry if there is an error.

  t mpl.Variable_Info
  .DropDownBox.StyleFieldIfError as L

• In-line style for errors

  Specify style attributes that override the settings inherited from the style sheet when errors occur. Click '...' to display the Style Editor.

  t mpl.Variable_Info
  .DropDownBox.ErrorInLineStyle as C

• Not in list rule

  If the current value in the variable does not match the list of choices in the control, how should the current value in the variable be changed. The options are:

  tmpl.Variable_Info
  .DropDownBox.NotInListRule as C

  • "First Entry"

  • "Null"

  • "Do Nothing" - Choose this value when the contents of the drop down box are being generated by a filtered database lookup. This choice prevents the last entry in the drop down box from reappearing.

Heading Properties

A heading is a static text control without a heading that spans the width of the dialog.

• Text

  The name of the image to display.

  tmpl.Variable_Info
  .Heading.Text as C

• In-line Style

  Specify style attributes that override the settings inherited from the style sheet. Click '...' to display the Style Editor.

  tmpl.Variable_Info
  .Heading.InLineStyle as C

Hidden Control Properties

Hidden controls are appropriate when you want to store a value in the dialog component.

Image Properties

• Image name

  The name of the image to display.

  tmpl.Variable_Info
  .Image.Imagename as C

• In-line Style

  Specify style attributes that override the settings inherited from the style sheet. Click '...' to display the Style Editor.

  tmpl.Variable_Info
  .Image.InLineStyle as C

• Text description

  Text description for the image.

  tmpl.Variable_Info
  .Image.Alt as C

• Is Hyperlink

  Indicates whether there is a hyperlink associated with the picture.

  tmpl.Variable_Info
  .Image.IsHyperLink as L

• Hyperlink target

  The page or URL to open when the link is clicked.

  tmpl.Variable_Info
  .Image.hyperlinkTarget as C

Label Properties

• In-line Style

  Specify style attributes that override the settings inherited from the style sheet. Click '...' to display the Style Editor.

  tmpl.Variable_Info
  .Label.InLineStyle as C

Link Properties

An essential decision about a link control is what it will display. The options are:

• Value from other field(s)

• Static text

• Static image

• In-line Style

  Specify style attributes that override the settings inherited from the style sheet. Click '...' to display the Style Editor.

  tmpl.Variable_Info
  .Link.InLineStyle as C

• Display what in link?

  Specifies what is displayed in the link. The options are:

  tmpl.Variable_Info
  .link.DisplayType as C

  • "Value in field"

  • "Value from other field(s)"

  • "Static text"

  • "Static image"

• Field(s) to display

  Specify the HTML to display in the link. Use field placeholders to include values from other fields in the grid. Typically, the fields that you reference will have the Hide row or Hide column properties checked.

  tmpl.Variable_Info
  .link.DisplayExpression as C

• Static text

  Specify the text to display in the link.

  tmpl.Variable_Info
  .StaticText as C

• Static image

  Specify the image to display in the link.

  tmpl.Variable_Info
  .StaticImage as C

• Static image inline style

  Specifies style attributes for the image.

  tmpl.Variable_Info
  .StaticImageInlineStyle as C

• Static image text

  Specifies the text description of the image.

  tmpl.Variable_Info
  .StaticImageAlt as C

• Dynamic image control

  Specify the control that contains the image to display.

  tmpl.Variable_Info
  .link.AlternateImageControl

• ink address type

  Information about how to process the link information.

  tmpl.Variable_Info
  .Link.Type as C

  • "Explicit or Computed"

• Link Address

  When the Link address type is "Computed from fields in the grid", this field appears. Click '...' to define the link address in the Link Address Builder.

  tmpl.Variable_Info
  .link.ComputedAddress

• Target frame or window

  The default is "Explicit". Defines where to display the linked page. The default is Null. The options are:

  tmpl.Variable_Info
  .Link.targetFrameOrWindow as C

  • "Same Frame"

  • "Whole Page"

  • "New Window"

  • "Parent Frame"

Lookup Properties

The lookup property allows you retrieve one or more field values from a grid. For more information about lookup windows, refer to Defining Lookups for Text Boxes.

• Lookup

  When checked, makes the Textbox or Textarea control able to open a secondary lookup grid and retrieve field values.

  tmpl.Variable_Info
  .HasLookup as L

• Lookup definition

  Specifies lookup grid to use, field mappings, and other properties of the lookup window.

• Grid name

  Specifies the name of the grid to display in the lookup window.

  tmpl.Variable_Info
  .Lookup.GridName as C

• Window title

  Specifies the title of the lookup window.

  tmpl.Variable_Info
  .Lookup.WindowTitle as C

• Width

  Sets the width of the lookup window in pixels.

  tmpl.Variable_Info
  .Lookup.WindowWidth as N

• Height

  Sets the height of the lookup window in pixels.

  tmpl.Variable_Info
  .Lookup.WindowHeight as N

• Scrollbars

  Enables and disables scrollbars in the lookup window.

  tmpl.Variable_Info
  .Lookup.HasScrollBars as L

• Resizable

  Enables or disables resizing of the lookup window.

  Enables or disables resizing of the lookup window.
  tmpl.Variable_Info
  .Lookup.IsResizeable as L

• Inherit parent style

  Specifies whether to use its style sheet or inherit the style sheet of the parent page.

  tmpl.Variable_Info
  .Lookup.LookupWindowInheritParentStyle as L

• Select record link label

  Specifies the text to display in the selection link.

  tmpl.Variable_Info
  .Lookup.LookupGrid.LinkLabel as C

• Select record link label style

  Specifies style attributes that override the settings inherited from the style sheet. Click '...' to define the In-line style. Refer to the Style Editor for details.

  tmpl.Variable_Info
  .Lookup.LookupGrid.LinkLabelStyle as C

• Field map

  A comma delimited list of the fields to retrieve from the lookup window.

  tmpl.Variable_Info
  .Lookup.LookupGrid.ReturnFields as  C

• A comma delimited list of the fields to write in the grid.

  tmpl.Variable_Info
  .Lookup.FillinFields as C

• Link type

  Specifies whether to display text or a graphic as the link to the lookup window. The options are:

  tmpl.Variable_Info
  .Lookup.LinkType as C

  • Text

  • Icon

• Link label

  If text is selected for link type, defines the text to display.

  tmpl.Variable_Info
  .Lookup.LinkLabel as C

• Link label style

  Specifies style attributes that override the settings inherited from the style sheet.

  tmpl.Variable_Info
  .Lookup.LinkLabelStyle as C

• Icon name

  If icon is selected for link type, defines the text to display.

  tmpl.Variable_Info
  .Lookup.IconName as C

• Override Settings

  Override settings.

  tmpl.Variable_Info
  .Lookup.LookupGrid.OverrideSettings as C

• Query Parameters

  Query parameters.

  tmpl.Variable_Info
  .Lookup.QueryParameters as C

Radio Button Properties

RadioButton controls are appropriate when you want to select between a small number of choices. The most important property for a check box control is the definition of its choices.

• Choices

  Specify the choices to display. Click '...' to display the Define Choices dialog box.

• In-line Style

  Specify style attributes that override the settings inherited from the style sheet. Click '...' to display the Style Editor.

  t mpl.Variable_Info
  .RadioButton.InLineStyle as C

• Orientation

  Specifies the placement of buttons. The options are:

  tmpl.Variable_Info
  .RadioButton.Orientation as C

  • "Horizontal"

  • "Vertical"

• Type

  Specifies the nature of the choices. The options:

  tmpl.Variable_Info
  .RadioButton.Type as C

  • "Static"

  • "Dynamic"

• Style control if error

  Indicate whether to change the style of the entry if there is an error.

  t mpl.Variable_Info
  .RadioButton.StyleFieldIfError as L

• In-line style for errors

  Specify style attributes that override the settings inherited from the style sheet when errors occur. Click '...' to display the Style Editor.

  t mpl.Variable_Info
  .RadioButton.ErrorInLineStyle as C

• Not in list rule

  If the current value in the variable does not match the list of choices in the control, how should the current value in the variable be changed. The options are:

  tmpl.Variable_Info
  .RadioButton.NotInListRule as C

  • "First Entry"

  • "Null"

  • "Do Nothing"

Row Properties

Row properties are available for all types of controls.

• Hide row

  Specifies whether or not to display this row in the Form. (Note: The control in this row can still be displayed in another row if you convert that row to a freeform layout.)

  t mpl.Variable_Info
  
  .Column.Hide as L

• Security Level

  Controls access to the control.

  t mpl.Variable_Info
  .Column.SecurityLevel as N

• Row label

  The label defaults to the name of the control.

  t mpl.Variable_Info
  .Column.Heading as C

• Row label position

  The position of the label in relationship to the control. The options are:

  tmpl.Variable_Info
  .Column.LabelPosition as C

  • "Left"

  • "Right"

  • "Above"

  • "Below"

• Row label in-line style

  Specify style attributes that override the settings inherited from the style sheet. Click '...' to display the Style Editor.

  t mpl.Variable_Info
  .Column.LabelInLineStyle as C

• Label prefix

  Specify text or an image that should be displayed to the left of the row label. You can use HTML tags in the text.

  t mpl.Variable_Info
  .Column.Heading_Left as C

• Freeform layout

  Specifies whether there is a freeform layout. The option is:

  tmpl.Variable_Info
  .Column.Type as C

  • "Freeform"

• Freeform template

  Specify if this row should display just this field, or allow a freeform layout.

  tmpl.Variable_Info
  
  .Column.FreeFormTemplate as C

• Cell in-line style

  Specify style attributes that override the settings inherited from the style sheet. Click '...' to display the Style Editor.

  t mpl.Variable_Info
  .Column.InLineStyle as C

• Style label if error

  Specify if the label should be styled if a validation error occurs (V6 only).

  t mpl.Variable_Info
  .Column.StyleLabelIfFieldError as L

• Label in-line error style

  Specify style attributes that override the settings inherited from the style sheet. Click '...' to display the Style Editor.

  t mpl.Variable_Info
  .Column.ErrorLabelInLineStyle as C

• Break Type

  When the number of layout columns is greater than 1, forces a new row. The options are:

  tmpl.Variable_Info
  .Breaktype as C

  • "None"

  • "Break before"

  • "Break after"

  • "Break before and after"

• Column Span

  When the number of layout columns is greater than 1, the number of columns to group together.

  tmpl.Variable_Info
  .nCols as N

• Bubble Help Text

  Optionally, set an initial value for the control to display.

  tmpl.Variable_Info
  .BubbleHelp as C

• Label Bubble Help Text

  Optionally, set an initial value for the control to display.

  tmpl.Variable_Info
  .BubbleHelpLabel as C

Tab Control and Tab Pane Properties

Optionally, add a tab control to your grid. A tab control allows you to selectively hide and display different groups of fields. Refer to Setting Dialog Tab Properties.

Text Area Properties

The most important properties of a Text Area control are the Rows and Columns properties, which define its size.

• Rows

  Specify the number of rows to display.

  t mpl.Variable_Info
  .TextArea.Rows as N

• Columns

  Specify the number of columns to display.

  t mpl.Variable_Info
  .TextArea.Cols as N

• In-line Style

  Specify style attributes that override the settings inherited from the style sheet. Click '...' to display the Style Editor.

  t mpl.Variable_Info
  .TextArea.InLineStyle as C

TextBox Properties

The most important properties of a TextBox control are the Size and MaxLength properties. The MaxLength should match the field definition in your table. The size can be larger or smaller than the MaxLength value, depending on the needs of your design.

• Size

  The width of the control.

  t mpl.Variable_Info
  
  .Textbox.Size as N

• Max Length

  The maximum number of characters to accept.

  t mpl.Variable_Info
  .Textbox.MaxLength as N

• In-line Style

  Specify style attributes that override the settings inherited from the style sheet. Click '...' to display the Style Editor.

  t mpl.Variable_Info
  .Textbox.InLineStyle as C

• Style control if error

  Specifies whether to use a different in-line style when an error occurs.

  t mpl.Variable_Info
  .Textbox.StyleFieldIfError as L

• Control in-line error style

  Specify style attributes that override the settings inherited from the style sheet when errors occur. Click '...' to display the Style Editor.

  t mpl.Variable_Info
  .Textbox.ErrorInLineStyle as C

• Is a password field

  Indicates that this is a password field.

  t mpl.Variable_Info
  .Textbox.IsPassword as L

Limitations

Web publishing applications only.

See Also

• Setting Dialog Properties