Oracle9iAS Portal Developer Kit (PDK)
Implementing NLS Service

Introduction

Oracle Portal provides a robust set of APIs for storing and retrieving of strings in different languages in your PL/SQL portlets. For an introductory overview of NLS Services, please refer to the Primer on using National Language Support.

NLS services are available through the wwnls_api package.

Assumptions

• You have already installed the Services Example downloaded from the PDK and understand the steps required to display a PL/SQL portlet on a portal page
• You have read the Primer on using National Language Support document for an introduction to this service.

How to use NLS

The general model for working with the NLS service can be described as follows:

1. Load your NLS string definitions to the database using the string equivalents for each language you intend to use. For this purpose call the wwnls_api.add_string or wwnls_api.set_string with an appropriate domain, sub-domain, error message name and error text combination.
2. Retrieve the strings you require by using the wwnls_api.get_string API for the language that you desire.

Loading NLS strings to Database

1. From the downloaded Services Example, review the services_seed.sql files which seeds all the NLS strings for the Services Example. An excerpt is provided below.
2. The add_string API is called with the parameters for domain name, sub-domain name, string name, language and the actual string text. It returns the String ID for the NLS string.
3. For setting equivalent strings in other languages, the set_string API is called with the same parameters.

   set serveroutput on size 1000000 set define off declare l_string_id integer; ... begin     dbms_output.put_line('Adding NLS strings...');     -- strings for portlet record fields --     l_string_id := wwnls_api.add_string( 'provider','services','ptldefname','us', 'Apply ');     wwnls_api.set_string( 'provider','services','ptldefname','d', 'HELLOWORLDPORTLET'); /     l_string_id := wwnls_api.add_string( 'provider','services','ptldefdesc','us', 'OK');     wwnls_api.set_string( 'provider','services','ptldefdesc','d', 'Hello World Portlet with NLS');     l_string_id := wwnls_api.add_string( 'provider','services','ptldeftitle','us', 'Cancel');     wwnls_api.set_string( 'provider','services','ptldeftitle','d', 'Hello World Portlet with NLS'); ... commit; exception    when others then         dbms_output.put_line('ERROR: Could not install seed data');         rollback; end;

On similar lines you can create your own loading script to seed the strings your portlet requires. This may include strings required by each show mode as well as strings required for error messages.

Implementing NLS functionality

1. From the downloaded Services Example, review the services_portlet.pkb file which is the package body for this portlet.
2. The domain, and sub-domain aliases at the beginning is provided for easy reference while retrieving the NLS strings. This code segment is highlighted below. You may choose your own domain and sub-domain names too instead.
3. Scroll the services_portlet.pkb file to the section that contains the procedure get_portlet_info. A call to wwnls_api.get_string is made for populating portlet name, title and description. This code segment is highlighted below.

   CREATE OR REPLACE package body SERVICES_PORTLET is        --   Constants  --     DOMAIN constant varchar2(30) := 'provider';     SUBDOMAIN constant varchar2(32) := 'services';       function get_portlet_info     (         p_provider_id in integer         ,p_language in varchar2     )     return wwpro_api_provider.portlet_record     is         l_portlet wwpro_api_provider.portlet_record;     begin         ...         l_portlet.id := services_provider.SERVICES_PORTLET_ID;         l_portlet.provider_id := p_provider_id;         l_portlet_title := wwnls_api.get_string(                                 p_domain => DOMAIN                                ,p_sub_domain => SUBDOMAIN                                ,p_name => 'ptldeftitle'                                ,p_language => p_language                            );         l_portlet_description := wwnls_api.get_string(                                 p_domain => DOMAIN                                ,p_sub_domain => SUBDOMAIN                                ,p_name => 'ptldefdesc'                                ,p_language => p_language                            );         l_portlet_name := wwnls_api.get_string(                                 p_domain => DOMAIN                                ,p_sub_domain => SUBDOMAIN                                ,p_name => 'ptldefname'                                ,p_language => p_language                            );        ...        ... end SERVICES_PORTLET; /

4. You will notice that NLS calls are made at various places throughout the code for retrieving different NLS strings.

Similarly you can use NLS strings wherever your functionality requires it. When you incorporate other services like Error Handling, you will find this especially useful.

View Portlet functionality

1. Create a page and add the Services portlet to your page. Take note to view the portlet title you obtained with the NLS API using different language settings of your browser for both 'US' and 'German'.