Skip Headers
Oracle® Application Server Portal Developer's Guide
10g Release 2 (10.1.4)
B14135-02
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

12 Extending Your Portal

This chapter describes how to use the APIs provided with OracleAS 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 Application Server 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 OracleAS 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 OracleAS 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. 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 OracleAS 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.

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

12.4.1 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 OracleAS 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 OracleAS Portal is installed.

If the file does not reside on the same server as the database in which OracleAS Portal is installed, you must first load the file into the content repository document tables using the upload_blob API. 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 OracleAS 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;
/

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.

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

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