12 Extending Your Portal

12.1 Creating a Page Group

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

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 versioning level for items in the page group:

  • 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 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".

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 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.

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

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.

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".

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, for example:

  • 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 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.

  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.

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

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

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.

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

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.

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

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.