Creating Items

An item is part of an HTML form. An item can be a text field, text area, password, select list, check box, and so on. Item attributes affect the display of items on a page. For example, these attributes can impact where a label displays, how large an item will be, and if the item will display next to or below the previous item.

There are two types of items: page items and application items. Page items are placed on a page and have associated user interface properties, such as Display As, Label and Label Template. Application items are not associated with a page and therefore have no user interface properties. You can use an application item as a global variable.

Topics:

Creating a Page-Level Item
Referencing Item Values
Editing Page Item Attributes
Displaying Conditional or Read-Only Page Items
Working with a Multiple Select List Item
Creating an Application-Level Item
Populating an Alternative Date Picker Format

Creating a Page-Level Item

You create a page-level item by running the Create Item Wizard from the Page Definition.

To create a new page-level item:

Navigate to the appropriate Page Definition:
1. Navigate to the Workspace home page.
2. Click the Application Builder icon.
3. Select an application.
4. Select a page.
  
  The Page Definition appears.
If necessary, create an HTML region. See "Customizing Regions".
Under Items, click the Create icon.
Select an item type. See "About Item Types".
Follow the on-screen instructions

About Item Naming Conventions

When specifying an item name, remember the following rules. Item names must:

Not have quotation marks
Begin with a letter or a number, and subsequent characters can be letters, numbers, or underscore characters,
Be case-insensitive.
Should not exceed 30 characters.
Cannot contain letters outside the base ASCII character set.

About Item Types

When you create an item, you specify an item type. Once you create an item, these types appear on the Display As list on the Edit Page Item page. Table 6-7 describes available item types.

Table 6-7 Available Item Types

Item Type	Description
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: "HTMLDB_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 from which 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 Only	Oracle HTML DB uses HTML tables to render items. Use this item to control the layout of items in forms by closing a table and starting a new one.
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 HTML DB provides a table for these files to be uploaded to as well as an API to retrieve the files.
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 `HTMLDB_UTIL API`. See Also: "Working with a Multiple Select List Item"
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 HTML DB 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 list of values with page IDs as return values. Changing the selected value in the select list causes the HTML DB engine to branch to the corresponding page. Note: Long select lists can result in error. 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 of 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. 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 have a large text area if you have a lot of data and a small text area if you have little or no 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.

Referencing Item Values

You can reference item values stored in session state in regions, computations, processes, validation, and branches. Table 6-8 describes the supported syntax for referencing item values.

See Also:

"Managing Session State Values"

Table 6-8 Syntax for Referencing Item Values

Type	Syntax	Description
SQL	`:MY_ITEM`	Standard bind variable syntax for items whose names are no longer than 30 bytes. Use this syntax for references within a SQL query and within PL/SQL.
PL/SQL	`V('MY_ITEM')`	PL/SQL syntax referencing the item value using the `V` function. See Also: "Oracle HTML DB APIs"
PL/SQL	`NV('MY_NUMERIC_ITEM')`	Standard PL/SQL syntax referencing the numeric item value using the `NV` function. See Also: "Oracle HTML DB APIs"
Static Text	`&MY_ITEM`	Static text.
Static Text (exact)	`&MY_ITEM.`	Static text. Exact Substitution.

You can set the value of an item in your application using any of the following methods:

For page items, use the Source Attribute to set the item value.

From the Page Definition, select the item name to view the Edit Page Item page. Scroll down to Source and edit the appropriate fields.

You can also set the value of an item in any region based on PL/SQL or a process using the following syntax:
```
BEGIN
 :MY_ITEM :=  'new value';
END;
```
Pass the value on a URL reference using f?p syntax. For example:
```
f?p=100:101:10636547268728380919::NO::MY_ITEM:ABC
```
Set the value using a computation. Computations are designed to set item values. For example:
```
TO_CHAR(SYSDATE,'Day DD Month, YYYY');
```
Use the PL/SQL API to set an item value within a PL/SQL context. For example:
```
HTMLDB_UTIL.SET_SESSION_STATE('MY_ITEM',SYSDATE);
```

Editing Page Item Attributes

Once you create an item, you can edit it on the Edit Page Item page.

To edit item attributes:

Navigate to the appropriate Page Definition:
1. Navigate to the Workspace home page.
2. Click the Application Builder icon.
3. Select an application.
4. Select a page.
  
  The Page Definition appears.
Under Items, select the item name.

The attributes page for the item appears.
Edit the appropriate item attributes. For information on a specific attribute, see item Help.
Click Apply Changes.

See Also:

"About Cross-Site Scripting Protection"

Displaying Conditional or Read-Only Page Items

You can choose to have an item display conditionally or as read-only by editing attributes on the Edit Pages Item page.

To display a conditional or read-only item:

Create the item. See "Creating a Page-Level Item".
Navigate to the appropriate Page Definition:
1. Navigate to the Workspace home page.
2. Click the Application Builder icon.
3. Select an application.
4. Select a page.
  
  The Page Definition appears.
Under Items, select the item name.

The attributes page for the item appears.
To display an item conditionally:
1. Scroll down to Conditions.
2. Make a selection from the Condition Type list.
3. Enter an expression in the fields provided.
To make an item read-only:
1. Scroll down to Read Only Display Settings.
2. Make a selection from the Read Only Condition Type list.
3. Enter an expression in the fields provided.
Click Apply Changes.

Working with a Multiple Select List Item

A multiple select item renders as a multiple select list form element. When submitted, selected values are returned in a single colon-delimited string. You can handle values in this format in two ways:

Using the INSTR function
Using the HTMLDB_UTIL.STRING_TO_TABLE function

Using HTMLDB_UTIL.STRING_TO_TABLE to Convert Selected Values

For example, suppose you had a report on the EMP and DEPT tables that is limited by the departments selected from a Department multiple select list. First, you create the multiple select item, P1_DEPTNO, using the following query:

SELECT dname, deptno
FROM dept

Second, you return only those employees within the selected departments as follows:

SELECT ename, job, sal, comm, dname
FROM emp e, dept d
WHERE d.deptno = e.deptno
AND instr(':'||:P1_DEPTNO||':',':'||e.deptno||':') > 0

Next, assume you want to programmatically step through the values selected in the multiple select item, P1_DEPTNO. To accomplish this, you would convert the colon-delimited string into a PL/SQL array using the HTMLDB_UTIL.STRING_TO_TABLE function. The following example demonstrates how to insert the selected departments into an audit table containing the date of the query.

DECLARE
    l_selected HTMLDB_APPLICATION_GLOBAL.VC_ARR2;
BEGIN
  --
  -- Convert the colon separated string of values into
  -- a PL/SQL array 

  l_selected := HTMLDB_UTIL.STRING_TO_TABLE(:P1_DEPTNO);

  --
  -- Loop over array to insert department numbers and sysdate
  --

  FOR i IN 1..l_selected.count 
  LOOP
    INSERT INTO report_audit_table (report_date, selected_department)
        VALUES (sysdate, l_selected(i));
  END LOOP;
END;

See Also:

"STRING_TO_TABLE Function"

Creating an Application-Level Item

Application level items do not display, but are used as global variables to the application.

To create a new application-level item:

Navigate to the Workspace home page.
Click the Application Builder icon.
Select an application.
When Application Builder appears, click Shared Components.
Under Logic, select Items.

The Application Items page appears.
To create a new application item, click Create.
Follow the on-screen instructions.

About the Application Items Page

Once you create a application item, it appears on the Application Items page. You control how the Application Items page displays by making a selection from the View list. Available options include:

Icons (the default) displays each application item as a large icon. To edit an application item, click the appropriate icon.
Details displays each application item as a line in a report. To edit an application item, click the name.

Accessing Application Item History

You can view a history of changes to application items by clicking History at the top of the Application Items page.

Populating an Alternative Date Picker Format

If you need to create a Date Picker item, but the format you need does not appear in the Display As list, select Date Picker (use application format mask). When an application uses this type of date picker, the HTML DB engine derives the date format from an item named PICK_DATE_FORMAT_MASK. You can populate this item in two ways:

By defining an application substitution string named PICK_DATE_FORMAT_MASK
By creating an application-level item named PICK_DATE_FORMAT_MASK

Defining PICK_DATE_FORMAT_MASK as an Application Substitution String

One approach to populating PICK_DATE_FORMAT_MASK is to create an application substitution string. You define application-level substitution strings on the Edit Application Attributes page. Remember that an application-level substitution string is a static value and cannot be altered at run time.

To define a new application substitution string named PICK_DATE_FORMAT_MASK:

Navigate to the Workspace home page.
Click the Application Builder icon.
Select an application.

Application Builder appears.
Click the Edit Attributes icon.
Click Edit Standard Attributes.
Scroll down to Static Substitution Strings.
Create a new static substitution string named PICK_DATE_FORMAT_MASK:
1. In Substitution String, enter the name PICK_DATE_FORMAT_MASK.
2. In Substitution Value, enter a value for your date format (for example, Month DD, YYYY).

Defining an Application-Level Item Named PICK_DATE_FORMAT_MASK

Another approach to populating PICK_DATE_FORMAT_MASK is to create an application-level item named PICK_DATE_FORMAT_MASK. This approach enables you to control any items rendered as Date Picker (use application format mask) by simply setting the value of this item. Plus, you can set the value of PICK_DATE_FORMAT_MASK using a computation from anywhere within your application.

If you want to provide the user with a list of date formats as preferences, you will need to create an application-level item named PICK_DATE_FORMAT_MASK and then use a computation to set the value of this item based upon the user's selection.

See Also:

"Creating an Application-Level Item"