Understanding Page-Level Items

About the Drag and Drop Icon

You can quickly change the appearance of a page by clicking the Drag and drop icon to access the Drag and Drop Layout page. The Drag and drop icon resembles a green rectangle and displays to the right of the Reorder Region Items icon.

You can use the Drag and Drop Layout page to interactively reorder items within a given region, change select item attributes, create items, or delete existing items. See "Using the Drag and Drop Layout Page".

About the Reorder Items Icon

You can quickly edit the label and position of items in a region by clicking the Reorder Region Items icon on the Page Definition. This icon resembles a light green down or up arrow.

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 a Page Definition".

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

3. Under Items, click the Create icon.

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

5. Follow the on-screen instructions.

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

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

About Item Naming Conventions

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

• Be unique within an application

• 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-2 describes available item types.

SELECT NULL display_text, 'YES' return_value FROM DUAL;

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

SELECT ename name, empno id 
   FROM emp

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

SELECT ename, empno FROM emp

SELECT ename display_text, empno return_value FROM emp

Creating Multiple Items Using Tabular Form

To create multiple items simultaneously:

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

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

3. Under Items, click the Create icon.

   The Create Item wizard appears.

4. At the bottom of the page, click the Create multiple Items Using Tabular Form link.

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.

Creating Multiple Items Using Drag and Drop

To create multiple items using the Drag and Drop Layout page:

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

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

3. Under Items, click the Create icon.

   The Create Item wizard appears.

4. At the bottom of the page, click the Create multiple Items Using Drag and Drop Layout link.

   The Drag and Drop Layout page appears.

5. Select an item from the palette on the left side of the page and drag it to the appropriate position on the page.

6. Edit the item attributes at the of the page.

   1. Display Name - Enter an item name. Use this name retrieve the value of the item. Item names longer than 30 characters cannot be referenced using bind variable syntax.

   2. Label - Enter the label for this item. You may include HTML, JavaScript, and shortcuts. You can also use the substitution string #CURRENT_ITEM_NAME# to obtain the name of the item associated with this label.

   3. Display Type - Select a display type (if applicable). See "About Item Types".

7. To edit an existing item, edit the Item Name and Label fields, or select a new Display Type at the top of the page.

8. Click Next.

9. Optionally, edit the each item's Name and Label.

10. Click Apply Changes.

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 a Page Definition".

2. Under Items, select the item name.

   The Edit Page Item page appears.

3. Under Name, specify how the item will be rendered. Make a selection from the Display As list.

4. 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 is the same as the display value.

5. To learn more, see item Help. To view help for a specific item on a page, click the item label.

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

6. 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

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 a Page Definition".

2. Under Items, select the item name.

   The Edit Page Item page appears.

3. To learn more about a specific attribute on a page, click the attribute label.

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

4. Click Apply Changes.

Using the Edit All Icon to Edit Multiple Items

You can edit multiple items at once by clicking the Edit All icon on the Page Definition. The Edit All icon resembles a small grid with a pencil on top of it.

Clicking the Edit All icon displays a series of pages that enable you to edit multiple items simultaneously or view a history of recent changes.

Topics in this section include:

• Page Items

• Item Help

• Reassign Region Items

• Delete Multiple Items

• History

Using the Reorder Region Items Icon

You can quickly edit the label and position of items in a region by clicking the Reorder Region Items icon on the Page Definition. This icon resembles a light green down or up arrow.

To use the Reorder Region Items icon:

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

2. Under Items, click the Reorder Region Items icon.

   The Reorder Region Items page appears with items laid out in tables. You can edit the position of an item by selecting values for New Line, New Field, Column Span, and Label Alignment attributes. Note that a graphical representation of how the items display appears at the bottom of the page.

3. To edit an item label, enter a new title in the Label field.

4. To change the position of an item, edit the following attributes:

   • New Line. Determines if the item displays on the same line as the previous item, or displays on the next line. Select Yes to have an item display as the first field in a new row in the table.

   • New Field. Determines if the item displays in the next column or in the same column as the previous item. Select Yes to have the label and value for the item display in a new HTML table cell. Use this attribute in combination with the New Line and Span attributes to control layout.

   • Column Span. Defines the value to be used for the COLSPAN attribute in the table cell. The COLSPAN attribute defines the number of columns that it spans across the table.

5. To change label alignment, make a selection from the Label Alignment list.

6. To change the order in which items display, click the up and down arrows in the far right column. Clicking the arrow moves the item one row up or down.

   Note that the order you specify here translates to sequence number in the Sequence attribute on the Edit Page Item page. See "Editing Page Item Attributes".

7. Click Apply Changes.

Accessing the Drag and Drop Layout Page

You access the Drag and Drop Layout page by either:

• Clicking the Drag and drop icon on the Page Definition. See "About the Drag and Drop Icon".

• Clicking the Reorder Regions Items icon and selecting the Drag and Drop Layout tab. See "Using the Reorder Buttons Icon".

About the Drag and Drop Layout Page

The Drag and Drop Layout page is divided into two sections: Item palette and Layout region.

The Item palette displays on the left side of the page. You add items by clicking an item type on the palette and dragging it to the correct position in the Layout region. Note that when you position the cursor over an item type, a tooltip appears.

Use the right side of the page (or Layout region) to position items. To move an item vertically, click the Add Row button to insert an empty row. Then drag and drop the item into the empty row.

Creating a New Item

To create a new item on the Drag and Drop Layout page:

1. Navigate to the Drag and Drop Layout page. See "Accessing the Drag and Drop Layout Page".

2. Click an item type in the Item palette on the left side of the page and drag it to the appropriate location in the Layout region.

   Note that when you position the cursor over an item type, a tooltip appears.

3. You can reposition the item:

   • To move an item horizontally, select the item and drag it to the appropriate position on the page.

   • To insert an existing or new item between two existing rows, click the Add Row button and drag it between the existing rows. This creates an empty row where you can then move the item.

4. Edit the item attributes at the of the page.

   1. Display Name - Enter an item name. Use this name to retrieve the value of the item. Item names longer than 30 characters cannot be referenced using bind variable syntax.

   2. Label - Enter the label for this item. You may include HTML, JavaScript, and shortcuts. You can also use the substitution string #CURRENT_ITEM_NAME# to obtain the name of the item associated with this label.

   3. Display Type - Select a display type (if applicable). Note that the select list is restricted to options corresponding to the type of item you are creating. See "About Item Types".

5. Click Next.

6. Optionally, edit the each item's Name and Label.

7. Click Apply Changes.

Editing Existing Items

To edit an existing item on the Drag and Drop Layout page:

1. Navigate to the Drag and Drop Layout page. See "Accessing the Drag and Drop Layout Page".

2. To reposition the item:

   • To move an item horizontally, select the item and drag it to the appropriate position on the page.

   • To insert an existing or new item between two existing rows, click the Add Row button and drag it between the existing rows. This creates an empty row where you can then move the item.

3. If required, select an item and edit its attributes at the of the page.

   1. Display Name - Enter an item name. Use this name retrieve the value of the item. Item names longer than 30 characters cannot be referenced using bind variable syntax.

   2. Label - Enter the label for this item. You may include HTML, JavaScript, and shortcuts. You can also use the substitution string #CURRENT_ITEM_NAME# to obtain the name of the item associated with this label.

   3. Display Type - Select a display type (if applicable). Note that the select list is restricted to options corresponding to the type of item you are creating. See "About Item Types". See "About Item Types".

4. Click Next.

5. Optionally, edit the each item's Name and Label.

6. Click Apply Changes.

Deleting Items

To delete an item, click it and drag it to the Recycle box at the bottom of the page. If you delete an existing item, it appears in the Recycle box and can be retrieved until you click Apply Changes on the next page. Note that if you drop a new item you have just created in the Recycle box, it instantly disappears and cannot be retrieved.

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, you would 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;