Introducing User Input Elements, Pg. 2

Introducing User Input Elements

Logi Info
v12.6 - Oct 2018

Page 2

1 | 2 | 3

This page continues the discussion of the user input elements and topics include:

 

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 our document Uploading Files.
 

More Information

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

  Back to the 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 the 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 the 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 Values element, 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 this Tips & Tricks article.

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 the 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 arrangement of items, its @Request token will contain the value for the lowest checked item in the tree, but the values of the other checked items above it in the tree 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 the 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 the 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 the 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.
 

 

 

  Back to top

  1 | 2 | 3  

 


© Copyright 2007-2019 Logi Analytics, Inc. All Rights Reserved