7.7 Understanding Page-Level Items

7.7.2.1 Viewing Items in Tree View

In Tree view, items display within a tree under the region which contains them.

To edit or add an item, right-click to display a context menu. Then, make a selection from the context menu.

To edit multiple items at once, right-click Items and select Edit All. The Items page appears. See "Editing Multiple Items Simultaneously".

7.7.2.2 Viewing Items in Component View

In Component view, items display under the Items. You can temporarily hide all other subsections by clicking the Items icon. To restore the view, click Show All. The Show All icon resembles an inverted triangle.

The following icons display next to the section title:

• Edit All. The Edit All icon resembles a small grid with a pencil on top of it. Use this icon to edit all items at once. See "Editing Multiple Items Simultaneously".

• Copy. The Copy icon resembles two small overlapping pages. Use this icon to make a copy of an existing item.

• Create. The Create icon resembles a plus (+) sign overlapping a small page. Click this icon to create an item.

Items are organized by region. To edit an item, click the item name.

7.7.3.1 About Item Naming Conventions

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

• Be unique within an application.

• Not include 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. Items longer than 30 characters cannot be referenced using bind variable syntax. See "About Bind Variable Syntax".

• Cannot contain letters outside the base ASCII character set

As a best practice Oracle recommends including the page number when naming items. By default, wizards prefix page item names with P<page no>_<item name> (for example, P1_NAME).

7.7.3.2 Creating a Page-Level Item on the Page Definition

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

To create a page-level item:

1. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

2. If necessary, create an HTML region. See "Understanding Regions".

3. To access the Create Item Wizard:

   • Tree view - Under Page Rending, right-click the region to contain the item and select Create Page Item.

   • Component view - Under Items, click the Create icon.

   The Create Item Wizard appears.

4. Select an item type. See "About Item Types".

   When creating a Popup LOV, Color Picker, or Text Field with Calculator Popup, select Popup LOV and then the specific popup list of values type.

5. For Display Position and Name:

   1. Item Name - Enter a name used to retrieve the value of the item. See "About Item Naming Conventions".

   2. Sequence - Specify the sequence for this component. The sequence determines the order of evaluation.

   3. Region - Select a region to contain this item.

   4. Click Next.

6. Follow the on-screen instructions.

7. To learn more about a specific field, click the field label.

   When help is available, the cursor changes to an arrow and question mark when you pass the cursor over an item. See "About Field-Level Help".

7.7.3.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. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

2. Access the attributes page for the item:

   • Tree view - Right-click the item and select Edit.

   • Component view -Under Items, select the item name.

   The Edit Page Item page appears.

3. Under Name, specify how the item is rendered. From Display As, select Select List.

4. Scroll down to List of Values.

5. Under List of Values, create a static list of values:

   1. From Named LOV, select Select Named LOV.

   2. In List of values definition, enter a definition using the following syntax:

      STATIC[2]:Display Value[;Return Value],Display Value[;Return Value]
      

      Where:

      • The first keyword may be STATIC or STATIC2.

        STATIC results in the values being sorted alphabetically by display value. STATIC2 results in the values being displayed in the order they are entered in the list.

      • A semicolon separates the display value from the return value in each entry.

      • Return Value is optional. If a Return Value is not included, the return value equals the display value.

6. To view help for a specific item on a page, click the item label. See "About Field-Level Help".

7. Click Apply Changes.

   The examples that follow demonstrate syntax for three different static LOVs.

STATIC:Cow,Dog,Cat,Lion

STATIC2:10,15,20,25,50,100,200,500,1000,10000

STATIC:Yes;Y,No;N

7.7.3.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. Application Builder includes cascading LOV support for the following item types: Select List, Shuttle, Checkbox, Radio Group, Popup LOV, and List Manager. To learn more about item types, see Appendix A, "About Item Types".

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 and name it P1_DEPTNO:

   1. Create a select list item. See "Creating a Page-Level Item on the Page Definition".

   2. For Item Type, select Select List.

   3. For Display Position and Name:

      • Item Name - Enter:

        P1_DEPTNO
        

      • Accept the remaining defaults and click Next.

   4. For Item Attributes:

      • Label - Enter Department

      • Accept the remaining defaults and click Next.

   5. For Settings, accept the defaults and click Next.

   6. For List of Values:

      • Display Null Value - Accept the default, Yes.

      • Null Display Value - Enter - Select Department -

        - Select Department -
        

      • In List of values definition, enter:

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

      • Click Next.

   7. Accept the remaining defaults.

   8. Click Create Item.

2. Create the second item named P1_EMPNO:

   1. Create a second item. See "Creating a Page-Level Item on the Page Definition".

   2. For Item Type, select Select List.

   3. For Display Position and Name:

      • Item Name - Enter:

        P1_EMPNO
        

      • Accept the remaining defaults and click Next.

   4. For Item Attributes:

      • Label - Enter Employee.

      • Accept the remaining defaults and click Next.

   5. For Settings, accept the defaults and click Next.

   6. For List of Values:

      • Display Null Value - Accept the default, Yes.

      • Null Display Value - Enter - Select Department -

        - Select Employee -
        

      • From Cascading LOV Parent Item(s) - Select P1_DEPTNO.

      • In List of values definition, enter:

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

      • Click Next.

   7. Accept the remaining defaults.

   8. Click Create Item.

Two select lists appear. Making a selection in the Department select list, determines which individuals display in the Employees select list.

7.7.3.5 Creating Multiple Items Using a Tabular Form

To create multiple items simultaneously:

1. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

2. If necessary, create an HTML region. See "Understanding Regions".

3. To access the Create Item Wizard:

   • Tree view - Under Page Rending, right-click the region to contain the item and select Create Page Item.

   • Component view - Under Items, click the Create icon.

   The Create Item Wizard appears.

4. Click the Create multiple items using tabular form link at the bottom of the page.

5. On the Create Multiple Items page, specify the following:

   1. Create Item(s) in Region - Select the region to contain the items.

   2. Item Template - Select an item template.

   3. For each item, enter the Sequence, Name, Label, Type and specify whether the item should be cached.

6. Click Create Multiple Items.

7.7.4.1 Editing Page Item Attributes

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

To edit page item attributes:

1. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

2. Access the attributes page for the item:

   • Tree view - Right-click the item and select Edit.

   • Component view -Under Items, select the item name.

   Tip:

   You can also edit an item by double-clicking the item name or selecting the name and pressing ENTER. See "Editing a Page in Tree View".

   The Edit Page Item page appears.

3. To learn more about a specific attribute on a page, click the attribute label. See "About Field-Level Help".

4. Click Apply Changes.

7.7.4.2 Defining Default Values

You define default values for an item using the attributes under Default on the Edit Page Item page. 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. Create the item. See "Creating Page-Level Items".

2. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

3. Access the attributes page for the item:

   • Tree view - Right-click the item and select Edit.

   • Component view -Under Items, select the item name.

   The Edit Page Item page appears.

4. Scroll down to Default.

5. In Default Value, enter a value.

6. From Default Value Type, select one of the following:

   • Static Text with Session State Substitutions

   • PL/SQL Function Body

   • PL/SQL Expression

7. Click Apply Changes.

7.7.4.3 Configuring Page Item Security

You can configure security for an item in Security region on the Edit Page Item page.

To configure page item security:

1. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

2. Access the attributes page for the item:

   • Tree view - Right-click the item and select Edit.

   • Component view -Under Items, select the item name.

   The Edit Page Item page appears.

3. Scroll down to Security.

4. Configure the attributes described in Table 7-11.

   Table 7-11 Edit 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 may be set by passing the item in a URL or in a form. No checksum is required in the URL. Restricted: May not be set from browser - The item may not be altered using the URL or POSTDATA. Select this option to restrict the way that the item value can be set to internal processes, computations, and so on. This attribute only applies to items that cannot be used as data entry items and is always observed, even if Session State Protection is disabled. Use this attribute for application items or for page items having the following Display As types: Display Only (Save State=No), Text Field (Disabled, does not save state), and Stop and Start Grid Layout (Displays label only). If Session State Protection is enabled, these additional attributes may be applied to items: Checksum Required: Application Level - The item may be set by passing the item in a URL if a checksum is also provided that is specific to the workspace and application. Checksum Required: User Level - The item may be set by passing the item in a URL if a checksum is also provided that is specific to the workspace, application, and user. Checksum Required: Session Level - The item may be set by passing the item in a URL if a checksum is also provided that is specific to the current session. See Also: "Understanding Session State Protection"
   Store value encrypted in session state	Session state that is sensitive can be encrypted when stored in Application Express session state management tables. To maintain session state encrypted for this item, set the value to Yes. 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	Use this attribute to restrict the characters that can be saved in session state. Oracle Application Express displays an error message if a user tries to save data which does not conform to the selected character restriction. Available options include: All Characters Allowed 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"

   
   

7.7.4.4 Creating a Quick Pick Selection

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. Create the item. See "Creating Page-Level Items".

2. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

3. Access the attributes page for the item:

   • Tree view - Right-click the item and select Edit.

   • Component view -Under Items, select the item name.

   The Edit Page Item page appears.

4. Scroll down to Quick Picks.

5. From Show Quick Picks, select Yes.

6. Define the Label and Value for each quick pick:

   1. Under Label, enter the label to display for each selection.

   2. Under Value, enter the corresponding value.

7. In Link Attributes, enter additional attributes for the quick picks.

8. Click Apply Changes.

7.7.4.5 Editing Multiple Items Simultaneously

Item attributes control how items display on a page. You can use the Page Items page to edit the sequence, field label, template, region, and overall position for all items on a page. The sections that follow describe how to edit items using these pages.

Topics:

• Items

• Reassign Region Items

• Delete Multiple Items

• Viewing Item Utilities

• History

7.7.6.1 Displaying Conditional Page Items

To display a conditional item:

1. Create the item. See "Creating Page-Level Items".

2. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

3. Access the attributes page for the item:

   • Tree view - Right-click the item and select Edit.

   • Component view -Under Items, select the item name.

   The Edit Page Item page appears.

4. Scroll down to Conditions.

5. Make a selection from the Condition Type list.

6. Enter an expression in the fields provided.

7. Click Apply Changes.

7.7.6.2 Displaying Read Only Page Items

To display a read-only item:

1. Create the item. See "Creating Page-Level Items".

2. Navigate to the appropriate Page Definition. See "Accessing the Page Definition".

3. Access the attributes page for the item:

   • Tree view - Right-click the item and select Edit.

   • Component view -Under Items, select the item name.

   The Edit Page Item page appears.

4. Scroll down to Read Only. Under Read Only:

   1. Make a selection from Read Only Condition Type.

      Depending on the item type, a read-only item may be rendered as plain text or as nonenterable field. Not selecting a condition causes the item to render normally.

      Tip:

      Setting Condition Type to Never always renders the item as an enterable field. This setting overwrites any read-only condition setting defined at the region or page-level.

   2. Enter an expression in the fields provided.

   3. In Read Only Element Table Cell(s) Attributes, enter attributes to be included in the HTML table cell tag, <td>, that contains the item when displayed in read only mode. For example:

      bgcolor="#FF0000"
      

      Tip:

      Read Only Element Table Cell(s) Attributes only be displays if the application uses HTML tables to layout regions and page items.

5. Click Apply Changes.

7.7.7.1 Using APEX_UTIL.STRING_TO_TABLE to Convert Selected Values

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 task, convert the colon-delimited string into a PL/SQL array using the APEX_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 APEX_APPLICATION_GLOBAL.VC_ARR2;
BEGIN
  --
  -- Convert the colon separated string of values into
  -- a PL/SQL array 

  l_selected := APEX_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;

7.7.7.2 Creating a Shuttle Item Type

Suppose you have a form on the DEPT table that shows which employees are assigned to a given department. To make assigning employees to a department easier, you can create a shuttle item that lists employees alphabetically.

To create a shuttle item:

1. Create a new Form page on DEPT using Form on a Table with Report:

   1. On the Workspace home page, click the Application Builder icon.

   2. Select an application.

   3. Click Create Page.

   4. For Page Type, select Form.

   5. Under Forms, select Form on a Table with Report.

   6. For Report Page, accept the defaults and click Next.

   7. For Table/View Name, select DEPT.

   8. Accept the remaining defaults and follow the on-screen instructions. To learn more about a specific field, click the item label.

2. Create a shuttle named P2_EMP_LIST and the form page.

   1. Go the Page Definition for the form page.

   2. Right-click the region containing the form and select Create Page Item.

   3. For Item Type, select Shuttle.

   4. For Item Name, enter P2_EMP_LIST and click Next.

      Tip:

      In this example, "P2" in the item name P2_EMP_LIST indicates the item resides on page 2.

   5. For Item Attributes, accept the defaults and click Next.

   6. For Setting, accept the defaults and click Next.

   7. For List of Values:

      • List of Values Query - Enter:

        SELECT ename, empno FROM emp ORDER BY 1
        

      • Click Next.

   8. For Source:

      • Source Type - Select SQL Query (return color separated value)

      • Item Source Value - Enter:

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

      • Click Create Item.

   9. Run the page by clicking the Run Page icon.

      
      Description of the illustration shuttle_example.gif