Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Portal
11g Release 1 (11.1.1)

Part Number E10238-05
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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:

More on OTN

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;
/

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;
/

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;
/

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;
/

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;
/

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:

The following are parameters for add_item_post_upload:

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;
/

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;
/