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.

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. You further specify what current looks like using template attributes.

Description of the illustration list.gif

Topics in this section include:

How To Create a List
Adding a List to a Page
Editing a List
Editing Multiple List Entries Simultaneously
Accessing List Reports

How To Create a List

To add a list to a page in your application, you must:

Create the list using one of these methods:
- Create a list from scratch by running the Create/Edit Lists Wizard from either the Shared Components page or Page Definition.
- Copy an existing list. If the list contains list items or entries, the items are also copied.
Add entries to the list:
- Create list entries from scratch.
- Copy a single list entry from the current list. This copies the list entry attributes.
- Copy list entries from another list into the current one. This merges the two sets of list entries without changing the list whose entries are copied into the current one.
Add the list to a page by creating a List region.

Topics in this section include:

Creating a List from Scratch
Copying Lists
Adding List Entries and Sublists
Changing Parents of List Entries
Removing Parent of Orphaned List Entries

Creating a List from Scratch

To create a list:

Access the Create/Edit Lists Wizard:

To access the wizard from the Shared Components page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application Builder home page, click Shared Components.
4. Under Navigation, click Lists.
5. Click Create.
To access the wizard from a Page Definition:
1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition".
2. Under Shared Components, click the Create icon in the Lists section.
In the Create/Edit Wizard:
1. Name - Enter a name for the list.
2. List Template - Select a list template.
3. 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.
Click Create.

Copying Lists

To copy a list:

Access the Copy List Wizard:

To access the wizard from the Shared Components page:
1. On the Workspace home page, click the Application Builder icon.
2. Select an application.
3. On the Application Builder home page, click Shared Components.
4. Under Navigation, click Lists.
5. Click Copy.
To access the wizard from a Page Definition:
1. Navigate to the appropriate Page Definition. See "Accessing a Page Definition".
2. Under Shared Components, click the Copy icon in the Lists section.
  
  The Copy icon appears only if a list exists for this page.
In the Copy Wizard, select the location of the list to copy and click Next.
If you selected List in another application, select the application and click Next.
For Identify List, enter a name for the new list and click Copy.

For the list to appear on a page, you must add it to the page.

Adding List Entries and Sublists

Once your list is created, you must add entries to it. You can add list entries from scratch, copy one list entry within a list, or copy 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.

Adding Entries or Sublists from Scratch

To add an entry or sublist from scratch:

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.
Select a list.
Click Create List Entry.

The Create/Edit List Entry page appears.
Under Entry:
1. Parent List Item - Identify the parent for this list entry. Use this attribute if you are creating a hierarchical list that will contain a sublist.
2. Sequence - Indicate the order in which list entries appear.
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 allows for the title image attribute to be automatically set based on the value of the list label text. For example:
```
title="#LIST_LABEL#"
```
5. List Entry Label - Enter the label text for this link.
Specify a target location.

If the target location is a URL, specify the following:
- Target is a - Select URL.
- 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.
  
  You can also select reset pagination for this page. Selecting this option causes the page to return to the first set of data meeting a user's new query.
  
  You can also select Printer Friendly. Selecting 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 - Specify the request to be used.
4. Clear Cache - Specify the page numbers on which to clear cache.
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\).
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 - Based on the selection above, define a condition to evaluate. When this condition is true, then the list item becomes current.
To make the list entry conditional, specify the appropriate information under Conditions.
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.
Under Configuration, you can select a build option for this component.

Build options are predefined settings that determine whether components within an application are enabled.
Under Click Counting, you can 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.
To specify additional attributes, use the User Defined Attributes section. For example, the following adds a tabindex and accesskey.
```
tabindex="15" accesskey="D"
```
When you are finished defining list attributes, click Create or Create and Create Another.

Copying List Entries

To copy list entries:

Navigate to the List Entries 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.
5. On the Lists page, click the name of the list whose entries you want to copy.
  
  The List Entries page appears.
To copy a single list entry that appears in the current list:
1. Click the Copy icon in the in the row you want to copy. The Copy icon appears under the Copy column in the list.
  
  All the attributes of the selected list entry, such as image and parent, will be copied to the new entry.
2. For Copy List Entry, enter the appropriate information and click Copy List Entry.
To copy list entries from one list to another:
1. Click Copy List Entries from one List to Another under the Tasks list on the right side of the page.
2. For Identify Copy Target, select the target list where you want to add the entries and click Next.
3. For Confirm List Entry Copy, click the Report of New Combined List to review the composite list.
4. Click Copy List Entries.

Changing Parents of List Entries

To change the parent of list entries:

Navigate to the List Entries 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.
5. On the Lists page, click the name of the list whose entries you want to update.
  
  The List Entries page appears.
From the Tasks list on the right, click Reparent List Entries within this List.
On the Reparent List Entries page:
1. Enter the appropriate information for List and Start With and click Go.
  
  You can use the Start With field to filter down a large, hierarchical list to pinpoint the entries you need to reparent. You can also use these fields to focus on a subset of a list you want to edit.
2. For Reparent To, select the new parent for the list entries.
3. Select the check boxes for the list entries you want to include.
4. Click Reparent Checked Entries.

Removing Parent of Orphaned List Entries

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

To remove the parent of an orphaned list entry:

Navigate to the List Entries 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.
5. On the Lists page, click the name of the list whose entries you want to update.
  
  The List Entries page appears.
From the Tasks list on the right, click Manage Oprhaned List Entries.
On the Manage Orphaned List Entries page:
1. From the Show list, select Orphaned and click Go.
2. Select the check boxes for the orphaned list entries.
3. Click Remove Parent Entry.

Adding a List to a Page

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.

Editing a List

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

To edit a list:

Navigate to the Lists page.

From the Page Definition:
1. Navigate to the Workspace home page.
2. Click the Application Builder icon.
3. Select an application.
4. Select a page.
5. Under Shared Components, click Edit All.
From the Shared Components 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.
On the Lists page, you can change the appearance of the page by making a selection from the View list:
- Icons (the default) displays each list as a large icon. To edit a list, click the appropriate icon.
- Details displays each list as a line in a report. To edit a list, click the list name.
Select a list.

The List Entries page appears.
Select the appropriate list name.

The Create/Edit List Entry 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.
Edit the appropriate attributes.
To learn more about 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".
Click Apply Changes.

Editing Multiple List Entries Simultaneously

You can edit multiple list entries simultaneously by clicking Grid Edit on the List Entries page.

To edit multiple list entries at once:

On the Workspace home page, click the Application Builder icon.
Select an application.
On the Application Builder home page, click Shared Components.
Under Navigation, click Lists.

The Lists page appears.
Select a list name.

The List Entries page appears.
Click Grid Edit.
Edit the appropriate items and click Apply Changes.

Accessing List Reports

You can view the List Utilization by Page, Unused Lists, and List History reports by clicking the appropriate tab at the top of the Lists page.

Note:

The List Utilization, Unused Lists, and History buttons only appear after you create a list.

Utilization

Click List Utilization on the Lists page to access the Lists 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, click List Template Utilization. Then click the name to view or edit the list template.

Unused

Click Unused on the Lists page to identify lists that are not used in the current application.

History

Click History on the Lists page to view changes to list definitions and list entries by developer and date.