Introducing User Input Elements

User Input elements produce input controls, which allow users to interact with applications at runtime. They're often used to often to provide data selection and filtering criteria. This topic discusses each of the Logi Info Input elements.

About Input Elements

Logi Info Input elements are based on the standard HTML input control types and provide useful interactivity. They can be used to gather user input at runtime in order to login to an application, to filter or restrict data, to modify the style or appearance of a report, to insert new or update existing data, and more.

When you include Input elements in a report definition, a ;<FORM> tag is automatically added to the HTML page generated. Following standard HTML behavior, when a user clicks links or buttons that reload the report or pass control to another definition, the form is submitted, along with all of the input control values that have been entered.

 When an report page is submitted, the values of all of its Input elements are automatically passed to the next Report or Process definition. DO NOT use Link Parameters to try to pass the entered values - they'll become null.

In the next Report or Process definition, you can access the entered values using Request tokens. For example, if an Input Text element has an element ID of inpLastName, its value is available in the token @Request.inpLastName~.

 Because the values are passed using HTTP POST, they will not appear in the URL. They are clearly shown, however, in the Debugger Trace Page when you turn debugging on, and this is a great tool for determining what's happening with user input values.

Due to the stateless nature of HTML pages, you generally have to submit (or refresh) a page before its value is usable in its own report definition. There are some exceptions to this; it's possible to use JavaScript to get and set the values of Input elements without submitting the page. This, and many other useful techniques, are described in Work with User Input Elements.

Our User Input Sample Application is also an good resource. Special mobile input elements are discussed in Intro to Logi Mobile Reports.

Now let's examine the available Input elements.

Back to top

Input Hidden

This is the invisible member of the Input elements family, so some might say it's debatable whether it's actually a user input element at all. However, it's extremely useful.
 

Using It

This element does not appear on the report page and has no caption but it can serve either of two purposes:

  1. It can hold any data value that you want to pass discreetly. Because the POST method is used when the current page is submitted, the data does not appear in the URL's query string. Contrast this behavior to a Link Parameter, which is passed as part of the query string and is therefore visible in the browser's URL display. Input Hidden is especially useful when passing data from within data tables to another Report definition or a Process task (see Work with User Input Elements) and its value can be set using JavaScript.
     
  2. It can act as a "change flag", indicating to another Report definition or Process task whether or not any input data has been changed prior to the page being submitted. This can be used with conditional processing to determine, for example, whether or not a database record needs to be updated. For more information, see Working with Change Flags in Work with User Input Elements.

This element's two attributes are required: a unique element ID and a Default Value, which may be set using tokens.
 

Getting Its Data

Input Hidden's value will be available in the next Report or Process task in a @Request token. For example, if the element's ID is set to hdnChangeFlag, then its data will be available in the token @Request.hdnChangeFlag~.
 

More Information

For additional information, see the Element Reference entry for Input Hidden.

Back to top

Input Text

The next four Input elements all use the same base control: a single-line text input box. The Input Text element is probably the most commonly-used of the group and allows users to type in characters. It looks like this in use:
 

     


Using It

The Input Text element attributes include:
 

Attribute Description

ID

(Required) The element ID, unique within the definition.

Caption

Specifies text that will be displayed to the left of the text input box.

Caption Class

Specifies one or more style sheet classes that will be applied to the element's Caption, if a different class than that applied to the Input element as whole is desired.

Change Flag Element ID

Specifies the ID of an Input Hidden element that will be used as a "change flag".

Class

Specifies one or more style sheet classes to be applied to the entire Input element.

Default Value

Specifies the default value that will appear in the text box. Can be used with tokens to display values from data, or passed from another report or a process. Overrides the Save In Local Storage attribute, sodo not use them at the same time.

Format

Specifies a format for the Default Value text displayed. This does not act as a mask (i.e. it does not force entry of characters in a specific pattern) nor does it change the visible data after entry. More information can be found in Format Data.

Input Maximum Length

Specifies the maximum number of characters than can be entered into the input box. If this is greater than the Input Size value, text will automatically scroll horizontally in the box.

Input Size

Specifies the physical width of the input box, in characters, on the screen.

Placeholder

Specifies the text of a short hint or caption, often used to describe the expected value, that appears within the input box when it's empty. The text is displayed in a gray color and you may care to use it instead of a Caption. The text disappears when data is entered and reappears if the entered data is deleted.

Save In Cookie

When True, stores the data entered by the user in a cookie, named after the element ID. The cookie can then be used to set the element's default value, so that previously entered data is retrieved, by setting the Default Value attribute to @Cookie.myInputId~.

Save In Local Storage

When True, stores the data entered by the user in the browser's "local storage" (if the browser supports this HTML5 technology). Data stored this way is retained between sessions and automatically restored as the Input element's default value when the page is redisplayed. The local storage size limit is approximately 5 MB and all values are stored as strings. Save In Local Storage is overridden by the Default Value attribute. Do not use them at the same time.

Security Right ID

Controls access to this element when using Logi Security. Provide the ID of a Right defined in the application's _Settings definition and only users that have a Role referenced in the Right will be able to view the element. Multiple Right IDs, separated by commas, may be entered.

Tooltip

Specifies text that appears when the user hovers the pointer over the input box. Tokens may be used here.


The Input Text element can be used with the AutoComplete element (see Work with User Input Elements), to assist users in entering text based on data. This element can be used by itself or within an Input Grid element to make alignment with other Input elements easier.
 

Getting Its Data

The text entered into this element will be available in the next Report or Process task by using an @Request token. For example, if the element's ID is set to txtFirstName, then its data will be available as the token @Request.txtFirstName~.
 

Input Text Delimiter Child Element

The Input Text Delimiter child element is available to be added beneath an Input Text element to control special characters in the input data and its attributes are:
 

Attribute Description

Class

Specifies an optional class to be applied to each delimited value within the Input Text control. For example, if using a Logi theme, the ThemeLinkButton class can be specified here to cause the values to appear as "pills".

Delimiter

Specifies the single character to be used to delimit multiple values entered into the Input Text control. Default value: comma.

Escape Character

Specifies the single character to be used as an escape character in the values entered in the input value. It will be ignored if no Qualifier attribute value is specified, but is required if a Qualifer value is specified. The Escape Character will be used to "escape" any instances of the Qualifier found within the input value.

For example, if the Escape Character is a backslash and the Qualifier character is a double-quote and the input string is:

      Lewis "Chesty" Puller

When the page is submitted, the resulting string value will have the Escape Character inserted and become:

   Lewis \"Chesty\" Puller

Qualifier

Specifies the single character that will enclose complete data values, allowing the Delimiter character to be included in the data without being processed as a delimiter. Leave this value blank only if there is no chance that the Delimiter character can be used in the data.

For example, consider an addresses that includes a city and state, separated by a comma: if the Delimiter is a comma, the city and state will be processed as two values when the page is submitted:

    McLean, Virginia            =     values: McLean,Virginia
     

However, if the Delimiter is not a comma and the Qualifier is a double-quote, only one value will be processed:

    McLean, Virginia            =     value: "McLean,Virginia"


When an Input Text element has both Input Text Delimiter and Auto Complete child elements, the Auto Complete element's Multiple Selections attribute is ignored and assumed True, and the Delimiter specified in the Input Text Delimiter element will be used (although the delimiter will not be visible).

More Information

For additional information, see the Element Reference entry for Input Text.

Back to top

Input Password

The purpose of this element is to allow the entry of passwords. It's identical to the Input Text element except that it does not show the characters being typed. Instead, a black dot is shown for each character entered. This is a commonly-accepted method of preventing a bystander from reading a password as it's entered.
 



Using It

The Input Password element's attributes are the same as those of the Input Text element and are not repeated here. This element can be used by itself or within an Input Grid element to make alignment with other Input elements easier.
 

Getting Its Data

The text entered into this element will be available in the next Report or Process task by using an @Request token. For example, if the element's ID is set to txtPassword, then its data will be available as the token @Request.txtPassword~.
 

More Information

For additional information, see the Element Reference entry for Input Password.

Back to top

Input Date

The purpose of this element is to allow the entry of a date or date range. It's similar to the Input Text element and a date can be typed right into it. It can also include an icon or link beside it which allows a date to be selected from a small pop-up calendar.
 


     

In the pop-up calendar, the current date is highlighted with one color and the selected date (or range of dates) is highlighted with another. Colors can be configured with CSS by overriding style classes found in <yourApp>\rdTemplate\rdCalendar\rdDataCalendarStyle.css.
 

Using It

The Input Date element shares many of the attributes of the Input Text element and also has these additional attributes:
 

Attribute Description

Calendar Caption Format

Specifies the format of the text above the popup calendar. Set to None to prevent display of the caption row entirely.

Calendar Link
Calendar Link Class
Calendar Link Type

These three attributes specify the type of popup calendar link, if any, that appears beside the text box. A small calendar image is provided or a custom image or text can be used.

Default Value

Specifies the default date that will appear in the text box. Can be used with @Function.Date~ token to display the current date in Short Date format.

End Date Default Value

Specifies the default value for the "end" date in a date range, if used.

End Date Range Caption

Specifies the caption for the "end" date text box, if used.

End Date Range ID

Specifies the ID to be associated with the "end" date text box, if used. This is the ID that will be used with a @Request token when the page is submitted.

Input Date Reformat

Causes the date entered to be reformatted into one of several formats before being made available as a request variable. More information can be found Format Data.

Number of Dropdown Years

Specifies the number of years that will appear in the Year drop-down list in the pop-up calendar associated with the input element. This value creates a range of years with the current year in the middle of the list.

Show Date Range

This attribute causes two text input boxes for dates to be displayed. If the popup calendar feature is used (Calendar Link Type = Image or Text), the first date selected becomes the value for the starting date; the second date selected sets the value for the ending date. Additional attributes are available that allow you to specify a Caption, Default Value, and ID for the second text input box. Dates can range over 1, 2, or 3 months.


The Input Date Calendar element can be added as a child of Input Date and used to configure the pop-up calendar. Input Date Calendar has the same attributes and behavior as the Date Picker element, which is described in the next section of this topic.

The control does not provide an "input mask" to control the format of what can be typed into it. Instead, developers must validate the date entered when the page is submitted, using Validation elements, or when various DHTML events occur, using Event Handler elements. For more information about validation and events, see Work with User Input Elements.

This element can be used by itself or within an Input Grid element to make alignment with other Input elements easier, and a special element, Validation.Date, is available as a child of Input Date, to ensure that a valid value is entered by the user.
 

Getting Its Data

The data placed into this element will be available in the next report or process by using an @Request token. For example, if the element's ID is set to txtHireDate, then its data will be available as the token @Request.txtHireDate~.

If Show Date Range is being used to allow entry of a date range, then the starting date is available using an @Request token that includes the Input Date element's ID, and the ending date is available using an @Request token that includes the ID specified in the End Date Range ID attribute.
 

Globalization and Localization

The format and presentation of calendars and dates varies widely depending on country and/or language. Some aspects of the date-related input elements are controlled by the "preferred language" settings of the browser being used and others may be affected by the default date and time format settings of the client operating system.

At the application level, date-related aspects of your Logi application can also be changed by adding and configuring a Globalization element in the application's _Settings definition. For example, it has two attributes, Default Input Date Format and Default Input Date Reformat, that can be used, if desired, to specify a format with global scope.

Setting the Globalization element's First Day of Week attribute will change the display of the calendars associated with Input elements. If the attribute value is set to 1, then Monday will be the first day in the calendar; the default is Sunday. More information about the Globalization element can be found in Internationalization and Localization .

In addition, the browser's preferred language setting will affect the pop-up calendar display and date value format:
 

     

In the examples shown above, a Globalization element has been used to change the first day of the week to Monday and the browser's preferred language has been set first to English and then to French. Notice that the month name and day-of-weekabbreviations in the calendar changed based on the browser's preferred language setting.

In addition, the actual value returned after the user clicks on a date, shown below the calendars, also reflects the language preference in any text it contains - "Nov" vs. "nov.". The element's Format attribute, of course, controls the format of the date value returned into the element's input text box after the mouse click.

In a "globalized date" scenario, when passing/submitting dates from your input controls to other definitions for use within tokens, as filters on queries, or within elements such as the Compare Filter, we highlyrecommend utilizing the ISO 8601 standard date format (yyyy-MM-dd) to avoid any locale/browser date conflicts that might arise. The input element's Input Date Reformat attribute can be used for this purpose.
 

More Information

For additional information, see the Element Reference entry for Input Date.

Back to top

Date Picker

The Date Picker element displays a calendar on the page, rather than a text input box, and allows the user to select a date. It can be configured to allow selection of a range of dates by selecting the starting and ending date. Its behavior is closely related to the Input Date element's pop-up calendar.
 


     

The current date is highlighted with one color and the selected date (or range of dates) is highlighted with another. Colors can be configured with CSS by overriding style classes found in <yourApp>\rdTemplate\rdCalendar\rdDataCalendarStyle.css.
 

Using It

The Date Picker element shares many of the attributes of other Input elements and also has these additional attributes:
 

Attribute Description

Border

Specifies the width of the border line, in pixels, drawn around the calendar. The default value is 1 pixel.

Calendar Caption Format

Specifies the format of the text above the popup calendar. Set to None to prevent display of the caption row entirely.

Cell Spacing

Specifies the width, in pixels, of the space between calendar cells.

Dropdown Year and Month

Specifies if the calendar header will have a drop-down list for year and month selection, allowing the user to change years and months. When set to False, the drop-down lists are replaced by a caption with the current calendar year and month names. Default: True

End Date Default Value
End Date Range ID

Specifies the default value for the "end" date in a date range and the ID to be used for that value.

Input Date Reformat

Causes the date selected to be reformatted into one of several formats before being made available as a request variable. Date format information relevant to this attribute can be found in Format Data.

Number of Dropdown Years

Specifies the number of years to be listed in the calendar's Year drop-down list.

Number of Months

Specifies if 1, 2, or 3 monthly calendars are displayed. If Show Date Range (see below) is True, highlighting for selected dates in different months can span the calendars.

Show Date Range

Specifies if a single date can be selected, or if a range of dates can be selected. If set to True, then all days in the range of dates selected will be highlighted. Default: False

Weekday Caption Format

Specifies the format for the weekday name captions that appear across the top of the calendar. The default value is dd, which displays a single letter for each day; use ddd to display a weekday name abbreviation ("Mon"); use dddd to display the full weekday name ("Monday"); and set the value to None to prevent display of the weekday names.

Width
Width Scale

Specifies the width of the element's calendar, in pixels or as a percent of its containing element. If left blank, a default value is automatically applied.


Getting Its Data

The Date Picker automatically adds Input Hidden elements to your definition and they are assigned the date(s) selected in the calendar. The IDs of the Input Hidden elements are based on the ID attributes of the Date Picker element. The selected dates will be available in the next Report or Process task by using an @Request token. For example, if the Date Picker element's ID is set to inpHireDate, then the selected date will be available as the token @Request.inpHireDate~.

If Show Date Range is enabled to allow selection of a date range, then the starting date is available using an @Request token that includes the Date Picker element's ID, as above, and the ending date is available using an @Request token that includes the ID specified in the End Date Range ID attribute.
 

More Information

The globalization and localization information presented about the Input Date element also applies to the Date Picker element.

For additional information, see the Element Reference entry for Date Picker.

Back to top

Input Email

The purpose of this element is to allow the entry of one or more email addresses. It's similar to the Input Text element and addresses can be typed right into it.
 


     

Using It

This element's attributes are the same as those of the Input Text element with include one additional attribute:
 

Attribute Description

Multiple Addresses

When set to True, multiple email addresses, separated by commas or semi-colons, may be entered.


This element can be used by itself or within an Input Grid element to make alignment with other Input elements easier, and a special element, Validation.Email, is available to ensure that valid email address values are entered by the user.
 

Getting Its Data

The data entered into this element will be available in the next Report or Process task by using an @Request token. For example, if the element's ID is set to inpEmail, then its data will be available as the token @Request.inpEmail~.
 

More Information

For additional information, see the Element Reference entry for Input Email.

Back to top

Input Number

Available only in Logi Info Mobile Report definitions, this element allows the entry of a number and may trigger a special data entry control in the mobile device interface. Otherwise, it's similar to the Input Text element and numbers can be typed right into it.
 



Using It

This element's attributes are the same as those of the Input Text element.

This element can be used by itself or within an Input Grid element to make alignment with other Input elements easier, and a special element, Validation.Numeric, is available to ensure that valid numeric values are entered by the user.
 

Getting Its Data

The data entered into this element will be available in the next Report or Process task by using an @Request token. For example, if the element's ID is set to inpQuantity, then its data will be available as the token @Request.inpQuantity~.
 

More Information

For additional information, see the Element Reference entry for Input Number.

Back to top

Input Telephone

Available only in Logi Info Mobile Report definitions, this element allows the entry of a telephone number and may trigger a special data entry control in the mobile device interface. Otherwise, it's similar to the Input Text element and numbers can be typed right into it.
 


     

Using It

This element's attributes are the same as those of the Input Text element. This element can be used by itself or within an Input Grid element to make alignment with other Input elements easier.
 

Getting Its Data

The data entered into this element will be available in the next Report or Process task by using an @Request token. For example, if the element's ID is set to inpCellNo, then its data will be available as the token @Request.inpCellNo~.
 

More Information

For additional information, see the Element Reference entry for Input Telephone.

Back to top

Input Time

The purpose of this element is to allow the entry of time. It's similar to the Input Text element and a time can be typed right into it. It can also include an icon or link beside it, which allows a time to be selected from a small pop-up panel.
 


     

As shown above, the pop-up panel has separate sections for hours and minutes, and selections are highlighted with a special color. Colors can be configured with CSS by overriding style classes found in <yourApp>\rdTemplate\rdClock\rdTimePickerStyle.css.
 

Using It

This element shares many of the attributes of the Input Text element and also includes these special attributes:
 

Attribute Description

Clock Link
Clock Link Class
Clock Link Type

These three attributes specify the type of popup link, if any, that appears beside the text box. A small clock image is provided, or a custom image or text link may be used.

Default Value

Specifies the default time that will appear in the text box. Can be used with @Function.Time~ token to display the current date in mm:hh:ss format.

Format

Specifies one of the three standard formats (Short, Medium, or Long Time) or your own custom format. More format information can be found in Format Data.

Input Time Reformat

Causes the time entered to be reformatted into one of several formats before being made available as a request variable.


The Input Time Clock element can be added as a child of Input Time and used to configure the popup panel. Input Time Clock has the following optional attributes:
 

Attribute Description

Clock Caption

Specifies a specific title in the popup panel. Default: Time Picker

Hours Header

Specifies a title for the Hours section. Default: Hours

Minutes Header

Specifies a title for the Minutes section. Default: Minutes

Seconds Header

Specifies a title for the Seconds section. Default: Seconds

Show Minutes

Specifies if the Minutes section is displayed. Default: True

Show Seconds

Specifies if the Seconds section is displayed. Default: False

Time Picker Hours

Specifies the hour scheme: 12-hour, 24-hour, or whatever the browser's Locale setting requires. Default: BrowserLocale


This element can be used by itself or within an Input Grid element to make alignment with other Input elements easier, and a special element, Validation.Time, is available to ensure that a valid time value is entered by the user.
 

Getting Its Data

The data placed into this element will be available in the next report or process by using an @Request token. For example, if the element's ID is set to inpStartTime, then its data will be available as the token @Request.inpStartTime~.
 

Globalization and Localization

The format and presentation of times varies depending on country and/or language. Some aspects of the time-related input elements are controlled by the "preferred language" settings of the browser being used and others may be affected by the default time format settings of the client operating system.

At the application level, time-related aspects of your Logi application can also be changed by adding and configuring a Globalization element in the application's _Settings definition. For example, it has two attributes, Default Input Time Format and Default Input Time Reformat, that can be used, if desired, to specify a format with global scope.

More information about the Globalization element can be found in Internationalization and Localization .

In a "globalized time" scenario, when passing/submitting dates and times from your input controls to other definitions for use within tokens, as filters on queries, or within elements such as Condition Filters, we highly recommend utilizing the ISO-standard date format (hh:mm:ss, with leading zeros) to avoid any locale/browser time conflicts that might arise. The input element's Input Time Reformat attribute can be used for this purpose.
 

More Information

For additional information, see the Element Reference entry for Input Time.
 

Input File Upload

The purpose of this element is to allow client system files to be uploaded to the web server. It's similar to the Input Text element but a value cannot be entered directly. Clicking the text box or the included "Browse..." button launches the client file explorer tool so the user can navigate through the file system to identify the desired file. The data selected must be a fully-qualified file path and file name.

 



     

Using It

The element has many of the attributes of the Input Text element but none that are special or unique. It can be used by itself or within an Input Grid element to make alignment with other Input elements easier.

 

Getting Its Data

When the page containing this element is submitted, an RFC 1867 file upload occurs. The uploaded file is then available and must be processed or saved using a Process task and the Procedure.Save File Upload element. A variety of information about the uploaded file (name, type, size, etc.) is then available using @Procedure tokens. For detailed information about these tokens and file upload processing, see Uploading Files.
 

More Information

For additional information, see the Element Reference entry for Input File Upload.

Back to top

Input Text Area

The purpose of this element is to allow multi-line entry of text. It's very similar to the Input Text element but allows paragraph-style text entry.

 



     

Using It

This element has most of the attributes of the Input Text element and includes these two additional attributes:

 

Attribute Description

Input Columns

Specifies the width of the input box, in characters.

Rows

Specifies the number of lines of text that will be visible in the input box, affecting its height on the page. Text entered will automatically wrap to the next line if it exceeds the width of the text box. If the number of lines of text entered exceeds this attribute's value, vertical scroll bars are displayed and the text scrolls.



This element can be used by itself or within an Input Grid element to make alignment with other Input elements easier.

 

Getting Its Data

The data placed into this element will be available in the next report or process by using an @Request token. For example, if the element's ID is set to txtSpeech, then its data will be available as the token @Request.txtSpeech~.

 

More Information

For additional information, see the Element Reference entry for Input Text Area.

Back to top

Input Checkbox

The next five user input elements are not related to the Input Text element and offer slightly more complexity in usage and alignment. The purpose of the Input Checkbox element is to provide a single, square box (with a caption) that can be checked or unchecked.

 



     

Using It

This element has many of the Input Text element's attributes and these attributes you should note:

 

Attribute Description

Caption

Specifies identifying text that is displayed to the left of the checkbox (top example shown above). To display a caption that follows the checkbox (bottom example), leave this attribute blank and add trailing Space and Label elements.

Checked Value

Specifies the value that will be passed to the next page or process task as a Request parameter if the checkbox is checked. No value is passed if the checkbox is unchecked and the token will not exist, unless an Unchecked Value (see below) is specified.

Default Value

Specifies the default value for the control. If it matches the Checked Value attribute, a check symbol will appear in the checkbox. Can be specified using a Request token for a value passed from another report or a process task, and other tokens.

Unchecked Value

 Specifies a value that will be passed to the next page or process task as a Request parameter when the item is not selected.



This element can be used by itself or within an Input Grid element to make alignment with other Input elements easier. If multiple Input Checkbox elements are placed on a page, there is no inherent relationship between them and each operates independently of the others.



Getting Its Data

The "state" of the checkbox, checked or unchecked, can be determined in the next Report or Process task with an @Request token. For example, if the element's ID is set to chkRememberMe and the checkbox is checked, then in the next page or process task the token @Request.chkRememberMe~ will equal the value in the Checked Value attribute. If it is not checked, then this @Request token will not exist, unless a value has been specified in its Unchecked Value attribute. This is an important distinction to note when creating conditional processing that evaluates this token.



More Information

For additional information, see the Element Reference entry for Input Checkbox.

Back to top

Input Select List

The next three user Input elements operate using collections of data and they require a datalayer to provide that data.

The purpose of the Input Select List element is to provide a drop-down list or fixed-length list of options, one or more of which can be selected. Here are three possible configurations:

 

Using It

The default configuration is for a drop-down list, but a static list can be created by entering a value in the element's Rows attribute.

This element requires a datalayer to provide the items that will appear in the list. If the list of items is short and unchanging, the DataLayer.Static element can be used to "hard code" the items. If the list is longer, the DataLayer.XML element can be used to read the data from an XML file. If the list is dynamic, elements such as DataLayer.SQL can be used to retrieve the items from a datasource, possibly with grouping to provide unique values.

If the datasource provides one, the value passed to the next Report or Process task can be different from the displayed text. The control automatically sizes itself to accommodate the widest display text.

The element has many of the attributes common to all Input elements and includes these additional attributes:

 

Attribute Description

Caption Column

(Required) Specifies the name of the datalayer column that contains the text to be displayed in the selection list.

Value Column

(Required) Specifies the name of the datalayer column that contains the value to be passed to the next report or process task. For example, if "United Kingdom - Pound" is selected in the list, the value "GBP" might be passed to the next report. This allows the flexibility to display and pass different values and even different types of values, such as numbers.

Default Value

Specifies a default value (not the displayed caption text). If it matches the value of an item in the list, then that item will be pre-selected in the control. Can be used with @Request tokens passed from another report or a process task, and other tokens.

To specify multiple default selected values in an Input Select List configured for multiple selections, enter a comma-separated list of values. Do not include any spaces in the list.

To use a data-driven set of default selected values, see the Default Values section below.

Group Caption Column

Specifies the datalayer column that provides the text for group headings in the option list. The is the same column used by the datalayer's Group Filter to group the options.

Group Class Column

Specifies the datalayer column that provides style sheet class names for the list's group captions. This allows each group caption to have its own styling, based on the data.

Include Blank

Include Blank Caption

Include Blank Value

These three attributes allow you to display and use a default item that is not based on data from the datalayer, for example, an instruction such as "Make a selection". See the notes below regarding use of these attributes under "Getting Its Data".

List Captions Element ID

Specifies the element ID of an Input Hidden element, which will contain the Caption Column values for the items selected when the definition is submitted. The values will be available in a @Request token using the same ID.

Multiple Selections

Specifies if multiple list items can be selected simultaneously, using the Ctrl or Shift keys. Default: False.

Rows

Specifies the number of items to display in a static list, determining the height of the control on the page. If the number of items in the list exceeds this value, vertical scroll bars are enabled and the control will scroll. The default blank setting for this attribute causes a drop-down list to be displayed instead.

Tooltip

Specifies text to be displayed as a tooltip when the mouse is hovered over the control and, if no Tooltip Column is specified, over the list of options.

Tooltip Column

Specifies the datalayer column that contains text to be shown as a tooltip when the mouse is hovered over each item in the list of options. Can be used with or without the Tooltip attribute.



This element can be used by itself or within an Input Grid element to make alignment with other Input elements easier.

 If the Input Select List is placed under a Data Table that produces multiple rows, the Input Select List's datalayer only runs once and thus all select lists will have the same rows. In such an arrangement, you cannot reference @Data tokens from the parent Data Table in the Input Select List's datalayer.

 

Hierarchical Grouping

Input Select List elements can be configured to list their options in groups, with a group caption, as shown earlier.

To use this, a Group Filter must be applied to the data, and its attributes set as shown above. Its Group Column value is the datalayer column that will supply the group captions.

The Input Select List element's Group Caption Column attribute is configured with the same column name used in the Group Filter, as shown above. The Group Class Column attribute gives you the option of setting a different style for each group caption, in the data.

 

Adding Default Values

A list of default values for the Input Select List can also retrieved from a datalayer. The Input Select List element's Default Value attribute must be left blank in order to use this technique.

As shown above, a Default Valueselement, with its own datalayer, is added as a child of the Input element. Its Data Column attribute is set to the name of the datalayer column containing the default values. This has be effect of turning all of the values in all datalayer rows in this column into a comma-separated list which is then fed into the Input element as its default value.

 

Getting Its Data

The value (from the "Value Column") associated with the selected item (from the "Caption Column") is available in the next Report or Process task with a @Request token. For example, if the element's ID is set to lbxCurrency then the token @Request.lbxCurrency~ will equal the selected item's value.

If you want to access the caption(s) of the item(s) selected, instead of or in addition to their values, set the List Captions Element ID attribute to the ID of an Input Hidden element. The caption(s) will be placed in this element when the report is submitted and will be available using a @Request token with the same ID.  For earlier Info versions, see Passing Input Select List Captions.

The availability of default data when using the Blank attributes varies based on the list type:

If you've specified a Blank Value and nothing is deliberately selected in a drop-down list (no Rows value) and the page is submitted, then the item visible in the control is considered selected and its value will be available using the @Request token.

However, if you've specified a Blank Value and nothing is selected in a static list (Rows > 0) and the page is submitted, then nothing is considered selected and this @Request token will not exist. This is an important distinction to note when creating conditional processing that evaluates this token.

If the Multiple Selections attribute is set to True, the @Request token will contain a comma-separated list of selected values. For use with SQL statements, it may be desirable to surround each individual value in the list with single quotes. This can be done using the SingleQuote token prefix. For example, consider the token:

    @Request.MySelections~   

which contains the string  1,2,3 . When we apply the SingleQuote token prefix, like this:

    @SingleQuote.Request.MySelections~  

the token is modified so it now contains '1','2','3' which is acceptable in a SQL query.

 

More Information

For additional information, see the Element Reference entry for Input Select List.

Back to top

Input Checkbox List

The Input Checkbox List element combines the features of the previous two elements: it displays items in a list, each with its own checkbox.

 

Using It

This element requires a datalayer to provide the items that will appear in the list. If the list of items is short and unchanging, the DataLayer.Static element can be used to "hard code" the items. If the list is longer, the DataLayer.XML element can be used to read the data from an XML file. If the list is dynamic, elements such as DataLayer.SQL can be used to retrieve the items from a datasource, possibly with grouping to provide unique values.

If the datasource provides one, the value passed to the next report or process task can be different from the displayed text. The control automatically sizes itself to accommodate the widest display text, or you can specify a width.

The element has many of the attributes common to all Input elements and includes these additional attributes:

 

Attribute Description

Caption Column

(Required) Specifies the name of the datalayer column that contains the text to be displayed in the selection list.

Value Column

(Required) Specifies the name of the datalayer column that contains the value to be passed to the next report or process task if the checkbox is checked.

Check All Caption

Specifies the text for the "Check all" checkbox. Enter a value of "none" to hide it altogether.

Checkbox List Dropdown

Specifies whether the list is rendered as a drop-down list. Default: False (i.e. static list)

Column Count

Specifies how many columns of items should be displayed. Default: 1

Default Value

Specifies the value of the item to be pre-checked in the control. Enter the actual the value (from the "Value" column), not the displayed text, in order to set this. Can be used with @Request tokens passed from another report or a process task, and other tokens.

To specify multiple items to be pre-checked, add a child Default Values element.

Dropdown Button Class

Specifies the style sheet class used to control the drop-down header and button appearance, such as font color. The actual button icon image can be overridden by creating a class named

.rd-checkboxlist-icon and setting its background-image selector to the desired image file.

Dropdown None Selected Caption

Specifies the text that appears in the drop-down header when there are no items selected. Default: Select options

Dropdown Selected Caption

As items are checked, their Caption text is displayed in a comma-separated list in the drop-down header. When there are too many items to be shown, the text changes to show the number of items selected. This attribute specifies the text displayed at that time. The "#" character is the placeholder for the number of selected items. Default: # selected

Height

Height Scale

Specifies the height of the element, in pixels or as a percent of its containing element. If left blank, a default value is automatically applied.

List Captions Element ID

Specifies the element ID of an Input Hidden element, which will contain the Caption Column values for the items selected when the definition is submitted. The values will be available in a @Request token using the same ID.

Multiple Selections

Specifies if multiple list checkboxes can be checked at the same time. Default: True

Tooltip

Specifies text to be displayed as a tooltip when the mouse is hovered over the control and, if no Tooltip Column is specified, over the list of options.

Tooltip Column

Specifies the datalayer column that contains text to be shown as a tooltip when the mouse is hovered over each item in the list of options. Can be used with or without the Tooltip attribute.

Width

Width Scale

Specifies the width of the element , in pixels or as a percent of its containing element. If left blank, a default value is automatically applied.



This element can be used by itself or within an Input Grid element to make alignment with other Input elements easier.

 If the Input Checkbox List is placed under a Data Table that produces multiple rows, the Input Checkbox List's datalayer only runs once and thus all checkbox lists will have the same rows. In such an arrangement, you cannot reference @Data tokens from the parent Data Table in the Input Checkbox List's datalayer.

 

Displaying Hierarchical List Items

The Checkbox List Branch element allows the items inside Input Checkbox List to be displayed in a hierarchical arrangement. The example below shows two levels of items below the major item:

When one or more Checkbox List Branch elements are used, data for the Input Checkbox List must come from a hierarchical datalayer. This can be created by using a datalayer that has a Group Filter element with its Hierarchical attribute set to True. The data should have the same number of hierarchical levels as there are Checkbox List Branch elements or, put more simply, the number of Group Filters under the datalayer should equal the number of Checkbox List Branch elements.

As with the Input Checkbox List element, Checkbox List Branch provides optional custom expanded/collapsed image attributes, and Class and initial state attributes.



Getting Its Data

The value (from the "Value column") associated with a checked item (from the "Caption column") is available in the next Report or Process task with an @Request token. For example, if the element's ID is set to inpCity then the token @Request.inpCity~ will equal that value.

If nothing is checked in the list and the page is submitted, then this @Request token will equal an empty string ("").

If the Multiple Selections attribute is not set to False, the @Request token will contain a comma-separated list of the checked values. For use with SQL statements, it may be desirable to surround each individual value in the list with single quotes. This can be done using the SingleQuote token modifier. Thus

    @Request.MySelections~   which has a value of     London,Berlin,Rome     becomes   

    @SingleQuote.Request.MySelections~  which has a value of    'London','Berlin','Rome'

If you want to access the caption(s) of the item(s) selected, instead of or in addition to their values, set the List Captions Element ID attribute to the ID of an Input Hidden element. The caption(s) will be placed in this element when the report is submitted and will be available using a @Request token with the same ID. Gettings multiple captions is dependent on setting the Multiple Selections attribute = True.

If you're using Input Checkbox List to show a hierarchical list of items, its @Request token will contain the value for the lowest checked item in a branch, but the values of the other checked items above it in the branch are not available in the same way.

Default values for an Input Checkbox List element with multiple selections can be provided using a child Default Values element. The default values are retrieved by a child datalayer beneath the Default Values element. If a Default Values element is present, then the Input Checkbox List's Default Value attribute is ignored.



More Information

For additional information, see the Element Reference entry for Input Checkbox List.

Back to top

Input Combo List

The Input Combo List element combines features of the Input Text, Input Select List, and AutoComplete elements.

Using It

Users can select values from a drop-down list by clicking the down arrow to show the list, then clicking an item in the list. Or they can start typing a value into the text box and the list will appear, dynamically filtering itself as more characters are typed.

If its Multiple Selections attribute is set to True, then users can select or enter multiple items, building a comma-separated list of values. As values are added to this list, they're remove from the drop-down list. These are the values that will be passed to the next Report or Process task.

Like other "list" elements, this one requires a datalayer to provide the list items and its Combo List Column attribute specifies the datalayer column that contains the values to be displayed in the drop-down list.

When blank values are part of the data set, they will be included in the drop-down list.

If you don't specify a width (Input Size attribute) the control will automatically size itself to accommodate the widest value, plus the down arrow icon.

The element has many of the attributes common to all Input elements and also these additional attributes:

 

Attribute Description

Combo List Column

(Required) Specifies the name of the datalayer column that contains the text to be displayed in the drop-down list.

Multiple Selections

Specifies whether users can select or enter multiple items from the drop-down list. If set to True, users can select or enter multiple items, building a comma-separated list of values. As values are added to this list, they're remove from the drop-down list, and the values list will be passed to the next Report or Process task.

Tooltip Column

 

Specifies the name of an column in the datalayer that contains explanatory text to be displayed as a tooltip unique to each list item.

Getting Its Data

Like an Input Text element, the value entered into or selected in this element will be available to the next Report or Process task as an @Request token. For example, if the element's ID is set to inpCountry, then its data will be available as the token @Request.inpCountry~. If no values is entered into the text box and the page is submitted, then its @Request token will equal an empty string ("").

If the element's Multiple Selections attribute is set to True, the @Request token will contain a comma-separated list of the selected or entered values. For use with SQL statements, it may be desirable to surround each individual value in this list with single quotes. This can be done using the SingleQuote token modifier. Thus

    @Request.inpCountry~   which has a value of    Australia,Sweden     becomes   

    @SingleQuote.Request.inpCountry~  which has a value of    'Australia','Sweden'

Default values for an Input Combo List element can be provided using its Default Values attribute, which can be a comma-separated list.



More Information

For additional information, see the Element Reference entry for Input Combo List.

Back to top

Input Radio Buttons

The purpose of this element is to provide at least two "radio buttons", small circles with captions. They are "mutually exclusive": only one radio button in a group can be selected at a time. The buttons can be arranged horizontally or vertically.

 



     

Using It

This element requires a datalayer to provide the items that will appar as button options. One button will be displayed for each record in the datalayer. If list of options is short and unchanging, the DataLayer.Static element can be used to "hard code" the options. If the list is longer, the DataLayer.XML element can be used to read the data from an XML file. If the options are dynamic, elements such as DataLayer.SQL can be used to retrieve the items from a datasource, possibly with grouping to provide unique values.

If the datasource provides one, the value passed to the next Report or Process task can be different from the displayed text. The control automatically sizes itself to accommodate the displayed text.

The element has many of the attributes common to all Input elements and also these additional attributes:

 

Attribute Description

Caption Column

(Required) Specifies the name of the datalayer column that contains the text to be displayed beside the radio buttons. This text is always displayed to the right of the button. In order to display text to the left, leave this attribute blank and precede the element with Label and Space elements.

Value Column

(Required) Specifies the name of the datalayer column that contains the value to be passed to the next report or process task. For example, if the "Larger" radio button is selected in the list, the value "4" might be passed to the next report. This allows the flexibility to display and pass different values and even different types of values, such as numbers.

Default Value

Specifies which radio button will be selected by default; enter the actual the value (from the "Value" column), not the displayed text, in order to set this. Can be used with @Request tokens passed from another report or a process task, or other tokens.

Radio Button Direction

Specifies the physical arrangement of the radio buttons: in a horizontal (Across) or vertical (Down) layout, as shown in the image above.

Tooltip Column

Specifies the name of an optional column in the datalayer that contains explanatory text to be displayed as a tooltip unique to each radio button.



This element can be used by itself or within an Input Grid element to make alignment with other Input elements easier.

  This element cannot be used beneath a Data Table element, so you cannot display radio buttons inside table columns.



Getting Its Data

The value (from the "Value" column) associated with the selected radio button (from the "Caption" column) is available in the next Report or Process with an @Request token. For example, if the element's ID is set to radFonts then the token @Request.radFonts~ will equal that value.

If there is no default selection and no radio button is selected and the page is submitted, then this @Request token will not exist. This is an important distinction to note when creating conditional processing that evaluates this token.



More Information

For additional information, see the Element Reference entry for Input Radio Buttons.

Back to top

Input Slider

The purpose of this element is to provide one, or a pair of, sliding "thumbs" that can be used to adjust numeric value inputs. The thumbs are clicked and dragged to change the input value and the thumb scale orientation can be horizontal or vertical.

 

     



Using It

The slider can be oriented horizontally or vertically. It does not have a Caption attribute, so a caption for this element must be provided separately. It features several standard attributes; other attributes of interest include:

 

Attribute Description

ID

(Required) Specifies the unique element ID associated with this control. This ID is used with an @Request token after the page is submitted to identify the data value for the first sliding thumb.

Background Image

Specifies the filename of an image for the background of the slider; if left blank, a default image is supplied. An image provided here is not stretched to fit; it must exactly fit the size of the slider; tick marks are automatically generated.

Decimal Points

Specifies the number of decimal places in the data values. The default is 0, which causes the slider to return only integer values.

Default Value

Specifies the default value associated with the first sliding thumb, shown when the report page is first displayed.

Minimum Value

Maximum Value

Specifies the range of numeric values represented by the slider scale. The default values are 0 and 100, respectively.

Second Default Value

Specifies the default value associated with the second sliding thumb, if used, when the report page is first displayed.

Second Slider ID

Specifying a value here causes a second sliding thumb to be displayed; leave this blank to display just one sliding thumb. This ID is used with an @Request token after the page is submitted to identify the data value for the second thumb.

Slider Length

Specifies the width or height of the slider, in pixels, depending on the Slider Orientation attribute. The value represents the distance that the thumbs can move. Default: 200 pixels.

Slider Orientation

Specifies the orientation of the slider: horizontal or vertical. Default: Horizontal.

Slider Thumb Offset Left

Slider Thumb Offset Top

Allows fine adjustment, in pixels, of the thumb image positioning, so that it aligns well with the slider.

Thumb Image

Specifies the filename of an image for the thumbs; if left blank, a default (shown above) is used.

Thumb Separation Value

When there are two sliding thumbs, specifies the minimum separation allowed between them. The value is based on the values of the Min Value and Max Value attributes, not in pixels.

Tick Count

Specifies the number of "detents", or stopping points, at which the thumbs will stop when dragged. Using this value, the detents are evenly distributed across the length of the slider; tick marks are automatically created.



This element cannot be used within an Input Grid element. If multiple Input Slider elements are used on a page, ensure that each thumb has a unique ID.

This element causes two DHTML events to occur. These can be used with Event Handler elements to provide user feedback, to refresh the current page, or to launch another report. The onDrag event is fired as a thumb is dragged, and the onChange event is fired when the dragging operation finishes.

This element incorporates a JavaScript function that can be called from script to set the slider value. The function syntax is:

    rdInputSliderSet('sliderID', value)

This element will not appear in exported reports.



Getting Its Data

The numeric value selected using this element will be available in the next Report or Process task by using an @Request token. For example, if the element's ID attribute is set to "Thumb1" and its Second Slider ID attribute is set to "Thumb2", then the selected values will be available in the next page or process task as the tokens @Request.Thumb1~ and @Request.Thumb2~.



More Information

For additional information, see the Element Reference entry for Input Slider.

Input Color Picker

The Input Color Picker was significantly improved in this release. Users of earlier Info v12 releases will see a subset of the features described here.

This element provides a visual interface for color selection. The current color selection appears as an icon next to a palette icon.

 

Clicking either icon displays the Color Picker pop-up panel, as shown above, from which new selections can be made.

 

Using It

This element shares many of the standard Input element attributes and includes these special attributes:

 

Attribute Description

Allow Transparency

Specifies whether the Color Picker pop-up panel will include a slider for selecting the transparency of the selected color. The default value is False.

Color Picker Caption

Specifies a custom caption for the Color Picker pop-up panel. The default value is Color Picker.

Default Value

Specifies the selected default color, by name, decimal RGB or RGBA value, or hex RGB value. Prefix hex values with the pound sign, like #112233.

Popup Modal

 

Specifies whether or not the Color Picker pop-up panel will be "system modal". Modal pop-ups disable the rest of the page until the panel is closed and the disabled area behind the panel get shaded in transparent gray.

Getting Its Data

The value associated with the color selected from the palette is available in the next Report or Process task with an @Request token. For example, if the element's ID is set to inpColors then the token @Request.inpColors~ will equal that value. This value will always be in hex RGB format: #112233.

 

More Information

For additional information, see the Element Reference entry for Input Color Picker.

Back to top

Input Chart List

A number of Classic Charts have been deprecated; they are still supported and will work, but their elements are no longer available in Studio. Use Chart Canvas Charts instead for all new development.

This element enables a Classic Chart to become an input control. Once a static Bar or Pie chart has been made the child of this element, users can select one or more bars, or one or more pie regions, by clicking on them. When the page is submitted, the Label values of the selected chart items are passed to the next report or process.

 

As shown above, the selected bars or wedges are displayed in a distinctly different color from the other bars or wedges by default. If the data has been grouped so that it's displayed as groups of several bars each, the entire group will be selected when clicked, rather than individual bars within the group.

 

Using It

This element shares many of the standard Input element attributes and includes these special attributes:

 

Attribute Description

Input Chart Value Column

Specifies the data column whose values which will be returned, such as the IDs for each selected bar in a Bar chart. The chart's Chart Label Column (aka: Label Data Column X-axis) is the default.

Selected Color

Specifies the selected bar or wedge's color, by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, such as #112233.

Selected Transparency

Specifies the transparency level of the selected bar or wedge. The lowest possible value of 0 indicates that the region is opaque, with no transparency. The other end of the scale, 15, indicates a completely transparent bar or wedge.

Unselected Color

Specifies the color of unselected bars or wedges, by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, such as #112233.

Unselected Transparency

Specifies the transparency level of the unselected bars or wedges. The lowest possible value of 0 indicates that the region is opaque, with no transparency. The other end of the scale, 15, indicates a completely transparent bar or wedge.



This element cannot be used within an Input Grid element. A child validation element, Validation.Required, is available to ensure that a selection is made by the user, if desired.

 

Getting Its Data

The Label values of the selected bars or wedges are available in the next Report or Process task with an @Request token. For example, if the element's ID is set to inpMyPie then the token @Request.inpMyPie~ will equal that value.

If no chart item is selected and the page is submitted, then this Request token will exist but it will be empty ("").

If multiple chart items are selected, the resulting Request token will contain a comma-separated list of selected values. When working use with SQL statements, it may be desirable to surround each individual value in the list with single quotes. This can be done using the SingleQuote token modifier. Thus

    @Request.inpCLPie~   which has a value of     1,2,3     becomes   

    @SingleQuote.Request.inpCLPie~  which has a value of     '1','2','3' 



More Information

For additional information, see the Element Reference entry for Input Chart List.

Back to top

Input Chart Range

A number of Classic Charts have been deprecated; they are still supported and will work, but their elements are no longer available in Studio. Use Chart Canvas Charts instead for all new development.

This element enables a Classic Chart to become an input control. Once a static Line, Spline, or Scatter chart has been made the child of this element, users can select a region in the chart by drawing a selection box (by dragging the mouse) on it. When the page is submitted, the maximum and minimum Label and Data values of the selected chart region are passed to the next Report or Process task.

 

The selected region is displayed in a distinctly different color from the rest of the chart by default.

 

Using It

The attributes of this element include:

 

Attribute Description

ID

(Required) A unique element ID.

MaxXaxisID

Specifies the name of the Request token that will provide the upper X-axis (Label) value in the next report or process.

MaxYaxisID

Specifies the name of the Request token that will provide the upper Y-axis (Data) value in the next report or process.

MinXaxisID

Specifies the name of the Request token that will provide the lower X-axis (Label) value in the next report or process.

MinYaxisID

Specifies the name of the Request token that will provide the lower Y-axis (Data) value in the next report or process.

Region Border Color

Specifies the border color of the region drawn on the chart, by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, like #112233.

Region Color

Specifies the color of the region drawn on the chart, by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, like #112233.

Region Transparency

Specifies the transparency level of the region drawn on the chart. The lowest possible value of 0 indicates that the region is opaque, with no transparency. The other end of the scale, 15, indicates a completely transparent bar or wedge.



This element cannot be used within an Input Grid element.

 

Getting Its Data

The minimum and maximum Label and Data values of the region drawn on the chart are available in the next Report or Process task with @Request tokens. For example, if the element's MaxXaxisID attribute is set to EndDate then the token @Request.EndDate~ will equal the maximum Label value.

If no selection region is drawn and the page is submitted, then the Request tokens will exist but they will be empty ("").

 

Special Event Elements

Two special, child event elements, Area Drawn and Area Cleared, are available for use with this element; both take Action elements as their children.

Area Drawn triggers its child Action element as soon as the user finishes drawing the area on the chart.

After an area has been drawn on the chart, if the user clicks somewhere on the chart again, the drawn area will be removed and Area Cleared will then trigger its child Action element.

 

More Information

For additional information, see the Element Reference entry for Input Chart Range.

Input Selection Point & Range

The Input Selection Point and Input Selection Range families of elements are available as children of some Chart Canvas chart Series elements. They provide the ability to interactively select portions of charts using the mouse and to initiate actions using the selected data. These input elements are discussed inInput Selection for Chart Canvas Charts.

More advanced information relating to many of input elements can be found inWork with User Input Elements.

Back to top