Understanding Page-Level Items

Check box

Displayed using a list of values. A list of values is required for items displayed as check boxes. The value corresponding to a checked box is returned in a single colon-delimited string.

The following example demonstrates how to create a single check box that returns YES. This example would display both a check box and a field label.

SELECT NULL display_text, 'YES' return_value FROM DUAL;

This example includes the additional text Click to select.

SELECT 'Click to select' display_text, 'YES' return_value FROM DUAL;

See Also: "APEX_UTIL" for information about breaking up returned values

Date Picker

Displays a text field with a Calendar icon next to it. When clicked, this icon displays a small calendar where the user can select a date and a time (optional).

If the format you need is not included in the Display As list, select Date Picker (use application format mask). When using a format mask, your application looks for the format in an item called PICK_DATE_FORMAT_MASK. Note that you need to populate this item before this item type will work.

See Also: "Populating an Alternative Date Picker Format"

Display As Text

Available Display As Text subtypes include:

• Display as Text (based on LOV, does not save state) - Displays the display value from an LOV by matching the item's source value with the LOV's return value.

• Display as Text (based on LOV, saves state) - Same as the previous option, but also generates a form item that gets submitted with the page to pass the return value into session state.

• Display as Text (based on PL/SQL, does not save state) - Displays the output of an anonymous PL/SQL block.

• Display as Text (does not save state) - Displays the item's source value on the page without creating a form item.

• Display as Text (escape special characters, does not save state) - Displays the item's source value with special characters ('<','>','&') escaped.

• Display as Text (saves state) - Displays the item's source value and creates a form item that gets submitted with the page to pass the value into session state.

File Browse

Displays a text field with a Browse... button. This enables the user to locate a file on a local file system and upload it. Oracle Application Express provides a table for these files to be uploaded to as well as an API to retrieve the files.

See Also: "Understanding the Security Risks of File Upload Tables"

Hidden

Renders an HTML hidden form element. Session state can be assigned and referenced just like a text field.

List Managers

Based on a list of values. This item enables you to manage a list of items by selecting and adding to a list. The list of values display as a popup.

Multiple Select

Renders as a multiselect HTML form element. When submitted, selected values are returned in a single colon-delimited string. You can break up the values using the APEX_UTIL API.

See Also: "Working with a Multiple Select List Item" and "APEX_UTIL"

Password

Renders as an HTML password form element.

Popup List of Values

Renders as a text field with an icon. When the user clicks the icon, a popup window appears with a list of values represented as a series of links. When the user makes a selection from this list, the selected value will be placed in the text field. You control popup LOVs through templates. You can only specify one popup LOV template for each application.

Using a popup LOV is a good choice for lists of values that are too large to return on a single page.

There are two types of Popup LOVs: one that fetches a set of rows when the window pops up and one that does not.

Popup LOVs must be based on a query that selects two columns with different column aliases. For example:

SELECT ename name, empno id 
   FROM emp

If one of the columns is an expression, remember to use an alias. For example:

SELECT ename||' '||job display_value, empno FROM emp

Radio

Renders as an HTML radio group form element, based on a list of values. Choose Radiogroup with Submit to have the page submitted when the radio button is selected.

The following example displays employee names (ename), but returns employee numbers (empno):

SELECT ename, empno FROM emp

Select List

Displays using a list of values. A list of values is required for items displayed as a select list. Select lists are rendered using the HTML form element <select>. The values in a select list are determined using a named list of values or a list of values defined at the item level. You can specify the NULL display value and NULL return value.

The following example would return employee names (ename) and employee numbers (empno) from the emp table. Note that column aliases are not required and are included in this example for clarity.

SELECT ename display_text, empno return_value FROM emp

Oracle Application Express provides additional enhancements to a standard HTML select list:

• Select List with Submit - Submits the page when the user changes its selected value. Upon submit, the REQUEST will be set to the name of the item that represents the select list, allowing you to execute conditional computations, validations, processes, and branches.

• Select List with Redirect - Redirects the user back to the same page, setting ONLY the newly selected value of the select list in session state.

• Select List Returning URL Redirect - Based on a list of values with URLs as the return values. Changing the value of the select list causes the browser to redirect to the corresponding URL.

• Select List with Branch to Page - Based on a list of values with page numbers as return values. Changing the selected value in the select list causes the Application Express engine to branch to the corresponding page.

Note: Long select lists can cause errors. If you have a long select list that generates an error, try using a Popup List of Values instead.

Stop and Start Table

Forces the close of an HTML table using the </table> tag and starts a new HTML table. You can use this item type to reset the column width in the middle of the region.

Note that a Stop and Start Table item only displays its label. You can prevent the label from displaying at all by setting it to null. To do this, you simply remove the default label.

Text

Displays as an HTML text field containing a maximum of 30,000 bytes of text. You control the maximum length and display width by editing the Height and Width item attribute.

Available Text display options include:

• Text Field - Renders as a text field.

• Text Field (Disabled, does not save state) - Displays a read-only version of a display value from a list of values by using the item's value in session state to look up the corresponding display value in the associated list of values. The value displayed on the screen is not saved in session state upon submit.

• Text Field (Disabled, saves state) - Displays a read-only version of a display value from a list of values by using the item's value in session state to look up the corresponding display value in the associated list of values.

• Text Field (always submits page when Enter pressed) - Displays a read-only version of the value in session state. Upon submit, the value displayed is saved in session state.

• Text Field with Calculator Popup - Renders as a text field with an icon next to it. When clicked, the icon displays a small window containing a calculator. Calculations are placed back in the text field.

Text Area

Renders as an HTML text area. There is no maximum length for an item displayed as a text area. You control the height and width by editing the Height and Width item attribute. Additional available Text Area Display As options include:

• Text Area (auto height) - Varies the height based on the amount of text. Use this option to scale the text area to the amount of data.

• Text Area with Counter - Includes a counter that displays the number of bytes entered in the field.

• Text Area with Spell Checker - Provides a popup English language spell checker.

• Text Area with HTML Editor - Provides basic text formatting controls. Note that these controls may not work in all Web browsers.