12 Extending Your Portal

This chapter describes how to use the APIs provided with Oracle Portal to extend your portal. It contains the following sections:

Section 12.1, "Creating a Page Group"
Section 12.2, "Creating Pages"
Section 12.3, "Creating Categories and Perspectives"
Section 12.4, "Creating Items"
Section 12.5, "Setting Perspectives Attributes of Pages and Items"
Section 12.6, "Approving and Rejecting Items"

For more information about any of these APIs, refer to the Oracle Portal PL/SQL API Reference on Portal Center:

http://portalcenter.oracle.com

In the Portal Focus Areas section, click Portlet Development, then in the APIs and References section, click PL/SQL API Reference.

Tip:

Remember, if you are calling the APIs from a Web provider or external application, you need to set the session context first. For more information, refer to Section 10.1, "Setting the Session Context".

12.1 Creating a Page Group

To create a new page group, use the add_content_area API as shown in Example 12-1.

Example 12-1 Creating a Page Group (add_content_area API)

declare
  l_new_page_group_id number;
begin
  -- Create the page group.
  l_new_page_group_id := wwsbr_api.add_content_area(
    p_name             => 'ENTERTAINMENT',
    p_display_name     => 'Entertainment Page Group',
    p_versioning       => wwsbr_api.VERSIONING_AUDIT,
    p_default_language => 'us'
  );
  -- process cache invalidation messages.
  wwpro_api_invalidation.execute_cache_invalidation;
exception
  ...
end;
/

p_name is the internal name for the new page group. This name is used in path based URLs and must be unique.
p_display_name is the display name for the new page group.
p_versioning is the version level for items in the page group. It can take the following values:
- wwsbr_api.VERSIONING_NONE
- wwsbr_api.VERSIONING_SIMPLE
- wwsbr_api.VERSIONING_AUDIT
p_default_language is the default language for the page group.

12.2 Creating Pages

If you want to create a new page, use the add_folder API. By default, the new page has two regions: a portlet region containing the default navigation page of the page group, and an item region. This means that pages created programmatically, rather than through the Oracle Portal user interface, may be quite limited in their layout.

However, you can programmatically create pages with a more sophisticated layout by basing the parent page of the new page on a Portal Template with the desired layout. Then if you configure the page group to automatically copy parent page properties, your new page will use the same template as its parent. Using this method means that your pages can have any layout that you require.

You cannot use this API to create JSP pages or navigation pages. To create these types of pages, use the Create Page Wizard in Oracle Portal.

If the page type on which you base the page has default values set for any page properties, these values override any values set using this API.

To define privileges for your new page, use the APIs in the WWSEC_API package (Example 12-2). For more information, refer to Section 15.2, "Setting Page Level Privileges".

Example 12-2 Creating a Page (add_folder API)

declare
  l_new_page_id       number;
  l_caid              number := 33;
begin
  -- create the page.
  l_new_page_id := wwsbr_api.add_folder(
    p_caid             => l_caid,
    p_name             => 'ENTERTAINMENT',
    p_display_name     => 'Entertainment Page',
    p_type_id          => wwsbr_api.FOLDER_TYPE_CONTAINER,
    p_type_caid        => wwsbr_api.SHARED_OBJECTS,
  );
  -- Process cache invalidation messages.
  wwpro_api_invalidation.execute_cache_invalidation;
exception
  ...
end;
/

p_caid is the ID of the page group to which you want to add the page.
p_name is the internal name for the new page. This name is used in path based URLs.
p_display_name is the display name (title) for the new page.
p_type_id is the ID of the page type on which you want to base the page. The page type must be available to the page group in which you are creating the page. Seeded page types have the following constants defined:
- wwsbr_api.FOLDER_TYPE_CONTAINER
- wwsbr_api.FOLDER_TYPE_URL
- wwsbr_api.FOLDER_TYPE_PLSQL
- A value from the ID column of the WWSBR_FOLDER_TYPES view
You can find the IDs for custom page types by querying the ID column of the WWSBR_FOLDER_TYPES view.
p_type_caid is the ID of the page group to which the page type used for the page belongs. This value must be the same as the page group in which you are creating the page (p_caid) or the Shared Objects page group (use the wwsbr_api.SHARED_OBJECTS constant).

12.3 Creating Categories and Perspectives

If you have already defined a quite large taxonomy for your portal, you might prefer to set it up programmatically, rather than use the Oracle Portal user interface.

Use the add_category API to create a new category (Example 12-3). Use the add_perspective API to create a new perspective (Example 12-4). To create a category or perspective, users must have Manage Classifications privileges or higher on the page group.

Example 12-3 Creating a Category (add_category API)

declare
  l_new_category_id number;
  l_caid            number := 33;
begin
  l_new_category_id := wwsbr_api.add_category(
    p_caid         => l_caid,
    p_parent_id    => 0,
    p_name         => 'newcategory1',
    p_display_name => 'New Category 1'
  );
  -- Process cache invalidation messages.
  wwpro_api_invalidation.execute_cache_invalidation;
exception
  ...
end;
/

Example 12-4 Creating a Perspective (add_perspective API)

declare
  l_new_perspective_id number;
  l_caid               number := 33;
begin
  l_new_perspective_id := wwsbr_api.add_perspective(
    p_caid         => 33,
    p_parent_id    => 0,
    p_name         => 'newperspective1',
    p_display_name => 'New Perspective 1'
  );
  -- Process cache invalidation messages.
  wwpro_api_invalidation.execute_cache_invalidation;
exception
  ...
end;
/

p_caid is the ID of the page group in which you want to create the category or perspective.
p_parent_id is the ID of the category or perspective under which you want to create the new category or perspective. If this is a top-level category or perspective, use 0 (zero).
p_name is the internal name for the new category or perspective.
p_display_name is the display name for the new category or perspective.

12.4 Creating Items

To create an item on a page, use the add_item API (Example 12-5).

This API returns the master ID of the item, which is not the item's unique ID. To look up the ID of the item after it is created, query the WWSBR_ALL_ITEMS view as shown in Example 10-7. For more information about the difference between an item's unique ID and its master item ID, refer to Section 10.2, "API Parameters".

Example 12-5 Creating a Text Item (add_item API)

declare
  l_new_item_master_id number;
begin
  l_new_item_master_id := wwsbr_api.add_item(
    p_caid              => 33,
    p_folder_id         => 13923,
    p_display_name      => 'Movie Review',
    p_type_id           => wwsbr_api.ITEM_TYPE_TEXT,
    p_type_caid         => wwsbr_api.SHARED_OBEJCTS,
    p_region_id         => 5,
    p_text              => 'This is the text of the review.',
  );
  -- Process cache invalidation messages.
  wwpro_api_invalidation.execute_cache_invalidation;
exception
  ...
end;
/

p_caid is the ID of the page group that owns the page in which you want to create the item.
p_folder_id is the ID of the page in which you want to create the item.
p_display_name is the display name (title) of the new item.
p_type_id is the ID of the item type on which the item is based. Use the constants defined in the WWSBR_API package. Example are as follows:
- wwsbr_api.ITEM_TYPE_FILE
- wwsbr_api.ITEM_TYPE_TEXT
- wwsbr_api.ITEM_TYPE_URL
For a full list of constants for the seeded item types, refer to the Oracle Portal PL/SQL API Reference on Portal Center:
```
http://portalcenter.oracle.com
```
In the Portal Focus Areas section, click Portlet Development, then in the APIs and References section, click PL/SQL API Reference.

You can find the IDs for custom item types by querying the ID column of the WWSBR_ITEM_TYPES view.

The item type must be available in the page group on which you are creating the item, and therefore listed in the WWSBR_CONTENT_AREA_ITEM_TYPES view.
p_type_caid is the ID of the page group to which the item type used for the item belongs. This value must be the same as the page group to which you are adding the item (p_caid), or the Shared Objects page group (use the wwsbr_api.SHARED_OBJECTS constant).
p_region_id is the ID of the region in which you want to create the item. If you do not specify a region, or if the region ID is invalid, the item is placed in the default item region for the page. Use the WWSBR_ALL_FOLDER_REGIONS view to look up the region ID.
p_text is the text for a text item.

Creating File Items

If an object is associated with one or more files (for example, images, file items, and so on), its APIs allow you to upload these files when creating or modifying the object. You can pass a file location consisting of a directory path and file name to the file and image parameters for these APIs. The directory in which you place the files must be visible to your database (that is, local to the database server) and the files themselves must have proper permissions. If you see strange exceptions resulting from API calls in which you are trying to upload files, double check the permissions on the directories and files.

When the file that you want to upload resides on the same server as the database in which Oracle Portal is installed, you can upload the file at the same time as you create or update the item. Example 12-6 shows how you might do this.

Example 12-6 Creating a File Item (add_item API)

declare
  l_item_masterthing_id number;
begin
  -- Add an item that resides on the same server as the OracleAS Portal
  -- content repository database.
  l_item_masterthing_id := wwsbr_api.add_item(
    p_caid          => 53,  -- A known page group ID.
    p_folder_id     => 1,   -- A known page ID.
    p_display_name  => 'My File',
    p_type_id       => wwsbr_api.ITEM_TYPE_FILE,
    p_type_caid     => wwsbr_api.SHARED_OBJECTS,
    p_region_id     => 513, -- A known region on the page.
    p_description   => 'Description of my file',
    p_file_filename => '/tmp/myfile.txt'
  );
  -- Process cache invalidation messages.
  wwpro_api_invalidation.execute_cache_invalidation;
exception
  ...
end;
/

p_caid is the ID of the page group that owns the page in which you want to create the item.
p_folder_id is the ID of the page in which you want to create the item.
p_display_name is the display name (title) of the new item.
p_type_id is the ID of the item type on which the item is based.
p_type_caid is the ID of the page group to which the item type used for the item belongs. This value must be the same as the page group to which you are adding the item (p_caid), or the Shared Objects page group (use the wwsbr_api.SHARED_OBJECTS constant).
p_region_id is the ID of the region in which you want to create the item. If you do not specify a region, or if the region ID is invalid, the item is placed in the default item region for the page. Use the WWSBR_ALL_FOLDER_REGIONS view to look up the region ID.
p_description is a description of the item.
p_file_filename is the directory path and file name of the file associated with this item. The file must be located on the same server as database in which Oracle Portal is installed.

If the file does not reside on the same server as the database in which Oracle Portal is installed, you must first load the file into the content repository document tables using the upload_blob API (Example 12-7). The upload_blob API returns a unique document name. Use the add_item_post_upload API to create a new item that claims the file specified by the returned document name.

Note:

Your calling application must declare a BLOB and assign it to an object compatible with the database BLOB data type (refer to Application Developer's Guide - Large Objects in your Oracle Database documentation set). You can then pass the BLOB to the p_blob parameter of the upload_blob API.

Example 12-7 Uploading a File to the Content Repository and Creating a File Item Using the Uploaded File (upload_blob API and add_item_post_upload API)

declare
  l_blob                blob;
  l_blob_filename       varchar2(250);
  l_mime_type           varchar2(100) := 'text/html';
  l_doc_name            varchar2(500);
  l_display_name        varchar2(250);
  l_region_id           number        := 2013;
  l_file_name           varchar2(100);
  l_image_name          varchar2(100);
  l_site_id             number        := 73;
  l_page_id             number        := 1;
  l_item_type_id        number        := wwsbr_api.ITEM_FILE_TYPE;
  l_item_type_siteid    number        := wwsbr_api.SHARED_OBJECTS;
  l_description         varchar2(1000);
  l_item_masterthing_id number;
begin
  -- Your calling application must define the my_get_blob() function and retrieve
  -- your document into a blob so that it can be uploaded in the subsequent step.
  l_blob := my_get_blob('8001.HTML');
  -- Upload the BLOB to the Oracle Portal document table.
  l_blob_filename := 'index2.html';
  l_doc_name := wwsbr_api.upload_blob(
    p_file_name => l_blob_filename,
    p_blob      => l_blob,
    p_mime_type => l_mime_type
  );
  l_display_name := l_blob_filename;
  l_file_name := l_doc_name;
  l_description := 'File uploaded to portal = ' || l_doc_name;
  -- Use add_item_post_upload() to claim the document and add the item to a page.
  l_item_masterthing_id := wwsbr_api.add_item_post_upload(
    p_caid          => l_site_id,
    p_folder_id     => l_page_id,
    p_display_name  => l_display_name,
    p_file_name     => l_file_name,
    p_type_id       => l_item_type_id,
    p_type_caid     => l_item_type_siteid,
    p_region_id     => l_region_id,
    p_description   => l_description,
    p_display_option => wwsbr_api.FULL_SCREEN
  );
  -- Process cache invalidation messages.
  wwpro_api_invalidation.execute_cache_invalidation;
exception
  ...
end;
/

The following are parameters for upload_blob:

p_file_name is the file name that you want to assign to the BLOB. This is not the value returned by the function. Usually this is the file name by which the file is known on the source file system.
p_blob is the BLOB containing the content.
p_mime_type is the MIME type for the BLOB. Use the predefined constants provided in the WWSBR_API package.

The following are parameters for add_item_post_upload:

p_caid is the ID of the page group that owns the page in which you want to create the item.
p_folder_id is the ID of the page in which you want to create the item.
p_display_name is the display name (title) of the new item.
p_file_name is the internal document name for the file item, matching a document in the document table. Pass the value returned by upload_blob to this parameter to reference the uploaded document as the file for this item.
p_type_id is the ID of the item type on which the item is based.
p_type_caid is the ID of the page group to which the item type used for the item belongs. This value must be the same as the page group to which you are adding the item (p_caid), or the Shared Objects page group (use the wwsbr_api.SHARED_OBJECTS constant).
p_region_id is the ID of the region in which you want to create the item. If you do not specify a region, or if the region ID is invalid, the item is placed in the default item region for the page. Use the WWSBR_ALL_FOLDER_REGIONS view to look up the region ID.
p_description is a description of the item.
p_file_filename is the directory path and file name of the file associated with this item. The file must be located on the same server as database in which Oracle Portal is installed.
p_display_option is how the item should be displayed. Use the following predefined constants:
- wwsbr_api.FULL_SCREEN to display a link that, when clicked, displays the item in the same browser window.
- wwsbr_api.NEW_WINDOW to display a link that, when click, displays the item in a new browser window.
- wwsbr_api.IN_PLACE to display the item in the region (this applies to text and PL/SQL items only).

If you have already created the item that you want to use to claim the uploaded document, use the modify_item_post_upload API.

12.5 Setting Perspectives Attributes of Pages and Items

When creating a page or item you can, optionally, specify the perspectives that apply to that page or item.

Example 12-8 shows how you specify the perspectives that apply to a page when creating the page. Example 12-9 shows how you specify the perspectives that apply to an item when creating the item.

Example 12-8 Specifying Perspectives When Creating a Page

declare
  l_new_page_id       number;
  l_perspective_ids   wwsbr_api.g_perspectiveidarray;
  l_perspective_caids wwsbr_api.g_caid_array;
begin
  select id, caid
  bulk collect into l_perspective_ids, l_perspective_caids
  from wwsbr_all_perspectives
  where caid in (l_caid, wwsbr_api.shared_objects);
  l_new_page_id := wwsbr_api.add_folder(
    p_caid             => 33,
    p_name             => 'ENTERTAINMENT',
    p_display_name     => 'Entertainment Page',
    p_type_id          => wwsbr_api.FOLDER_TYPE_CONTAINER,
    p_type_caid        => wwsbr_api.SHARED_OBJECTS,
    p_perspectives     => l_perspective_ids,
    p_perspective_caid => l_perspective_caids
  );
  -- Process cache invalidation messages.
  wwpro_api_invalidation.execute_cache_invalidation;
exception
  ...
end;
/

Example 12-9 Specifying Perspectives When Creating an Item

declare
  l_new_item_master_id number;
  l_perspective_ids    wwsbr_api.g_perspectiveidarray;
  l_perspective_caids  wwsbr_api.g_caid_array;
begin
  -- Select perspectives with the name prefix = 'ENTERTAINMENT'.
  select id, caid
  bulk collect into l_perspective_ids, l_perspective_caids
  from wwsbr_all_perspectives
  where caid in (l_caid, wwsbr_api.shared_objects) and
        display_name like 'ENTERTAINMENT%';
  l_new_item_master_id := wwsbr_api.add_item(
    p_caid              => 33,
    p_folder_id         => 13923,
    p_display_name      => 'Movie Review',
    p_type_id           => wwsbr_api.ITEM_TYPE_TEXT,
    p_type_caid         => wwsbr_api.SHARED_OBEJCTS,
    p_region_id         => 5,
    p_text              => 'This is the text of the review.',
    p_perspectives      => l_perspective_ids,
    p_perspectives_caid => l_perspective_caids
  );
  -- Process cache invalidation messages.
  wwpro_api_invalidation.execute_cache_invalidation;
exception
  ...
end;
/

p_perspectives is an array of perspective IDs.
p_perspective_caid is an array of page group IDs for the perspectives identified in p_perspectives. The position of each element in this array must match the position of the corresponding perspective ID in p_perspectives. The values in p_perspective_caid must be the same as the page group in which you are creating the page or item (p_caid) or the Shared Objects page group (use the wwsbr_api.SHARED_OBJECTS constant).

For descriptions of the other parameters in these examples, refer to Example 12-2 and Example 12-5.

12.6 Approving and Rejecting Items

The WWSBR_API package includes two APIs to help with managing approvals. To see how you might use these APIs in conjunction with the Content Management Event Framework, refer to Section 16.7, "Example: Item Validation" and Section 16.8, "Example: Integrating External Workflow"

Example 12-10 shows how to approve a pending item . Example 12-11 shows how to reject a pending item .

Example 12-10 Approving an Item

begin
  wwsbr_api.approve(
    p_item_id => 8056,
    p_site_id => 53,
    p_comment => 'Item approved'
  );
  -- Process cache invalidation messages.
  wwpro_api_invalidation.execute_cache_invalidation;
end;
/

Example 12-11 Rejecting an Item

begin
  wwsbr_api.reject(
    p_item_id => 8056,
    p_site_id => 53,
    p_comment => 'Item rejected'
  );
  -- Process cache invalidation messages.
  wwpro_api_invalidation.execute_cache_invalidation;
end;
/

p_item_id is the unique ID of the item being approved or rejected.
p_site_id is the ID of the page group to which the item belongs.
p_comment provides additional information about the approval or rejection of the item.