Creating Lists

A list is a shared collection of links. You add a list to a page by creating a region and specifying the region type as List. You control the appearance of a list through list templates.

You can define a list by creating static or dynamic definition to display a specific type of page item, such as progress bars, sidebar, or a bullet navigation list. The following illustration is an example of a static list using the template Vertical Unordered List with Bullets.

Description of the illustration list.gif

You can further control how a list displays using template attributes. For information about altering a list display, see "Creating a New Template" and "List Templates".

Topics:

• About List Types

• About Static Lists

• About Dynamic Lists

• Copying a List

• Adding a List to a Page by Creating a Region

• Editing List Attributes

• Accessing List Reports

About List Types

Oracle Application Express supports two types of lists: static and dynamic.

Static Lists

When you create a static list you define a list entry label and a target (either a page or URL). You can add list entries when you create the list (creating from scratch), by copying existing entries, or by adding the list entries. You can control when list entries display by defining display conditions. See "About Static Lists".

Dynamic Lists

Dynamic lists are based on a SQL query or a PL/SQL function executed at runtime. A dynamic list enables you to dynamically create styled list items that support mobile frameworks such as jQuery Mobile. See "About Dynamic Lists" and "Understanding Dynamic List Syntax".

About Static Lists

To create a static list:

1. Create the list by running the Create List Wizard.

2. Specify whether to create the list from scratch or by copying an existing list.

   You can add list entries by either creating them from scratch or by coping entries from an existing list. If you copy an entire list, you also copy all of its list entries.

3. If creating a list from scratch, you are prompted to select a list type. Select Static.

   Each list element has a display condition, which enables you to control when it displays. You can define a list element to be either current or non-current for a specific page. See "Editing List Attributes" and "Conditional Entries".

4. Add the list to a page by creating a List region.

How you perform these steps is a personal preference. You can perform all three when you run the Create List Wizard. Alternatively, you can perform these steps one at a time.

Topics:

• Creating a Static List from Scratch

• Adding Entries and Sublists to a Static List

• Copying Static List Entries Between Lists

• Reparenting Static List Entries

• Managing Orphaned Static List Entries

• Resequencing Static List Entries

Creating a Static List from Scratch

To create a list:

1. Access the Create/Edit Lists Wizard:

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

   2. Select an application.

   3. On the Application home page, click Shared Components.

   4. Under Navigation, click Lists.

   5. Click Create.

2. For Source, select From Scratch and click Next.

3. For Name and Type:

   1. Name - Enter a numeric or alphanumeric name for the list.

   2. Type - Select Static.

   3. List Template - Select a list template to control the appearance of your list.

      To view currently used list templates, expand the List Template Utilization region. You can specify default templates on the Define Theme page.

   4. Build Option - If applicable, select a build option for this component. Build options are predefined settings that determine whether components within an application are enabled.

   5. Click Next.

4. For Define List Entries, specify the following:

   1. List Entry Label - Enter a numeric or alphanumeric name for the list.

   2. Target Page ID or custom URL - Select a target page or enter a custom URL.

   3. Click Next.

5. For Confirm, specify the following:

   1. Create List Regions - Select whether or not to create a list region. Options include:

      • Do not create list region(s)

      • Create list region on current page

      • Create list region for each target page

   2. Region Position - If creating a new region, select the region position.

   3. Region Template - If creating a new region, select a region template.

   4. Click Create.

Tip:

You can also create a list under Shared Components on the Page Definition. To learn more, see "Accessing the Page Definition", "Editing a Page in Tree View", and "Editing a Page in Component View"

Adding Entries and Sublists to a Static List

Once you create a list, you must add entries to it. You can add list entries when creating a list from scratch, copying a list entry from within a list, or copying existing entries from one list to another.

You can also create hierarchical lists that contain sublists. To create a hierarchical list, you must:

• Select a list template that supports hierarchical lists. To determine which list templates support hierarchical lists, look for templates having the naming convention "with Sublist."

• Select a Parent List Item when you create each list entry.

See Also:

"Customizing Templates" and "List Templates"

Adding Entries or Sublists from Scratch

To add an entry or sublist from scratch:

1. Navigate to the Lists page:

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

   2. Select an application.

   3. On the Application home page, click Shared Components.

   4. Under Navigation, select Lists.

      The Lists page appears.

2. Select a list.

   The List Details page appears.

3. Click Create List Entry.

4. Under Entry:

   1. Parent List Entry - If applicable, select the parent for this list entry. Use this attribute if you are creating a hierarchical list that will contain a sublist.

      Note this attribute does not appear if you are creating the parent list entry.

   2. Sequence - Indicate the order in which list the list entry appears. The sequence determines the order of evaluation.

   3. Image - Identify the file name for the image used to display this list entry. List templates control this attribute.

   4. Attributes - Identify the image attributes (such as width="12" height="12") for the list element image.

      Use the #LIST_LABEL# substitution string to reference the list label text. This substitution string enables the title image attribute to be automatically set based on the value of the list label text. For example:

      title="#LIST_LABEL#"
      

   5. Alt Attribute - Identify the image alt attribute for the list element image.

      Use the #LIST_LABEL# substitution string to reference the list label text. This substitution string enables the Alt attribute to be automatically set based on the value of the list label text. For example:

      ...alt="#LIST_LABEL#"...
      

   6. List Entry Label - Enter the label text for this link.

5. Specify a target location. Options include: URL or Page in this Application.

   If the target location is a URL, specify the following:

   1. Target Type - Select URL.

   2. URL Target - Enter a URL. For example:

      http://www.yahoo.com
      

   If the target location is a page:

   1. Target Type - Select Page in this Application.

   2. Page - Specify the target page number.

      Other options include:

      • reset pagination for this page - Select this option to have the page to return to the first set of data meeting a user's new query.

      • Printer Friendly - This option displays the target page using the application's Printer Friendly template. Printer friendly templates optimize a page for printing. "Changing the Default Templates in a Theme" and "Optimizing a Page for Printing".

   3. Request - Enter text to set the built-in application item REQUEST. This is also the item that is set with the name of a button that was clicked.

   4. Clear Cache - Specify the page numbers on which to clear cache. To learn more, see item Help. See "About Field-Level Help".

   5. To set session state (that is, give a listed item a value):

      • Set these items - Enter a comma-delimited list of item names for which you would like to set session state.

      • With these values - Enter a comma-delimited list of values for the items specified in the previous step.

        You can specify static values or substitution syntax (for example, &APP_ITEM_NAME.). Note that item values passed to f?p= in the URL cannot contain a colon. Additionally, item values cannot contain commas unless you enclose the entire value in backslashes (for example, \1234,56\).

6. Under Current List Entry:

   1. List Entry Current for Pages Type - Specify when this list entry should be current based on the page type.

      List items can be current or non-current. Current list items use the current template; non-current list items use the non-current list item template. The actual condition and templates are defined in subsequent attributes.

   2. List Entry Current for Condition - Displays conditionally. Based on the selection above, define a condition to evaluate. When this condition is true, then the list item becomes current. To learn more, see item Help. See "About Field-Level Help".

7. Under Conditions, specify the appropriate information to make the list entry conditional.

8. Under Authorization, you can specify an authorization scheme.

   This authorization scheme must evaluate to TRUE in order for this component to be rendered or otherwise processed.

9. Under Configuration, select a build option for this component.

   Build options are predefined settings that determine whether components within an application are enabled.

10. Under Click Counting, specify if you want the list entries to be included in the click count.

    If this is a link to an external page, such as www.google.com, you can count clicks. For more information, see "COUNT_CLICK Procedure" in Oracle Application Express API Reference.

11. To specify additional attributes, use the User Defined Attributes section. For example, the following adds a tabindex and accesskey.

    tabindex="15" accesskey="D"
    

12. When you are finished defining list attributes, click Create or Create and Create Another.

Copying Static List Entries Between Lists

You can copy static list entries from one list to another.

To copy list entries between lists:

1. Navigate to the Lists page.

   1. Navigate to the Workspace home page.

   2. Click the Application Builder icon.

   3. Select an application.

   4. On the Application home page, click Shared Components.

   5. Under Navigation, click Lists.

      The Lists page appears.

2. Select the list to copy.

3. On the Tasks list, click Copy List Entries from one List to Another.

4. From Copy List Entries, select the list to copy to and click Next.

5. Click Copy List Entries.

Reparenting Static List Entries

Use the Reparent List Entries page to manage list entry hierarchy.

To reparent list entries:

1. Navigate to the Lists page.

   1. Navigate to the Workspace home page.

   2. Click the Application Builder icon.

   3. Select an application.

   4. On the Application home page, click Shared Components.

   5. Under Navigation, click Lists.

      The Lists page appears.

2. Select the list.

3. From the Tasks list, click Reparent List Entries within this List.

4. Use Start With to restrict your view to a subset of hierarchy. Make a selection and click Go.

5. From Reparent To, select a new parent.

6. Select the entries to move.

7. Click Reparent Checked Entries.

Managing Orphaned Static List Entries

An orphaned list entry is a list entry which has a parent, but the parent is no longer a member of the current list. When a list entry becomes orphaned, remove the parent entry.

To manage orphaned list entries:

1. Navigate to the Lists page.

   1. Navigate to the Workspace home page.

   2. Click the Application Builder icon.

   3. Select an application.

   4. On the Application home page, click Shared Components.

   5. Under Navigation, click Lists.

      The Lists page appears.

2. Select the list.

3. From the Tasks list, click Manage Orphaned List Entries.

4. Select the entries to remove.

5. Click Clear Parent Entries.

Resequencing Static List Entries

You can resequence list entries in increments of 10 on the Clean Up page.

To clean up list entries:

1. Navigate to the Lists page.

   1. Navigate to the Workspace home page.

   2. Click the Application Builder icon.

   3. Select an application.

   4. On the Application home page, click Shared Components.

   5. Under Navigation, click Lists.

      The Lists page appears.

2. Select the list.

3. From the Tasks list, click Clean Up List Entries.

4. Click Clean Up.

About Dynamic Lists

A dynamic list enables you to dynamically create styled list items that support mobile frameworks such as jQuery Mobile. Dynamic lists are based on a SQL query or a PL/SQL function returning a SQL query.

To create a dynamic static list:

1. Create the list by running the Create List Wizard.

2. Specify whether to create the list from scratch or by copying an existing list.

3. If creating a list from scratch, you are prompted to select a list type. Select Dynamic.

4. Enter a SQL query or a PL/SQL function returning a SQL query.

5. Add the list to a page by creating a List region. See "Adding a List to a Page by Creating a Region".

Topics:

• Understanding Dynamic List Syntax

• Creating a Dynamic List from Scratch

Understanding Dynamic List Syntax

You create a dynamic list using a SQL query or a function returning a SQL Query.

Syntax for a SQL query:

SELECT level, labelValue label, 
       [targetValue]            target, 
       [is_current]             is_current_list_entry,
       [imageValue]             image, 
       [imageAttributeValue]    image_attribute,
       [imageAltValue]          image_alt_attribute,
       [attribute1]             attribute1,
       [attribute2]             attribute2,
       [attribute3]             attribute3,
       [attribute4]             attribute4,
       [attribute5]             attribute5,
       [attribute6]             attribute6,
       [attribute7]             attribute7,
       [attribute8]             attribute8,
       [attribute9]             attribute9,
       [attribute10]            attribute10
FROM ...
WHERE ...
ORDER BY ...

Syntax for a function returning a SQL query:

RETURN
'SELECT level, labelValue label,'||
'       [targetValue]         target,'|| 
'       [is_current]          is_current_list_entry,'||
'       [imageValue]          image,'||
'       [imageAttributeValue] image_attribute, '||
'       [imageAltValue]       image_alt_attribute,'||
'       [attribute1]          attribute1,'||
'       [attribute2]          attribute2,'||
'       [attribute3]          attribute3,'||
'       [attribute4]          attribute4,'||
'       [attribute5]          attribute5,'||
'       [attribute6]          attribute6,'||
'       [attribute7]          attribute7,'||
'       [attribute8]          attribute8,'||
'       [attribute9]          attribute9,'||
'       [attribute10]         attribute10'||
'FROM ...'||
'WHERE ...'||
'ORDER BY ...';

Where:

• level and labelvalue are required.

• level - For hierarchical lists, the level parameter should be supplied. For non-hierarchical lists, this parameter can be set to NULL.

• labelvalue - Text to appear as list entry.

• targetvalue - Target URL to branch to when list entry is selected.

• is_current - Controls the behavior of the list entry. Values include:

  • NULL - Currency of target is based upon Target URL.

  • 'YES' - List entry is always current.

  • 'NO' - List entry is not current.

  If 'YES', list entry is always current, if NO, list entry is not current.

• imagevalue - The name of image to be display on the list entry

• imageattributevalue - Attributes of the image, such as the width or height

• imagealtvalue - Value for Image ALT tag, required for accessibility purposes in templates where the user must click on the image.

• attribute1 to 10: These attributes tie in with the existing ten User Attributes exposed on the Static List Entry page.

Creating a Dynamic List from Scratch

To create a dynamic list:

1. Access the Create/Edit Lists Wizard:

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

   2. Select an application.

   3. On the Application home page, click Shared Components.

   4. Under Navigation, click Lists.

   5. Click Create.

2. Click From Scratch and click Next.

3. For Name and Type:

   1. Name - Enter a numeric or alphanumeric name for the list.

   2. Type - Select Dynamic.

   3. List Template - Select a list template to control the appearance of your list.

      To view currently used list templates, expand the List Template Utilization region.

   4. Build Option - If applicable, select a build option for this component. Build options are predefined settings that determine whether components within an application are enabled.

   5. Click Next.

4. For Query or Static Values:

   1. Query Source Type - Select SQL Query or Function Returning SQL Query.

   2. Query - Enter a SQL query or function returning a SQL query. See "Understanding Dynamic List Syntax".

   3. Click Next.

5. For Confirm, specify the following:

   1. Create List Regions - Select whether or not to create a list region. Options include:

      • Do not create list region(s)

      • Create list region on current page

   2. Region Position - If creating a new region, select the region position.

   3. Region Template - If creating a new region, select a region template.

   4. Click Create.

Tip:

You can also create a list under Shared Components on the Page Definition. To learn more, see "Accessing the Page Definition", "Editing a Page in Tree View", and "Editing a Page in Component View"

Copying a List

You can copy a list from another application or from a list in the existing application.

Topics:

• Copying a List from the Current Application

• Copying a List Between Applications

Copying a List from the Current Application

You can copy list entries from one list to another.

To copy list entries between lists:

1. Navigate to the Lists page.

   1. Navigate to the Workspace home page.

   2. Click the Application Builder icon.

   3. Select an application.

   4. On the Application home page, click Shared Components.

   5. Under Navigation, click Lists.

      The Lists page appears.

2. Select the list to copy.

3. On the Tasks list, click Copy List.

4. On Copy List, select List in this application and click Next.

5. For Identify List:

   1. Copy List - Select the list to be copied.

   2. New List Name - Enter a new name for the copied list.

   3. Click Copy.

Copying a List Between Applications

You can copy a list from the current application or from another application.

To copy a list:

1. Navigate to the Lists page.

   1. Navigate to the Workspace home page.

   2. Click the Application Builder icon.

   3. Select an application.

   4. On the Application home page, click Shared Components.

   5. Under Navigation, click Lists.

      The Lists page appears.

2. Select the list to copy.

3. On the Tasks list, click Copy List.

4. On Copy List, select List in another application and click Next.

5. For Identify List:

   1. Copy From Application - Select the application from which you want to copy a list.

   2. Copy List - Select the list you are copying.

   3. New List Name - Enter a name for the new list.

   4. Click Copy.

Adding a List to a Page by Creating a Region

Once you create a list and list entries, the next step is to add it to a page by creating a region and specifying the region type as List.

See Also:

"Creating a New Template" and "List Templates" for information about altering list display

To add a list to a page:

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

2. On the Page Definition, add a list region:

   • Tree view - Under Page Rendering, right-click Regions and select Create.

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

   The Create Region Wizard appears.

3. For Region, select List as the region type and click Next.

4. For Display Attributes, specify the following and click Next:

   • Title - Enter a title for the region. This title will display if the region template you choose displays the region title.

   • Region Template - Choose a template to control the look of the region.

   • Parent Region - Defines the parent region to which the new region belongs.

   • Display Point - Identify a display point for this region. There are two types of display points:

     • Page body positions are displayed where indicated by the #BODY# substitution string in the page template.

     • Page template positions are controlled by page template substitution strings (#REGION_POSITION_01#..#REGION_POSITION_08#). Page template region positions enable exact placement of a region within a template.

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

   • Column - Indicate the column where this region is to be displayed. A page can have multiple regions, which can be displayed in different columns. Note that this attribute only applies to regions that are displayed in a Page Template Body position.

5. For Source, select the list you want to add.

6. For Conditional Display, optionally select a condition type or authorization scheme.

7. Click Create Region.

Repeat these procedures for each page where you would like to add a list.

Editing List Attributes

Once you create a list, you can edit it on the Lists page.

To edit a list:

1. Navigate to the Lists page.

   1. Navigate to the Workspace home page.

   2. Click the Application Builder icon.

   3. Select an application.

   4. On the Application home page, click Shared Components.

   5. Under Navigation, click Lists.

      The Lists page appears.

      You can change the appearance of each page by using the Search bar at the top of the page.

2. Select a list.

   The List Details page appears.

3. To change the list name, template, or build options, click the Edit List button.

4. For a dynamic list:

   1. Edit the appropriate attributes. To learn more about an attribute, click the item label. See "About Field-Level Help".

   2. Click Apply Changes.

5. For a static list:

   1. To edit the list sequence, link text, target, or current status for all list entries, click Grid Edit.

   2. Click the Edit icon adjacent to the appropriate list entry.

      The Create/Edit page that appears is divided into sections. You can access these sections by scrolling down the page, or by clicking a navigation button at the top of the page. When you select a button at the top of the page, the selected section appears and all other sections are temporarily hidden. To view all sections of the page, click Show All.

   3. Edit the appropriate attributes. To learn more about an attribute, click the item label. See "About Field-Level Help".

   4. Click Apply Changes.

Accessing List Reports

You can view the Unused, Conditional Entries, Utilization, and History reports by clicking the appropriate tab at the top of the Lists page. Note that these reports only display after you create a list.

To view list reports:

1. Navigate to the Lists page.

   1. Navigate to the Workspace home page.

   2. Click the Application Builder icon.

   3. Select an application.

   4. On the Application home page, click Shared Components.

   5. Under Navigation, click Lists.

      The Lists page appears.

2. Click the appropriate tab:

   • Unused

   • Conditional Entries

   • Utilization

   • History

   You can change the appearance of each page by using the Search bar at the top of the page.

   To learn more, see the sections that follow.

Unused

Click the Unused tab to identify lists that are not used in the current application.

Conditional Entries

Click the Conditional Entries tab to view conditional lists.

Utilization

Click the List Utilization tab to access the Utilization report. This report displays all lists included in the current application. From the report:

• To edit list entries, select the list name.

• To view the pages on which the list appears, click the number in the Pages column.

• To view the template used with the list, expand List Template Utilization. Then click the name to view or edit the list template.

History

Click the History tab to view changes to list definitions and list entries by developer and date.