14.2 Adding Items to a Page

Oracle Portal comes with many seeded item types, which you can use to add content to your pages. Additionally it provides the capability of developing your own custom item types. The process of adding items to your pages is largely the same from item to item, whether seeded or custom. What differs are the attributes associated with the item type. To highlight some of those differences, this section describes how to add a variety of different item types to a page. It includes the following subsections:

• Section 14.2.1, "Adding a File Item"

• Section 14.2.2, "Adding Text to a Page"

• Section 14.2.3, "Adding a URL Link to a Page"

• Section 14.2.4, "Adding a Simple Item Link to a Page"

• Section 14.2.5, "Adding Dynamic Data (PL/SQL Item)"

• Section 14.2.6, "Specifying How Item URLs Are Formed"

• Section 14.2.7, "Tricks for Adding and Editing Items"

14.2.1 Adding a File Item

When you add a file to a portal page, the display option that you select determines whether the content is displayed in place on the page or as a link. When a link displays, users click it to view item content or to download item content to their local file system.

To add a file-type item:

Note:

The item attributes included in this process are the default item attributes for the item. You may be adding a simple or custom version of the item type, in which case, the attributes may vary. That is, some of the attributes included in the following steps will not be present; some that are not included will be.

1. Log in to Oracle Portal.

2. Go to the page to which to add the item.

   For information on locating a page through the Page Groups portlet, see Section 8.1, "Locating Pages in Oracle Portal".

3. Click the Edit link at the top of the page.

   This opens the page in Edit mode.

4. Go to the region to which to add the item, and click the Add Item icon (Figure 14-2).

   Figure 14-2 The Add Item Icon

   
   

   Note:

   If the Add Item icon does not display next to the region, the region may be a portlet region. You can add items only to an item region.

   To add a sub-item to an existing item, click the Actions icon (Figure 14-3) next to that item and then choose Add a subitem.

   Figure 14-3 The Actions Icon

   
   

   Note:

   To add sub-items to an item, you must have the at least the item privilege Edit on the item.

5. On the Item Type Selection page, select a file-based item type from the Content Item Types list.

   For example, select File or Simple File. If the item type does not appear on the list, contact your page group administrator. The page group administrator specifies the types of items available to the page group.

   Note:

   If the page group administrator has configured the page group to allow only one type of item, the Item Type Selection page is skipped, and the Item Attributes page is displayed. For example, if the page group is configured to include only file-type items, when a user clicks the Add Item icon, the Item Attributes page for file-type items displays.

6. Click Next.

7. On the Item Attributes page, in the File Name field, enter the path and file name of the item or browse to and select the item.

   The file name is case sensitive and must be unique on the page. If the file name is not unique, a value is automatically added to the end of the name. Use up to 126 characters. In addition to character restrictions imposed by your operating system, you cannot use the following characters in the file name:

   & # %

   Note:

   For a summary of the rules governing the naming of objects in Oracle Portal, see Appendix D, "Object Naming Rules in Oracle Portal".

   In the Oracle Portal user interface, an asterisk (*) indicates a field that requires a value.

8. In the Display Name field, enter a display name for the item.

   Use up to 256 characters. Use any character, including spaces. When the item displays as a link, the Display Name is the link text that users click to view the item. This field defaults to the file name when no Display Name is specified.

9. From the Category drop-down list, select the category that most accurately classifies item content.

10. In the Description field, enter a brief description of the item content.

11. In the Publish Date field, specify the date on which the item should display to other users.

    Use the format: DD-MON-YYYY HH12:MI PM. You will see the item when you edit the page, but no other users (except administrators) will see it until the publish date.

12. Specify an Expiration Date:

    On the day you specify, the content is marked (in Edit mode) as expired, and is removed from other users' view of the page. If the page group is configured to display expired items, you will still be able to see it in Edit mode and, if you wish, un-expire it, until the portal administrator purges expired items from the portal.

    Choose from:

    • Never Expires—The item does not expire.

    • Expires In [ ] Days—The item expires in the number of days you specify (calculated from the publish date).

    • Expires On [ ] (DD-MON-YYYY HH12:MI PM)—The item expires on the date and time you specify.

13. Click the perspectives you will use to classify this content in the Available Perspectives list, then click the Move icon that points to the Displayed Perspectives list.

    In Windows, press and hold the Ctrl key to select two or more perspectives. In UNIX, simply click each perspective.

14. Select an image/icon for the item.

    Either:

    • Click the Browse button to locate and select an image on your file system; or

    • Enter the URL or the internal name of a previously uploaded image.

    Add images in the JPEG, GIF, or PNG formats.

    Any images associated with the item—whether the image is the item itself or an attribute of the item—are affected by item versioning. If you are using item versioning and you always want to show the current version of the image, use the image's durable URL instead of the internal file name. The durable URL always picks up the latest version of the image. For more information, see Section 14.12.4, "Images and Item Versioning".

    You can use settings at the region level to ensure that all image/icons display in a uniform size. For more information, see Section 10.2.8, "Setting a Uniform Height and Width for Item Icons".

15. Select an image alignment from the Image Alignment drop-down list.

    Images are aligned relative to the item's Display Name. For illustrations of the image alignment options, see Table 14-1, "Item Image Alignment Options".

16. In the Basic Search Keywords field, enter keywords to assist users in finding this item during a search.

    Separate each word with a space, a comma, or some other punctuation mark.

17. In the Author field, enter the name of the item's author.

18. Select Enable Item Check-Out to enable users to check an item out for individual use.

    This prevents other users from overwriting the item while it is checked out. However, page group administrators and page designers can check-in items that have been checked-out by other users.

19. Select the way the item will display from the Display Options radio buttons.

    Choose from:

    • Link That Displays Item In Full Browser Window

      When users click the item link, the item content displays in the current browser window

    • Link That Displays Item In New Browser Window

      When users click the item link, the item content displays in a new, second browser window.

    A third display option, Item Displayed Directly In Page Area, is available for some items when you edit the item (though not when you add one). This option displays only when the item is of the type Text, PL/SQL, URL, or File, and only for Files of type text/html or text/plain.

    Note:

    You can use a Portal Template for items only when you select one of the Link display options when you specify item attribute values. The Link display options include Link That Displays Item In Full Browser Window and Link That Displays In New Browser Window. When you select the item display option Item Displayed Directly In Page Area, the Portal Template for items you have associated with the item in page properties or in item attributes is ignored. For more information on Portal Templates for items, see Chapter 12, "Providing a Standard Look and Feel".

20. Click Finish to save your changes and return to the page.

Table 14-1 Item Image Alignment Options

Alignment	Description	Example
Left	Aligns the image on the left side of the page.
Right	Aligns the image on the right side of the page.
Top	Aligns the top of the image with the top of the display name.
Bottom	Aligns the bottom of the image with the baseline of the display name. Same as Baseline.
Absolute Middle	Aligns the middle of the image with the absolute middle of the display name.
Absolute Bottom	Aligns the bottom of the image with the absolute bottom of the display name.
Text Top	Aligns the top of the image with the top (tallest text) of the display name.
Middle	Aligns the middle of the image with the baseline of the display name.
Baseline	Aligns the bottom of the image with the baseline of the display name. Same as Bottom.
Image Above Link	Aligns the image over the display name.

Adding an Excel Spreadsheet

Before adding an excel spreadsheet you need to do the following:

1. Save your .xls file as Web Page in the Save As dialog box.

2. In the Save As dialog box, click on Tools at the top right corner and select Web Option.

3. In the Web Options dialog box, click the Browsers tab.

4. Under Options, select Rely on VML for displaying graphics in browsers.

5. Click OK.

6. Click Save.

To add the excel file to your Portal, see Adding a File Item.

14.2.2 Adding Text to a Page

Using the Oracle Portal rich text editor, you can add up to 32 KB of plain text, or embedded HTML, to a text-based item on a page. Use text-based items for:

• Browser-based authoring—Text, including HTML, can be added directly to portal pages through the addition of a Text item type. Enter HTML tags to format the content. Alternatively, use the embedded WYSIWYG rich text editor to build the underlying HTML for you.

• In-place display—Text item content can be displayed directly on a portal page. This is useful when you want to add headings, announcements, news summaries, product descriptions, and the like to portal pages.

Note:

If the content of your text item includes special characters, such as HTML tags, these characters are escaped before the size of the item is calculated. Therefore, you may find that you unexpectedly reach the 32K limit. <<TODO include list of special characters if possible>>

This section describes how to add text to a page and how to use the Oracle Portal rich text editor. It contains the following subsections:

• Section 14.2.2.1, "Adding a Text Item"

• Section 14.2.2.2, "The Rich Text Editor"

14.2.2.1 Adding a Text Item

To add text:

Note:

The item attributes included in the following steps are the default item attributes for the item. You may be adding a simple or custom version of the item type, in which case, the attributes may vary. That is, some of the attributes included in the following steps will not be present; some that are not included will be.

1. Log in to Oracle Portal.

2. Go to the page to which to add the item.

   For information on locating a page through the Page Groups portlet, see Section 8.1, "Locating Pages in Oracle Portal".

3. Click the Edit link at the top of the page.

   This opens the page in Edit mode.

4. Go to the region to which to add the item, and click the Add Item icon (Figure 14-4).

   Figure 14-4 The Add Item Icon

   
   

   Note:

   If the Add Item icon does not display next to the region, the region may be a portlet region. You can add items only to an item region.

   To add a sub-item to an existing item, click the Actions icon (Figure 14-5) next to that item and then choose Add a subitem.

   Figure 14-5 The Actions Icon

   
   

   Note:

   To add sub-items to an item, you must have at least the item privilege Edit on the item.

5. On the Item Type Selection page, choose a text-based item type from the Content Item Types list.

   For example, choose Text or Simple Text. If the item type you are looking for does not appear in the list, contact your page group administrator. The page group administrator specifies the types of items available to the page group.

   Note:

   If the page group administrator has configured the page group to allow only one type of item, the Item Type Selection page is skipped, and the Item Attributes page is displayed. For example, if the page group is configured to include only file-type items, when a user clicks the Add Item icon, the Item Attributes page for file-type items displays.

6. Click Next.

7. On the Item Attributes page, in the Text field, enter text using the Rich Text Editor.

   Note:

   For more information on the Rich Text Editor, see Section 14.2.2.2, "The Rich Text Editor".

   In the Oracle Portal user interface, an asterisk (*) indicates a field that requires a value.

   • The text size is limited to 32 KB. Note that HTML tags that are included in the text are included as part of the 32 KB. Note also that the size of the item is calculated after special characters (such as &, ", <, and >) are escaped (for example, to &amp;, &quot;, &lt;, and &gt;) , which also increases the size of the item. If the text is larger than 32 KB, create another text item, or consider putting the text in a file and adding it as a file item.

   • To display the current user's name in this item, you can enter the following variables in the Text field:

     • #USER#, for the user's name

     • #USER.FULLNAME#, for the user's full name

   • To include a link to another item or page in the portal, use a relative URL. Using a relative URL means that the link will not break if the portal is moved to a different machine.

     For more information about the formation of URLs in Oracle Portal, see Appendix C, "Formation of URLs in Oracle Portal".

8. In the Display Name field, enter a name to display for the item in the portal.

   Use up to 256 characters. Use any character, including spaces. If this item is displayed as a link, the Display Name is used as the link text that users click to view the item.

   Note:

   For a summary of the rules governing the naming of objects in Oracle Portal, see Appendix D, "Object Naming Rules in Oracle Portal".

9. From the Category drop-down list, select the category that most accurately classifies item content.

10. In the Description field, enter a brief description of the item content.

11. In the Publish Date field, specify the date on which the item should display to other users.

    Use the format: DD-MON-YYYY HH12:MI PM. You will see the item when you edit the page, but no other users (except administrators) will see the item until the publish date.

12. Specify an Expiration Date:

    On the day you specify, the content is marked (in Edit mode) as expired, and is removed from other users' view of the page. If the page group is configured to display expired items, you will still be able to see it in Edit mode and, if you wish, un-expire it, until the portal administrator purges expired items from the portal.

    Choose from:

    • Never Expires—The item does not expire.

    • Expires In [ ] Days—The item expires in the number of days you specify.

    • Expires On [ ] (DD-MON-YYYY HH12:MI PM)—The item expires on the date and time you specify.

13. Select the perspectives you will use to classify this content in the Available Perspectives list, and click the Move icon that points to the Displayed Perspectives list.

    In Windows, press and hold the Ctrl key to select two or more perspectives. In UNIX, simply click each perspective.

14. In the Image field, specify a image/icon for the item.

    Either:

    • Click the Browse button to locate and select an image on your file system; or

    • Enter the URL or the internal name of a previously uploaded image.

    Add images in the JPEG, GIF, or PNG formats.

    Any images associated with the item—whether the image is the item itself or an attribute of the item—are affected by item versioning. If you are using item versioning and you always want to show the current version of the image, use the image's durable URL instead of the internal file name. The durable URL always picks up the latest version of the image. For more information, see Section 14.12.4, "Images and Item Versioning".

15. Select an image alignment relative to the item display name from the Image Alignment drop-down list.

    For illustrations of the image alignment options, see Table 14-1, "Item Image Alignment Options".

16. In the Basic Search Keywords field, enter keywords to assist users in finding this item during a search.

    Separate each word with a space, a comma, or some other punctuation mark.

17. In the Author field, enter the name of the item's author.

18. Select Enable Item Check-Out to enable users to check an item out for individual use.

    This prevents other users from overwriting the item while it is checked out. However, page group administrators and page designers can check-in items that have been checked-out by other users.

19. Select the way the item will display from the Display Options radio buttons.

    Choose from:

    • Link That Displays Item In Full Browser Window

      When users click the item link, the item content displays in the current browser window

    • Link That Displays Item In New Browser Window

      When users click the item link, the item content displays in a new, second browser window.

    A third display option, Item Displayed Directly In Page Area, is available for some items when you edit the item (though not when you add one). This option displays only when the item is of the type Text, PL/SQL, URL, or File, and only for Files of type text/html or text/plain.

    Note:

    You can use a Portal Template for items only when you select one of the Link display options when you specify item attribute values. The Link display options include Link That Displays Item In Full Browser Window and Link That Displays In New Browser Window. When you select the item display option Item Displayed Directly In Page Area, the Portal Template for items you have associated with the item in page properties or in item attributes is ignored. For more information on Portal Templates for items, see Chapter 12, "Providing a Standard Look and Feel".

20. Click Finish to save your changes and return to the page.

14.2.2.2 The Rich Text Editor

When you add a text item to a page, Oracle Portal provides a rich text editor for entering WYSIWYG text or HTML source code. This section provides an overview of this editor, including a table that lists and describes all the controls available through the editor. It includes the following subsections:

• Section 14.2.2.2.1, "About the Rich Text Editor"

• Section 14.2.2.2.2, "Rich Text Editor Controls"

Note:

Consider disabling the rich text editor if you are using a browser that does not support it. Otherwise, the editor may hang or exhibit inconsistent behavior.

Browsers that support the rich text editor include:

• Microsoft Internet Explorer 6.0

• Netscape 7.2

• Mozilla 1.7

• Firefox 1.0

For information on disabling the Oracle Portal rich text editor, see Section 5.5.5, "Disabling the Rich Text Editor".

14.2.2.2.1 About the Rich Text Editor

Starting with the 9.0.4.1 version of Oracle Portal, the rich text editor (WYSIWIG editor) that is used to enter content for text items is much improved. Improvements include:

• Multi-browser support

• Enhanced table editing support

• Additional features, such as Select All, Search and Replace, and Table Cell Properties buttons

• Support for embedded JavaScript in HTML

  JavaScript is retained rather than stripped, as happened in earlier versions of the editor. Note that the editor does not execute the JavaScript inside the HTML when it is rendered in the editor in WYSIWYG mode (though the JavaScript does execute at runtime). This means the content you see in the rich text editor might be very different from what is rendered in the browser.

• Support for relative URLs

  Now, both absolute and relative URLs are supported. This enables you to refer to an image item using a relative path to the page where the text item is located. That is, when you insert an image with the URL /images/logo.gif, the reference remains a relative link and is not converted to an absolute URL (as happened in earlier versions).

• Possibility of extending or replacing the seeded rich text editor

  You can customize the Oracle Portal rich text editor to support your needs: from simple changes, for example, replacement of buttons on the editor's toolbar, to more complex changes, for example, replacement of the seeded editor with one of your own.

  Such changes involve altering the files that comprise the user interface and functions of the seeded rich text editor. This being the case, this feature is intended for advanced Oracle Portal administrators. Additionally, you should be aware that future upgrades of Oracle Portal may impact any modifications made to these files. Support for this feature is offered through the Portal Content Area discussion forum and not through Oracle Support; consequently, if you have questions, you must take them to the forum and not to Oracle Support. Finally, we strongly advise that you back up the original editor's files before making any modifications, and that you back up modified files.

Note:

The Rich text editor ignores the following tags:

• Script tags

• Form elements such as input, select, textarea, and form.

• Frame/frameset

• Document' tags such as html, head, body, meta, and title.

• Unknown tags sych as <foo></foo>.

14.2.2.2.2 Rich Text Editor Controls

The rich text editor available through Oracle Portal offers two ways to create and modify Web pages:

• WYSIWYG (what you see is what you get) edit mode provides a visual representation of your page.

• HTML edit mode provides a means of modifying the HTML source code.

The functionality listed and described in Table 14-2 is available through the rich text editor toolbar. In your portal, hover your mouse pointer over any toolbar button to view a tool tip with the name of the feature.

Accessibility Note:

To navigate out of the editor's text field using the keyboard, you must switch off your screen reader's form mode. (In JAWS, use the Plus key (+) on your numeric keypad to turn form mode off.) Once form mode is off, press the Tab key to change focus to the next HTML element on the page.

Table 14-2 Rich Text Editor Controls

Button/Keystrokes	Mode: WYSIWYG/HTML/Both	Function
Ctrl + X	Both	Cut selected content. Cut content can be re-pasted, provided no other cuts have been performed in the interim.
Ctrl + C	Both	Copy selected content.
Ctrl + V	Both	Paste content.
Ctrl + Z	WYSIWYG	Undo last action. Click (or press) again to undo preceding actions.
Ctrl + Y	WYSIWYG	Redo last action. Click (or press) again to perform additional redo's.
	WYSIWYG	Select the font in which to set the selected or subsequent text. Choose from the fonts available on your file system.
	WYSIWYG	Select a font size in which to set the selected or subsequent text: 1 = smallest 7 = largest
Ctrl + B	Both	Bold selected or subsequent text.
Ctrl + I	Both	Italicize selected or subsequent text.
Ctrl + U	Both	Underline selected or subsequent text.
	WYSIWYG	Set the text color.
	WYSIWYG	Set the text background color. This is also called highlighting. The selected color appears behind the text.
Tools menu: Change Edit Mode	Both	Switch between a graphical edit mode (WYSIWYG) and an HTML edit mode. WYSIWYG is the default. Use the WYSIWYG edit mode to display text as it will appear on your page. Use HTML edit mode to modify the HTML source code.
	WYSIWYG	Add/change a link. You can create any kind of standard Web link. For example: Link to another Web page. Enter the full URL, for example: http://www.oracle.com Link to an e-mail address by entering "mailto:", for example: mailto:[e-mail]. When users click this type of link, a new, blank e-mail message window opens, addressed to the addressee you enter here, in the current browser's default e-mail application. For a mailto link to work, the user's browser preferences must be properly configured. In Netscape browsers, you can find e-mail settings under Preferences in the Mail & Newsgroups section. In Internet Explorer browsers, you can find e-mail settings under Internet Options on the Programs tab.
	WYSIWYG	Insert a horizontal line.
	WYSIWYG	Insert an image. Use images that are available in your portal. To obtain the image URL to use with this feature: Go to the portal page where the image is uploaded. Enter page edit mode. If necessary, edit the region that contains the image to include the Property Sheet attribute. Display the image's property sheet. Copy the URL listed next to the Item Link label in the image's property sheet.
	WYSIWYG	Insert a table. Specify the following table attributes: Number of rows Number of columns Border size. Enter a value in pixels. Enter 0 if you do not want a border. Cell padding. Enter a value in pixels to provide space between the cell content and the cell boundary. Cell spacing. Enter a value in pixels to provide space between each cell. Cell width: Enter a value in pixels to define the width of all cells.
	WYSIWYG	Add or delete a row. Added rows are always placed above the row where the cursor is located.
	WYSIWYG	Add or delete a column. Added columns are placed to the left of the column where the cursor is located.
	WYSIWYG	Edit the following table cell properties: Cell width Cell height Text alignment Vertical alignment Background color
	WYSIWYG	Align the current paragraph left, center, or right.
	WYSIWYG	Add/remove a bulleted or numbered list. Once you start a list, every time you press Enter a new bulleted or numbered item is added. Press Enter twice to end the list.
	WYSIWYG	Decrease or increase the current paragraph's indentation. Note: You must use these keys to increase or decrease indents in WYSIWYG mode. Using the Tab key does not indent a paragraph.
	WYSIWIG	Find and replace text within the editor window.
	WYSIWYG	Select all. This highlights all of the content in the editor window.
Ctrl + P	Both	Print the content in the editor window. Note: Your cursor must be in the editor window for this key combination to have the desired effect.

14.2.3 Adding a URL Link to a Page

You can add a link to another Web page, Web site, or document URL that is internal or external to the page group. To do this, you add a URL item to the page.

You can also add a direct link to an item in your portal by entering the item's path-based or durable URL. See Section 2.1.3, "Understanding Page and Item URLs".

To add a link to a URL:

Note:

The item attributes included in this process are the default item attributes for the item. You may be adding a simple or custom version of the item type, in which case, the attributes may vary. That is, some of the attributes included in the following steps will not be present; some that are not included will be.

1. Log in to Oracle Portal.

2. Go to the page to which to add the item.

   For information on locating a page through the Page Groups portlet, see Section 8.1, "Locating Pages in Oracle Portal".

3. Click the Edit link at the top of the page.

   This opens the page in Edit mode.

4. Go to the region to which to add the item, and click the Add Item icon (Figure 14-6).

   Figure 14-6 The Add Item Icon

   
   

   Note:

   If the Add Item icon does not display next to the region, the region may be a portlet region. You can add items only to an item region.

   To add a sub-item to an existing item, click the Actions icon (Figure 14-7) next to that item and then choose Add a subitem.

   Figure 14-7 The Actions Icon

   
   

   Note:

   To add sub-items to an item, you must have at least the item privilege Edit on the item.

5. On the Item Type Selection page, choose URL from the Content Item Types list.

   If the item type you are looking for does not appear in the list, contact your page group administrator. The page group administrator specifies the types of items available to the page group.

   Note:

   If the page group administrator has configured the page group to allow only one type of item, the Item Type Selection page is skipped, and the Item Attributes page is displayed. For example, if the page group is configured to include only file-type items, when a user clicks the Add Item icon, the Item Attributes page for file-type items displays.

6. Click Next.

7. On the Item Attributes page, in the URL field, enter the target URL.

   Note:

   When URL items with Display Options set to Item Displayed Directly In Page Area are to be rendered on Portal Templates for items, they cannot point to a URL that requires HTTP authentication. Such items rendered as links have no such restriction.

   In the Oracle Portal user interface, an asterisk (*) indicates a field that requires a value.

   • If you want to add an e-mail link, enter the appropriate HTML code containing the person's e-mail address. For example, remove "https://" from the URL field and enter mailto:[e-mail].

     For a mailto link to work, the user's browser preferences must be properly configured. In Netscape browsers, you can find e-mail settings under Preferences in the Mail & Newsgroups section. In Internet Explorer browsers, you can find e-mail settings under Internet Options on the Programs tab.

   • For backward compatibility, the URL item type supports direct access, relative URLs. Users who click the resulting link are redirected to a splash screen that links to the item in the current URL syntax (if the splash screen is enabled, see Appendix C, "Formation of URLs in Oracle Portal"). Keep in mind that if a URL item is not created with http:// or https:// at the beginning, the URL is treated as a relative URL, and not an absolute URL.

     To avoid the splash screen and redirection, consider using the Simple Item Link item type to link to objects that are inside your portal. See Section 14.2.4, "Adding a Simple Item Link to a Page".

     For more information about the formation of URLs in Oracle Portal, see Appendix C, "Formation of URLs in Oracle Portal".

   Note:

   URL-type items that point to locations outside the firewall require a reconfiguration of the Web Cache Manager's proxy server. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle Portal.

8. In the Display Name field, enter a display name for the item.

   This is used for the link text that users click to access the URL item's target. Use up to 256 characters. Use any character, including spaces.

   Note:

   For a summary of the rules governing the naming of objects in Oracle Portal, see Appendix D, "Object Naming Rules in Oracle Portal".

9. From the Category drop-down list, select the category that most accurately classifies item content.

10. In the Description field, enter a brief description of the item content.

11. In the Publish Date field, specify the date on which the item should display to other users.

    Use the format: DD-MON-YYYY HH12:MI PM. You will see the item when you edit the page, but no other users (except administrators) will see it until the publish date.

12. Specify an Expiration Date:

    On the day you specify, the content is marked (in Edit mode) as expired, and is removed from other users' view of the page. If the page group is configured to display expired items, you will still be able to see it in Edit mode and, if you wish, un-expire it, until the portal administrator purges expired items from the portal.

    Choose from:

    • Never Expires—The item does not expire.

    • Expires In [ ] Days—The item expires in the number of days you specify.

    • Expires On [ ] (DD-MON-YYYY HH12:MI PM)—The item expires on the date and time you specify.

13. Click the perspectives you will use to classify this content in the Available Perspectives list, and click the Move icon that points to the Displayed Perspectives list.

    In Windows, press and hold the Ctrl key to select two or more perspectives. In UNIX, simply click each perspective.

14. Select an image/icon for the item; either:

    • Click the Browse button to locate and select an image on your file system; or

    • Enter the URL or the internal name of a previously uploaded image.

    Add images in the JPEG, GIF, or PNG formats.

    Any images associated with the item—whether the image is the item itself or an attribute of the item—are affected by item versioning. If you are using item versioning and you always want to show the current version of the image, use the image's durable URL instead of the internal file name. The durable URL always picks up the latest version of the image. For more information, see Section 14.12.4, "Images and Item Versioning".

15. Select an image alignment relative to the item display name from the Image Alignment drop-down list.

    For illustrations of the image alignment options, see Table 14-1, "Item Image Alignment Options".

16. In the Basic Search Keywords field, enter keywords to assist users in finding this item during a search.

    Separate each word with a space, a comma, or some other punctuation mark.

17. In the Author field, enter the name of the item's author.

18. Select Enable Item Check-Out to enable users to check an item out for individual use.

    This prevents other users from overwriting the item while it is checked out. However, page group administrators and page designers can check-in items that have been checked-out by other users.

19. From the Display Options radio buttons, select the way the item will display.

    Choose from:

    • Item Displayed Directly In Page Area

      The URL's target content displays in the current browser window.

    • Link That Displays Item In Full Browser Window

      When users click the item link, the item content displays in the current browser window

    • Link That Displays Item In New Browser Window

      When users click the item link, the item content displays in a new, second browser window.

    Note:

    You can use a Portal Template for items only when you select one of the Link display options when you specify item attribute values. The Link display options include Link That Displays Item In Full Browser Window and Link That Displays In New Browser Window. When you select the item display option Item Displayed Directly In Page Area, the Portal Template for items you have associated with the item in page properties or in item attributes is ignored. For more information on Portal Templates for items, see Chapter 12, "Providing a Standard Look and Feel".

20. Click Finish to save your changes and return to the page.

14.2.4 Adding a Simple Item Link to a Page

The Simple Item Link item type provides a swift, easy means of linking to existing portal content (such as, a file, text, a URL, an image, and so on) that is contained within the same page group as the link. Using this feature eliminates the need to upload separately-maintained copies of the item. Users click the item link, and the item is rendered on its own in the current browser window.

To add a Simple Item Link:

1. Log in to Oracle Portal.

2. Go to the page to which to add the item.

   For information on locating a page through the Page Groups portlet, see Section 8.1, "Locating Pages in Oracle Portal".

3. Click the Edit link at the top of the page.

   This opens the page in Edit mode.

4. Go to the region to which to add the item, and click the Add Item icon (Figure 14-8).

   Figure 14-8 Add Item Icon

   
   

5. Go to the region to which to add the item, and click the Add Item icon (Figure 14-12).

   Figure 14-9 The Add Item Icon

   
   

   Note:

   If the Add Item icon does not display next to the region, the region may be a portlet region. You can add items only to an item region.

   To add a sub-item to an existing item, click the Actions icon (Figure 14-13) next to that item and then choose Add a subitem.

   Figure 14-10 The Actions Icon

   
   

   Note:

   To add sub-items to an item, you must have at least the item privilege Edit on the item.

6. On the Item Type Selection page, choose Simple Item Link from the Content Item Types list.

   If the item type you are looking for does not appear in the list, contact your page group administrator. The page group administrator specifies the types of items available to the page group.

   Note:

   If the page group administrator has configured the page group to allow only one type of item, the Item Type Selection page is skipped, and the Item Attributes page is displayed. For example, if the page group is configured to include only file-type items, when a user clicks the Add Item icon, the Item Attributes page for file-type items displays.

   In the Oracle Portal user interface, an asterisk (*) indicates a field that requires a value.

7. Under Item Attributes, click the Choose Item icon (Figure 14-11) next to the Item Link field.

   Figure 14-11 The Choose Item Icon

   
   

   The Select an item page displays.

8. Select an item, either:

   • Under Search, search for the item by its Display Name, Author, or Status. Click Go to execute the search. Click the item link in the search results to select the item. Click Reset to return to the original selection page; or

   • Under Select an item, click an item link to select an item or click a page link to drill to an item link on a sub-page.

9. Optionally, in the Display Name field enter a display name for the link text.

   If you leave this field blank, the Display Name of the referenced item is used. If the referenced item has no Display Name, nothing is used, and there is no apparent link for users to click.

10. Click OK to save your changes and return to the page.

14.2.5 Adding Dynamic Data (PL/SQL Item)

Use the following steps to add PL/SQL code that executes a PL/SQL procedure and displays the results on a page.

To add a PL/SQL item to a page:

Note:

The item attributes included in this process are the default item attributes for the item. You may be adding a simple or custom version of the item type, in which case, the attributes may vary. That is, some of the attributes included in the following steps will not be present; some that are not included will be.

1. Log in to Oracle Portal.

2. Go to the page to which to add the item.

   For information on locating a page through the Page Groups portlet, see Section 8.1, "Locating Pages in Oracle Portal".

3. Click the Edit link at the top of the page.

   This opens the page in Edit mode.

4. Go to the region to which to add the item, and click the Add Item icon (Figure 14-12).

   Figure 14-12 The Add Item Icon

   
   

   Note:

   If the Add Item icon does not display next to the region, the region may be a portlet region. You can add items only to an item region.

   To add a sub-item to an existing item, click the Actions icon (Figure 14-13) next to that item and then choose Add a subitem.

   Figure 14-13 The Actions Icon

   
   

   Note:

   To add sub-items to an item, you must have at least the item privilege Edit on the item.

5. On the Item Type Selection page, choose PL/SQL from the Content Item Types list.

   If the item type you are looking for does not appear in the list, contact your page group administrator. The page group administrator specifies the types of items available to the page group.

   Note:

   If the page group administrator has configured the page group to allow only one type of item, the Item Type Selection page is skipped, and the Item Attributes page is displayed. For example, if the page group is configured to include only file-type items, when a user clicks the Add Item icon, the Item Attributes page for file-type items displays.

6. Click Next.

7. On the Item Attributes page, in the PL/SQL Code field, enter the PL/SQL code to execute when this item is clicked.

   If the PL/SQL code you enter for the item is fairly long, consider putting it into a procedure and calling the procedure using the item.

   Note:

   The PL/SQL code you enter here is not validated when you finish creating or editing the item. Validation is performed when an attempt is made to execute the code. If the code is valid, it executes when the item is rendered. If the code is invalid, error messages are returned. Once you create the item, be sure to test the code.

   In the Oracle Portal user interface, an asterisk (*) indicates a field that requires a value.

8. In the Display Name field, enter the item's link text.

   This is the text that users click to execute the PL/SQL code.

9. Choose a category that describes this item.

10. Enter a Description for this item.

11. Change the Publish Date default to the date and time to publish the item to other users.

    The format is DD-MON-YYYY HH12:MI PM.

    When you upload the item, you can see it immediately, despite the Publish Date you enter here. Other users will not see this item until the date and time you specify.

12. Select an expiration option from the Expiration Period radio buttons.

    On the day you specify, the content is marked (in Edit mode) as expired, and is removed from other users' view of the page. If the page group is configured to display expired items, you will still be able to see it in Edit mode and, if you wish, un-expire it, until the portal administrator purges expired items from the portal.

    Choose from:

    • Never Expires—The item does not expire.

    • Expires In [ ] Days—The item expires in the number of days you specify (calculated from the publish date).

    • Expires On [ ] (DD-MON-YYYY HH12:MI PM)—The item expires on the date and time you specify.

    The format is DD-MON-YYYY HH12:MI PM.

13. In the Perspectives field, click the Move icons to move a perspective from the Available Perspectives to the Displayed Perspectives list.

    Use the Move icons to the right of Displayed Perspectives to set the order in which to display the perspectives.

    You can choose more than one perspective for an item. For example, a sales report might belong to both the Sales Representative and Marketing Manager perspectives. In Windows, select multiple perspectives by pressing and holding the Ctrl key while clicking each perspective. In UNIX, simply click each selection.

14. In the Image field, enter the location of the image/icon to associate with this item.

    Click the Browse button to locate and select the image from your file system. Alternatively, use the second field to enter the URL of an image, or reuse an image that has already been uploaded to the portal. To reuse an uploaded image, enter its internal name (not file name) without a path in this field, for example, enter 1645.GIF.

    To obtain the internal name Oracle Portal has assigned to an image, go to a place within your portal where the image is already in use; right click it; and select Properties from the right-click menu.

    Note:

    If you are using item versioning and you always want to show the current version of an image, see Section 14.12.4, "Images and Item Versioning".

15. From the Image Alignment list, choose an alignment option for the item's image/icon.

    For descriptions and examples of image alignment options, see Table 14-1, "Item Image Alignment Options".

16. In the Basic Search Keywords field, enter one or more search terms for the item.

    Separate keywords by spaces, commas, or some other punctuation mark.

17. In the Author field, enter the name of the item's author.

18. Select Enable Item Check-Out to enable users to check this item into and out of the portal.

    Item check-out prevents other users from overwriting an item while it is being edited.

19. In the Display Options field, choose a display method for the item.

    Choose from:

    • Item Displayed Directly In Page Area to display the execution results in the portlet region that hosts this item.

    • Link That Displays Item In Full Browser Window to replace the displayed page with the execution results.

    • Link That Displays Item In New Browser Window to display the execution results in a second browser window.

    Note:

    You can use a Portal Template for items only when you select one of the Link display options when you specify item attribute values. The Link display options include Link That Displays Item In Full Browser Window and Link That Displays In New Browser Window. When you select the item display option Item Displayed Directly In Page Area, the Portal Template for items you have associated with the item in page properties or in item attributes is ignored. For more information on Portal Templates for items, see Chapter 12, "Providing a Standard Look and Feel".

20. In the PL/SQL Execute Options field, choose the database schema in which to execute this PL/SQL item: the Public schema or another schema that you select.

    To select a schema other than the Public schema, click the Browse Database Schemas icon next to the Schema field. A PL/SQL item is executed by default as the public user. You can also explicitly select a user to execute the item.

21. Click Finish to save your changes and return to the page.

14.2.6 Specifying How Item URLs Are Formed

When you add items to a page, you enter values for the item's attributes. You can choose to display those values by editing the attribute settings on the region that contains the item (for more information, see Section 10.2.9, "Changing the Attributes Displayed in a Region"). Included among the many item attributes you can display are item links that use the item's durable URL and item links that use the item's path-based URL.

A durable URL is formed using a globally unique identifier (GUID). Because the GUID of an item never changes, the URL continues to be valid if the item name changes.

In contrast, you can also use the item's path-based URL to form the item link. A path-based URL is formed by identifying the path taken through the portal to get to a particular item. This uses page and item names in the URL and thus, if the name of a page or an item within the path is changed, the URL is no longer valid.

Path-based URLs are a little more intuitive, because they follow an observable path through the portal. Durable URLs are a little more sturdy because they can withstand an item name change and still link to the item, and they can be reliably bookmarked.

The attributes of interest include:

• Link - Display Name—Path-based URL

• Link - Display Name (durable)—Durable URL

• Link - Image—Path-based URL

• Link - Image (durable)—Durable URL

• Link - Image and Display Name—Path-based URL

• Link - Image and Display Name (durable)—Durable URL

• Link - Image OR Display Name—Path-based URL

• Link - Image OR Display Name (durable)—Durable URL

To specify which type of URL to use for an item link, follow the steps provided in Section 10.2.9, "Changing the Attributes Displayed in a Region". To understand more about URLs in Oracle Portal, see Appendix C, "Formation of URLs in Oracle Portal". For a detailed explanation of what is rendered for each of these attributes, see Section A.2, "Base Attributes".

14.2.7 Tricks for Adding and Editing Items

This section provides a couple of tricks to simplify the process of adding content to a region or editing content. It contains the following subsections:

• Section 14.2.7.1, "Creating a Shortcut to Adding Content"

• Section 14.2.7.2, "Creating a Shortcut to Editing Content"

14.2.7.1 Creating a Shortcut to Adding Content

When a page is in Edit mode, you click a region's Add Item icon when you want to add an item. The Add Item wizard appears, and, when you've completed the wizard, you click OK and are placed back on the page, still in Edit mode. The new item is in the correct region, and all invalidations needed for the page have been performed.

How can you accomplish this task with the page still in View mode? Add a URL item type that uses a modified version of the Add Item wizard's URL.

Why would you want to? Imagine that you have a site where you provide a catalog of objects. The object list is dynamic, making it a frequent task to add content to the page. Placing an Add Object link on the page could simplify and speed the task of getting into and out of page Edit mode.

To create a shortcut to adding content:

1. Log in to Oracle Portal.

2. Click the Build tab to bring it forward.

3. From the Page Group portlet Work In drop-down list, select the page group that owns the page on which to add items.

4. Under Pages in the Layout & Appearance section, click the name of the page on which to add items.

   This opens the page in Edit mode.

5. Go to the region in which items are typically added, and click the Add Item icon (Figure 14-14).

   Figure 14-14 The Add Item Icon

   
   

   This opens the Add Item wizard.

6. In your browser address bar, copy the URL, and click Cancel to exit the Add Item wizard.

7. Go to the region in which to add the Add Object link.

8. Click the Add Item icon.

9. Select URL from the Content Item Types drop-down list.

10. Click Next.

11. Clear the URL field and paste the Add Item wizard URL you copied in step 6.

    Among other things, the URL specifies the region to which content should be added. Another important part of the URL is the looplink, which tells the portal where to return to when the Add Item wizard Finish or Cancel button is clicked.

    Portal knows whether to show a page in View or Edit mode, depending on whether the page URL is passed a mode parameter value. Provided you have the privilege to enter page Edit mode, you can append ?_mode=16 to a portal page's URL to place the page in Edit mode. (This assumes no other parameter values are passed. If other values are passed, you do not need the question mark (?), but you must add an ampersand (&) to append the parameter/value pair to the string of parameters included in the URL, that is, &_mode=16.)

    Looking at the URL, notice that the looplink calls the page back in Edit mode. By removing %3F_mode%3D16, you prevent the return to page Edit mode. Instead, you are returned to the page in View mode.

12. Remove _mode=16 (in our example, %3F_mode%3D16) from the looplink statement.

13. Enter a Display Name for the link.

14. Revise any other item attributes you care to.

15. Click OK.

Clicking the new URL item invokes the Add Item wizard, exactly the same as clicking the Add Item icon in Edit mode. And, because the _mode=16 parameter was removed from the looplink URL, users are returned to the page in View mode once they click the wizard's Finish or Cancel buttons.

Should you care to limit the list of users who can perform this action, you could enable item level security and set access rules on the URL item. For information about item level security, see Section 17.9, "Securing Items".

14.2.7.2 Creating a Shortcut to Editing Content

Using a technique similar to the one described in the previous section, you can use the URL item type along with the URL for the Edit Item wizard to create another shortcut—this one to edit a particular item.

To create a shortcut to edit a specific item:

1. Log in to Oracle Portal.

2. Click the Build tab to bring it forward.

3. From the Page Group portlet Work In drop-down list, select the page group that owns the page on which to edit a specific item.

4. Under Pages in the Layout & Appearance section, click the name of the page on which to edit a specific item.

   This opens the page in Edit mode.

5. Go to the region that contains the item for which to create an edit shortcut, and click the Edit Item icon (Figure 14-15).

   Figure 14-15 The Edit Item Icon

   
   

   This opens the Edit Item wizard.

6. In your browser address bar, copy the URL, and click Cancel to exit the Edit Item wizard.

7. Go to the region in which to add the Edit Object link.

8. Click the Add Item icon.

9. Select URL from the Content Item Types drop-down list.

10. Click Next.

11. Clear the URL field and paste the Edit Item wizard URL you copied in step 6.

    Among other things, the URL specifies the item to be edited. Another important part of the URL is the looplink, which tells the portal where to return to when the Edit Item wizard Finish or Cancel button is clicked.

    Portal knows whether to show a page in View or Edit mode, depending on whether the page URL is passed a mode parameter value. Provided you have the privilege to enter page Edit mode, you can append ?_mode=16 to a portal page's URL to place the page in Edit mode. (This assumes no other parameter values are passed. If other values are passed, you do not need the question mark (?), but you must add an ampersand (&) to append the parameter/value pair to the string of parameters included in the URL, that is, &_mode=16.)

    Looking at the URL, notice that the looplink calls the page back in Edit mode. By removing %3F_mode%3D16, you prevent the return to page Edit mode. Instead, you are returned to the page in View mode.

12. Remove _mode=16 from the looplink statement (in our example, %3F_mode%3D16).

13. Enter a Display Name for the link.

14. Revise any other item attributes you care to.

15. Click OK.

Clicking the new URL item invokes the Edit Item wizard, exactly the same as clicking the Edit Item icon in Edit mode. And, because the _mode=16 parameter was removed from the looplink URL, users are returned to the page in View mode once they click the wizard's Finish or Cancel buttons.