14.1 Managing Page-Level Items

An item is part of an HTML form. Examples of page-level item include a check box, a date picker, plain text, a file browse field, a popup list of values, a select list, a text area, and so on.

This section describes what a page-level item is, how to view existing page-level items, how to create new page-level items, and how to edit an item in Page Designer to change its appearance or behavior.

• Understanding Page-Level Items
  An item is part of an HTML form such as a check box, date picker, display as text, file browse field, popup list of values, select list, or a text area.
• Viewing Page-Level Items
  Learn how to view page-level attributes in Page Designer.
• Creating Page-Level Items
  You create page-level items in Page Designer in either the Rendering tab or by adding an item from the Gallery.
• Editing Page-Level Items
  Developers edit Item attributes in Page Designer to control how items display on a page.

14.1.1 Viewing Page-Level Items

Learn how to view page-level attributes in Page Designer.

Item attributes affect the display of items on a page. For example, these attributes can impact where a label displays, how large an item is, and if the item displays next to or below the previous item.

To view page-level attributes in Page Designer:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In either the Rendering tab or the Layout tab, select the item to edit.

   The Property Editor changes to display the attributes. Attributes are organized in groups.

3. To find a group or attribute:

   • Search for the group or attribute - Enter keywords in the Filter Properties field. The Property Editor displays the group or attributes. To return to the default display, delete the keywords.

   • Use Go to Group - Click Go to Group and select the group. To return the default display, click Go to Group again and select Expand All.

4. Edit the appropriate attributes in the Property Editor.

   Tip:

   To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the center pane.

5. Click Save.
6. Click Save and Run to view the page.

14.1.2 Creating Page-Level Items

You create page-level items in Page Designer in either the Rendering tab or by adding an item from the Gallery.

• Creating a Page-Level Item from the Rendering Tab
  
• Adding a Page-Level Item from the Gallery
  
• Creating a Static List of Values
  
• Creating a Cascading List of Values
  
• Creating a Shuttle Item on the Form Page in Page Designer
  

14.1.2.1 Creating a Page-Level Item from the Rendering Tab

To create a page-level item from the Rendering tab:

1. View the page to contain the item in Page Designer.
2. If necessary, create a region to contain the item.
3. In the Rendering tab, right-click the region to contain the item and select Create Page Item.

   The Property Editor displays attributes for the item. Attributes are organized in groups.

4. To find a group or attribute:

   • Search for the group or attribute - Enter keywords in the Filter Properties field. The Property Editor displays the group or attributes. To return to the default display, delete the keywords.

   • Use Go to Group - Click Go to Group and select the group. To return the default display, click Go to Group again and select Expand All.

5. Edit the appropriate attributes in the Property Editor.

   Tip:

   To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the center pane.

6. Click Save.

See Also:

"Viewing a Page in Page Designer" and "About Regions"

14.1.2.2 Adding a Page-Level Item from the Gallery

To create a page-level item by adding if from the Gallery:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. If necessary, create a region to contain the item.
3. In the central pane, click Layout and then the Items tab in the Gallery.

   Passing the cursor over an item displays a tooltip that describes it.

4. Select an item and drag it to the appropriate location in the Layout tab.

   Tip:

   You also right-click the item, click Add To, and select the appropriate location.

   The Property Editor displays Page Item attributes.

   The Messages tab displays a red or yellow badge to identify messages you need to address. Selecting a message displays the associated attribute in the Property Editor. You must address red error message before you can save.

5. Edit the appropriate attributes in the Property Editor.

   Tip:

   To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the central pane.

6. Click Save.

See Also:

"Viewing a Page in Page Designer" and "About Regions"

14.1.2.3 Creating a Static List of Values

One way to create a static list of values is to edit an item's List of Values definition. Note that this type of list of values is not reusable. As a best practice, create a list of values as a shared component whenever possible.

To create a static list of values:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. Create a new item from the Rendering tab or by adding it from the Gallery.
   The Property Editor displays the Page Item attributes. Attributes are organized in groups.
3. To find a group or attribute:

   • Search for the group or attribute - Enter keywords in the Filter Properties field. The Property Editor displays the group or attributes. To return to the default display, delete the keywords.

   • Use Go to Group - Click Go to Group and select the group. To return the default display, click Go to Group again and select Expand All.

4. Edit the appropriate attributes in the Property Editor.

   Tip:

   To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the center pane.

5. Under Identification:
   1. Name - Enter the name of this item. Item names must be valid Oracle identifiers. Oracle recommends that item names be no longer then 30 bytes so they can be used as bind variables in SQL Queries.
   2. Type - Select Select List.
6. Under List of Values:
   1. Type - Select Static Values.
   2. Static Values - Click the Display1, Display2 button. A dialog appears.
      In the Static Values dialog:

      • Display Value - Enter the Display Value for each entry.

      • Return Value - Enter the Return Value for each entry. If you do not include a Return Value, the return value equals the Display Value

      • Move Up and Move Down - Click the Move Up and Move Down arrow buttons to change the order.

      • Sort - Select Yes to sort the list at alphabetically at runtime.

      Tip:

      See the sections that follow to view examples.

   3. Click OK.
7. Edit the remaining List of Values attributes as appropriate. To learn more about an attribute, select the attribute and click the Help tab in the central pane.
8. Click Save to save your changes.
9. Click Save and Run to view the page.

Example 14-1 Example 1: Four Values Displayed in Alphabetical Order

This example shows the Static Values dialog with four values defined: Lion, Dog, Cow, and Cat. The return value of each entry is capitalized. Sort at Runtime is set to Yes so that the list displays alphabetical order.

Description of the illustration static_four_values.png

In a running application this select list would look similar to the following illustration.

Description of the illustration static_4_values_run.png

Example 14-2 Example 2: Ten Values Displayed in the Order Listed

This example shows the Static Values dialog with ten values defined: 10, 15, 20, 25, 50, 100, 200, 500, 1000, and 10000 which display in the order listed. The return value of each entry equals the display value.

Description of the illustration static_10_values.png

In a running application this select list would look similar to the following illustration.

Description of the illustration static_10_values_run.png

Example 14-3 Example 3: A List of Values with Having Both a Return and Display Value

This example shows the Static Values dialog with two values defined. The first value has a Display Value of Yes and a Return Value of Y. The second value has a Display Value of No and a Return Value of N Sort at Runtime is set to No to make sure Yes always displays first.

Description of the illustration static_display_return.png

In a running application this select list would look similar to the following illustration.

Description of the illustration static_display_return_run.png

See Also:

"Creating Lists of Values at the Application-Level" and "About Item Naming Conventions"

14.1.2.4 Creating a Cascading List of Values

By creating a cascading list of values (LOV), one item on a page determines the list of values for another item. App Builder includes cascading LOV support for the following item types: Select List, Shuttle, Checkbox, Radio Group, Popup LOV, and List Manager.

You create a cascading LOV by creating two items. To populate the second item, you specify a Cascading LOV Parent Item when running the Create Item Wizard or by editing the item's attributes.

The following example demonstrates how to create two related select lists where the value of the first list populates the second.

To create a cascading list of values:

1. Create the first item, P1_DEPTNO:
   1. Create a select list item.
   2. In the Property Editor, edit the attributes:

      • Identification: Name - Enter P1_DEPTNO

      • Identification: Type - Select Select List.

      • Label: Label - Enter Department

   3. In the Property Editor, edit the List of Values attributes:

      • List of Values: Type - Select SQL Query.

      • List of Values: SQL Query, enter:

        SELECT dname as d,
               deptno as r
          FROM dept
         ORDER BY dname
        

      • List of Values: Display Null Value - Select Yes.

      • List of Values: Null Display Value - Enter:

        - Select Department -
        

      • Accept the remaining defaults.

      • Click Save.

2. Create the second item, P1_EMPNO:
   1. Create a select list item.
   2. In the Property Editor, edit the attributes:

      • Identification: Name - Enter P1_EMPNO

      • Identification: Type - Select Select List.

      • Label: Label - Enter Employee

   3. In the Property Editor, edit the List of Values attributes:

      • List of Values: Type - Select SQL Query.

      • List of Values: SQL Query, enter:

        SELECT ename as d,
               empno as r
          FROM emp
         WHERE deptno = :P1_DEPTNO
        

      • List of Values: Display Null Value - Select Yes.

      • List of Values: Null Display Value - Enter:

        - Select Employee -
        

      • Accept the remaining defaults.

      • Click Save.

3. Click Save and Run to view the page.
   Two select lists appear. Making a selection in the Department select list, determines which individuals display in the Employees select list.

14.1.2.5 Creating a Shuttle Item on the Form Page in Page Designer

To create a shuttle on the form page:

This section demonstrates how to create shuttle item type. First, you first create a report and form on the DEPT table that shows which employees are assigned to a given department. Second, you create a shuttle item that lists employees alphabetically to make it easier to assign employees to a department.

To create a shuttle item on a form:

1. View the form page in Page Designer.
2. In Page Rendering, right-click region containing the form and select Create Page Item.
3. In the Property Editor, edit the following attributes:
   1. Identification: Name - Enter the name of this item (for example, PX_EMP_LIST).
      Where PX in the item name (for example P2_EMP_LIST) indicates the page on which the item resides.
   2. Identification: Type - Select Shuttle.
4. In the Property Editor, edit the List of Values attributes:
   1. List of Values: Type - Select SQL Query.
   2. List of Values: SQL Query, enter:

      SELECT ename, empno FROM emp ORDER BY 1
      

5. In the Property Editor, edit the Source attributes
   1. Source: Type - Select SQL Query (return colon separated value).
   2. Source: Item Source Value - Enter the SQL Query that returns one or more rows to be used as the source for this item value. If the result contains multiple rows then the value from each row is formed into a single colon delimited value. For example:

      SELECT empno FROM emp WHERE deptno = :P8_DEPTNO ORDER BY ename
      

6. Click Save.
7. Click Save and Run to view the page.

14.1.3 Editing Page-Level Items

Developers edit Item attributes in Page Designer to control how items display on a page.

For example, item attributes can determine where a label displays, how large an item is, and if the item displays next to or below the previous item. Item attributes also control item behavior such as the item’s default value, whether the item displays conditionally, or if the item is read-only.

• Editing Page Item Attributes in the Property Editor
  
• Defining Default Values for Page Items
  
• Configuring Page Item Security
  
• Creating a Quick Pick Selection
  
• Displaying Conditional Page Items
  
• Displaying Read Only Page Items
  
• Applying a Format Mask to an Item
  
• Configuring Item Attributes to Warn Users of Unsaved Changes
  
• Controlling How Page Items Write Session State
  
• Viewing Item Utilities
  

14.1.3.1 Editing Page Item Attributes in the Property Editor

To edit item attributes in the Property Editor:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In either the Rendering tab or the Layout tab, select the item to edit.

    The Property Editor displays attributes for the item.

   Tip:

   Attributes are organized in groups. To find a group or attribute, enter keywords in the Filter Properties field, or click Go to Group and select the group.
3. Edit the appropriate attributes.

   Edited attributes display a blue marker to the left of the attribute name until the page is saved.

   Note:

   To learn more about an attribute, see field-level Help. See "Viewing Field-Level Help."

4. Click Save.

14.1.3.2 Defining Default Values for Page Items

You define default values for an item using the Default attribute. The default value is used when the item's value is not derived from session state and when the source value is NULL.

To define a default value for an item:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In either the Rendering tab or the Layout tab, select the item to edit.

   The Property Editor displays the item attributes.

   Note:

   Attributes are organized in groups. To find a group or attribute, enter keywords in the Filter Properties field, or click Go to Group and select the group.
3. In the Property Editor, find the Default group.
4. Under Default, select a Type. Options include:
   • Static Value - In Static Value, specify a default value for this item. The default value is used when the item's value is not derived from session state and when the source value is null.
   • PL/SQL Expression - In PL/SQL Expression, enter the PL/SQL expression that produces the value for this item.
   • PL/SQL Function Body - In PL/SQL Function Body, enter the PL/SQL function body which returns the value for this item.
5. Click Save.

14.1.3.3 Configuring Page Item Security

To configure page item security:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In either the Rendering tab or the Layout tab, select the item to edit.

   The Property Editor displays the item attributes.

   Note:

   Attributes are organized in groups. To find a group or attribute, enter keywords in the Filter Properties field, or click Go to Group and select the group.
3. Find Security. Configure the following Security attributes.

   Table 14-1 Property Editor - Page Item, Security

   Attribute	Description
   Authorization Scheme	Select an authorization scheme which must evaluate to TRUE in order for this component to be rendered or otherwise processed. See Also: "Providing Security Through Authorization"
   Session State Protection	Select a Session State Protection level. Options include: Unrestricted - The item can be set by passing the item in a URL or in a form. No checksum is required in the URL. Checksum Required - User Level - The item can be set by passing the item in a URL that includes a checksum specific to the workspace, application and user. Checksum Required - Session Level - The item can be set by passing the item in a URL that includes a checksum specific to the the session. Restricted - May not be set from browser - The item cannot be altered using the URL or POSTDATA. Select this option to restrict what can set the item value to internal processes, computations, and so on. This attribute only applies to items that are not used as data entry items and is always observed, even if Session State Protection is disabled. Use this attribute for page or application items that have the following Display As types Display Only (Save State=No) Text Field (Disabled, does not save state) See Also: "Preventing URL Tampering"
   Store value encrypted in session state	Specify whether to encrypt this item when stored in session state. If the contents of an item contain sensitive data, then you should encrypt the value when it is stored in the Application Express session state management tables. Otherwise, anyone with rights to read the Application Express meta data tables could potentially write a query to extract this sensitive data. Values up to 4000 bytes in length can be encrypted. Attempts to encrypt values longer than 4000 bytes produce an error message.
   Escape Special Characters	This attribute only displays with some item types. Select Yes to prevent Cross-Site Scripting (XSS) attacks. Select No if you want that HTML tags which are stored in the page item or in the entries of a list of value are actually rendered. See Also: "Understanding Cross-Site Scripting Protection"
   Restricted Characters	Select how to restrict the characters that can be saved in session state. Application Express displays an error message if a user tries to save data that does not conform to the selected character restriction. Restricting the characters hardens application security and is a possible counter measure to cross-site scripting (XSS) attacks. Available options include: All characters can be saved. No restriction applies. Whitelist for a-Z, 0-9 and space Only allow characters a-z, A-Z, 0-9, and space. Blacklist HTML command characters (<>"). Do not allow reserved HTML characters Blacklist &<>"/;,*|=% and --: Do not allow &, <, >, ", /, ;, ",", *, |, =, % and "--" (PL/SQL comment). Blacklist &<>"/;,*|=% or -- and new line Do not allow &, <, >, ", /, ;, ",", *, |, =, %, "--", and new line characters See Also: "Understanding Cross-Site Scripting Protection"

14.1.3.4 Creating a Quick Pick Selection

Quick picks enable users to select predefined values with just one click, rather than typing in text or selecting from a list of available options. If the item type supports quick pick selection, use the Quick Picks attributes to define up to ten selections that display under a give item. Clicking on a quick pick sets the value of item. The following example shows quick picks for 5%, 10%, 15%, and 20%.

To create a quick pick:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In either the Rendering tab or the Layout tab, select the item to edit.

   The Property Editor displays the item attributes.

   Tip:

   Attributes are organized in groups. To find a group or attribute, enter keywords in the Filter Properties field, or click Go to Group and select the group.
3. Under Quick Picks:
   1. Show Quick Picks - Select Yes.
   2. Link Attributes - Enter HTML attributes that are associated with the display of each Quick Pick link
   3. Label - Enter the label for the each Quick Pick. This label is the text the end user of the application sees.
   4. Value - Enter the value associated with each Quick Pick. This value replaces the existing item value when the user clicks the quick pick.
4. Click Save.

14.1.3.5 Displaying Conditional Page Items

To display a conditional item:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In either the Rendering tab or the Layout tab, select the item to edit.

   The Property Editor displays the item attributes.

   Note:

   Attributes are organized in groups. To find a group or attribute, enter keywords in the Filter Properties field, or click Go to Group and select the group.
3. Find Server-side Condition. Select a condition Type and enter appropriate information in the field provided.

   Tip:

   To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the central pane.
4. Click Save.

14.1.3.6 Displaying Read Only Page Items

To display a read-only item:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In either the Rendering tab or the Layout tab, select the item to edit.

   The Property Editor displays the item attributes.

   Tip:

   Attributes are organized in groups. To find a group or attribute, enter keywords in the Filter Properties field, or click Go to Group and select the group.
3. Under Read Only , select a Type, and enter appropriate information in the field provided.

   Tip:

   To learn more about an attribute, select the attribute in the Property Editor and click the Help tab in the central pane.
4. Click Save.

14.1.3.7 Applying a Format Mask to an Item

You can apply a format mask to an item by selecting the item in Page Designer and editing the Format Mask attribute. Developers commonly select a format mask to determine how numbers and dates display.

To apply a format mask to an item:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In either the Rendering tab or the Layout tab, select the item to edit.
   The Property Editor displays the item attributes.

   Tip:

   Attributes are organized in groups. To find a group or attribute, enter keywords in the Filter Properties field, or click Go to Group and select the group.
3. Under Appearance, Format Mask - Select a format mask.

   Tip:

   Only apply number format masks to items that contain numbers and only apply date format masks to items that contain dates. Otherwise, is raised since the component contains a value that can not be converted using the specified format mask.
4. Click Save.

14.1.3.8 Configuring Item Attributes to Warn Users of Unsaved Changes

Developers can use the Warn on Unsaved Changes item attribute to specify if the page item should be included in the unsaved changes check. This check warns the user when they try to navigate away from a page and when the page contains unsaved changes. Items not based on a database column (for example, a search item) may not need to be checked. For those items, set Warn on Unsaved Changes to Do Not Check.

To configure the Warn on Unsaved Changes attribute:

1. View the page in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In either the Rendering tab or the Layout tab, select the item to edit.

   The Property Editor displays the item attributes.

   Tip:

   Attributes are organized in groups. To find a group or attribute, enter keywords in the Filter Properties field, or click Go to Group and select the group.
3. Find Advanced.
4. For Warn on Unsaved Changes, select one of the following:

   • Page Default - Check for unsaved changes when the button is clicked if Warn on Unsaved Changes is enabled at the page-level.

   • Do Not Check - Changes to the item are ignored by the unsaved changes check. Select this option for items not based on a database column (for example, a search item).

5. Click Save.

Tip:

The Warn on Unsaved Changes attribute is implemented using the apex.page.warnOnUnsavedChanges API.

See Also:

"Configuring Page Attributes to Warn Users of Unsaved Changes" and "warnOnUnsavedChanges" in Oracle Application Express JavaScript API Reference

14.1.3.9 Controlling How Page Items Write Session State

You can control whether a page item writes its session state into persistent (disk) session state or just into memory by configuring the item attribute, Maintain Session State.

To configure how a page item writes session state:

1. View the page containing the item to be configured in Page Designer:
   1. On the Workspace home page, click the App Builder icon.
   2. Select an application.
   3. Select a page.
   Page Designer appears.
2. In either the Rendering tab or the Layout tab, select the item to edit.

   The Property Editor displays the item attributes.

   Tip:

   Attributes are organized in groups. To find a group or attribute, enter keywords in the Filter Properties field, or click Go to Group and select the group.
3. In the Property Editor, find the Source group.
4. Under Source, Maintain Session State, select one of the following options:
   • Per Request (Memory Only) - Do not save state in the database. State is only available when processing the current request. When AJAX requests need to use an item, make sure to pass the item name using the Page Items To Submit attribute..
   • Per Session (Disk)- Maintain for each session by storing the value in the database, to access it across
   • Per User (Disk) - Value is saved in a user attribute repository and it is also available for later APEX sessions.

   Note:

   When creating database items that work with a Form region (for example as part of a wizard), Per Request (Memory Only) is the default. Per User (Disk) is not available for these items.
5. Click Save.

See Also:

"About Setting Session State"

14.1.3.10 Viewing Item Utilities

The Utilities page includes Grid Edit pages and reports that enable you to edit items on multiple pages within a selected application.

To access the Utilities page:

1. On the Workspace home page, click the App Builder icon.
2. Select an application.
3. Click Utilities.
4. From Page Specific Utilities region, click Item Utilities.
5. Select one of the following reports:

   • Grid Edit of all Item Labels

   • Grid Edit of all Item Help Text

   • Item Help Subscriptions

   • All Page Items

   • Password Items

   • Conditional Items