Go to primary content
Oracle® Application Express Application Builder User's Guide
Release 5.0
E39147-04
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

15.3 Managing Page-Level Items in Component View

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. This section describes how to create page-level items in Component View.

15.3.1 Viewing Page-Level Items in the Component View

This section describes how to create and edit page-level items.

Description of pg_item_cv.png follows
Description of the illustration pg_item_cv.png

In Component View, items display under the section Items. To edit, copy, and create items, click the following icons 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.

15.3.2 Creating Page-Level Items in Component View

This section describes how to create page-level items by running the Create Item Wizard.

15.3.2.1 Creating a Page-Level Item in Component View

To create a page-level item:

  1. Navigate to the appropriate page. See "Viewing a Page in Component View."

  2. If necessary, create a region. See "About Regions."

  3. Under Items, click the Create icon.

    The Create Item Wizard appears.

  4. For Create Item:

    1. Item Type - 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.

    2. Show Unsupported - Selecting No only displays items types designed for the user interface of the current page. Selecting Yes displays any additional item types which are designed for other user interfaces.

    3. Click Next.

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

  5. For Display Position and Name:

    1. Item Name - Enter an item name. This name provides a handle for retrieving the value of the item. Item names longer than 30 characters cannot be referenced using bind variable syntax. See "About Item Naming Conventions."

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

    3. Region - Determines the region in which the item is placed.

    4. Click Next.

  6. Follow the on-screen instructions.

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

15.3.2.2 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. See "Viewing a Page in Component View."

  2. If necessary, create a region. See "About Regions."

  3. Under Items, click the Create icon.

    The Create Item Wizard appears.

  4. For Create Item:

    1. Item Type - Select Select List.

    2. Show Unsupported - Selecting No only displays items types designed for the user interface of the current page. Selecting Yes displays any additional item types which are designed for other user interfaces.

    3. Click Next.

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

  5. For Display Position and Name:

    1. Item Name - Enter an item name. This name provides a handle for retrieving the value of the item. Item names longer than 30 characters cannot be referenced using bind variable syntax. See "About Item Naming Conventions."

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

    3. Region - Determines the region in which the item is placed.

    4. Click Next.

  6. For Item Attributes:

    1. Label - Enter an item label. The label is the text that appears next to the item when it displays. If you do not want a label, leave the label attribute blank.

    2. Height - Enter the number of rows high for the item display. For most items this should be 1.

    3. Template - Optionally, select a field template to control the display of the item.

    4. Click Next.

  7. For Settings:

    1. Value Required - If set to Yes and the page item is visible, Application Express automatically performs a NOT NULL validation when the page is submitted.


      Tip:

      By defining a message called APEX.PAGE_ITEM_IS_REQUIRED in Shared Components/Text Messages, the predefined error text can be replaced by an application specific error text. The display location of the message is defined by the application-level setting Default error display location.

    2. Page Action on Selection - Specify whether multiple values or only a single value can be selected from the list of values. Multiple values are returned as a comma-separated list.

    3. Allow Multi Selection - Specify whether multiple values or only a single value can be selected from the list of values. Multiple values are returned as a comma-separated list.

    4. Click Next.

  8. For List of Values:

    1. Named LOV - Select Select Named LOV.

    2. List of Values Query - Enter a query 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.

    3. Edit the remaining attributes and click Next.

  9. Edit the remaining attributes as needed and click Create Item.

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

15.3.2.2.1 Example 1: Four Values Displayed in Alphabetical Order

In this example, the list of values has four values (Cow, Dog, Cat, and Lion) that display in alphabetical order. The return value of each entry equals the display value.

STATIC:Cow,Dog,Cat,Lion

15.3.2.2.2 Example 2: Ten Values Displayed in the Order Listed

In this example, the list of values has ten values that display in the order listed in the definition. The return value of each entry equals the display value.

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

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

In this example, the list of values has two values: Yes and No (the display value Yes and its return value Y, and the display value No and its return value N).

STATIC:Yes;Y,No;N

15.3.2.3 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 "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 sections 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. Navigate to the appropriate page. See "Viewing a Page in Component View."

    2. If necessary, create a region. See "About Regions."

    3. Under Items, click the Create icon.

      The Create Item Wizard appears.

    4. For Item Type, select Select List.

    5. For Display Position and Name:

      • Item Name - Enter:

        P1_DEPTNO
        
      • Accept the remaining defaults and click Next.

    6. For Item Attributes:

      • Label - Enter Department

      • Accept the remaining defaults and click Next.

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

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

    9. Accept the remaining defaults.

    10. Click Create Item.

  2. Create the second item named P1_EMPNO:

    1. Navigate to the appropriate page. See "Viewing a Page in Component View."

    2. If necessary, create a region. See "About Regions."

    3. Under Items, click the Create icon.

      The Create Item Wizard appears.

    4. For Item Type, select Select List.

    5. For Display Position and Name:

      • Item Name - Enter:

        P1_EMPNO
        
      • Accept the remaining defaults and click Next.

    6. For Item Attributes:

      • Label - Enter Employee.

      • Accept the remaining defaults and click Next.

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

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

    9. Accept the remaining defaults.

    10. Click Create Item.

  3. Click Run to view a rendered version of the page.

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

    Description of cascading_lov.png follows
    Description of the illustration cascading_lov.png

15.3.2.4 Creating Multiple Items Using a Tabular Form

To create multiple items simultaneously:

  1. Navigate to the appropriate page. See "Viewing a Page in Component View."

  2. If necessary, create a region. See "About Regions."

  3. Access the Create Item Wizard. 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.

15.3.3 Editing Page-Level Items in Component View

You can edit page-level items by editing page item attributes or using the Edit All or Reorder Items icons.


See Also:

"About Item Types"

15.3.3.1 Editing Page Item Attributes in Component View

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. See "Viewing a Page in Component View."

  2. Under Items, select the item name.

    The Edit Page Item page appears.

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

  4. Click Apply Changes.

15.3.3.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 in Component View."

  2. View the item attributes. Under Items, select the item name.

    The Edit Page Item page appears.

  3. Scroll down to Default.

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

    • Static Text with Session State Substitutions

    • PL/SQL Function Body

    • PL/SQL Expression

  5. In Default Value, enter a value or code based on your selection.

  6. Click Apply Changes.

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

  2. View the item attributes. Under Items, select the item name.

    The Edit Page Item page appears.

  3. Scroll down to Security.

  4. Configure the attributes described in Table 15-3.

    Table 15-3 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"


15.3.3.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%.

Description of quick_pick.png follows
Description of the illustration quick_pick.png

To create a quick pick:

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

  2. View the item attributes. Under Items, select the item name.

    The Edit Page Item page appears.

  3. Scroll down to Quick Picks.

  4. From Show Quick Picks, select Yes.

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

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

  7. Click Apply Changes.

15.3.3.5 Displaying Conditional Page Items

To display a conditional item:

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

  2. View the item attributes. Under Items, select the item name.

    The Edit Page Item page appears.

  3. Scroll down to Conditions.

  4. Make a selection from the Condition Type list.

  5. Enter expressions in the fields provided.

  6. Click Apply Changes.

15.3.3.6 Displaying Read Only Page Items

To display a read-only item:

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

  2. View the item attributes. Under Items, select the item name.

    The Edit Page Item page appears.

  3. 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 expressions 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.

  4. Click Apply Changes.

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

15.3.3.7.1 Editing Multiple Items

To edit multiple items simultaneously:

  1. Navigate to the page containing the items. See "Viewing a Page in Component View."

  2. Access the Page Items page. Under Items, click the Edit All icon. The Edit All icon resembles a small page with a pencil on top of it.

    The Items tab appears.

    A Navigation bar displays at the top of the page. Use the Page field to navigate to another page. Use the Name field to search for a specific item. To limit the display to just items in a specific region, make a selection from Regions list.

    The Page Items page displays items in an editable report. Table 15-4 describes editable attributes.

    Table 15-4 Editable Attributes on Page Items

    Attribute Description

    Sequence

    Specify the display sequence for this component. The sequence determines the order of evaluation.

    Prompt

    Enter the label for this HTML form element. 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.

    Field Template

    Determines the label template. Label templates enable you to define the user interface attributes in a central place and share that definition among many labels.

    Region

    Defines the region in which the item displays. All items must be in a region.

    New Line

    Determines whether this item displays on the same line as the previous item or whether it displays on the next line. Items are laid out in an HTML table. Select Yes to have an item display as the first field in a new row in the table.

    New Field

    If set to Yes, this item is rendered into its own HTML table cell which is the default. If set to No, the item is rendered into the same HTML table cell as the previous page item.

    Note that rendering into the same table cell looks more attached to the previous page item.

    Width

    Specifies the length (in characters) of the form element that displays for this item.

    Height

    Specifies the height (in lines) for text areas and multi select lists.

    Column Span

    Items are laid out in HTML tables. This property defines the value to be used for the COLSPAN attribute in the table cell.

    Row Span

    Items are laid out in HTML tables. The attribute determines the value to be used for the ROWSPAN attribute in the table cell that the item displays in.

    Post Element

    Text or HTML code is rendered immediately after the page item element.


15.3.3.7.2 Reassigning Region Items

Use the Reassign Region Items page to assign items to a new region.

To assign items to a new region on the Reassign Region Items page:

  1. Navigate to the page containing the items. See "Viewing a Page in Component View."

  2. Access the Page Items page. Under Items, click the Edit All icon. The Edit All icon resembles a small page with a pencil on top of it.

  3. Click Reassign Region Items.

    The Reassign Region Items page appears.

    Use the Navigation bar at the top of the page to narrow or broaden the display. Available options include:

    • Page - Select or enter a new number and click Go.

    • Show Region(s) - Select a region to display and click Go.

  4. To reassign an item to another region:

    1. Select the items to reassign.

    2. From Assign to Region, select a new region.

    3. Click Reassign.

15.3.3.7.3 Deleting Multiple Items

Use the Delete Multiple Items page to simultaneously delete multiple items.

To delete multiple items:

  1. Navigate to the page containing the items. See "Viewing a Page in Component View."

  2. Access the Page Items page. Under Items, click the Edit All icon. The Edit All icon resembles a small page with a pencil on top of it.

  3. Click Delete Multiple Items.

    The Delete Multiple Items page appears.

    Use the Navigation bar at the top of the page to narrow or broaden the display. Use the Page field to navigate to a new page. Select or enter a new number and click Go.

  4. To delete items:

    1. Select the items.

    2. Click Remove Items.

15.3.3.7.4 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. Navigate to the page containing the items. See "Viewing a Page in Component View."

  2. Access the Page Items page. Under Items, click the Edit All icon. The Edit All icon resembles a small page with a pencil on top of it.

  3. Click Utilities.

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

    • Conditional Items

15.3.3.7.5 Viewing Page Item History

Use the History page to view a summary of recent edits to page-level items.

To access the History page:

  1. Navigate to the page containing the items. See "Viewing a Page in Component View."

  2. Access the Page Items page. Under Items, click the Edit All icon. The Edit All icon resembles a small page with a pencil on top of it.

  3. Click History.

    The Page Item History page appears.