PK (oUIoa,mimetypeapplication/epub+zipPK(oUIOEBPS/part1.htmz Getting Started with Oracle HTML DB

Part I

Getting Started with Oracle HTML DB

Part I provides an introduction to Oracle HTML DB. These chapters introduce you to basic Oracle HTML DB concepts.

Part I contains the following chapters:

PKSPK(oUIOEBPS/advanc.htm Advanced Programming Techniques

15 Advanced Programming Techniques

This section provides information about advanced programming techniques including establishing database links, using collections, running background SQL, utilizing Web Services and managing user preferences.

This section contains the following topics:

Sending E-mail from an Application

You can send an e-mail from an Oracle HTML DB application by:

Topics in this section include:


See Also:

"Configuring Oracle HTML DB to Send Mail" and "Managing E-mail" for more information on viewing the mail queue and the mail log

Sending E-mail Using a Background Job

Oracle HTML DB stores unsent e-mail messages in a table named HTMLDB_MAIL_QUEUE. A DBMS_JOB background process is automatically created when you install Oracle HTML DB. This background process pushes the mail queue every 15 minutes. The package that is executed by the background process has two parameters:

  • p_smtp_host is the hostname of your SMTP gateway. The default value is localhost.

  • p_smtp_portno is the port number of your SMTP gatway. The default value is 25.

The most efficient approach to sending e-mail is to create a background job (using a DBMS_JOB package) to periodically send all mail messages stored in the active mail queue.

Sending E-mail Manually by Calling HTMLDB_MAIL

You can send an e-mail from an Oracle HTML DB application by calling a PL/SQL package called HTMLDB_MAIL. This package is built on top of the Oracle supplied UTL_SMTP package. Because of this dependence, in order to use HTMLDB_MAIL, the UTL_SMTP package must be installed and functioning.


See Also:

PL/SQL Packages and Types Reference for more information

HTMLDB_MAIL contains two procedures for manually sending e-mail:

  • Use the HTMLDB_MAIL.SEND procedure to manually send an outbound e-mail message from your application

  • Use HTMLDB_MAIL.PUSH_QUEUE to deliver mail messages stored in HTMLDB_MAIL_QUEUE

Oracle HTML DB stores unsent e-mail messages in a table named HTMLDB_MAIL_QUEUE. You can deliver mail messages stored in this queue to the specified SMTP gateway by calling the procedure HTMLDB_MAIL.PUSH_QUEUE. This procedure requires two input parameters:

  • p_smtp_hostname defines the hostname of your SMTP gateway

  • p_smtp_portno defines port number of your SMTP gateway (for example, 25)

Oracle HTML DB logs successfully submitted messages in the table HTMLDB_MAIL_LOG with the timestamp reflecting your server's local time.

The following example demonstrates the use of the HTMLDB_MAIL.PUSH_QUEUE procedure using a shell script. This example only applies to UNIX/LINUX installations. In this example, the SMTP gateway hostname is defined as smtp01.oracle.com and the SMTP gateway port number is 25.

SQLPLUS / <<EOF
FLOWS_010600.HTMLDB_MAIL.PUSH_QUEUE('smtp01.oracle.com','25');
DISCONNECT
EXIT
EOF


See Also:

"HTMLDB_MAIL" for more information on using the HTMLDB_MAIL

Accessing Data with Database Links

Since Oracle HTML DB runs on top of an Oracle database, you have access to all distributed database capabilities. Typically, you perform distributed database operations using database links.

To create a database link:

  1. Navigate to the Workspace home page.

  2. Click SQL Workshop.

  3. Under SQL Workshop, select Create Object.

    The Create Database Object Wizard appears.

  4. Select Database Link.

  5. Follow the on-screen instructions.

    Note that Database Link names must conform to Oracle naming conventions and cannot contain spaces, or start with a number or underscore.

Using Collections

Collections enable you to temporarily capture one or more non-scalar values. You can use collections to store rows and columns currently in session state so they can be accessed, manipulated, or processed during a user's specific session. Think of a collection as a bucket in which you can temporarily store and name rows of information.

Examples of when you might use collections include:

Topics in this section include:

About the HTMLDB_COLLECTION API

Every collection contains a named list of data elements (or members) which can have up to 50 attributes (or columns). You insert, update, and delete collection information using the PL/SQL API HTMLDB_COLLECTION.

About Collection Naming

When you create a new collection, you must give it a name that cannot exceed 255 characters. Note that collection names are not case-sensitive and will be converted to upper case.

Once named, you can access the values in a collection by running a SQL query against the view HTMLDB_COLLECTION.

Creating a Collection

Every collection contains a named list of data elements (or members) which can have up to 50 attributes (or columns). Use the following methods to create a collection:

  • CREATE_COLLECTION

  • CREATE_OR_TRUNCATE_COLLECTION

  • CREATE_COLLECTION_FROM_QUERY

CREATE_COLLECTION raises an exception if the named collection already exists. For example:

HTMLDB_COLLECTION.CREATE_COLLECTION(
    p_collection_name => collection name );

CREATE_OR_TRUNCATE_COLLECTION creates a new collection if the named collection does not exist. If the named collection already exists, this method truncates it. Truncating a collection empties it, but leaves it in place. For example:

HTMLDB_COLLECTION.CREATE_OR_TRUNCATE_COLLECTION(
    p_collection_name => collection name );
    p_generate_md5    => YES or NO );

CREATE_COLLECTION_FROM_QUERY creates a collection and then populates it with the results of a specified query. For example:

HTMLDB_COLLECTION.CREATE_COLLECTION_FROM_QUERY(
    p_collection_name => collection name,
    p_query           => your query );
    p_generate_md5    => YES or NO );

CREATE_COLLECTION_FROM_QUERY_B also creates a collection and then populates it with the results of a specified query. For example:

HTMLDB_COLLECTION.CREATE_COLLECTION_FROM_QUERY_B(
    p_collection_name => collection name,
    p_query           => your query );
   

CREATE_COLLECTION_FROM_QUERY_B offers significantly faster performance than CREATE_COLLECTION_FROM_QUERY by performing bulk SQL operations, but has the following limitations:

  • No column value in the select list of the query can be more than 2,000 bytes. If a row is encountered that has a column value of more than 2,000 bytes, an error will be raised during execution.

  • The MD5 checksum will not be computed for any members in the collection.

About the Parameter p_generate_md5

Use the p_generate_md5 flag to specify if the message digest of the data of the collection member should be computed. By default, this flag is set to NO. Use this parameter to check the MD5 of the collection member (that is, compare it with another member or see if a member has changed).


See Also:

"Determining Collection Status" for more information on using the function GET_MEMBER_MD5

Truncating a Collection

Truncating a collection removes all members from the specified collection, but leaves the named collection in place. For example:

HTMLDB_COLLECTION.TRUNCATE_COLLECTION(
    p_collection_name => collection name );

Deleting a Collection

Deleting a collection deletes the collection and all of its members. Be aware that if you do not delete a collection, it will eventually be deleted when the session is purged. For example:

HTMLDB_COLLECTION.DELETE_COLLECTION (
    p_collection_name => collection name );

Deleting All Collections for the Current Application

Use the method DELETE_ALL_COLLECTIONS to delete all collections defined in the current application. For example:

HTMLDB_COLLECTION.DELETE_ALL_COLLECTIONS;

Deleting All Collections in the Current Session

Use the method DELETE_ALL_COLLECTIONS_SESSION to delete all collections defined in the current session. For example:

HTMLDB_COLLECTION.DELETE_ALL_COLLECTIONS_SESSION;

Adding Members to a Collection

When data elements (or members) are added to a collection, they are assigned a unique sequence ID. As you add members to a collection, the sequence ID will change in increments of 1 with the newest members having the largest ID.

You add new member to a collection using the function ADD_MEMBER. Calling this method returns the sequence ID of the newly added member. The following example demonstrates how to use the procedure ADD_MEMBER.

HTMLDB_COLLECTION.ADD_MEMBER(
    p_collection_name => collection name,
    p_c001          => [member attribute 1],
    p_c002          => [member attribute 2],
    p_c003          => [member attribute 3],
    p_c004          => [member attribute 4],
    p_c005          => [member attribute 5],
    p_c006          => [member attribute 6],
    p_c007          => [member attribute 7],
  ...
    p_c050          => [member attribute 50]);
    p_clob001       => [CLOB member attribute 1],    p_generate_md5  => YES or NO);

The next example demonstrates how to use the function ADD_MEMBER. This function returns the sequence number assigned to the newly created member.

l_id := HTMLDB_COLLECTION.ADD_MEMBER(
    p_collection_name => collection name,
    p_c001          => [member attribute 1],
    p_c002          => [member attribute 2],
    p_c003          => [member attribute 3],
    p_c004          => [member attribute 4],
    p_c005          => [member attribute 5],
    p_c006          => [member attribute 6],
    p_c007          => [member attribute 7],
  ...
    p_c050          => [member attribute 50]);
    p_clob001       => [CLOB member attribute 1],    p_generate_md5  => YES or NO);

You can also add new members (or an array of members) to a collection using the method ADD_MEMBERS. This method raises an exception if the specified collection does not exist with the specified name of the current user and in the same session. Also any attribute exceeding 4,000 characters will be truncated to 4,000 characters. The number of members added is based on the number of elements in the first array. For example:

HTMLDB_COLLECTION.ADD_MEMBERS(
    p_collection_name => collection name,
    p_c001          => member attribute array 1,
    p_c002          => member attribute array 2,
    p_c003          => member attribute array 3,
    p_c004          => member attribute array 4,
    p_c005          => member attribute array 5,
    p_c006          => member attribute array 6,
    p_c007          => member attribute array 7,
    ...
    p_c050          => member attribute array 50);
    p_generate_md5  => YES or NO);

About the Parameters p_generate_md5 and p_clob001

Use the p_generate_md5 flag to specify if the message digest of the data of the collection member should be computed. By default, this flag is set to NO. Use this parameter to check the MD5 of the collection member (that is, compare it with another member or see if a member has changed).

Use p_clob001 for collection member attributes which exceed 4,000 characters.


See Also:

"Determining Collection Status" for more information on using the function GET_MEMBER_MD5

Updating Collection Members

You can update collection members by calling UPDATE_MEMBER and referencing the desired collection member by its sequence ID. This procedure replaces an entire collection member, not individual member attributes. This procedure raises an exception if the named collection does not exist. For example:

HTMLDB_COLLECTION.UPDATE_MEMBER (
    p_collection_name => collection name,
    p_seq             => member sequence number,
    p_c001            => member attribute 1,
    p_c002            => member attribute 2,
    p_c003            => member attribute 3,
    p_c004            => member attribute 4,
    p_c005            => member attribute 5,
    p_c006            => member attribute 6,
    p_c007            => member attribute 7,
    ...
    p_c050            => member attribute 50);
    p_clob001       => [CLOB member attribute 1],  

Use p_clob001 for collection member attributes which exceed 4,000 characters.

If you wish to update a single attribute of a collection member, use UPDATE_MEMBER_ATTRIBUTE. Calling this procedure raises an exception if the named collection does not exist. For example:

HTMLDB_COLLECTION.UPDATE_MEMBER_ATTRIBUTE(
    p_collection_name => collection name,
    p_seq             => member sequence number,
    p_c001            => member attribute 1,
    p_c002            => member attribute 2,
    p_c003            => member attribute 3,
    p_c004            => member attribute 4,
    p_c005            => member attribute 5,
    p_c006            => member attribute 6,
    p_c007            => member attribute 7,
    ...
    p_c050            => member attribute 50);
    p_clob_number     => number of CLOB attribute to be updated, <-- Only valid value for now is 1    p_clob_value      => new CLOB attribute value);

Deleting a Collection Member

You can delete a collection member by calling DELETE_MEMBER and referencing the desired collection member by its sequence ID. For example:

HTMLDB_COLLECTION.DELETE_MEMBER(
    p_collection_name => collection name,
    p_seq             => member sequence number);

Be aware that this procedure leaves a gap in the sequence IDs in the specified collection. Also, calling this procedure results in an error if the named collection does not exist.

You can also delete all members from a collection by when an attribute matches a specific value. For example:

HTMLDB_COLLECTION.DELETE_MEMBERS(
    p_collection_name => collection name,
    p_attr_number     => number of attribute used to match for the specified
                         attribute value for deletion, 
    p_attr_value      => attribute value of the member attribute used to 
                         match for deletion);

Be aware that this procedure also leaves a gap in the sequence IDs in the specified collection. Also, this procedure raises an exception if:

  • The named collection does not exist

  • The specified attribute number is outside the range of 1 to 50, or is in invalid

If the supplied attribute value is null, then all members of the named collection will deleted.

Determining Collection Status

The p_generate_md5 parameter determines whether the MD5 message digests are computed for each member of a collection. The collection status flag is set to FALSE immediately after you create a collection. If any operations are performed on the collection (such as add, update, truncate, and so on), this flag is set to TRUE.

You can reset this flag manually by calling RESET_COLLECTION_CHANGED. For example:

HTMLDB_COLLECTION.RESET_COLLECTION_CHANGED (
    p_collection_name => collection name)

Once this flag has been reset, you can determine if a collection has changed by calling COLLECTION_HAS_CHANGED. For example:

l_changed := HTMLDB_COLLECTION.COLLECTION_HAS_CHANGED(
  p_collection_name => collection_name);

When you add a new member to a collection, an MD5 message digest is computed against all 50 attributes and the CLOB attribute if the p_generated_md5 parameter is set to YES. You can access this value from the MD5_ORIGINAL column of the view HTMLDB_COLLECTION using the function GET_MEMBER_MD5. For example:

HTMLDB_COLLECTION.GET_MEMBER_MD5 (
    p_collection_name => collection name,
    p_seq             => member sequence number );
    RETURN VARCHAR2;

Merging Collections

You can merge members of collection with values passed in a set of arrays. By using the argument p_init_query, you can create a collection from the supplied query. For example:

HTMLDB_COLLECTION.MERGE_MEMBERS
p_collection_name => collection_name

Be aware, however, that if the collection exists, the following occurs:

  • Rows in the collection (not in the arrays) will be deleted

  • Rows in the collection and in the arrays will be updated

  • Rows in the array and not in the collection will be inserted

Any attribute value exceeding 4,000 characters will be truncated to 4,000 characters. Table 15-1 describes the available arguments you can use when merging collections.

Table 15-1 Available Arguments for Merging Collections

Argument Description
p_c001 Array of first attribute values to be merged. Maximum length can be 4,000 characters. If the maximum length is greater, it will be truncated to 4,000 characters.

The count of elements in the P_C001 PL/SQL table is used as the total number of items across all PL/SQL tables. For example, if P_C001.count = 2 and P_C002.count = 10, only 2 members will be merged. Be aware that if P_C001 is null, an application error will be raised.

p_c0xx Attribute of XX attributes values to be merged. Maximum length can be 4,000 characters. If the maximum length is greater, it will be truncated to 4,000 characters.
p_collection_name Name of the collection.

See Also: "About Collection Naming"

p_null_index Use this argument to identify rows the merge function should ignore. This argument identifies an row as null. Null rows are automatically removed from the collection. Use p_null_index in conjunction with.
p_null_value Use this argument in conjunction with the p_null_index. Identifies the null value. If used this value cannot be null. A typical value for this argument is 0.
p_init_query Use the query defined by this argument to create a collection if the collection does not exist.

Managing Collections

You can use the following utilities to manage collections.

Obtaining a Member Count

Use COLLECTION_MEMBER_COUNT to return the total count of all members in a collection. Be aware that this count does not imply the highest sequence in the collection. For example:

l_count := HTMLDB_COLLECTION.COLLECTION_MEMBER_COUNT (
  p_collection_name => collection name );

Resequencing a Collection

Use RESEQUENCE_COLLECTION to resequence a collection to remove any gaps in sequence IDs while maintaining the same element order. For example:

HTMLDB_COLLECTION.RESEQUENCE_COLLECTION (
   p_collection_name => collection name )
   

Verifying Whether a Collection Exists

Use COLLECTION_EXISTS to determine if a collection exists. For example:

l_exists := HTMLDB_COLLECTION.COLLECTION_EXISTS  (
  p_collection_name => collection name );

Adjusting Member Sequence ID

You can adjust the sequence ID of a specific member within a collection by moving the ID up or down. When you adjust a sequence ID, the specified ID is exchanged with another one. For example, if you were to move the ID 2 up, 2 would become 3 and 3 would become 2.

Use MOVE_MEMBER_UP to adjust a member sequence ID up by one. Alternately, use MOVE_MEMBER_DOWN to adjust a member sequence ID down by one. For example:

HTMLDB_COLLECTION.MOVE_MEMBER_DOWN(
    p_collection_name => collection name,
    p_seq             => member sequence number);

Be aware that while using either of these methods an application error displays:

  • If the named collection does not exist for the current user in the current session

  • If the member specified by sequence ID p_seq does not exist

However, an application error will not be returned if the specified member already has the highest or lowest sequence ID in the collection (depending on whether you are calling MOVE_MEMBER_UP or MOVE_MEMBER_DOWN).

Sorting Collection Members

Use SORT_MEMBERS to reorder members of a collection by the column number. This method not only sorts the collection by a particular column number, but it also reassigns the sequence IDs for each member to remove gaps. For example:

HTMLDB_COLLECTION.SORT_MEMBERS(
    p_collection_name       => collection name,
    p_sort_on_column_number => column number to sort by);

Clearing Collection Session State

By clearing the session state of a collection, you remove the collection members. A shopping cart is a good example of when you might need to clear collection session state. When a user requests to empty his or her cart and start again, you would need to clear the session state for a collection. You can remove session state of a collection by calling the CREATE_OR_TRUNCATE_COLLECTION method or by using f?p syntax.

Calling CREATE_OR_TRUNCATE_COLLECTION deletes the existing collection and then recreates it. For example:

HTMLDB_COLLECTION.CREATE_OR_TRUNCATE_COLLECTION(
    p_collection_name       => collection name,

You can also use the sixth f?p syntax argument to clear session state. For example:

f?p=App:Page:Session::NO:1,2,3,collection name

Running Background PL/SQL

You can use the HTMLDB_PLSQL_JOB package to run PL/SQL code in the background of your application. This is an effective approach for managing long running operations that do not need to complete in order for a user to continue working with your application.

Topics in this section include:

Understanding the HTMLDB_PLSQL_JOB Package

HTMLDB_PLSQL_JOB is a wrapper package around DBMS_JOB functionality offered in the Oracle database. Be aware that the HTMLDB_PLSQL_JOB package only exposes that functionality which is necessary to run PL/SQL in the background. The following is a description of the HTMLDB_PLSQL_JOB package.

SQL> DESC HTMLDB_PLSQL_JOB
FUNCTION JOBS_ARE_ENABLED RETURNS BOOLEAN
PROCEDURE PURGE_PROCESS
 Argument Name                  Type                    In/Out Default?
 ------------------------------ ----------------------- ------ --------
 P_JOB                          NUMBER                  IN
FUNCTION SUBMIT_PROCESS RETURNS NUMBER
 Argument Name                  Type                    In/Out Default?
 ------------------------------ ----------------------- ------ --------
 P_SQL                          VARCHAR2                IN
 P_WHEN                         VARCHAR2                IN     DEFAULT
 P_STATUS                       VARCHAR2                IN     DEFAULT
FUNCTION TIME_ELAPSED RETURNS NUMBER
 Argument Name                  Type                    In/Out Default?
 ------------------------------ ----------------------- ------ --------
 P_JOB                          NUMBER                  IN
PROCEDURE UPDATE_JOB_STATUS
 Argument Name                  Type                    In/Out Default?
 ------------------------------ ----------------------- ------ --------
 P_JOB                          NUMBER                  IN
 P_STATUS                       VARCHAR2                IN
 P_DESC                         

Table 15-1 describes the functions available in the HTMLDB_PLSQL_JOB package.

Table 15-2 HTMLDB_PLSQL_JOB Package Available Functions

Function Description
SUBMIT_PROCESS Use this procedure to submit background PL/SQL. This procedure returns a unique job number. Since you can use this job number as a reference point for other procedures and functions in this package, it may be useful to store it in your own schema.
UPDATE_JOB_STATUS Call this procedure to update the status of the currently running job. This procedure is most effective when called from the submitted PL/SQL.
TIME_ELAPSED Use this function to determine how much time has elapsed since the job was submitted.
JOBS_ARE_ENABLED Call this function to determine whether or not that database is currently in a mode which supports submitting jobs to the HTMLDB_PLSQL_JOB package.
PURGE_PROCESS Call this procedure to clean up submitted jobs. Submitted jobs stay in the HTMLDB_PLSQL_JOBS view until either Oracle HTML DB cleans out those records, or you call PURGE_PROCESS to manually remove them.

You can view all jobs submitted to the HTMLDB_PLSQL_JOB package using the HTMLDB_PLSQL_JOBS view. The following is the description of HTMLDB_PLSQL_JOBS view.

SQL> DESCRIBE HTMLDB_PLSQL_JOBS
 Name                              Null?    Type
 --------------------------------- -------- ----------------------------
 ID                                         NUMBER
 JOB                                        NUMBER
 FLOW_ID                                    NUMBER
 OWNER                                      VARCHAR2(30)
 ENDUSER                                    VARCHAR2(30)
 CREATED                                    DATE
 MODIFIED                                   DATE
 STATUS                                     VARCHAR2(100)
 SYSTEM_STATUS                              VARCHAR2(4000)
 SYSTEM_MODIFIED                            DATE
 SECURITY_GROUP_ID                          NUMBER

Table 15-3 describes the columns available in HTMLDB_PLSQL_JOBS view.

Table 15-3 HTMLDB_PLSQL_JOBS View Columns

Name Description
ID An unique identifier for each row.
JOB The job number assigned to each submitted PL/SQL job. The HTMLDB_PLSQL_JOB.SUBMIT_PROCESS function returns this value. This is also the value you pass into other procedures and functions in the HTMLDB_PLSQL_JOB package.
FLOW_ID The application from which this job was submitted.
OWNER The database schema that owns the application. This identifies what schema will parse this code when DBMS_JOB runs it.
ENDUSER The end user (that is, who logged into the application) that caused this process to be submitted.
CREATED The date when the job was submitted.
MODIFIED The date when the status was modified.
STATUS The user defined status for this job. Calling HTMLDB_PLSQL_JOB.UPDATE_JOB_STATUS updates this column.
SYSTEM_STATUS The system defined status for this job.
SYSTEM_MODIFIED The date when the system status was modified.
SECURITY_GROUP_ID The unique ID assigned to your workspace. Developers can only see jobs submitted from their own workspace.

About System Status Updates

Submitted jobs can contain any of the following system status settings:

  • SUBMITTED. Indicates the job has been submitted, but has not yet started. DBMS_JOB does not guarantee immediate starting of jobs.

  • IN PROGRESS. Indicates that DBMS_JOB has started the process.

  • COMPLETED. Indicates the job has finished.

  • BROKEN (sqlcode) sqlerrm. Indicates there was a problem in your job that resulted in an exception. The SQL code and SQL Error Message for the exception should be included in the system status. Review this information to determine what went wrong.

Using a Process to Implement Background PL/SQL

The simplest way to implement the HTMLDB_PLSQL_JOB package is to create a page process that specifies the process type PLSQL DBMS JOB. By selecting this process type, Application Builder will submit the PL/SQL code you specify as a job. Since you are not calling the function directly, you can use the built-in substitution item APP_JOB to determine the job number of any jobs you submit.

The following example runs a PL/SQL job in the background for testing and explanation.

001  BEGIN
002    FOR i IN 1 .. 100 LOOP
003      INSERT INTO emp(a,b) VALUES (:APP_JOB,i);
004      IF MOD(i,10) = 0 THEN
005        HTMLDB_PLSQL_JOB.UPDATE_JOB_STATUS(
006          P_JOB     => :APP_JOB,
007          P_STATUS  => i || 'rows inserted');
008      END IF;
009      HTMLDB_UTIL.PAUSE(2);
010    END LOOP;
011  END;

In this example, note that:

  • Lines 002 to 010 run a loop that inserts 100 records into the emp table.

  • APP_JOB is referenced as a bind variable inside the VALUES clause of the INSERT, and specified as the P_JOB parameter value in the call to UPDATE_JOB_STATUS.

  • APP_JOB represents the job number which will be assigned to this process as it is submitted to HTMLDB_PLSQL_JOB. By specifying this reserved item inside your process code, it will be replaced for you at execution time with the actual job number.

  • Notice this example calls to UPDATE_JOB_STATUS every ten records, INSIDE the block of code. Normally, Oracle transaction rules dictate updates made inside code blocks will not be seen until the entire transaction is committed. The HTMLDB_PLSQL_JOB.UPDATE_JOB_STATUS procedure, however, has been implemented in such a way that the update will happen regardless of whether or not the job succeeds or fails. This last point is important for two reasons:

    1. Even if your status reads "100 rows inserted," it does not mean the entire operation was successful. If an exception occurred at the time the block of code tried to commit, the user_status column of HTMLDB_PLSQL_JOBS would not be affected since status updates are committed separately.

    2. These updates are performed autonomously. You can view the job status before the job has completed. This gives you the ability to display status text about ongoing operations in the background as they are happening.

Implementing Web Services

Web services enable applications to interact with one another over the Web in a platform-neutral, language independent environment. In a typical Web services scenario, a business application sends a request to a service at a given URL by using the protocol over HTTP. The service receives the request, processes it, and returns a response. You can incorporate calls with external Web services in application developed in Oracle HTML DB

Web services in Oracle HTML DB are based on SOAP (the Simple Object Access Protocol). SOAP is a World Wide Web Consortium (W3C) standard protocol for sending and receiving requests and responses across the Internet. SOAP messages can be sent back and forth between a service provider and a service user in SOAP envelopes.

SOAP offers two primary advantages:

Topics in this section include:


Note:

The SOAP 1.1 specification is a W3C note. (The W3C XML Protocol Working Group has been formed to create a standard that will supersede SOAP.)

For more information on Simple Object Access Protocol (SOAP) 1.1 see:

http://www.w3.org/TR/SOAP/


Understanding Web Service References

To utilize Web services in Oracle HTML DB, you create a Web service reference using a wizard. Each Web service reference is based on a Web Services Description Language (WSDL) document that describes the target Web service. When you create a Web service reference, the wizard analyzes the WSDL and collects all the necessary information to create a valid SOAP message, including:

  • The URL used to post the SOAP request over HTTP

  • An Uniform Resource Identifier (URI) identifying the SOAP HTTP request

  • Input parameters for each operation

  • Output parameters for each operation

Accessing the Web Service References Page

You manage Web service references on the Web Service References page.

To access the Web Service References page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

    Application Builder appears.

  3. Click Shared Components.

    The Shared Components page appears.

  4. Under Logic, select Web Service References.

    The Web Service References page appears.

Specifying an Application Proxy Server Address

If your environment requires a proxy server to access the Internet, you must specify a proxy server address on the Application Attributes page before you can create a Web service reference.

To specify a proxy address for an application:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

    Application Builder appears.

  3. Click Edit Attributes.

  4. Under Application Definition, enter the proxy server in Proxy Server.

Creating a Web Service Reference

When you create a Web service reference you need to decide how to locate the WSDL. You can locate a WSDL in two ways:

  • By searching a UDDI registry

  • by entering the URL to the WSDL document

A Universal Description, Discovery, and Integration (UDDI) registry is a directory where businesses register their Web services.

Creating a Web Service Reference by Searching a UDDI Registry

To create a new Web service by searching a UDDI registry:

  1. Navigate to the Web Service References page. (See "Accessing the Web Service References Page".)

  2. Click Create.

  3. When prompted whether to search a UDDI registry to find a WSDL, click Yes.

  4. For UDDI Location you can either:

    • Enter a URL endpoint to a UDDI registry.

    • Click the List icon and select a UDDI registry.

  5. Under Search for Services, specify whether to search for a business name or a service name.

    1. For Search Type, specify whether to search for a business name or a service name. You cannot search for both.

    2. In Name, enter the business name or service name to search for.

    3. Optionally indicate whether the search should be case-sensitive or an exact match. Use the percent (%) symbol as a wildcard character.

    4. Click Search.

    5. When the search results appears, make a selection and click Next.

    A summary page appears describing the selected Web service.

  6. Review your selection and click Next to continue.

    The URL to the WSDL document displays in the WSDL Location field.

  7. Click Finish.

The Web service reference is added to the Web Service References Repository.

Creating a Web Service Reference by Specifying a WSDL Document

To create a new Web service by specifying a URL to a specific WSDL document:

  1. Navigate to the Web Service References page. (See "Accessing the Web Service References Page".)

  2. Click Create.

  3. When prompted whether to search a UDDI registry to find a WSDL, click No.

  4. In WSDL Location, enter the URL to the WSDL document.

  5. Click Finish.

The Web service reference is added to the Web Service References Repository.

Using the Web Service Reference Repository

Web service references are stored in the Web Service Reference Repository.

To access the Web Service References Repository:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

    Application Builder appears.

  3. Click Shared Components.

    The Shared Components page appears.

  4. Under Logic, select Web Service References.

From the Web Service References Repository you can:

  • Edit a reference by clicking the Edit icon.

  • Test a reference by clicking the Run icon.

  • View details about a reference, by clicking the reference name.

Testing a Web Service Reference

Once you have created a Web service reference you can test it on the Test Web Service Reference.

To test a Web service reference:

  1. Navigate to the Web Service Repository. (See "Using the Web Service Reference Repository".)

  2. Click Run adjacent to the Web Service reference name.

    The Test Web Service Reference page appears. The Web service name and URL endpoint display at the top of the page.

  3. From Operation, select an operation (that is, the method to be executed).

  4. Under Input Parameters, enter the appropriate value.

  5. Click Test.

    The message request and response appear at the bottom of the page.

Creating an Input Form and Report on a Web Service

The Create Form and Report on Web Service Wizard creates an input form, a submit button, and a report for displaying results. You can execute this wizard directly after creating the Web service reference, or by adding a new page.

Use this wizard when you expect a non-scalar result from the Web service. The Amazon Web service is a good example. This Web service returns many results based on the search criteria entered in an input form.

Creating a Form and Report Directly After Creating a Reference

To create a form and report directly after creating a Web Service Reference:

  1. Create the Web service reference. (See "Creating a Web Service Reference".)

  2. Once the Web service references has been added, select Create Form and Report on Web Service.

  3. For Web Service Reference and Operation, select the Web service reference and operation (that is, the method to be executed).

  4. For Identify Page and Region Attributes, review the page and region attributes. If the page you specify does not exist, the wizard creates the page for you.

  5. For Items for Input Parameters:

    1. Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.

    2. If necessary, edit the item label.

  6. For Base Node:

    1. In Temporary Result Set Name, enter a name for the collection that stores the Web service result.

    2. For Result Tree to Report On, select the portion of the resulting XML document that contains the information you want to include in the report.

  7. For Result Parameters to Display, select the parameters to be included in the report.

  8. Click Finish.

Creating a Form and Report by Adding a New Page

If you have an existing Web service reference, you can create an input form and report by adding a new page.

To create a form and report by adding a new page:

  1. Create the Web service reference. (See "Creating a Web Service Reference".)

  2. Create a new page. (See "Adding Additional Pages".)

    In the Create Page Wizard:

    1. Select Page with Component.

    2. For Select Component Type, select Form.

    3. For Create Page, select Form and Report on Web Service.

  3. For Web Service Reference and Operation, select the Web service refereJnce and operation (that is, the method to be executed).

  4. For Identify Page and Region Attributes, review the page and region attributes. If the page you specify does not exist, the wizard creates the page for you.

  5. For Items for Input Parameters:

    1. Identify which items to add to the form. To include an item, select Yes in the Create column. Otherwise, select No.

    2. If necessary, edit the item label.

  6. For Base Node:

    1. In Temporary Result Set Name, enter a name for the collection that stores the Web service result.

    2. In Result Tree to Report On, select the portion of the resulting XML document that contains the information you want to include in the report.

  7. For Result Parameters to Display, select the parameters to be included in the report.

  8. Click Finish.

Creating a Form on a Web Service

The Create Form on Web Service wizard creates a form and a submit button. You can execute this wizard directly after creating the Web service reference, or from the Page Definition.

Use this wizard when you expect a scalar result from the Web service. A Web service that looks up a stock price is a good example since the input is a stock symbol and the output is the scalar value price.

Creating a Form Directly After Creating a Reference

To create a form directly after creating a Web Service Reference:

  1. Create the Web service reference. (See "Creating a Web Service Reference".)

  2. Once the Web service references has been added, select Create Form on Web Service.

  3. For Web Service Reference and Operation, select the Web service reference and operation (that is, the method to be executed).

  4. For Identify Page and Region Attributes, review the page and region attributes. If the page you specify does not exist, the wizard creates the page for you.

  5. For Items for Input Parameters:

    1. Identify which items to add. To include an item, select Yes in the Create column. Otherwise, select No.

    2. If necessary, edit the item label.

  6. For Items for Output Parameters:

    1. Identify which items need to be added. To include an item, select Yes in the Create column. Otherwise, select No.

    2. If necessary, edit the item label.

  7. Click Finish.

Creating a Form by Adding a New Page

If you have an existing Web service reference, you can create form by adding a new page.

To create a form by adding a new page:

  1. Create the Web service reference. (See "Creating a Web Service Reference".)

  2. Create a new page. (See "Adding Additional Pages".)

    In the Create Page Wizard:

    1. Select Page with Component.

    2. For Select Component Type, select Form.

    3. For Create Page, select Form on Web Service.

  3. For Web Service Reference and Operation, select the Web service reference and operation (that is, the method to be executed).

  4. For Identify Page and Region Attributes, review the page and region attributes. If the page you specify does not exist, the wizard creates the page for you.

  5. For Items for Input Parameters:

    1. Identify which items need to be added. To include an item, select Yes in the Create column. Otherwise, select No.

    2. If necessary, edit the item label.

  6. For Items for Output Parameters:

    1. Identify which items need to be added. To include an item, select Yes in the Create column. Otherwise, select No.

    2. If necessary, edit the item label.

  7. Click Finish.

Invoking a Web Service as a Process

You can also implement a Web Service as a process on the page. Running the process submits the request to the service provider. You can then display the request results in report.

To invoke a Web Service as a process:

  1. Create a new page. (See "Adding Additional Pages".)

    In the Create Page Wizard:

    1. Select Blank Page.

    2. When prompted whether to use tabs, select No.

  2. Navigate to the Page Definition. (See "Viewing a Page Definition".)

  3. Under Page Rendering, Processes, click the Create icon.

    The Create Page Processes Wizard appears.

  4. From the process category, select Web Services.

  5. Specify a process name, sequence, and processing point.

  6. Select the Web service reference and operation (that is, the method to be executed).

  7. Define the process. You can store the results in a collection or in items on the page by selecting options under Web Service Output Parameters.

    1. To store the results in a collection:

      • For Store Result in, select Collection.

      • Enter a name for the collection in the value field.

    2. To store the results in items on the page:

      • For Store Result in, select Items.

      • Enter the appropriate items value in the fields provided.

  8. Click Create Process.

Displaying Web Service Results in a Report

To create a report in which to display Web Service request results:

  1. Navigate to the Page Definition.

  2. Under Regions, click the Create icon.

    The Create Region Wizard appears.

  3. For the region type, select Report.

  4. For the report implementation, select Report on collection containing Web service result.On Identify Region Attributes, enter a region title and optionally edit the region attributes.

  5. For Web Service Reference and Operation, select a Web service reference and an operation (that is, the method to be executed).

  6. For Result Tree to Report On, select the portion of the resulting XML document that contains the information you want to include in the report.

  7. For Result Parameters:

    1. In Temporary Result Set Name, enter a name for the collection that stores the Web service result.

    2. Select and deselect the appropriate parameters.

  8. Click Create SQL Report.

Editing a Web Service Process

Once you create a process of type Web service, you can map input parameters to a static value (for example to pass a key) by editing the Web service process.

To edit a Web service process:

  1. Create a Web service process. (See "Invoking a Web Service as a Process".)

  2. Navigate to the Page Definition containing the Web service process.

  3. Select the process name.

    The Edit Page Process page appears.

  4. Scroll down to Web Service Input Parameters.

  5. To map an input parameter to a static value:

    1. Scroll down to Web Service Input Parameters.

    2. Enter a value in the Value field adjacent to the appropriate parameter name.

  6. Click Apply Changes.

Viewing a Web Service Reference History

The Web Services History displays changes to Web service references for the current application by application ID, Web service references name, developer, and date.

To view a history of Web service reference changes:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

    Application Builder appears.

  3. Click Shared Components.

    The Shared Components page appears.

  4. Under Logic, select Web Service References.

  5. Click History.

Managing User Preferences

You can use preferences to set the session state for a specific user. Once set, these preferences can only be removed by an Oracle HTML DB administrator. You can set user preferences by creating a page process, by the calculation of a preference Item Source Value, or programatically using the PL/SQL API.

Topics in this section include:

Viewing User Preferences

You view user preferences for a specific user on the Session State Management page.

To view user preferences for a specific user:

  1. From the Oracle HTML DB home page select the Administration tab.

  2. Under Administration Services, click Manage Users and then Session State.

    The Session State Management page appears.

  3. Click Report preferences for users.

  4. Type a username in the field provided and click Go.


See Also:

"Managing Session State and User Preferences" for more information on using the Session State Management page

Setting User Preferences

You can set user preferences within your application through the creation of a page process, by creating a preference item, or programatically.

Topics in this section include:

Setting User Preferences Using a Page Process

To set user preference values by creating a page process:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Page Processes, click the Create icon.

    The Create Page Computation Wizard appears.

  3. Specify a process name, sequence, and processing point.

  4. From Type, select one of the following:

    • Set Preference to value of item

    • Set Preference to value of item if item is not NULL

  5. Specify the preference value in the field provided using the format:

    PreferenceName:Item
    
    
  6. Click Page Items to see a list of available items.

  7. Follow the on-screen instructions

Setting the Source of an Item Based on a User Preference

You can set the source of an item based on a user preference by defining the item source type as Preference.

To define the source of item based on a user preference:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Item, click the Create icon.

    The Create Page Computation Wizard appears.

  3. Specify the Item Name and Display Position Attributes and click Next.

  4. Specify the Item Attributes click Next.

  5. From the Item Source list, select Preferences.

  6. In Item Source Value, enter the name of the preference.

  7. Follow the on-screen instructions

Setting User Preferences Programatically

To set or reference user preferences programatically, you must use a PL/SQL API. User level caching is available programmatically. You can use the set_preference function to set a user level preference called NAMED_PREFERENCE. For example:

HTMLDB_UTIL.SET_PREFERENCE(
 p_preference=>'NAMED_PREFERENCE',
 p_value =>:ITEM_NAME);

You can reference the value of a user preference using the function GET_PREFERENCES. For example:

NVL(HTMLDB_UTIL.GET_PREFERENCE('NAMED_PREFERENCE'),15)

In the previous example, the preference would default to the value 15 if the preference contained no value.

Resetting User Preferences Manually

You can manually purge user preferences for a specific user.

To manually purge preferences for a specific user:

  1. From the Oracle HTML DB home page select Administration tab.

  2. Under Administration Services, click Manage Users and then Session State.

    The Session State Management page appears.

  3. Click Purge preferences for a selected user.

  4. Specify a user and follow the on-screen instructions.


See Also:

"Managing Session State and User Preferences" for more information on using the Session State Management page

Resetting Preferences Using a Page Process

You can reset user preferences by creating a page process and selecting the process type Reset Preferences.

To reset user preferences using a page process:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Page Processes, click the Create icon.

    The Create Page Computation Wizard appears.

  3. Specify a process name, sequence, and processing point.

  4. From Type, select Reset Preferences.

  5. Follow the on-screen instructions

PKd; KJPK(oUI OEBPS/nav.htm Adding Navigation

10 Adding Navigation

When you build an application you can include a number of different types of navigation controls, including navigation bars, tabs, menus, lists, and trees. This section describes how to implement navigation in your application.

Navigation controls are shared components. Once you create them, you can add them to any page within your application. You add a specific type of navigation control at the application level on the Shared Components page.

This section contains the following topics:

Creating a Navigation Bar

Navigation bars (see Figure 10-1) offer an easy way for users to move between pages in an application. The location of a navigation bar depends upon the associated page template. A navigation bar icon enables you to display a link from an image or text. A navigation bar entry can be an image, an image with text beneath it, or text. You must supply navigation bar entry images and text. When you create a navigation bar entry, you can specify an image, text, a display sequence, or a URL.

Figure 10-1 Navigation Bar Entries

Description of nav_bar_2.gif follows


Navigation bars are different from other shared components in that you not need to reference them on a page by page basis. If your page template includes the #NAVIGATION_BAR# substitution string, the HTML DB engine automatically includes any defined navigation bars when it renders the page.


See Also:

"Supported Page Template Substitution Strings" on using the #NAVIGATION_BAR# substitution string

Creating a Navigation Bar Entry

Before you can add a navigation bar, you must create a navigation bar entry on the Navigation Bar page. You can access the Navigation Bar page from either the Page Definition or from the Shared Components page.

To create a navigation bar entry referencing an icon:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

    The Page Definition appears.

  2. Under Shared Components, scroll down to Navigation Bar.

  3. Under Navigation Bar, click Create.

    The Create NavBar Entry Wizard appears.

  4. Specify the following NavBar entry attributes:

    • Sequence

    • Alt Tag Text

    • Icon Image Name

    • Image Height and Image Width

    • Text

    Specify the target location.

  5. If the target location is a URL:

    1. From Target is a, select URL.

    2. In URL Target, type a URL.

  6. If the target location is a page:

    1. From Target is a, select Page in this application.

    2. In Page, specify the page number.

  7. If the navigation bar entry will display conditionally, specify the appropriate conditional information and click Create.

To create a navigation bar entry without icons:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

    The Page Definition appears.

  2. Under Shared Components, scroll down to Navigation Bar.

  3. Under Navigation Bar, click Create.

    The Create NavBar Entry Wizard appears.

  4. Specify the following icon attributes:

    • Sequence

    • Text

  5. If the target location is a page:

    1. From Target is a, select Page in this application

    2. In Page, specify the page number

  6. If the navigation bar entry will display conditionally, specify the appropriate conditional information and click Create.

Managing Navigation Bar Entries

To manage navigation bar entries:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Select the heading Navigation Bar.

    The Navigation Bar page appears.

  3. On the Navigation Bar page you can:

    • View details about a specific entry by clicking the Edit icon

    • Access an editable summary view, by clicking Edit selected attributes.

    • View navigation bar entries that are subscribed to by clicking Subscriptions.

    • View a history of recently changed navigation bar entries by clicking History.

    • Create a new navigation bar entry, by clicking Create

Creating Tabs

Tabs are an effective way to navigate users between pages of an application. You can create a tabbed application look by using parent tabs, standard tabs, and Oracle HTML DB lists.

Application Builder includes two different types of tabs:

An application having only one level of tabs uses a standard tab set. A standard tab set is associated with a specific page and page number. You can use standard tabs to link users to a specific page. A parent tab set functions as a container to hold a group of standard tabs. Parent tabs give users another level of navigation as well as a context (or sense of place) within the application. You can use parent tabs link users to a specific URL associated with a specific page.

Topics in this section include:


Note:

When running the Create Application Wizard, you have the option of creating an application with tabs. The following procedures assume you have already created an application that does not have any tabs.

About Template Support

Before you can create parent and standard tabs, you need to check that your default template has positions defined for both standard and parent tabs using the appropriate substitution strings. You also need to make sure you do not override this template at the page level.


See Also:


Using Tab Manager

You manage tab information using Tab Manager. You can access Tab Manager from the Shared Components page, or by clicking either the Parent Tabs or Standard Tabs heading on the Page Definition.

Accessing Tab Manager

To access Tab Manager from the Shared Components page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Shared Components.

  4. Under Navigation, click Tabs.

    Tab Manager appears displaying a graphical representation of the tabs defined in your application.

  5. To make another tab current, click the tab.

    Notice the two Add buttons. Use the Add button on the upper right side of the graphic to add Parent tabs. Use the Add button at the lower left side of the graphic to add standard tabs.

  6. To add a new tab, click Add adjacent to the appropriate tab type.

    Think of parent tabs as a container to hold standard tabs. For example, in order to add two levels of tabs you first create a parent tab and then add standard tabs to it.

To access Tab Manager from the Page Definition:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

    The Page Definition appears.

  2. Under Shared Components, select one of the following headings:

    • Parent Tabs

    • Standard Tabs

    Tab Manager appears displaying a graphical representation of the tabs defined in your application. The currently selected standard or parent tab is highlighted.

  3. To make another tab current, click the tab.

    Notice the two Add buttons. Use the Add button on the upper right side of the graphic to add Parent tabs. Use the Add button at the lower left side of the graphic to add standard tabs.

  4. To add a new tab, click Add adjacent to the appropriate tab type.

    Think of parent tabs as a container to hold standard tabs. For example, in order to add two levels of tabs you first create a parent tab and then add standard tabs to it.

Creating a New Tab from the Page Definition

To create a new tab from the Page Definition:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Tabs, click the Create icon.

    Create Tab Wizard appears.

  3. Follow the on-screen instructions.

Editing Multiple Tabs at Once

You can edit multiple tabs at once by clicking Edit all standard tabs and Edit all parent tabs on the Tab Manager page.

To edit multiple tabs at once:

  1. Navigate to Tab Manager. (See "Using Tab Manager".)

  2. Click one of the following to edit tab attributes in a summary view:

    • Edit all standard tabs

    • Edit all parent tabs

Accessing Tab Reports

Application Builder includes the following tab reports

You can access these reports by clicking the appropriate button at the top of the Tab Manager page.

Standard Tab Utilization

Click Utilization to access the Standard Tab Utilization report. This report lists the standard tabs used in the current application.

Standard and Parent Tab History

Click History to view the Standard Tab History and Parent Tab History reports. These reports display a history of changes to tab attributes for the current application.

Controlling Flow Using Branches

A branch is an instruction to link to a specific page, procedure, or URL. For example you can branch from page 1 to page 2 after page 1 is submitted.


Note:

If a page has a select list and a submit button, it can submit itself. However, you must create a branch to call the page or the submit will fail.

You create a new branch by running the Create Branch Wizard and specifying Branch Point and Branch Type. The Branch Type defines the type of branch you are creating.

To create a branch:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Branching, click the Create icon to run the Create Branch Wizard.

  3. Select a Branch Point:

    • On Submit: Before Computation - Occurs before computations, validations, or processing. Use this option for a Cancel button.

    • On Submit: Before Validation - Occurs after computations, but before validations or processing. Typically not used. If a validation fails, page processing stops, a rollback is issued, and the page displays the error. Because of this default behavior, you do not need to create branches to accommodate validations. However, you might want to branch based on the result of a computation (for example, to the previous branch point).

    • On Submit: Before Processing - Occurs after computations and validations, but before processing. Use this option to branch based on a validated session state, but before performing any page processing.

    • On Submit: After Processing - Occurs after computations, validations, and processing. This option branches to a URL or page after performing computations, validations, and processing. When using this option, remember to sequence your branches if you have multiple branches for a given branch point.

    • On Load: Before Header - Occurs before a page rendered. This option displays another page instead of the current page or redirects the user to another URL or procedure.

  4. Select a Branch Type.

    Depending upon the Branch Type, specify the following types of information on the pages that follows:

    • A page number of the page you wish to branch to

    • PL/SQL code

    • A URL address

  5. Follow the on-screen instructions.

Creating Menus

Menus provide users with hierarchical navigation. A menu is a hierarchical list of links that display using templates. You can display menus as a list of links, or as a breadcrumb path.

Topics in this section include:


See Also:

"Creating a New Template" and "Menu Templates" for more information on changing menu display

About Breadcrumb Menus

As shown in Figure 10-2, a breadcrumb style menu indicates where the user is within the application from a hierarchical perspective. In addition, users can click a specific page to instantly view it. You can include a breadcrumb menu that functions as second level of navigation and displays beneath the standard tabs at the top of each page.

Figure 10-2 Breadcrumb Style Menu

Description of menu.gif follows


Creating a Menu

To add a menu to a page in your application you must:

  • Create the menu by running the Create Menu Wizard.

  • Add options to it

  • Add the menu to a page by creating a menu region

To create a menu from the Shared Components page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Shared Components.

  4. Under Navigation, click Menus.

    The Menus page appears.

  5. To create a new menu, click Create.

  6. Follow the on-screen instructions.

To create a menu from a Page Definition:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Shared Components, scroll down to Menu and click Create.

    The Menus page appears.

  3. To create a new menu, click Create.

  4. Follow the on-screen instructions.

Once your menu has been created, you need to add options to it.

Adding Options to a Menu

To add options to a menu:

  1. Navigate to the Menus page.

  2. Select a menu and click Create Menu Option.

  3. Under Menu Identification, specify the page on which this menu will be current

  4. Under Menu Option, specify the following:

    • Sequence - Indicate the order in which menu options appear.

    • Parent Menu Option - Identify the parent of this menu entry.

    • Short Name - Specify the short name of this menu option (referenced in the menu template).

    • Long Name - Specify the long name of this menu option (referenced in the menu template).

  5. Specify a target location.

    If the target location is a URL:

    1. From Target is a, select URL.

    2. In URL Target, type a URL.

    If the target location is a page:

    1. From Target is a, select Page in this Application

    2. In Page, specify the page number

  6. To make the menu conditional:

    1. Make a selection from the Condition Type list.

    2. Enter an expression in the fields provided.

  7. When you are finished defining menu attributes, click Create at the top of the page.

Repeat these procedures for each menu option you need to create.

Adding a Menu to a Page

Once you create a menu and a menu template, the next step is to add it a page by creating a region and specifying the region type as Menu.


See Also:

"Creating a New Template" and "Menu Templates" for more information on changing menu display

To add a menu to a page:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Regions, click Create.

    The Create Region Wizard appears.

  3. Under Regions, click Create.

  4. While running the Create Region Wizard:

    • Select Menu for the region type.

    • Enter a title.

    • Select a menu and menu template.

  5. Click Create Menu Region.

Repeat these procedures for each page on which you would like to add a menu.

About Creating a Dynamic Menu

To give users a more exact context, you may include session state in a menu, making your menus dynamic. For example, suppose a page in your application displays a list of orders for a particular company and you want to include the following breadcrumb menu:

Home > Orders > Orders for ACME Inc

In this example, ACME Inc not only indicates the page a user is on, but also the navigation path. The HTML DB engine stores the value of ACME Inc. in session state.

To create this type of dynamic menu, you must include a reference to a session state item in the menu's short name or long name, for example:

&COMPANY_NAME.

Editing Multiple Menu Names Simultaneously

You can edit multiple menu entries at once by clicking Edit multiple menu entries text at the top of the Menus page.

To edit menu entries at once:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Shared Components.

  4. Under Navigation, click Menus.

    The Menus page appears.

  5. Click Edit multiple menu entries text.

  6. Edit the appropriate menu name and click Apply Changes.

Accessing Menu Reports

Application Builder includes the following menu reports:

You can access these reports by clicking the appropriate button at the top of the Menus page.

Menu Utilization Report

Click Utilization to access the Menu Utilization Report. This report lists menus by page. Click the page number to link to a specific page.

Recent Menu Option Changes

Click History to view the Recent Menu Option Changes report. This report lists recent changes to menus.

Creating Lists

As shown in Figure 10-3, a list is a shared collection of links. You control the appearance of a list through list templates. Each list element has a display condition which enables you to control when it displays. You can define a list element to be either current or non current for a specific page. You further specify what current looks like using template attributes. You add a list to a page by creating a region and specifying the region type as List.

Figure 10-3 List

Description of list.gif follows


Topics in this section include:


See Also:

"Creating a New Template" and "List Templates" for more information on altering list display

Creating a List

To add a list to a page in your application you must:

  • Create the list by running the Create Lists Wizard.

  • Add items to the list.

  • Add the list to a page by creating a List region.

To create a list from the Shared Components page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Shared Components.

  4. Under Navigation, click Lists.

    The Lists page appears.

  5. To create a new list, click Create List.

  6. Follow the on-screen instructions.

To create a list from a Page Definition:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Shared Components, scroll down to Lists and click Create.

    The Create / Edit List Object page appears.

  3. To create a new list, click Create.

  4. Follow the on-screen instructions.

Once your list has been created, you need to add items to it.

Adding Items to a List

To add items to a list:

  1. Navigate to the Lists page.

  2. Select a list

  3. Click Create List Entry to add entries to it.

    The List Entry Attributes page appears.

  4. Under Label and Sequence, edit the appropriate attributes. In List Entry Label (required), enter the label text for this link.

    Use Target to specify a target location.

  5. If the target location is a page:

    1. From Target Type, select Page in this Application.

    2. In Page, specify the target page number.

      To reset pagination for this page, select reset pagination for this page.

    3. In Request, specify the request to be used.

    4. In Clear Cache, specify the pages (that is, the page numbers) on which to clear cache. Specify multiple pages by listing the page numbers in a comma delimited list.

      You can set session state (that is, give a listed item a value) using the next two attributes:

    5. To set session state:

      • In Set these items, enter a comma delimited list of item names for which you would like to set session state.

      • In With these values, enter a comma delimited list of values for the items specified in the previous step.

        You can specify static values, or substitution syntax (for example, &APP_ITEM_NAME.). Note that item values passed to f?p= in the URL may not contain a colon (:). Additionally, item values may not contain commas unless you enclose the entire value in backslash characters (for example, \1234,56\).

    If the target location is a URL:

    1. From Target type, select URL.

    2. In URL Target, type a URL.

    If the target location is a page:

    1. From Target type, select Page in this Application.

    2. In Page, specify the page number.

  6. If the target location is a URL:

    1. From Target type, select URL.

    2. In URL Target, type a URL.

  7. To make the list entry conditional:

    1. Make a selection from the Condition Type list.

    2. Enter an expression in the fields provided.

  8. When you are finished defining list attributes, click Create or Create and Create Another.

Adding a List to a Page

Once you created a list, the next step is to add it a page by creating a region and specifying the region type as List.


See Also:

"Creating a New Template""List Templates" for more information on altering list display

To add a list to a page:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Regions, click Create to run the Create Region Wizard.

  3. Select List as the region type.

  4. Specify region attributes:

    • Enter a title

    • Select a region template

    • Specify a display point

    • Specify a sequence

  5. From List, select the list you want to add.

  6. Click Create List Region.

Repeat these procedures for each page on which you would like to add a list.

Editing Multiple List Entries Simultaneously

You can edit multiple list entries at once by clicking Grid Edit on the List Entries page.

To edit menu entries at once:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Shared Components.

  4. Under Navigation, click Lists.

    The Lists page appears.

  5. Select a list name.

    The List Entries page appears.

  6. Click Grid Edit.

  7. Edit the appropriate items and click Apply Changes.

Accessing List Reports

Application Builder includes the following list reports:

You can access these reports by clicking the appropriate button at the top of the Lists page.

List Utilization

Click Utilization to access the Lists Utilization report. This report displays all lists included in the current application. To edit list entries, select the list name. To view the pages on which the list appears, click the number in the Pages column.

Unused lists

Click Unused Lists to identify lists that are not used in the current application.

List Definition and List Entry History

Click History to view changes to list definitions and list entries by developer and date.

Creating Trees

You can use a tree in your application to effectively communicate hierarchical or multiple level data.

To create a tree:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Shared Components.

  4. Under Navigation, click Trees.

    The Trees page appears.

  5. To create a new tree, click Create.

  6. Enter basic page information.

  7. Enter a Tree Name and specify the Default Expanded Levels.

  8. Specify how tabs should be implemented.

  9. Identify tree attributes:

    1. Enter a tree name.

    2. Under Start Tree, specify how the starting tree node is created:

      • Based on new item with popup list of values - Creates a tree based on a new item with a popup list of values (LOV). Requires an LOV query that selects, displays, and returns values from a tree table. Use this method to select a different starting point each time you visit a page.

      • Based on a SQL Query - Creates a tree based on a SQL query. Requires a SQL query that selects a primary key from a tree table.

      • Static value - Creates a tree based on a static value.

      Keep in mind that the option Based on new item with popup list of values enables you to select a different starting point each time you visit a page. The starting point for the last two options always remains the same.

      You build a tree based on a table that contains the node data. This base table must have an ID (a primary key) and a parent ID that functions as a foreign key of the table. These IDs determine the number of tree levels.

  10. Select a tree template.

  11. Follow the on-screen instructions and specify the owner and name of the table on which the tree will be based.

  12. Under Identify Query:

    1. In ID, enter the column you want to use as the ID.

    2. In Parent ID, enter the Parent ID.

    3. In Leaf Node Text, specify the text that should appear on the leaf nodes.

    4. Under Link Option, select Existing Application Item to make the leaf node text a link.

Accessing Tree Reports

Application Builder includes the following tree reports:

You can access these reports by clicking the appropriate button at the top of the Lists page.

Tree Utilization

Click Utilization to access the Tree Utilization report. This report displays all trees included in the current application. To edit a tree, select the tree name.

Tree History

Click History to view changes to trees by developer and date.

PKWUɳPK(oUIOEBPS/sqlshop.htm Managing Database Objects with SQL Workshop

5 Managing Database Objects with SQL Workshop

This section provides information on how to use SQL Workshop to view and manage database objects, create and manage user interface defaults, and browse the data dictionary.

This section contains the following topics:

About SQL Workshop

You can use SQL Workshop to view and manage database objects from a Web browser.

To access the SQL Workshop home page, click the SQL Workshop icon on the Workspace home page. (See Figure 5-1.)

Figure 5-1 SQL Workshop Icon

Description of htmldb_sqlico.gif follows


The SQL Workshop home page is divided into four primary sections:

About Transaction Support

Oracle HTML DB is a browser-based development environment which communicates over HTTP. Because HTTP is a stateless protocol, any command you issue using SQL Workshop is automatically followed by a database COMMIT. There is no support for transactions that span multiple pages in the SQL Workshop. For example, you cannot issue an UPDATE statement on one page in the SQL Workshop and then revert it on a subsequent page using a ROLLBACK command.

Since the commands COMMIT, ROLLBACK and SAVEPOINT are executed as one transaction, you can include these commands in SQL Workshop by using scripts.


See Also:

"Using the SQL Script Repository" for information on running scripts

About Unsupported SQL*Plus Commands

SQL Workshop does not support SQL*Plus commands. If you attempt to enter a SQL*Plus command in SQL Workshop an error message displays. The following are examples of unsupported SQL*Plus commands:

SET ECHO OFF
SET ECHO ON
SET VERIFY ON
SET LONG 600
COLUMN dummy NOPRINT
COLUMN name FORMAT A20
DEFINE
ACCEPT
PROMPT
REMARK
SHOW

Viewing Database Objects

You can use SQL Workshop to view database objects. For example, you can view details about database objects by querying the Oracle dictionary. You can also run SQL commands and SQL scripts in the SQL Command Processor or view database objects in the Database Browser.

Topics in this section include:

Using the SQL Command Processor

You use the SQL Command Processor to run SQL commands and SQL scripts on any Oracle database schema for which you have privileges.

To access the SQL Command Processor:

  1. Click SQL Workshop on the Workspace home page.

  2. Under SQL Workshop, click SQL Command Processor.

    The SQL Command Processor appears.

  3. Select a schema from the list and follow the on-screen instructions.

  4. To run entered commands, click Run SQL.

    For example, to describe a database object you would type DESC MY_OBJECT. For example:

     DESC DEMO_ABOUT
    
    

    Alternatively, if you are using Internet Explorer, you can also press CTRL+Enter to execute your SQL Statement.

  5. To save entered commands, click Save.


See Also:

"Accessing Saved Commands in the SQL Archive" for more information on viewing saved commands and queries

About Command Termination

You can terminate commands in the Command Processor using either a semicolon (;) or forward slash (/). Consider the following examples:

INSERT INTO emp
      (50,'John Doe','Developer',10,SYSDATE,1000,10);

INSERT INTO emp
      (50,'John Doe','Developer',10,SYSDATE,1000,10)
/

The first example demonstrates the use of a semicolon (;). The second example demonstrates the use of forward slash (/).

Using Explain Plan

Use Explain Plan to view the plan the Oracle Optimizer uses to run your SQL Command.

To view the Explain Plan:

  1. Click SQL Workshop on the Workspace home page.

  2. From the Tasks list on right side of the page, select Explain Plan.

    Explain Plan appears.

  3. Enter a command in the field provided and click Explain Plan.

Viewing Database Objects

You can use the Database Browser to view database objects. To find a database object, select the schema you would like to view. The values available in the schema depend upon your resource privileges.

To browse database objects:

  1. Click SQL Workshop on the Workspace home page.

  2. Under Database Browser, select the type of database object you would like to view.

  3. To search for an object, select a schema, an object type, type a search string in the Search field, and click Go. Searches are case insensitive and no wildcards or quotes are necessary.

  4. To view object details, click the View icon adjacent to the appropriate name.

  5. Optionally, select a task from the Tasks list on the right side of the page.

Querying by Example

Once you have located a specific table you can declaratively create a report to display the data in the table.

To Query by Example:

  1. Click SQL Workshop on the Workspace home page.

  2. Under Database Browser, select Tables.

    The Database Browser appears.

  3. Click the View icon to view details about a specific object.

    The Object Detail appears.

  4. From the Tasks list, select Query by Example.

  5. Follow the on-screen instructions.

Managing Database Objects

You can use SQL Workshop to manage database objects. For example, you can create new database objects, manage script files and control files, or alter a table.

Topics in this section include:

Creating Database Objects

You can create new database objects using the Create Database Object Wizard.

To create new database objects in SQL Workshop:

  1. Click SQL Workshop on the Workspace home page.

  2. Under SQL Workshop, select Create Object.

    The Create Database Object Wizard appears.

  3. Select the type of database object you would like to create.

  4. Follow the on-screen instructions.

Dropping Database Objects

You can drop database objects using the Drop Database Object Wizard. When you drop a table using this wizard, you also remove all related triggers and indexes.

To drop a database object:

  1. Click SQL Workshop on the Workspace home page.

  2. From the Tasks list on the right side of the page, select Drop Database Object.

    The Drop Database Object Wizard appears.

  3. Select a schema and then an object type.

  4. Follow the on-screen instructions.

Restoring Dropped Database Objects

If you are running Oracle HTML DB with Oracle Database 10g release 1 (10.1), you can use the Recycle Bin to view and restore dropped database objects. When you drop a table, the space associated with the table is not immediately removed. The Oracle database renames the table and places it and any associated objects in the Recycle Bin where it can be recovered at a later time.


Note:

The Recycle Bin feature is only available if you are running Oracle HTML DB with an Oracle 10g database.

To use the Recycle Bin:

  1. Click SQL Workshop on the Workspace home page.

  2. From the Tasks list on the right side of the page, select Manage Recycle Bin.

    The Recycle Bin appears.

  3. To search for an object, select a schema, an object type, type a search string in the Search field, and click Go.

  4. To view object details, click the View icon adjacent to the appropriate name.

    On the Object Summary page, you can:

    • Click Restore Object to restore the current object

    • Click Purge to permanently delete the current object

To empty the Recycle Bin without viewing the objects:

  1. Click SQL Workshop on the Workspace home page.

  2. From the Tasks list on the right side of the page, select Manage Recycle Bin.

    The Recycle Bin appears.

  3. From the Tasks list on the right side of the page, select Purge Recycle Bin.

Using the SQL Script Repository

You can use the SQL Script Repository to view, edit, and run uploaded script files. For example, you can upload new script files as well as create and edit your create table, create index, and create PL/SQL package scripts.

Topics in this section include:

Managing Script Files in the SQL Script Repository

Use the SQL Script Repository to view, edit, run, and delete uploaded script files.

To view scripts in the SQL Script Repository:

  1. Click SQL Workshop on the Workspace home page.

  2. Under SQL Scripts, click Scripts.

    SQL Script Repository appears. Scripts are stored based on your workspace username.

  3. To search for a script, select a username from the Show list, enter a search string in the Find field (optional), and click Go.

    While in the Script Repository you can:

    • Reorder a list by clicking the column heading

    • View details about a specific file by clicking the View icon

    • Edit a script by clicking the Edit icon

    • Run a script by clicking Run in the Actions column

    • Delete a script by selecting it and clicking Delete Checked

    • Upload a script by clicking Upload

    • Create a script by clicking Create

To view script details:

  1. In the Script Repository, click the View icon.

    The Files Details page appears.

  2. Under View Links, you can:

    • Click Native file format to download the file locally

    • Click View document as text to view the file in your Web Browser

    • Click Parse this script to parse the script to run

To run a script in the Script Repository:

  1. In the Actions column, click Run.

    The Run page appears.

    If you have parameters in your script you must define them. You can define up to ten different parameters in each script.

  2. Enter a parameter name and value in the fields provided.

  3. To view the script file, click View File.

  4. To run the script file, click Run Script.

    The Run Results page appears displaying the number of success, failure and the elapsed time. RED indicates that errors occurred while executing the file.

  5. To view the script file source, click View Source.

  6. To run the file again, click Run Script again.

    Once you have run a script file, you can view a history of previous executions by clicking Previous Runs.

To delete a script file from the Script Repository:

  1. In the Script Repository, select the script to be deleted.

  2. Click Delete Checked.

Uploading and Creating Script Files

To upload a script file into the Script Repository:

  1. In the Script Repository, click Upload.

    The Upload Script page appears.

  2. Follow the on-screen instructions.

If the script file you upload has a valid file extension, SQL Workshop recognizes the file as a script and automatically parses it. Table 5-1 describes the file extensions SQL Workshop considers to be valid for script files.

Table 5-1 Valid Script File Extensions

Extension Description
pkh Package headers
plb Package bodies
sql Scripts
con Constraints
ind Indexes
sqs Sequences
tab Tables
trg Triggers
pkb Package bodes
pks Package specs

To create a script file while in the Script Repository:

  1. In the Script Repository, click Create.

    The Create Script page appears.

  2. Follow the on-screen instructions.

About Script Termination

You terminate a statement in a script by adding a carriage return and a forward slash (/) at the end of each statement. Consider the following examples:

INSERT INTO emp values(10,'aaa')
/
INSERT INTO emp values(20,'bbb')
/
INSERT INTO emp  values(30,'ccc')
/

Using Parameters in a Script

You can parameterize a script using a pound sign (#) or ampersand (&). The following two examples demonstrate valid parameter syntax.

CREATE TABLE #OWNER#.xyz (X INT)
/
CREATE TABLE #OWNER#.abc (Y NUMBER)
/

CREATE TABLE &OWNER.xyz (X INT)
/
CREATE TABLE &OWNER.abc (Y NUMBER)
/

Including SQL Queries in a Script

If you include SELECT statements in a script, the script will run without errors, but the result set will not display.

Exporting a Script File

You can export SQL Script Repository scripts using the Export Import Wizard in Application Builder.

To export a script from SQL Workshop:

  1. Navigate to the Workspace home page.

  2. Click Application Builder.

  3. When Application Builder appears, click Export/Import.

    The Export Import Wizard appears.

  4. Select Export and click Next.

  5. Click the Script Files button and follow the on-screen instructions.

If you export a UNIX format, the wizard generates a file with rows delimited by CHR (10) (that is, line feeds). If you export a DOS format then each row is terminated with CHR(13)||CHR(10) (that is, CR LF or carriage return line feed).

Accessing Saved Commands in the SQL Archive

When you click Save in SQL Command Processor, SQL Workshop saves entered commands and scripts to the SQL Archives.

The SQL Archives is different from the SQL Script Repository. By saving frequently used SQL commands in the SQL Archives, you can run the commands again without retyping. When you save a SQL command to the SQL Archives, the saved command does not appear in the Script Repository.

To view the SQL Archives:

  1. Click SQL Workshop on the Workspace home page.

  2. From the Tasks list on the right side of the page, select Manage SQL Archive.

    SQL Archives appears. Scripts are stored based on your workspace username.

  3. Follow the on-screen instructions.

Accessing the SQL Command History

SQL Command History displays the 200 most recent commands and scripts run in the SQL Command Processor.

To view the SQL Command History:

  1. Click SQL Workshop on the Workspace home page.

  2. From the Tasks list on the right side of the page, select View SQL History.

    SQL Command History appears.

  3. To run a command, click the appropriate SQL link.

    The selected SQL command or the script displays in the SQL Command Processor.

Generating DDL

If you are running Oracle HTML DB with Oracle Database 10g release 1 (10.1), you can use DDL statements to create, alter, and drop schema objects when they are no longer needed. You can also use DDL statements to grant and revoke privileges and roles, analyze table, index, or cluster information, establish auditing options, or add comments to the data dictionary.

To generate DDL statement in SQL Workshop:

  1. Click SQL Workshop on the Workspace home page.

  2. Under SQL Scripts, click Generate DDL.

    The Generate DDL Wizard appears.

  3. Follow the on-screen instructions.


See Also:


Managing Control Files

k(

Control files enable you to run a series of scripts in a predefined order. From the Control Files Repository, you can create, edit, delete, or run control files.

To access the Control Files Repository:

  1. Click SQL Workshop on the Workspace home page.

  2. Under SQL Scripts, click Script Control.

    Control Files Repository appears.

  3. To search for a script, select a username from the Show list, enter a search string in the Find field (optional), and click Go.

    While in the Control Files Repository you can:

    • Reorder a list by clicking the column heading

    • Edit a file by clicking the Edit icon

    • Run a file by clicking Run

    • Delete a script by selecting it and clicking Delete Checked

To create a control file:

  1. In the Control Files Repository, click Create.

    The Control File Create page appears.

  2. Enter a name for the control file, select the script files you would like to include, and click Create.

  3. Specify the execution order and click Done.

To edit a control file:

  1. In the Control Files Repository, click the Edit icon.

    The Edit Control File page appears.

  2. On the Edit Control File page you can:

    • Change the order in which files are executed by clicking Edit Execution Order

    • Add additional script files by clicking Add More Files

    • Delete a script by selecting it and clicking Delete Checked

To run a control file in the Control Files Repository:

  1. In the Action Column, click Run.

    The Run File page appears.

  2. Select an Oracle Schema from the Parse As list.

    If your script files include parameters you must define them. You can define up to ten different parameters in each script.

  3. Enter a parameter name and value in the fields provided.

    If you wish to run the control file in the background, select Run in Background. Running a control file in the background means that Oracle HTML DB submits it as a job. The advantage of this approach is that you do not have to wait for it to finish to continue using SQL Workshop.

  4. Click Run File.

    The Run Results page appears displaying the number of success, failures, and the elapsed time. RED indicates that errors occurred while executing the file.

  5. To run the file again, select Run File again

Viewing the Control File Run History

Once you have run a file, you can view a history of previous executions by clicking Previous Runs on the Run File page.

To view the Control File Run History:

  1. Run the control file as described in the previous procedure.

  2. Select Previous Runs.

Viewing Control File Job Status

You can view control file job status from either the Edit File or Run File page.

To view the status of a job:

  1. Run the control file as described in the previous section with the Run in Background option selected.

  2. From the Tasks list, select View Job Status.

Managing Tables

You can also use SQL Workshop to create new tables or edit existing tables.

To create a new table:

  1. Click SQL Workshop on the Workspace home page.

  2. Under SQL Workshop, click Create Object.

    The Create Database Object Wizard appears.

  3. Select Table and click Next.

  4. Follow the on-screen instructions.


Note:

To edit an existing table, you must first navigate to it using the Database Browser.

To edit an existing table:

  1. Click SQL Workshop on the Workspace home page.

  2. Under Database Browser, select Tables.

  3. To search for a table, select a schema, table type, type a search string in the Search field, and click Go.

  4. To view table details, click the View icon.

    The Table Definition appears.

  5. To edit the table or generate a report, make selection from the Tasks list. Table 5-2 describes the options available on the Tasks list.

    Table 5-2 Table Tasks

    Task Description
    Count Rows Counts all rows in the currently selected table.
    Create Lookup Table Creates a lookup table for the column you select. The selected column becomes a foreign key for the lookup table.
    Drop this object Drops the current table.
    Generate Create Table Script Generates a create table script.
    Insert Row Inserts a row into the current table.
    Manage Table Displays a wizard for performing a variety of tasks on the current table, including:
    • table (copy, drop, rename, analyze, truncate)

    • columns (add, drop, modify, and rename)

    • constraints (add, disable, drop)

    • trigger (create, disable, drop, enable)

    • index (create and drop

    Popup Table Columns Displays a popup window that lists the columns in the current table.
    Query by Example Displays a form so you can create a report and view the data in selected columns.
    Report Dependent Objects Displays a report that describes database objects that have dependencies on the selected table.
    View Data Model Displays a report that shows the referential integrity constraints for the current table.

  6. To view user interface defaults, click the Manage User Interface Defaults button.

Managing User Interface Defaults

User interface defaults enable developers to assign default user interface properties to a table, column, or view within a specified schema. When a developer creates a form or report using a wizard, the wizard uses this information to create default values for region and item properties.

Since user interface defaults are associated with a table, you can use them with applications created using the form and report wizards.

Topics in this section include:


See Also:

"Application Builder Concepts" and "Using Application Builder" for more information on regions and item properties

Viewing Tables Utilizing User Interface Defaults

To view tables that utilize user interface defaults:

  1. Click SQL Workshop on the Workspace home page.

  2. Under SQL Workshop, select User Interface Defaults.

    A list of tables for which user interface defaults are defined displays.

  3. Select a specific table by clicking the Edit icon adjacent to the table name.

Editing a Column Attributes

You define user interface defaults for a specific column by editing column attributes on the Column Definition page.

To edit column attributes:

  1. Click SQL Workshop on the Workspace home page.

  2. Under SQL Workshop, select User Interface Defaults.

    A list of tables for which user interface defaults are defined displays.

  3. Select a specific table by clicking the Edit icon adjacent to the table name.

    The View Details page appears. The following information displays at the top of the page:

    • Schema is the schema that owns the table.

    • Table/View Name is the name of the selected table or view.

    • Report Region Title and Form Region Title becomes the default title for all report or form regions. Both of these names a modified versions of Table/View Name in which the first letter is capitalized and any underscores are replaced with spaces.

    Column-level User Interface Defaults appear next. You can edit select attributes for all displayed columns, by clicking Grid Edit.

  4. To select a specific column, click the Edit icon adjacent to the column name.

Editing Column-level Defaults

Edit Column-level Defaults is divided into two pages: Column Definition and List of Values. The topics that follow describes how to edit specific attributes on the Column Definition and List of Values pages.

Edit Column-level User Interface Defaults

The top of the page displays the selected schema, table or view name, and column name.

Default for Label (used in Reports and Forms)

Use Label to specify default label text for items in a form and the heading for columns in reports.

Defaults for Reports

Available Display for Reports attributes include:

  • Display - Indicates whether the column displays in a report. The default is Yes.

  • Display Sequence - Specifies the display sequence of items in a report. The default value is based on the column ID, which is based on the order of the columns in the table.

  • Display As - Specifies how the column should be displayed in reports

  • Mask - Indicates if a mask should be applied against the data. This attribute is not applicable for character- based items.

  • Alignment - Specifies report alignment (Left, Center, or Right). If the column is a number, the default is Right. Otherwise, the default is Left.

  • Searchable - Indicates whether the column should be searchable in reports. If the column is VARCHAR2 or CHAR, the default is Yes. If not, the default is No.

  • Group By - Indicates whether the column should be used for Group By and then the sequence of the grouping. The default is Yes.

  • Aggregate By - Indicates whether the column should be used for aggregation in reports and charts.

Defaults for Tabular Forms

Use Display As to specify how an item should display in a tabular form.

Defaults for Forms

Available Defaults for Forms attributes include:

  • Display - Indicates whether the column displays in a form. The default is Yes.

  • Display Sequence - Specifies the sequence of items in a form. The default is based on the column ID, which is based on the order of the columns in the table.

  • Display As - Indicates how items in a form display. The default selection is Text Field.

  • Mask - Indicates a mask to be applied against the data in a form. Not used for character-based items.

  • Default Value - Specifies the default value associated with this column.

  • Width - Specifies the display width.

  • maxWidth - Specifies the maximum string length a user is allowed to enter in this item.

  • Height - Specifies the display height of an item.

  • Required - Used to generate a validation in which the resulting item must not be null. If resulting item is not null, select Yes.

  • Help Text - Becomes Item help. By default, this text is pulled from the column hint (if applicable).

List of Values

To access List of Values defaults, click the List of Values tab. Once you select the type, you are prompted to enter either Display Value, Return Value pairs, or a list of values query.

The top of the page displays the selected schema, table or view name, and column name. Use the List of Values Type list to specify whether the selected column will include a static or dynamic list of values.

Viewing the Column Definition Report

You can view details about a specific column by accessing the Column Definition report. The Column Definition report displays the data type, data length, nullable, default, comment as well as any check constraints, primary and unique keys, and foreign keys that reference the column.

To view the Column Definition report:

  1. Click SQL Workshop on the Workspace home page.

  2. Under SQL Workshop, select User Interface Defaults.

  3. Select a table by clicking the Edit icon adjacent to the table name.

  4. Select a column.

  5. From the Tasks list, select View Column Definition.

Applying User Interface Defaults to a Table or View

You can view a listing of tables without user interface defaults on the Tables without Defaults page.

To apply user interface defaults to a table or view:

  1. Click SQL Workshop on the Workspace home page.

  2. Under SQL Workshop, select User Interface Defaults.

  3. From the Tasks list, select Tables without User Interface Defaults.

  4. To apply user interface defaults to a table or view, select the Default link to the left of the table or view name.

Comparing User Interface Defaults Across Applications

Use the Compare Defaults report to monitor consistency in user interface design across all pages in a single application or multiple applications in the current workspace. Running the Compare Defaults report compares currently defined user interface defaults (or column attributes) against the column attributes set for forms, reports, and tabular forms.

To run the Compare Defaults report:

  1. Click SQL Workshop on the Workspace home page.

  2. Under SQL Workshop, select User Interface Defaults.

  3. From the Tasks list, select Compare User Interface Defaults.

    The Compare Defaults page appears.

  4. Select a schema, table name, and column.

  5. From Display, select the attributes you want to compare.

  6. Optionally select an application.

  7. Click Go.

About Exporting and Importing User Interface Defaults

You export user interface defaults in the same way you export any related application file. Exporting user interface defaults from one Oracle HTML DB development instance to another involves the following steps:

  • Export the user interface defaults using the Export User Interface Defaults utility

  • Import the exported file into the target Oracle HTML DB instance

  • Install the exported file from Export Repository

When you export user interface defaults, all user interface defaults for the selected schema are exported to a single script. The file contains an API call to create table hints by making calls to the application PL/SQL API. You can use this file to import user interface defaults to another database and Oracle HTML DB instance.

Browsing the Data Dictionary

Each Oracle database has a data dictionary. An Oracle data dictionary is a set of tables and views that are used as a read-only reference about the database. For example, a data dictionary stores information about both the logical and physical structure of the database. A data dictionary also stores information about valid Oracle database users, integrity constraints for tables in the database, and the amount of space allocated for a schema object as well as how much of it is being used.

To browse the data dictionary:

  1. Click SQL Workshop on the Workspace home page.

  2. From the Tasks list, select Query Data Dictionary.

    The Data Dictionary Browser appears.

  3. Click the View icon to display the Query By Example (QBE) form. Use this form to query the Oracle data dictionary for details about database objects.


See Also:

Oracle Database Concepts for more information on the data dictionary

To view data dictionary reports:

  1. Click SQL Workshop on the Workspace home page.

  2. From the Tasks list, select Query Data Dictionary.

    The Data Dictionary Browser appears.

  3. From the Tasks list, select Data Dictionary Reports.

PK1*PK(oUIOEBPS/img_text/darbbook.css*/* ========================================================================== */ /* darbbook.css */ /* Release 0.0.1 */ /* Last revision 02/07/03 */ /* 2003, Oracle Corporation. All rights reserved. */ /* ========================================================================== */ /* This is not intended to be a stand-along CSS. Instead, it cascades on */ /* top of the BLAF CSS, providing minimal changes to the existing styles */ /* in BLAF, while defining further styles for DARB-specific classes. */ /******************************************************************************/ /* BLAF Overrides/Additions */ /******************************************************************************/ /* First, we need a couple tweaks to the BLAF CSS. */ /* H4 needs to be weight BOLD, as "normal" is too light for accessibility */ H4 { font-weight:bold; } /* BLAF doesn't include styles for H5/H6, so we'll include them. Same */ /* Font family as H1-H4, just slightly smaller and BOLD as well. */ H5, H6 { font-family: Arial, Helvetica, Geneva, sans-serif; color:#336699; background-color : #FFFFFF; } H5 { font-size: 0.9em; font-weight: bold; } H6 { font-size: 0.7em; font-weight: bold; } /* Loose the H1 underscore */ H1 { border-width : 0px 0px 0px 0px; } /* BLAF doesn't provide much contrast between links and visited links */ /* so we'll add a little red to increase contrast. */ A:visited { color : #AA3300; background-color : #FFFFFF; } /******************************************************************************/ /* DARB-specific formats */ /******************************************************************************/ .bold { font-weight: bold; } .italic { font-style: italic; } .bolditalic { font-weight: bold; font-style: italic; } .codeinlinebold { font-weight: bold; } .codeinlineitalic { font-style: italic; } .codeinlineboldital { font-weight: bold; font-style: italic; } .syntaxinlinebold { font-weight: bold; } .syntaxinlineitalic { font-style: italic; } .syntaxinlineboldital { font-weight: bold; font-style: italic; } .bridgehead { font-family: Arial, Helvetica, Geneva, sans-serif; color:#336699; background-color : #FFFFFF; font-weight: bold; } .term, .glossterm { font-weight: bold; } .glossaryterm { font-weight: bold; } .keyword { font-weight: bold; } .variable { font-style: italic; } .msg, .msgexplankw, .msgactionkw { font-weight: bold; } .underline { text-decoration: underline; } .superscript { vertical-align: super; } .subscript { vertical-align: sub; } .listofeft { border: none; } .titleinfigure, .titleinexample, .titleintable, .titleinequation { font-weight: bold; font-style: italic; } .subhead1, .subhead2, .subhead3 { font-family: Arial, Helvetica, Geneva, sans-serif; color: #336699; background-color : #FFFFFF; font-weight: bold; } .subhead1 { font-size:1.1em; } .subhead2 { font-size:1.0em; } .subhead3 { font-size:0.9em; display: inline; } /* When lists are inside tables, they need to be more "compact" so they don't */ /* spread the table out. We need to suppress the natural line break in the */ /* para element for "paras inside a list item inside a table data" */ td li p { display: inline; } TD.copyrightlogo { text-align:center; font-size: xx-small; } SPAN.copyrightlogo { text-align:center; font-size: xx-small; } IMG.copyrightlogo { border-style:none; } p.betadraftsubtitle { text-align:center; font-weight:bold; color:#FF0000; } .betadraft { color:#FF0000; } .comment { color:#008800; } PK*/*PK(oUIOEBPS/img_text/blafdoc.css/* blafdoc.css */ /* Release 1.1.0 */ /* Copyright 2002, 2003 Oracle. All rights reserved. */ /* ========================================================================== */ BODY { font-family : Arial, Helvetica, Geneva, sans-serif; background-color : #FFFFFF; color : #000000; } BODY, P, TABLE, TD, TH, OL, UL, A, DL, DT, DD, BLOCKQUOTE, CAPTION { font-family : Arial, Helvetica, Geneva, sans-serif; font-size : small; } A:link { color : #663300; background-color : #FFFFFF; } A:active { color:#ff6600; background-color : #FFFFFF; } A:visited { color:#996633; background-color : #FFFFFF; } A.glossary-link { border-bottom : 1px dotted; text-decoration : none; } H1, H2, H3, H4 { font-family: Arial, Helvetica, Geneva, sans-serif; color: #336699; background-color : #FFFFFF; } H1 { font-size : 1.6em; font-weight: bold; border : solid #CCCC99; border-width : 0px 0px 1px 0px; width : 100%; } H2 { font-size:1.3em; font-weight: bold; } H3 { font-size:1.1em; font-weight: bold; } H4 { font-size:1em; font-weight: normal; } H1 A, H2 A, H3 A, H4 A { font-size: 100%; } PRE, CODE { font-family: Courier, "Courier New", monospace; font-size:1em; } CODE { color: #336699; } CODE .code-comment { color: #000000; } H1 A CODE, H2 A CODE, H3 A CODE, H4 A CODE { color: #336699; font-weight: bold; } A:link CODE { color: #663300; } A:active CODE { color: #ff6600; } A:visited CODE { color: #996633; } TABLE { font-size: small; } CAPTION { text-align : center; font-weight : bold; width: auto; } TD { vertical-align : top; } TH { font-weight: bold; text-align: left; vertical-align : bottom; color: #336699; background-color: #FFFFFF; } TABLE.table-border { border : 1px solid #CCCC99; } TABLE.table-border TD, TABLE.table-border TH { padding : 2px 4px 2px 4px; background-color: #FFFFFF; border : 1px solid #CCCC99; } TABLE.table-border TH.table-header-border-left, TABLE.table-border TH.table-header-border-middle, TABLE.table-border TH.table-header-border-right { background-color: #cccc99; color: #336699; } TABLE.table-border TH.table-header-border-left { border-left : 1px solid #CCCC99; border-right : 1px solid #FFFFFF; background-color: #cccc99; } TABLE.table-border TH.table-header-border-middle { border-left : 1px solid #FFFFFF; border-right : 1px solid #FFFFFF; background-color: #cccc99; } TABLE.table-border TH.table-header-border-right { border-left : 1px solid #FFFFFF; border-right : 1px solid #CCCC99; background-color: #cccc99; } SPAN.gui-object { font-weight: bold; } P.horizontal-rule { width : 100%; border : solid #CCCC99; border-width : 0px 0px 1px 0px; margin-bottom : 2em; } div.zz-skip-header { margin-bottom : 0px; margin-top : -2px; padding : 0px; text-align:center; line-height : 1px; } div.zz-skip-header a:link, div.zz-skip-header a:visited, div.zz-skip-header a:active { color:white; background-color:white; text-decoration:none; font-size:.1em; line-height : 1px; } TD.zz-nav-header-cell { text-align : left; font-size : small; width : 99%; color:#000000; background-color : #FFFFFF; font-weight : normal; vertical-align : top; margin-top : 0px; padding-top : 0px; } A.zz-nav-header-link { font-size : small; } TD.zz-nav-button-cell { text-align : center; width : 1%; vertical-align : top; padding-left : 4px; padding-right : 4px; margin-top : 0px; padding-top : 0px; } A.zz-nav-button-link { font-size : x-small; } DIV.zz-nav-footer-menu { width : 100%; text-align : center; margin-top : 1em; margin-bottom : 2em; } P.zz-legal-notice, A.zz-legal-notice-link { font-size : xx-small; /* display : none ; */ /* Uncomment this to hide the legal notice */ } P.notep1 { font-size:1em; font-weight: bold; font-family: Arial, Helvetica, sans-serif; } PKɃt$PK(oUIOEBPS/buildr.htm Using Application Builder

7 Using Application Builder

This section provides important background information about how to use Application Builder. You use Application Builder to build dynamically rendered applications in Oracle HTML DB. An application is a collection of database-driven Web pages linked together using tabs, buttons, or hypertext links.

This section contains the following topics:

Accessing Application Builder

An application is a collection of pages that share a common session state definition and authentication method. Application Builder is the tool you use to build the pages that comprise an application. You access Application Builder from the Workspace home page. (See Figure 7-1.)

Figure 7-1 Workspace Home Page

Description of htmldb.gif follows


To access Application Builder:

  1. Log in to Oracle HTML DB.

    The Workspace home page appears.

  2. To access Application Builder, you can either:

    • Select an application name from the Applications list

    • Create a new application by clicking Create Application

      The Application Builder home page appears.

About the Application Builder Home Page

As shown in Figure 7-2, the top of the Application Builder home page displays the current application name and application ID, last update date, and parsing schema.

Figure 7-2 Application Builder Home Page (Top)

Description of bldr_hm_top.gif follows


Click the one of the following to run the current application, edit application attributes, create shared components, export and import information, or create a new page:

  • Run submits the pages in the current application to the HTML DB engine to render viewable HTML

  • Edit Attributes displays the Edit Application Attributes page

  • Shared Components links to a new page for building shared application components and user interface controls

  • Export/Install links you to the Export Import Wizard

  • Create Page links to a wizard for creating a new page

As shown in Figure 7-3, the Pages list displays at the bottom of the page. To access a specific page, select the page name. To search for a specific page number, enter a page number in the Find field and click Find. To view all pages in an application, leave the Find field blank and click Find.

Figure 7-3 Pages List

Description of bldr_hm_pglist.gif follows


A Tasks list displays on the right side of the page. It contains the following links:

  • Delete this Application enables you to delete the current application. (See "Deleting an Application".)

  • Manage Page Groups links to the Page Groups page. Make the pages within your application easier to access by organizing them into page groups. (See "Grouping Pages".)

  • Manage Page Locks links to the Locked Pages page. Locking pages in an application, prevents conflicts during application development. (See "Locking and Unlocking Page".)

  • View Application Reports displays links to summary application reports. (See "Viewing Application Reports".)

Editing Application Attributes

Application attributes apply to an entire application. Once you create an application the next step is to specify application attributes.

To edit application attributes:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

    Application Builder appears.

  3. Click the Edit Attributes icon. (See Figure 7-4.)

    Figure 7-4 Edit Attributes Icon

    Description of edit_att.gif follows


Edit Application Attributes page appears. Oracle HTML DB creates a unique application ID when you create a new application. The application ID displays at the top of the page. Beneath the application ID are links to various sections of the page. Required values are marked with a red asterisk (*).

The topics that follow describe the specific sections of the Edit Application Attributes page, including:

Application Definition

Use Application Definition attributes to define basic characteristics of your application, including the application name, an optional alphanumeric alias, a version number, and the application owner. Table 7-1 describes all Application Definition attributes.

Table 7-1 Application Definition Attributes

Attribute Description
Name Provides a short descriptive name for the application to distinguish it from other applications in the Oracle HTML DB development environment.
Application Alias Assigns an alternate alphanumeric application identifier. You can use this identifier in place of the application ID.For example, suppose you create an alias of myapp for application 105. Using f?p syntax, you could call application 105 as either:
  • f?p=105:1

  • f?p=myapp:1

Version Includes the application's version number on a page. You can also automatically tie the version to the date of last modification using the following format masks:
  • YYYY.MM.DD

  • MM.DD.YYYY

  • DD.MM.YYYY

If your application version uses YYYY.MM.DD then Oracle HTML DB replaces this format mask with the date of last modification of any application attribute.

Image Prefix Determines the virtual path the Web server uses to point to the images directory distributed with Oracle HTML DB. During installation, the virtual path is configured as /i/.

When embedding an image in static text (for example, in page or region headers or footers) you can reference an image using the substitution string #IMAGE_PREFIX#. For example, to reference the image go.gif you would use the following syntax:

<img src="#IMAGE_PREFIX#go.gif">

See Also: "IMAGE_PREFIX", "Uploading Images", and "Referencing Images"

Proxy Server Use this field to specify a proxy server.

For example, Application Builder may require a proxy server when using a region source type of URL. The URL region source embeds the results of the URL (that is, the page returned by navigating to the URL) as the region source. If you use a firewall and the target of a URL is outside the firewall relative to Oracle HTML DB, you may need to specify a proxy server.

You can reference values entered into this field from PL/SQL using the PL/SQL package variable HTMLDB_APPLICATION.G_PROXY_SERVER.

Logging Determines whether user activity is recorded in the Oracle HTML DB activity log. When set to Yes, every page view will be logged, allowing a Workspace administrator to monitor user activity for each application.

Disabling logging may be advisable for high volume applications.

Parsing Schema Specifies the schema that all SQL and PL/SQL in the application will be parsed as. You may use #OWNER# to reference this value in SQL queries and PL/SQL (for example, in a region or a process).
Exact Substitutions Select whether or not only exact substitutions will be supported. For optimal runtime performance, it is recommended you use exact substitutions.

Exact substitutions use the following sytnax:

&ITEM.

Non-exact substitutions use the following sytnax:

&ITEM


See Also:


Authorization

Use Authorization to specify an authorization scheme for your application. You may assign only one authorization to an entire application. However, you may assign an authorization scheme to individual pages, page controls (such as a region, a button, or an item), or a shared component (such as a menu, a list, or tab). An authorization scheme is a binary operation that either succeeds (equals true) or fails (equals false). If it succeeds then the component or control can be viewed, if it fails then the component or control cannot be viewed or processed. When you attach an authorization scheme to a page and it fails, an error message displays instead of the page. However, when you attach an authorization scheme to a page control (for example, a region, a button, or an item) and it fails, no error page displays. Instead, the control either does not display or is not processed or executed.

Session Management

Use Session Management when establishing your authentication and session management infrastructure. Table 7-2 describes all session management attributes.

Table 7-2 Session Management Attributes

Attribute Description
Home Link This is the relative URL used to display the home page of your application. For example, f?p=6000:600 could be for application 6000 with a home page number of 600.

The value you enter here replaces #HOME_LINK# substitution string in application templates.

You can also use this attribute to specify a custom procedure to function as a home link. For example, you could create a custom procedure named personal_calendar to call an HTML page to serve as the application home.

Login URL Specifies the location of the application login page.

See Also: "Using Substitution Strings" and "Creating an Authentication Scheme"

Public User Identifies the Oracle schema (that is, the user) used to connect to the database when generating unprotected pages.

When a user logs in as this user, the HTML DB engine considers this to be a "public user" session. The HTML DB engine supports the following built -in display conditions:

  • USER_IS_PUBLIC_USER

  • USER_IS_NOT_PUBLIC_USER

If the current application user (or V('USER') equals the value of this attribute, then the user is considered to be a public user. Some applications have public (not logged in) and a private (logged in) modes. By determining if the user is a public user, you can conditionally display or hide information.

For example you can show a login button if the user is a public user and a logout link if the user is not the public user. The public user (if null) defaults to "PUBLIC_USER". Reference this value using HTMLDB_APPLICATION.G_PUBLIC_USER. The HTML DB engine also has built-in condition types USER_IS_PUBLIC_USER and USER_IS_NOT_PUBLIC.

See Also: "Establishing User Identity Through Authentication"


To view details about a selected authentication scheme, click mange next to Authentication: SCHEME.

Theme

Themes are collections of templates that can be used to define the layout and style of an entire application. Each theme provides a complete set of templates that accommodate every user interface pattern that may be needed in an application.

Globalization

Use Globalization attributes to specify globalization options such as the primary application language. Table 7-3 describes theses attributes.

Table 7-3 Globalization Attributes

Attribute Description
Application Primary Language Identifies the language in which an application is developed. This language is the base language from which all translations are made. For example, suppose application 100 was authored in English, translated it into French, and published as application 101. The application ID would be transparent to the end user.

All modifications to the application should be made to the primary language specified here.

Application Language Derived From Specifies how Oracle HTML DB determines or derives the application language. The application primary language can be static (that is, derived from the Web browser language) or determined from a user preference or item. The database language setting determines date display and sorting characteristics.

This option enables you to disable browser derived language support. You also have the option of having the application language derived from an application preference.


Application Availability

Use these attributes to manage your application by defining an application status and build status. For example, if you select the status Restricted Access, you can specify which users who have access and can run the application. Table 7-4 describes these attributes.

Table 7-4 Application Availability Attributes

Attribute Description
Status Specifies if the application is available or unavailable for use.
Build Status Identifies the build status of the current application:
  • Run and Build Application - Developers can both run and develop the application.

  • Run Application Only - Developers can only run the application.

Message for unavailable application If Status is set to Unavailable this text displays. This text will not display if Status is set to Available.
Restrict to comma separated user list (Status must equal Restricted Access) Specifies users who can run the application if the Status is set to Restricted Access. To use this attribute:
  1. From the Status list, select Restricted Access.

  2. Enter a comma delimited list of users who can run the application in the field provided.


Global Notifications

You can use the Global Notifications attribute to communicate system status to application users. For example, you can use this attribute to notify users of scheduled downtime or communicate other messages regarding application availability. If your page template contains a #GLOBAL_NOTIFICATION# substitution string, then the text entered here displays on each page.

To create a global notification:

  1. Include the #GLOBAL_NOTIFICATION# substitution string in your page template.

  2. Navigate to the Edit Application Attributes page and enter a message in the Global Notifications attribute.

  3. Click Apply Changes.

Virtual Private Database (VPD)

VPD provides an application programmatic interface (API) which enables developers to assign security policies to database tables and views. Using PL/SQL, developers can create security policies with stored procedures and bind the procedures to a table or view by means of a call to an RDBMS package. Such policies are based on the content of application data stored within the database, or are based on context variables provided by the Oracle database. In this way, VPD permits access security mechanisms to be removed from applications and centralized.

The PL/SQL you enter in this field is executed immediately after the user is authenticated. V('USER') is accessible from this function. Session state for the current call is not yet initialized when this call is made. If your application does not need to employ VPD to support multiple customers in the same database, leave this attribute null.

Static Substitution Strings

Use these fields to define static substitution strings for your application. You can use static substitution string for phrases or labels that occur in many places within an application. Defining static substitution strings centrally enables you to change text strings in multiple places in your application by making a single change to the Substitution Value defined on this page.

Logo

Use these attributes to identify an image to be used as the logo for this application. In Image identify the image name. If you identify an image in the Image attribute and include the #LOGO# substitution string in your page template, the HTML DB engine generates an image tag. Use Logo Image Attributes to identify specific image attributes for the logo image. For example:

width="100" height="20" alt="Company Logo"

Build Options

Use Build Options to enable or disable functionality. Most application attributes have a build option attribute. Do not specify a build option unless you plan on excluding that object from specific installations. Build Options have two possible values: INCLUDE and EXCLUDE. If you specify an attribute as being included then the HTML DB engine considers it at runtime. However, if you specify an attribute as being excluded then the HTML DB engine treats it as if it does not exist.

Application Template Defaults

Application Template Defaults list the default templates for this application. To specify a new template at the application level, you can either:

  • Select a new theme

  • Select a new default page template on the Define Theme page

You can also override this default by making a selection from the Page Template list on the Page Attributes page.

Table 7-5 describes Application Template Defaults for the current application.

Table 7-5 Application Template Defaults Attributes

Attribute Description
Default Page Template Indicates the default page template for displaying pages. You can override this selection by making a selection from the Page Template list on the Page Attributes page.

See Also: "Editing Page Attributes"

Print Mode Page Template Identifies the template to be used when the HTML DB engine is in printer friendly mode.

When calling the HTML DB engine to render a page, you have the option of specifying whether or not the page should be displayed in a printer friendly mode.

If you specify YES, then the page displays using a printer friendly template. The HTML DB engine displays all text within HTML Form Fields as text. The printer friendly template does not need to have the #FORM_OPEN# or #FORM_CLOSE# substitution string.

See Also: "Optimizing a Page for Printing"

Error Page Template Optional. Specifies a page template to use for errors that display on a separate page as opposed to those that display inline.

Wizard Template Defaults

Wizard Template Defaults identify default templates Application Builder uses when running wizards. You can override these settings on the attributes page for each control or component. Table 7-6 describes Wizard Template Defaults for the current application.

Table 7-6 Wizard Template Defaults Attributes

Attribute Description
Calendar Default calendar template used when creating a new calendar.
Label Default label template used when you create new page items.
Report Default report template used when you create new report.
List Default template used when you create a list.
Menu Default template used when you create a menu.
Button Default template to be used when you create new buttons that are template controlled.
Region Default region template used when you create a new region.
Chart Region Default region template used when you create a chart.
Form Region Default region template used when you create a form.
Report Region Default region template used when you create a report.
Tabular Form Region Default region template used when you create a tabular form.
Wizard Region Default region template used when you create a new wizard component
Menu Region Default region template used when you create a new menu.
List Region Default region template used when you create a new list.

Application Comments

Use this attribute to record developer comments about the current application.

Viewing a Page

A page is the basic building block of an Oracle HTML DB application. Each page can have buttons and fields (called items) and application logic (or processes). You can branch from one page to the next using conditional navigation, perform calculations (called computations), perform validations (such as edit checks), and display reports, calendars, and charts.

Topics in this section include:

Viewing a Page Definition

You can view, create, and edit the controls and components that define a page by accessing the Page Definition.

To view the Page Definition for an existing page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

    Application Builder appears. The list of pages in the current application appears at the bottom of the page.

  3. From the Pages list, select a page.

    As shown in Figure 7-5, the Page Definition appears.

    Figure 7-5 Page Definition

    Description of pg_def.gif follows


Understanding the Page Definition

As shown in Figure 7-6, a breadcrumb menu displays at the top of each Page Definition. Breadcrumb menus appear on every page in Oracle HTML DB. Each menu entry indicates your location relative to other pages in the current application and functions as a navigation path. You can instantly link to another page by clicking a breadcrumb menu entry.

Figure 7-6 Page Definition (Top)

Description of pg_def_top.gif follows


The current page number displays on the far right side of the page, next to a small button that resembles a traffic light. Clicking this button to runs the current page and renders it into viewable HTML.

A page navigation bar appears next. (See Figure 7-6.) Options available on the page navigation bar include:

  • Page. This field displays the current page number. To access another page directly, enter a page number and click Go. To access the previous or next page number, click the arrow buttons.

  • Delete. Deletes the currently selected page.

  • Copy. Creates a copy of the selected page within the current application.

  • Edit Attributes. Links to Page Attributes. Use this page to edit high-level page attributes such as the page name, an optional name alias, and view information about defined tab sets, specified templates, and authorization schemes.

  • Create. Links to a wizard for creating a new page.

The page name and last update date appear next.

The center of every Page Definition is divided into three sections as described in Table 7-7.

Table 7-7 Divisions of the Page Definition

Section Description
Page Rendering Defines all attributes for the page, regions, buttons, items, page rendering computations and page level processes.

See Also: "Understanding Page Rendering Controls"

Page Processing Specifies page level application logic such as computations, validations, processes, and branching.

See Also: "Understanding Page Processing Controls"

Shared Components Displays application components that can be shared among multiple pages.

See Also: "Working with Shared Components", "Creating Tabs", "Creating Lists of Values", "Creating Menus", "Creating Lists", "Customizing Templates", "Understanding Security", and "Creating a Navigation Bar"


Additional Page Definition Features

Each Page Definition contains the following row of buttons at the top of the page:

  • Event View links to a report that details currently defined page controls and processes

  • Object References displays a list of database objects referenced by the current page

  • Export enables you to export the current page

  • History displays a history of recently changed pages


See Also:

"Viewing a Page"

Event View

Clicking Event View displays the Page Application View report. This report details all currently defined page controls and processes. It provides a chronological view of how and in what order the HTML DB engine renders the page, invokes logic, and runs processes. You can control the amount of information that displays by selecting one of the following view options:

  • Show All displays all possible page controls and processes, including those not currently defined

  • Show Used displays currently used page controls and processes (Default)

To view details about a specific page control or process, click the appropriate hypertext link. Alternately, you can create new page controls and processes by clicking the small icons to the left of each entry.

To run the current page, click Run. To create a new page, click Create.

Object References

Clicking Object References displays a list of database objects referenced by the current page. Click the Referenced Name to view object details. Click the application number to view all database objects referenced by the current application.

Export

Click Export to export the current page. Remember that some pages may reference shared components. To export all pages within an application, you need to complete an application export.

History

Clicking History displays the Recent Changes report. This report displays a history of recent changes to the currently selected page by developer, application, page number, modification date, attribute, and action.

Using the Developer Toolbar

Users who log in to Oracle HTML DB having developer privileges have access to the Developer toolbar. The Developer toolbar offers a quick way to edit the currently selected page, create a new page, control, or component, view session state, or turn edit links on an off.

The Developer toolbar (see Figure 7-7) displays at the bottom of every page in a running application.

Figure 7-7 Developer Toolbar

Description of d_toolbar.gif follows


The Developer toolbar consists of the following links:

Editing a Page Definition

A page is the basic building block of an application. Each page has page number, a name, and typically some text attributes such as a header, title and footer. You add content to your page by creating page controls (regions, items, and buttons). Page templates and page region templates control the exact look and feel of each page.

Topics in this section include:

Accessing a Page Definition

You can view, create, and edit the controls and components that define a page by accessing the Page Definition.

To view the Page Definition for an existing page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

    Application Builder appears. The list of pages for the selected application appears at the bottom of the page.

  3. From the Pages list, select a page name.

    The Page Definition appears.

Accessing a Summary View of Controls, Components, and Application Logic

Each Page Definition serves a a central navigation point for all the controls, components, and application logic that defines a page.

You can access a summary view of all defined controls or components by selecting the title (for example, Regions, Button, Items, Computations, Processes, and so on). For example, selecting Regions displays a summary report of all currently defined regions on the current page. Use this summary view to:

  • Edit the multiple attributes at once by making new selections from the available fields and select lists

  • Link to a definition page by clicking the Edit icon

You can access additional summary views by clicking the buttons at the top of each page. To save your edits to any summary view, click Apply Changes.

You can also view the attributes of a specific control or component by selecting its name on the Page Definition. For example, if your Page Definition contained a region named Customers, clicking the region name displays an attribute page for that region.

Copying or Creating a New Control or Component

You can copy or create new controls or components by clicking the Copy and Create icons. (See Figure 7-8.) The Copy icon resembles two small overlapping pages. The Create icon consists of a plus (+) sign overlapping a small page. Click the Copy icon to make a copy of the current control or component. Click the Create icon to create a new control or component.

Figure 7-8 Copy and Create Icons

Description of buttons.gif follows


Editing Page Attributes

Page attributes only apply to a specific page. You access page attributes from the Page Definition.

To edit page attributes:

  1. Navigate to the Page Definition. (See "Viewing a Page Definition".)

  2. From the navigation bar at the top of the page, click Edit Attributes.

    The Page Attributes page appears. Required values are marked with a red asterisk (*).

The topics that follow describe the specific sections of the Page Attributes page, including:


See Also:

"Adding Additional Pages" for more information on creating a new page

Page Identification

Use these attributes to define general attributes for the current page such as a page name, an optional alphanumeric alias, and associated page groups. Table 7-9 describes these attributes.

Table 7-8 Page Identification Attributes

Attributes Descriptions
Name Identifies the name of the current page for application developers. This name is used in numerous Oracle HTML DB pages and reports, along with the page number and page title.
Page Alias Enter an alphanumeric alias for this page. This alias must be unique within the current application.

For example, if you were working on page 1 of application 100, you could create an alias called home. You could then access this page from other pages using the following f?p syntax:

f?p=100:home
Group Identify the page group you would like to associate with this page.

See Also: "Grouping Pages"


Primary Display Attributes

Use these attributes to define general display attributes for the current page such as the selected page template, standard tab set, title, and cursor focus. Table 7-9 describes these attributes.

Table 7-9 Primary Display Attributes

Attributes Descriptions
Page Template Select a page template to control the appearance of this page. Making a selection here overrides the use of the default page template selected for the application when rendering this page.
Standard Tab Set Select a standard tab set to be used for this page. A standard tab set is associated with a specific page and page number. You can use standard tabs to link users to a specific page.

See Also: "Creating Tabs"

Title Enter a title to display in the title bar of the browser window. The HTML DB engine uses the title you specify here in place of the #TITLE# substitution string used in the page template. This title is inserted between the HTML tag <TITLE></TITLE>.
Cursor Focus Select whether you want the cursor focus to be placed in the first field on the page.

Select Do not focus cursor if you do not want to include JavaScript.


HTML Header

Use this attributes to replace the #HEAD# substitution string in the page template header. The values entered here are inserted after the HTML <HEAD> tag. Common uses of these attributes:

  • Code page specific inline cascading style classes

  • Add additional style sheets for a specific page

  • Code page specific JavaScript

  • Code page specific meta tag page refresh

Page Header, Footer and Text Attributes

Use these attributes to define page header, body header, body footer, and page footer text. Table 7-10 describes these attributes.

Table 7-10 Page Header, Footer and Text Attributes

Attribute Description
Header Text Enter text of HTML to display after the page template header and before page template body.
Body Header Enter text of HTML to display before showing regions. Displays before the page template #BOX_BODY# substitution string.
Footer Enter text of HTML to display after page template body and before page template footer.

On Load JavaScript

Use this attribute to add onload events such as calls to JavaScript. In the Page HTML Body Attribute, enter JavaScript or text to be substituted for your page template's #ONLOAD# substitution string. To use this feature, your page template must include the #ONLOAD# substitution string.

You can use the Page HTML Body Attribute to write into the contents of the opening BODY tag. A typical page template might use #ONLOAD# within the opening <body> tag as shown in the following example:

<html>
<head>
...
</head>
<body #ONLOAD# >

Security

Use these attributes to specify an authorization scheme for the current page and indicate whether the page requires an authentication method.

From the Authorization Scheme list, select an authorization scheme to be applied to the page. Authorization schemes are defined at the application level and can be applied to many elements within the application. A given authorization scheme is evaluated either once for each application session (at session creation), or once for each page view. If the selected authorization scheme evaluates to true, then the page displays and is subject to other defined conditions. If it evaluates to false, then the page will not display and an error message displays.

From the Authentication list, specify whether this page has been defined as public or requires authentication. If a page is identified as public, the page can be viewed before authentication. This attribute only applies if the application uses SCHEME authentication. The application's page sentry function may access this page attribute to identify pages that do not require prior authentication to view. The implementation of the authentication scheme's page sentry function determines whether this attribute has any effect.

Duplicate Page Submission Checks

Use the Allow duplicate page submissions list to specify whether Oracle HTML DB enables users to process a page multiple times in a row. Set this attribute to No to prevent duplicate page submissions from being processed multiple times.

Examples of duplicate page submissions include:

  • A user clicks the Submit button multiple times

  • You create a branch of type Branch to Page and the user clicks the browser reload button

Configuration Management

Build options allow you to enable or disable functionality. Most application attributes have a build option attribute. Do not specify a build option unless you plan on excluding that object from specific installations.

Build options have two possible values: INCLUDE and EXCLUDE. If you specify an attribute as being included, then the HTML DB engine considers it part of the application definition at runtime. Conversely, if you specify an attribute as being excluded, then the HTML DB engine treats it as if it does not exist

On Error Text

Use this attribute to specify the error text that displays in the #NOTIFICATION_MESSAGE# substitution string in the event of an error occurring on the page.


See Also:

"Page Templates"

Page Help Text

Use this attribute to enter help text for the current page. Page level help supports shortcuts using the following syntax:

"SHORTCUT_NAME"

Help text is displayed using a help system that you must develop. To show the help for a specific page, call the HTMLDB_APPLICATION.HELP procedure from a page that you create for displaying help text. For example, you could use a navigation bar icon similar to:

f?p=4000:4600:&SESSION::&DEBUG::LAST_STEP:&APP_PAGE_ID

Comments

Use this attribute to record developer comments about the current page. These comments never display when the application is running.

Understanding Page Rendering Controls

Use the Page Rendering section of the Page Definition to specify attributes for defined regions, buttons, items, page rendering computations, and page processes.

Topics in this section include:

Regions

A region is a section of a page that serves as a container for content within a page. The content of a region is determined by the region source. For example, a region may contain a report based on a SQL query you define, or it may contain static HTML.


See Also:


Buttons

As you design your application you can use buttons to direct users to a specific page or URL, or to post or process information. Buttons can be placed in predefined region template positions or among items in a form.

Items

An item can be a text field, text area, password, combobox, check box, and so on. Item attributes affect the display and behavior of items on a page. For example, these attributes can impact where a label displays, how large an item will be, and whether the item will display next to, or below, the previous item.

There are two types of items, page items and application items. Page items are placed on a page and have associated user interface properties, such as Display As, Label, and Label Template. Application items are not associated with a page and therefore have no user interface properties. An application item can be used as a global variable.


See Also:

"Creating Items"

Page Computations

You can use computations to assign a value to an identified item when a page is submitted or displayed. You can also use application level computations to assign values to items. Most application level computations are performed for every page in an application. In contrast, computations created at the page level only execute when that page is rendered or processed.

Page Processes

You create a page process to execute some logic (for example, using PL/SQL), or to make a call to the rendering engine. Typically a process performs an action. For example, a process may be hand coded PL/SQL, or the invocation of a predefined process available within Oracle HTML DB.

A page process is a unit of logic that runs when a specific event occurs, such as loading or submitting page. From a functional perspective, there is no difference between page level and application level processes. The difference lies in the point at which the process occurs.

Understanding Page Processing Controls

Use the Page Processing section of the Page Definition to specify application logic such as computations, validations, processes, and branching. In general, the HTML DB engine runs this logic in the order it appears on the Page Definition.

Understanding Validations

You can define a validation declaratively by selecting a built-in validation type or by entering custom SQL or PL/SQL. You enter the actual validation edit check in the Validation Messages field. Be aware that if a validation fails, subsequent page processing does not occur. Also remember that the validation you enter must be consistent with validation type you selected. For more information on validation types, see online help.

Creating a Validation

To create a new validation:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Validations, click the Create icon.

  3. When the Create Validations Wizard appears, follow the on-screen instructions.

    Validations Types are divided into two categories:

    • Item. These validations start with the phrase "Item" and provide common checks you may want to perform on the item that the validation is associated with.

    • Code. These validations require you provide either PL/SQL code or a SQL query that defines the validation logic. Use this type of validation to perform custom validations that require verifying values of more than one item or accessing additional database tables.

  4. Follow the on-screen instructions.


Note:

Validations may not contain more than 3,950 characters.

Defining How Validation Error Messages Display

You can choose to have validation error messages display inline (that is, on the page where the validation is performed) or on a separate error page.

To define how a validation error message displays:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page".)

  2. Under Validations, select the appropriate validation.

    The attributes page for the validation appears.

  3. Scroll down to Error Messaging.

  4. In Error Message, enter your error message text.

  5. From Error message display location, select a display location.

    This attribute identifies where a validation error message displays. Validation error messages can display on an error page or inline within the existing page. Inline error messages can display in a notification area (defined as part of the page template) or within the field label.

    To create a hard error that stops processing of any remaining validations, you must display the error on an error page.

  6. If you select Inline with Field or Inline with Field and in Notification, you need to associate an item with the error message. To associate an item with the error message, select the item from the Associated Item list.

  7. Click Apply Changes.

Processing Validations Conditionally

You can control when and if a validation is performed under Conditional Validation Processing. To have a validation performed when a user clicks a button, make a selection from the When Button Pressed list.

You can add other conditions by making a selection from the Condition Type list and entering text in the expression fields.

Understanding Branching

A branch is an instruction to go to a specific page, procedure, or URL. For example you can branch from page 1 to page 2 after page 1 is submitted.

You create a new branch by running the Create Page Branch Wizard and specifying Branch Point and Branch Type. The Branch Type defines the type of branch you are creating. For more information on Branch Types, see online help.

Defining a Branch Point and Branch Action

You specify when a branch executes by making a selection from the Branch Point list. Valid options include:

  • On Submit: Before Computation - Occurs before computations, validations, or processing. Use this option for buttons that do not need to invoke any processing, for example, a Cancel button.

  • On Submit: Before Validation - Occurs after computations, but before validations or processing. If a validation fails, page processing stops, a rollback is issued, and the page displays the error. Because of this default behavior, you do not need to create branches to accommodate validations. However, you may want to branch based on the result of a computation (for example, to a previous branch point).

  • On Submit: Before Processing - Occurs after computations and validations, but before processing. Use this option to branch based on a validated session state, but before performing any page processing.

  • On Submit: After Processing - Occurs after computations, validations, and processing. This option branches to a URL or page after performing computations, validations, and processing. When using this option, remember to sequence your branches if you have multiple branches for a given branch point.

  • On Load: Before Header - Occurs before a page is rendered. This option displays another page instead of the current page or redirects the user to another URL or procedure.

Depending upon the Branch Type you select, you can specify the following additional information in Branch Action attributes:

  • The page number of the page you wish to branch to

  • PL/SQL procedure which ultimately renders a branch target page

  • A URL address

Branching Conditionally

Like other controls, branches can be made conditional. To create a conditional branch, make a selection from the Condition Type list and enter text in the expression fields to implement the condition type you choose.

Creating a Page Computation

You create a page computation by running the Create Page Computation Wizard. For each computation, specify the item for which you are creating the computation as well as a computation type.

To create a page computation:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Computations, click the Create icon.

  3. Select a category.

  4. Follow the on-screen instructions.

Editing Computation Attributes

You can edit how a computation works on the Edit Page Computation page. To access the Edit Page Computation page, navigate to the Page Definition and select the computation name.

Defining a Computation Point and Computation Source

You control when a computation executes under Firing Points attributes by specifying a sequence number and a computation point. The computation point On New Instance executes the computation when a new session (or instance) is generated.

Under Computation Source, enter an expression or query to compute an item's value. In the event a computation fails, you can optionally define an error message in Computation Error Message field.

Creating Conditional Computations

You can make a computation conditional by making a selection from the Condition Type list and entering text in the expression fields.

Creating a Page Process

You create a process by running the Create Process Wizard. During the wizard, you define a process name, specify a sequence, the point at which process will execute, and select a process category. You can change nearly all of these attributes on the Edit Page Process page.


See Also:

"Page Processes"

To create a new process:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Processes, click the Create icon.

  3. Select a category. Table 7-11 describes available page process categories.

    Table 7-11 Process Categories

    Process Category Description
    Data Manipulation Oracle HTML DB supports the following declarative data manipulation processes:
    • Select Automatic Row Fetch and Automatic Row Processing (DML) to create an automatic DML (Data Manipulation Language) process

    • Use Multi Row Update and Multi Row Delete in conjunction with tabular forms.

    • Use Add Rows to Tabular Form in conjunction with a tabular form

    Form Pagination Implements pagination through the detail records associated with a master detail form. This process check the master table to determine which set of detail records you are in and determines what the next detail record should be.

    See Also: "Building a Master Detail Form"

    On Demand Creates an application level process that can only be executed when called from a specific page. When you create this process type at the page level, it creates a procedure that calls a previously defined On Demand procedure from the application level.
    PL/SQL Runs the PL/SQL you provide. Use this process type to execute a block of PL/SQL entered directly into the process or to simply call an existing API.
    Report Pagination Resets pagination back to the first result set. The HTML DB engine keeps track of where the user is within a given result set. This process category returns the user to the beginning result set. In other words, this category resets the counters associated with the report region to return the first part of the result set the next time the result set displays.
    Session State Sets the values of existing session state items to null. Select this process type to clear the cache for applications, sessions, or items as well as to clear existing user preferences.

    See Also: "Managing Session State Values" and "Managing User Preferences"

    Web Services Implements a Web Service as a process on a page. Running the process submits a request to the service provider.

    See Also: "Invoking a Web Service as a Process"


  4. Follow the on-screen instructions.

Editing Process Attributes

Once you create a process you can control when the process executes and what the process does by editing attributes on the Edit Page Process page.

To edit an existing page process:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Select the process name.

    The Edit Page Process page appears.

Changing Processing Points and Source

You control when a process executes by specifying a sequence number and a process point under Process Firing Point. You can prevent a process from running during subsequent visits to a page by selecting one of the following options under Run Process:

  • Once for each page visit

  • Once for each session or when reset

Enter the appropriate code for PL/SQL process types. For PL/SQL anonymous block processes, enter the appropriate code under Process. For Clear Cache processes, enter the appropriate code under Source. In the event a process fails, you can optionally define an error message in the Process Error Message field.

Creating Conditional Processes

You can make a process conditional by selecting a condition type and entering an expression under Conditional Processing.

Additionally, you can also make a selection from the When Button Pressed attribute. When you select a button from this list, the process only executes if a user clicks the selected button.

Working with Shared Components

You can use the tools and wizards on the Shared Components page either at the application level, or on specific pages. Examples of shared components include logic controls (build options, computations, processes), shared navigation and user interface elements (menus, lists, tabs, lists of values, templates) and authentication and authorization schemes.

Accessing Shared Components

To access the Shared Components page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Shared Components.

    The Shared Components page appears. Shared components are grouped into the following categories:

  4. To create a shared component, select the appropriate link and follow the on-screen instructions.

Logic

Logic contains links to tools for creating and managing application level logic controls such as build options, computations, items, processes, and Web services. Table 7-12 describes the options available under Logic.

Table 7-12 Shared Components - Logic

Shared Component Description
Build Options Use build options to conditionally display or process specific functionality within an application. You can use build options to control which features of an application are turned on for each application deployment. If you specify a build option at the application level, you do not need to specify it for each component (for example, for each page, branch, button, item, or tab).

See Also: "Using Build Options to Control Configuration"

Computations Use application level computations to assign values to application and page level items for each page displayed or for a new page instance.

You can also create an application level computation and execute it conditionally on multiple pages.

Items Application level items do not display, but are used as global variables to the application. You set the value of a page level item using an application or page computations. Use the ON_NEW_INSTANCE computation to set a value.

See Also: "Creating Items"

Processes Use application processes to run PL/SQL logic:
  • At specific points for each page in the application

  • As defined by the conditions under which the process is set to execute

  • Upon the create of a new session

Note that On Demand processes executes only when called from specific pages.

Web Services Web services in Oracle HTML DB are based on SOAP (the Simple Object Access Protocol). You can create a reference to a Web service and then incorporate it into an application to process data submitted by a form, or to render output in the form.

See Also: "Implementing Web Services"


Navigation

Contains links to tools for creating and managing lists, menus, navigation bars, tabs, and trees. Table 7-13 describes the available options under Navigation.

Table 7-13 Shared Components - Navigation

Shared Component Description
Lists A list is a shared collection of links. You control the appearance of a list through list templates. Each list element has a display condition which enables you to control when it displays.

See Also: "Creating Lists"

Menus A menu is a hierarchical list of links that displays using templates. You can display menus as a list of links, or as a breadcrumb path.

See Also: "Creating Menus"

Navigation Bar Navigation bars offer users a simple navigation path for moving between pages in an application. The location of a navigation bar depends upon the associated page template. A navigation bar icons can display as a link from an image or text. A navigation bar entry can be an image, an image with text beneath it, or text.

See Also: "Creating a Navigation Bar"

Tabs Tabs are an effective way to navigate users between pages in an application. You can create two types of tabs: standard tabs or parent tabs. A standard tab set is associated with a specific page and page number. A parent tab set functions as a container to hold a group of standard tabs.

See Also: "Creating Tabs"

Trees A tree is an effective way to communicate hierarchical or multiple level data.

See Also: "Creating Trees"


Security

Contains links to the Authentication and Authorization pages. You provide security for your application through authentication and authorization. Authentication is the process of establishing users' identities before they can access an application. Authorization controls user access to specific controls or components based on predefined user privileges.

User Interface

Contains links to tools for creating and managing lists of values, shortcuts, and templates. Table 7-14 describes the available options under User Interface.

Table 7-14 Shared Components - User Interface

Shared Component Description
Lists of Values A list of values (LOV) is a static or dynamic definition used to display a popup list of values, select list, check box, or radio group.

See Also: "Creating Lists of Values"

Shortcuts When you create a shortcut, you define frequently used HTML in a central repository so you can later references it in various locations within your application.

See Also: "Utilizing Shortcuts"

Themes and Templates Templates control the look and feel of the page in your application.

See Also: "About Themes and Templates" and "Customizing Templates"


Translations

Contains links to the tools for translating applications developed in Oracle HTML DB. You can develop applications in Oracle HTML DB that can run concurrently in different languages. A single Oracle database and Oracle HTML DB instance can support multiple database sessions customized to support different languages. Table 7-15 describes the available options under Translations.

Table 7-15 Shared Components - Translations

Shared Component Description
Translation Services Translate an application. To translate an application, you must map the primary and target application IDs, seed and export text to a translation file, translate the text, and then apply and publish the translation file.
Manage Messages Translate messages. Messages are named text strings that can be called from PL/SQL code you write. This PL/SQL can be anonymous blocks within page processes and page regions, or in packages and procedures.

Files

Contains links to repositories for uploading and managing style sheets, images, and static files.

About Themes and Templates

The HTML DB engine constructs the appearance of an application using themes. A theme is a named collection of templates that defines the application user interface.

Each theme contains templates for every type of application component and page control, including individual pages, regions, reports, lists, labels, menus, buttons, and list of values. Templates contain HTML and variables that the HTML DB engine substitutes with dynamic values at runtime. The primary advantage of themes is that you can manage the appearance of components and controls in one central location.

How Themes and Page Templates Effect User Interface

The HTML DB engine creates the user interface of an application based on a named collection of templates called a theme. Each templates contains HTML and variables that the HTML DB engine substitutes at runtime with dynamic values. By using themes, you can manage the appearance of your application user interface in one central location.

You can also override the default page level template on a page by page basis. An application can have any number of page templates. If you do not specify a template, the HTML DB engine uses the default template specified in the current theme.

Viewing Application Reports

Application Builder includes a number of reports to help you better manage your application.

To access application reports:

  1. Navigate to the Workspace home page.

  2. Select an application name from the Applications list.

  3. From the Tasks list, select View Application Reports.

    Application Reports page appears. Reports are categorized as follows:

    • Shared Component Reports

    • Page Component Reports

    • Activity Reports

  4. Select a report to review.


See Also:

"Viewing Application and Schema Reports" for information on other reports that are available to all developers

About the Database Object Dependencies Report

The Database Object Dependencies report identifies database objects referenced by the current application.

To view the Database Object Dependencies report:

  1. Navigate to the Workspace home page.

  2. Select an application name from the Applications list.

  3. From the Tasks list, select View Application Reports.

    Application Reports page appears.

  4. Under Shared Component Reports, select Database Object Dependencies.

  5. To view the components that reference a specific database object, select the Reference Count number.

About the Region Source Report

Use the Region Source report to search through all region source in your application.

To view the Region Source report:

  1. Navigate to the Workspace home page.

  2. Select an application name from the Applications list.

  3. From the Tasks list, select View Application Reports.

    Application Reports page appears.

  4. Page Component Reports, select Region Source.

  5. To view the components that reference a specific database object, select the Reference Count number.

PKgzv:? & PK(oUIOEBPS/preface.htmo Preface

Preface

Oracle HTML DB User's Guide describes how to use the Oracle HTML DB development environment to build and deploy database-centric Web applications. Oracle HTML DB turns a single Oracle database into a shared service by enabling multiple workgroups to build and access applications as if they were running in separate databases.

This preface contains these topics:

Audience

Oracle HTML DB User's Guide is intended for application developers who are building database-centric Web applications using Oracle HTML DB. The guide describes how to use the Oracle HTML DB development environment to build, debug, manage, and deploy applications.

To use this guide, you need to have a general understanding of relational database concepts as well as an understanding of the operating system environment under which you are running Oracle HTML DB.

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For additional information, visit the Oracle Accessibility Program Web site at

http://www.oracle.com/accessibility/

Accessibility of Code Examples in Documentation

JAWS, a Windows screen reader, may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, JAWS may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.

Structure

This document contains:

Part I, "Getting Started with Oracle HTML DB"

Part I provides an introduction to Oracle HTML DB by introducing you to basic Oracle HTML DB concepts.

Chapter 1, "What is Oracle HTML DB?"

This section offers a general description of Oracle HTML DB and the components you can use it to develop database-centric Web applications.

Chapter 2, "Quick Start"

This section offers a quick introduction to using Oracle HTML DB.

Chapter 3, "Running a Demonstration Application"

This section describes how to run a demonstration application and defines fundamental concepts that are unique to Oracle HTML DB.

Part II, "Using Oracle HTML DB"

Part II describes how to use Data Workshop, SQL Workshop, and Application Builder to develop database-driven applications.

Chapter 4, "Managing Data with Data Workshop"

This section describes how to use Data Workshop to import data into and export data using a Web Browser.

Chapter 5, "Managing Database Objects with SQL Workshop"

This section provides information on how to use SQL Workshop to view and manage database objects, create and manage user interface defaults, and browse the data dictionary.

Chapter 6, "Application Builder Concepts"

This section provides basic conceptual information about Application Builder, the core component within Oracle HTML DB that enables you to build database centric Web applications.

Chapter 7, "Using Application Builder"

This section provides important background information about using Application Builder.

Chapter 8, "Building an Application"

This section describes how to use Application Builder to build an application and application components.

Chapter 9, "Controlling Page Layout and User Interface"

This section describes different approaches to customizing an application's user interface and page layout including customizing regions, editing item attributes, customizing templates, and incorporating cascading style sheets and images.

Chapter 10, "Adding Navigation"

This section describes how to implement navigation in your application using different types of navigation controls, including navigation bars, tabs, menus, lists, and trees.

Chapter 11, "Debugging an Application"

This section describes a approaches to debugging your application including viewing Debug Mode, enabling SQL tracing, viewing page reports, and how to manually remove a controls to isolate a problem.

Chapter 12, "Deploying an Application"

This section describes how move an application from one Oracle HTML DB instance to another.

Chapter 13, "Managing a Development Workspace"

This section describes different user roles and common tools and reports available to developers and Workspace administrators.

Chapter 14, "Managing Security"

This section describes how to provide security for your application through authentication and authorization.

Chapter 15, "Advanced Programming Techniques"

This section provides information about advanced programming techniques including establishing database links, using collections, running background SQL, implementing Web Services and managing user preferences.

Chapter 16, "Managing Globalization"

This section describes how to translate an application created in Oracle HTML DB.

Chapter 17, "Oracle HTML DB APIs"

This chapter describes available Oracle HTML DB APIs.

Part III, "Administration"

Part III describes the tasks associated with administering Oracle HTML DB, including creating and managing workspaces, translating an application, and managing activities, log files, and sessions.

Chapter 18, "Managing an Oracle HTML DB Hosted Service"

This section describes tasks an Oracle HTML DB administrator performs when administering an Oracle HTML DB hosted service.

Appendix A, "Available Conditions"

Provides a listing of conditions available in Oracle HTML DB.

Related Documents

For more information, see these Oracle resources:

Printed documentation is available for sale in the Oracle Store at

http://oraclestore.oracle.com/

To download free release notes, installation documentation, white papers, or other collateral, please visit the Oracle Technology Network (OTN). You must register online before using OTN; registration is free and can be done at

http://otn.oracle.com/membership/

If you already have a username and password for OTN, then you can go directly to the documentation section of the OTN Web site at

http://otn.oracle.com/documentation/

Conventions

This section describes the conventions used in the text and code examples of this documentation set. It describes:

Conventions in Text

We use various conventions in text to help you more quickly identify special terms. The following table describes those conventions and provides examples of their use.

Convention Meaning Example
Bold Bold typeface indicates terms that are defined in the text or terms that appear in a glossary, or both. When you specify this clause, you create an index-organized table.
Italics Italic typeface indicates book titles or emphasis. Oracle Database Concepts

Ensure that the recovery catalog and target database do not reside on the same disk.

UPPERCASE monospace (fixed-width) font Uppercase monospace typeface indicates elements supplied by the system. Such elements include parameters, privileges, datatypes, Recovery Manager keywords, SQL keywords, SQL*Plus or utility commands, packages and methods, as well as system-supplied column names, database objects and structures, usernames, and roles. You can specify this clause only for a NUMBER column.

You can back up the database by using the BACKUP command.

Query the TABLE_NAME column in the USER_TABLES data dictionary view.

Use the DBMS_STATS.GENERATE_STATS procedure.

lowercase monospace (fixed-width) font Lowercase monospace typeface indicates executable programs, filenames, directory names, and sample user-supplied elements. Such elements include computer and database names, net service names and connect identifiers, user-supplied database objects and structures, column names, packages and classes, usernames and roles, program units, and parameter values.

Note: Some programmatic elements use a mixture of UPPERCASE and lowercase. Enter these elements as shown.

Enter sqlplus to start SQL*Plus.

The password is specified in the orapwd file.

Back up the datafiles and control files in the /disk1/oracle/dbs directory.

The department_id, department_name, and location_id columns are in the hr.departments table.

Set the QUERY_REWRITE_ENABLED initialization parameter to true.

Connect as oe user.

The JRepUtil class implements these methods.

lowercase italic monospace (fixed-width) font Lowercase italic monospace font represents placeholders or variables. You can specify the parallel_clause.

Run old_release.SQL where old_release refers to the release you installed prior to upgrading.


Conventions in Code Examples

Code examples illustrate SQL, PL/SQL, SQL*Plus, or other command-line statements. They are displayed in a monospace (fixed-width) font and separated from normal text as shown in this example:

SELECT username FROM dba_users WHERE username = 'MIGRATE';

The following table describes typographic conventions used in code examples and provides examples of their use.

Convention Meaning Example
[ ]
Anything enclosed in brackets is optional.
DECIMAL (digits [ , precision ])
{ }
Braces are used for grouping items.
{ENABLE | DISABLE}
|

A vertical bar represents a choice of two options.
{ENABLE | DISABLE}
[COMPRESS | NOCOMPRESS]
...
Ellipsis points mean repetition in syntax descriptions.

In addition, ellipsis points can mean an omission in code examples or text.

CREATE TABLE ... AS subquery;

SELECT col1, col2, ... , coln FROM employees;
Other symbols You must use symbols other than brackets ([ ]), braces ({ }), vertical bars (|), and ellipsis points (...) exactly as shown.
acctbal NUMBER(11,2);
acct    CONSTANT NUMBER(4) := 3;
Italics
Italicized text indicates placeholders or variables for which you must supply particular values.
CONNECT SYSTEM/system_password
DB_NAME = database_name
UPPERCASE
Uppercase typeface indicates elements supplied by the system. We show these terms in uppercase in order to distinguish them from terms you define. Unless terms appear in brackets, enter them in the order and with the spelling shown. Because these terms are not case-sensitive, you can use them in either UPPERCASE or lowercase.
SELECT last_name, employee_id FROM employees;
SELECT * FROM USER_TABLES;
DROP TABLE hr.employees;
lowercase
Lowercase typeface indicates user-defined programmatic elements, such as names of tables, columns, or files.

Note: Some programmatic elements use a mixture of UPPERCASE and lowercase. Enter these elements as shown.

SELECT last_name, employee_id FROM employees;
sqlplus hr/hr
CREATE USER mjones IDENTIFIED BY ty3MU9;

Conventions for Windows Operating Systems

The following table describes conventions for Windows operating systems and provides examples of their use.

Convention Meaning Example
Choose Start > menu item How to start a program. To start the Database Configuration Assistant, choose Start > Programs > Oracle - HOME_NAME > Configuration and Migration Tools > Database Configuration Assistant.
File and directory names File and directory names are not case-sensitive. The following special characters are not allowed: left angle bracket (<), right angle bracket (>), colon (:), double quotation marks ("), slash (/), pipe (|), and dash (-). The special character backslash (\) is treated as an element separator, even when it appears in quotes. If the filename begins with \\, then Windows assumes it uses the Universal Naming Convention. c:\winnt"\"system32 is the same as C:\WINNT\SYSTEM32
C:\> Represents the Windows command prompt of the current hard disk drive. The escape character in a command prompt is the caret (^). Your prompt reflects the subdirectory in which you are working. Referred to as the command prompt in this manual.
C:\oracle\oradata>
Special characters The backslash (\) special character is sometimes required as an escape character for the double quotation mark (") special character at the Windows command prompt. Parentheses and the single quotation mark (') do not require an escape character. Refer to your Windows operating system documentation for more information on escape and special characters.
C:\> exp HR/HR TABLES=emp QUERY=\"WHERE job='REP'\"
HOME_NAME
Represents the Oracle home name. The home name can be up to 16 alphanumeric characters. The only special character allowed in the home name is the underscore.
C:\> net start OracleHOME_NAMETNSListener
ORACLE_HOME and ORACLE_BASE In releases prior to Oracle8i release 8.1.3, when you installed Oracle components, all subdirectories were located under a top level ORACLE_HOME directory. The default for Windows NT was C:\orant.

This release complies with Optimal Flexible Architecture (OFA) guidelines. All subdirectories are not under a top level ORACLE_HOME directory. There is a top level directory called ORACLE_BASE that by default is C:\oracle\product\10.1.0. If you install the latest Oracle release on a computer with no other Oracle software installed, then the default setting for the first Oracle home directory is C:\oracle\product\10.1.0\db_n, where n is the latest Oracle home number. The Oracle home directory is located directly under ORACLE_BASE.

All directory path examples in this guide follow OFA conventions.

Refer to Oracle Database Installation Guide for 32-Bit Windows for additional information about OFA compliances and for information about installing Oracle products in non-OFA compliant directories.

Go to the ORACLE_BASE\ORACLE_HOME\rdbms\admin directory.

PKЌo5poPK(oUIOEBPS/darbbook.css*/* ========================================================================== */ /* darbbook.css */ /* Release 0.0.1 */ /* Last revision 02/07/03 */ /* 2003, Oracle Corporation. All rights reserved. */ /* ========================================================================== */ /* This is not intended to be a stand-along CSS. Instead, it cascades on */ /* top of the BLAF CSS, providing minimal changes to the existing styles */ /* in BLAF, while defining further styles for DARB-specific classes. */ /******************************************************************************/ /* BLAF Overrides/Additions */ /******************************************************************************/ /* First, we need a couple tweaks to the BLAF CSS. */ /* H4 needs to be weight BOLD, as "normal" is too light for accessibility */ H4 { font-weight:bold; } /* BLAF doesn't include styles for H5/H6, so we'll include them. Same */ /* Font family as H1-H4, just slightly smaller and BOLD as well. */ H5, H6 { font-family: Arial, Helvetica, Geneva, sans-serif; color:#336699; background-color : #FFFFFF; } H5 { font-size: 0.9em; font-weight: bold; } H6 { font-size: 0.7em; font-weight: bold; } /* Loose the H1 underscore */ H1 { border-width : 0px 0px 0px 0px; } /* BLAF doesn't provide much contrast between links and visited links */ /* so we'll add a little red to increase contrast. */ A:visited { color : #AA3300; background-color : #FFFFFF; } /******************************************************************************/ /* DARB-specific formats */ /******************************************************************************/ .bold { font-weight: bold; } .italic { font-style: italic; } .bolditalic { font-weight: bold; font-style: italic; } .codeinlinebold { font-weight: bold; } .codeinlineitalic { font-style: italic; } .codeinlineboldital { font-weight: bold; font-style: italic; } .syntaxinlinebold { font-weight: bold; } .syntaxinlineitalic { font-style: italic; } .syntaxinlineboldital { font-weight: bold; font-style: italic; } .bridgehead { font-family: Arial, Helvetica, Geneva, sans-serif; color:#336699; background-color : #FFFFFF; font-weight: bold; } .term, .glossterm { font-weight: bold; } .glossaryterm { font-weight: bold; } .keyword { font-weight: bold; } .variable { font-style: italic; } .msg, .msgexplankw, .msgactionkw { font-weight: bold; } .underline { text-decoration: underline; } .superscript { vertical-align: super; } .subscript { vertical-align: sub; } .listofeft { border: none; } .titleinfigure, .titleinexample, .titleintable, .titleinequation { font-weight: bold; font-style: italic; } .subhead1, .subhead2, .subhead3 { font-family: Arial, Helvetica, Geneva, sans-serif; color: #336699; background-color : #FFFFFF; font-weight: bold; } .subhead1 { font-size:1.1em; } .subhead2 { font-size:1.0em; } .subhead3 { font-size:0.9em; display: inline; } /* When lists are inside tables, they need to be more "compact" so they don't */ /* spread the table out. We need to suppress the natural line break in the */ /* para element for "paras inside a list item inside a table data" */ td li p { display: inline; } TD.copyrightlogo { text-align:center; font-size: xx-small; } SPAN.copyrightlogo { text-align:center; font-size: xx-small; } IMG.copyrightlogo { border-style:none; } p.betadraftsubtitle { text-align:center; font-weight:bold; color:#FF0000; } .betadraft { color:#FF0000; } .comment { color:#008800; } PK*/*PK(oUIOEBPS/intro.htm5 What is Oracle HTML DB?

1 What is Oracle HTML DB?

The section offers a general description of Oracle HTML DB and the components you can use to develop database-centric Web applications.

This section contains the following topics:

About Oracle HTML DB

Oracle HTML DB is a hosted declarative development environment for developing and deploying database-centric Web applications. Oracle HTML DB turns a single Oracle database into a shared service by enabling multiple workgroups to build and access applications as if they were running in separate databases. Thanks to built-in features such as design themes, navigational controls, form handlers, and flexible reports, Oracle HTML DB accelerates the application development process.

The HTML DB engine renders applications in real time from data stored in database tables. When you create or extend your application, Oracle HTML DB creates or modifies metadata stored in database tables. When the application is run, the HTML DB engine then reads the metadata and displays the application.

Oracle HTML DB automatically maintains session state without requiring any coding. To provide stateful behavior within an application, Oracle HTML DB transparently manages session state in the database. Application developers can get and set session state using simple substitutions as well as standard SQL bind variable syntax.

The Oracle HTML DB development platform consists of the following components:

About Application Builder

You use Application Builder to assemble an HTML interface (or application) on top of database objects such as tables and procedures. An application is a collection of database-driven Web pages linked together using tabs, buttons, or hypertext links. Once you create an application, the HTML DB engine renders the application using the templates and user interface elements you specify.

A page is the basic building block of an application. Each page can have buttons and fields and can include application logic (or processes). You can branch from one page to the next using conditional navigation, perform calculations, run validations (such as edit checks), and display reports, forms, and charts.

About SQL Workshop

You use SQL Workshop to view and manage database objects from a Web browser. Using SQL Workshop you can store and retrieve data, execute SQL commands, and perform the following tasks:

About Data Workshop

You use Data Workshop to import data into and export data from the hosted database. Supported import formats include text (such as comma or tab delimited data), XML documents, and spreadsheets. Supported export formats include text (such as comma or tab delimited data) and XML documents.

For example, you can quickly share data with multiple users by converting a spreadsheet into a database table using the Import Spreadsheet Data Wizard. Running this wizard creates a new table and loads the data without requiring any SQL knowledge. Once the data is loaded into a database table, you can build a application on top of it just like you would on any other database table.

PKBuPK(oUIOEBPS/global.htm Managing Globalization

16 Managing Globalization

This section describes how to translate an application built-in Oracle HTML DB.

This section contains the following topics:

About Translating an Application and Globalization Support

In Oracle HTML DB you can develop applications that can run concurrently in different languages. A single Oracle database instance and Oracle HTML DB can support multiple database sessions customized to support different language.

In general, translating an Oracle HTML DB application involves the following steps:

Topics in this section include:

About Language Identification

After you create an application, you specify a language preference on the Edit Application Attributes page. Under Globalization, you select a primary application language and select how the HTML DB engine determines the application language. You can specify to have the application language based on the user's browser language preference, an application preference, or an item preference.

Rule for Translating Applications in Oracle HTML DB

When using translated applications in Oracle HTML DB, use the following rules to determine which translated version to use:

  • Look for an exact match between the user language preference and the language code of the translated application

  • Look for a truncated match. That is, see if the language and locale exist. For example, if the user language preference is en-us and the translated version of en-us does not exist, look for a translated application that has the language code en

  • Use the primary application

For example, suppose you create an application with the primary language of German, de, and you create a translated version of the application with a language code of en-us. Users accessing this application with a browser language of en-us execute the English en-us version of the application. Users accessing the application with a browser language of en-gb view the application in the application primary language. In this example, these users see the application in German, which is the application's primary language. For this example, you should create the translated English version using language code en to encompass all variations of en.

How Translated Applications Are Rendered

Once Oracle HTML DB determines the language for an application, the HTML DB engine alters the database language for a specific page request. It then looks for a translated application in the appropriate language. If the HTML DB engine finds that language, it render the application using that definition. Otherwise, it renders the application in the base (or primary) application language.

Note that the text that displays within an application is not translated on the fly. Oracle HTML DB dynamically collects page attributes from either a base language application definition or an alternative application definition.

About Translatable Components

When you build an application in Oracle HTML DB, you define a large number of declarative attributes such as field labels, region headings, page header text, and so on. Using the steps described in this chapter, you can make all the application definition attributes within your application translatable.

About Shortcuts that Support Translatable Messages

Oracle HTML DB includes two shortcuts type that enable you to reference translatable messages:

  • Message - Use this shortcut to reference a translatable message at runtime. Note that the name of the shortcut must match the corresponding message name. At runtime, the name of the shortcut expands to the text of the translatable message for the current language.

  • Message with JavaScript Escaped Single Quotes - Use this shortcut to reference a shortcut inside of JavaScript literal string and reference a translatable message at runtime. This shortcut defines a text string. When the shortcut is referenced, it escapes the single quotes required for JavaScript.

About Messages

If your application includes PL/SQL regions or PL/SQL processes, you may need to translate any generated HTML or text. Within Oracle HTML DB these types of generated HTML and text are called "messages." You can define all messages and translate them on the Translatable Messages page. You can use the HTMLDB_LANG.MESSAGE API to translate text strings from PL/SQL stored procedures, functions, triggers, packaged procedures and functions.

About Dynamic Translation Text Strings

Dynamic translations are used for database data that needs to be translated at runtime. For example, you might use a dynamic translation to translate a list of values based on a database query. A dynamic translation consists of a "translate-from" language string, a language code, and a "translate-to" string. You can also use the HTMLDB_LANG.LANG API to retrieve dynamic translations programmatically.

About Translating Templates

By default, templates in Oracle HTML DB are not translatable and therefore not included in the generated translation file. Generally, templates do not and should not contain translatable text. However, if you need to mark a template as translatable, mark the Translatable check box on the Edit Page Template page.

To identify a template as translatable:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Shared Components.

  4. Under User Interface, select Templates.

    The Templates page appears.

  5. Locate the template you wish to edit and select the template name.

  6. Under Template Identification, select Translatable.

One way to include translatable text at the application level is to define the translatable text using static substitution strings. Since application level attributes are translated any text defined as a static substitution strings will be included in the generated translation file.

Specifying the Primary Language for an Application

Globalization attributes specify how the HTML DB engine determines the primary language of an application.

To edit Globalization attributes:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. Click the Edit Attributes icon.

    The Edit Application Attributes page appears.

  4. Scroll down to Globalization.

  5. From Application Primary Language, select the language in which the application is being developed.

  6. From Application Language Derived From, specify how the HTML DB engine determines (or derives) the application language. Available options are described in Table 16-1.

    Table 16-1 Application Language Derived From Options

    Option Description
    No NLS (Application not translated) Select this option if the application will not be translated.
    Use Application Primary Language Determines the application primary language based on the Application Primary Language attribute (see step 5).
    Browser (use browser language preference) Determines the application primary language based on the user's browser language preference.
    Application Preference (use FSP_LANGUAGE_PREFERENCE) Determines the application primary language based a value defined using the HTMLDB_UTIL.SET_PREFERENCE API. Select this option to maintain the selected language preference across multiple log ins.

    See Also: "SET_PREFERENCE Procedure"

    Item Preference (use item containing preference) Determines based on an application level item called FSP_LANGUAGE_PREFERENCE. Using this option requires Oracle HTML DB to determine the appropriate language preference every time the user logs in.

Using Format Masks for Items

The HTML DB engine applies Globalization settings for each rendered page. This default behavior can impact the display of certain items such as numbers and dates.

For example, suppose your application determines the application language based on the user's browser language preference. If the HTML DB engine determines the users's browser language preference is French, it displays dates and numbers in a format that conforms to French standards. You can override this default behavior and explicitly control how items display by applying a format mask. You apply a format mask by making a selection from the Display As list:

  • When you create the item

  • After you create the item by editing the item attributes

To edit item attributes

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Items, drill down on the item name.

    The Edit Page Item page appears.

  3. Under Identification, make a select from the Display As list.


See Also:

"Items" for more information on item attributes.

Translating Applications for Multibyte Languages

If your application needs to run in several languages (such as Chinese or Japanese) simultaneously, you should consider configuring your database with a character set to support all of the languages. The same character set has to be configured in the corresponding DAD (Data Access Description) in mod_plsql. UTF8 and AL32UTF8 are the character sets you can use to support almost all languages around the world.

Understanding the Translation Process

To translate an application developed in Oracle HTML DB, you must map the primary and target application IDs, seed and export text to a translation file, translate the text, and then apply and publish the translation file.

Topics in this section include:

Navigating to the Translate Application Page

You perform the translation process on the Translate Application page.

To navigate to the Translate Application page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. Click the Shared Components icon.

  4. Under Translations, select Translation Services.

    The Translate Application page appears.

Mapping Primary and Target Application IDs

The first step in translating an application is to map the primary and target application IDs. The primary application is the application to be translated. The target application is the resulting translated application.

To map the primary and target application IDs:

  1. Navigate to the Translate Application page. (See "Navigating to the Translate Application Page".)

  2. On the Translate Application page, select Map your primary language application to a translated application ID.

    The Application Mappings page appears.

  3. Click Create.

  4. On the Translation Application Mapping page:

    • In Translation Application, type a numeric application ID to identify the target application. The translated application ID must be an integer and cannot end in zero.

    • From Translation Application Language Code, select the language you are translating to.

    • In Image Directory, enter the directory where images will be obtained.

      This attribute determines the virtual path for translated images. For example, if your primary language application had an image prefix of '/images/', you could define additional virtual directories for other languages such as '/images/de/' for German or '/images/es/' for Spanish.

  5. Click Create.

Seeding and Exporting Text to a Translation File

The second step in translating an application is to seed the translation table and then export the translation text to a translation file.

Seeding Translatable Text

To translate a application, you must seed the translations. Seeding the translation copies all translatable text into a translation text repository. Once you have seeded the application and specific language in the translation text repository, you can then generate and export an XLIFF file for translation.

The seeding process keeps your primary language application synchronized with the translation text repository. You should run the seed process any time your primary language application changes.

To seed translatable text:

  1. Navigate to the Translate Application page. (See "Navigating to the Translate Application Page".)

  2. On the Translate Application page, select Seed and export the translation text of your application into a translation file.

  3. From Language Mapping, select the appropriate primary and target application ID map.

  4. Click Seed Translatable Text.

    The XLIFF Export page appears.


    Note:

    XML Localization Interchange File Format (XLIFF) is a XML-based format for exchanging localization data. For more information on the XLIFF, or to view the XLIFF specification see:
    http://www.xliff.org
    

Exporting Text to a Translation File

Once you have seeded translatable text, a status box displays at the top of the XLIFF Export page indicating the total number of attributes that may require translation as well as the number of:

  • Existing updated attributes that may require translation

  • New attributes that may require translation

  • Purged attributes that no longer require translation

You can use this information to determine whether you need to export translatable text for an entire application or just a specific page.

The XLIFF Export page is divided into two sections. Use the upper half of the page to export translatable text for an entire application (that is, all pages, lists of values, messages, and so on). Use the lower section to export translatable text for a specific page.

To export translatable text for an entire application:

  1. Seed the translatable text as described in the previous procedure, "Seeding Translatable Text".

  2. Under Step 2, Export XLIFF:

    • From Application, select the appropriate primary and target application ID map

    • Specify whether to include XLIFF target elements

    • Under Export, specify what translation text is included in your XLIFF file

    • Click Export XLIFF for Application

  3. Follow the on-screen instructions.

To export translatable text for a specific page:

  1. Seed translatable text as described in "Seeding Translatable Text".

  2. Under Export XLIFF for specific Page:

    • From Application, select the appropriate primary and target application ID map

    • Specify whether to include XLIFF target elements

    • Under Export, specify what translation text is included in your XLIFF file

    • Click Export XLIFF for Page

  3. Follow the on-screen instructions.

About Include XLIFF Target Elements

When Oracle HTML DB generates an XLIFF document, each document contains multiple translation units. Each translation unit consists of a source element and a target element. The XLIFF document can be generated with both the source and target elements for each translation unit. You have the option of generating a file containing only source elements. The updated translations will be applied from the target elements of translation units.

About Export

Use Export to specify what translation text is included in your XLIFF file. Select All translatable elements to include all translation text for an application. In contrast, select Only those elements requiring translation to include only new elements that have not yet been translated. Only those elements requiring translation produces an XLIFF file containing new or modified translation units. Also, if translation units were intentionally not previously translated (that is, the source of the translation element equals the target of the translation element), those translation units will also be included in the file.

Translating the XLIFF File

After you export a translatable file to XLIFF format, you can translate it into the appropriate languages. Since XLIFF is an open standard XML file for exchanging translation, most translation vendors should support it. Oracle HTML DB only supports XLIFF files encoded in UTF-8 character sets. In other words, it exports XLIFF files for translation in UTF-8 and assumes that the translated XLIFF files will be in the same character set.

Translation is a time consuming task. Oracle HTML DB supports incremental translation so that application development can be done in parallel with the translation. An XLIFF file can be translated and uploaded to Oracle HTML DB even when only part of the XLIFF file is translated. For strings that have no translation in the corresponding translated application, Oracle HTML DB uses the corresponding ones in the primary language.



Uploading and Publishing a Translated XLIFF Document

Once your XLIFF document has been translated, the next step is to upload it back into Oracle HTML DB.

To upload a translated XLIFF document:

  1. Navigate to the Translate Application page. (See "Navigating to the Translate Application Page".)

  2. On the Translate Application page, select Apply your translation file and publish.

  3. Click Upload XLIFF.

  4. On the XLIFF Upload page:

    • Specify a title

    • Enter a description

    • Click Browse and locate the file to be uploaded

    • Click Upload XLIFF File

    The uploaded document appears in the XLIFF Files repository.

Once you upload an XLIFF document, the next step is to apply the XLIFF document and then publish the translated application. When you apply an XLIFF document, the HTML DB engine parses the file and then updates the translation tables with the new translatable text.

Publishing your application creates a copy of the base language application, substituting the translated text strings from your translations table. This published application can then be used to render your application in alternate languages.

Remember that in order to run an application in an alternative language, you need to run it with Globalization settings that will cause an alternative language version to display. For example, if the language is derived from the browser language, you must set the browser language to the same language as the translated application.


See Also:

For more information on the XLIFF, or to view the XLIFF specification see:
http://www.xliff.org

See Also:

"Specifying the Primary Language for an Application"

To apply and publish a translated XLIFF document:

  1. Navigate to the Translate Application page. (See "Navigating to the Translate Application Page".)

  2. On the Translate Application page, select Apply your translation file and publish.

  3. In the XLIFF Files repository, click the View icon adjacent to the document you wish to publish.

  4. From Apply to, select the appropriate primary and target application ID map.

  5. Click Apply XLIFF Translation File.

  6. Click Publish Application.

To delete an uploaded XLIFF document:

  1. Navigate to the Translate Application page. (See "Navigating to the Translate Application Page".)

  2. On the Translate Application page, select Apply your translation file and publish.

  3. In the XLIFF Files repository, select the check box to the left of the document title.

  4. Click Delete Checked.

You should verify the existence of the translated application once it is published. Translated applications do not display in the Available Applications list on the Application Builder home page. Instead, use the Application Navigate list on the left side of the page.

Note that in order for a translated application to appear in Application Builder, you need to make sure the you have correctly configured the application Globalization attributes.

Translating Messages Used in PL/SQL Procedures

If your application includes PL/SQL regions or PL/SQL processes or calls PL/SQL package, procedures, or functions, you may need to translate generated HTML. First, you define each message on the Translatable Messages page. Second, you use the HTMLDB_LANG.MESSAGE API to translate the messages from PL/SQL stored procedures, functions, triggers, or packaged procedures and functions.

Defining Translatable Messages

You create translatable messages on the Translate Messages page.

To define a new translation message:

  1. Navigate to the Translate Application page. (See "Navigating to the Translate Application Page".)

  2. On the Translate Application page, select Optionally translate messages which are used by PL/SQL procedures and functions.

  3. On the Translate Messages page, click Create.

  4. On the Identify Text Message page:

    • In Name, type a name to identify the text message

    • In Language, select the language for which the message would be used

    • In text, type the text to be returned when the text message is called.

      For example, you could define the message GREETING_MSG in English as:

      Good morning %0
      
      

      Or, you could define the message GREETING_MSG in German as:

      Guten Tag %0
      
      
  5. Click Create.

HTMLDB_LANG.MESSAGE API

Use the HTMLDB_LANG.MESSAGE API to translate text strings (or messages) generated from PL/SQL stored procedures, functions, triggers, packaged procedures and functions.

Syntax

HTMLDB_LANG.MESSAGE (
    p_name    IN    VARCHAR2 DEFAULT NULL,
    p0        IN    VARCHAR2 DEFAULT NULL,
    p1        IN    VARCHAR2 DEFAULT NULL,
    p2        IN    VARCHAR2 DEFAULT NULL,
    ...
    p9        IN    VARCHAR2 DEFAULT NULL,
    p_lang    IN    VARCHAR2 DEFAULT NULL)
    RETURN VARCHAR2;

Parameters

Table 16-2 describes the parameters available in the HTMLDB_LANG.MESSAGE.

Table 16-2 HTMLDB_LANG.MESSAGE Parameters

Parameter Description
p_name Name of the message as defined in Oracle HTML DB.
p0

...

p9

Dynamic substitution value. p0 corresponds to 0% in the message. p1 corresponds to 1% in the message. p2 corresponds to2% in the message and so on.
p_lang Language code for the message to be retrieved. If not specified, Oracle HTML DB uses the current language for the user as defined in the Application Language Derived From attribute.

See Also: "Specifying the Primary Language for an Application"


Example

The following example assumes you have defined a message called GREETING_MSG in your application in English as Good morning%0 and in German as Guten Tag%1. The following example demonstrates how you could invoke this message from PL/SQL:

BEGIN
    --
    -- Print the greeting
    --
    HTMLDB_LANG.MESSAGE('GREETING_MSG', V('APP_USER'));
END;

How p_lang attribute is defined depends on how the HTML DB engine derives the Application Primary Language. For example, if you are running the application in German and the previous call is made HTMLDB_LANG.MESSAGE, the HTML DB engine first looks for a message called GREETING_MSG with a LANG_CODE of de. If it does not find anything, then it will revert to the Application Primary Language attribute. If it still does not find anything, the HTML DB engine looks for a message by this name with a language code of en-us.


See Also:

"Specifying the Primary Language for an Application" for more information on the Application Primary Language attribute

Translating Data that Supports List of Values

You create a dynamic translation to translate dynamic pieces of data. For example, you might use a dynamic translation on a list of values based on a database query.

Dynamic translations differ from messages in that you query a specific string rather then a message name. You define dynamic translations on the Dynamic Translations page. You then use the HTMLDB_LANG.LANG API to return the dynamic translation string identified by the parameter p_primary_text_string.

Defining a Dynamic Translation

You define dynamic translations on the Dynamic Translations page. A dynamic translation consists of a "translate-from" language string, a language code, and a "translate-to" string.

To define a dynamic translation:

  1. Navigate to the Translate Application page. (See "Navigating to the Translate Application Page".)

  2. On the Translate Application page, select Optionally identify any data that needs to be dynamically translated to support SQL based lists of values.

  3. On the Dynamic Translations page, click Create and specify the following:

    • In Language, select a target language

    • In Translate From Text, type the source text to be translated

    • In Translate To, type the translated text

  4. Click Create.

HTMLDB_LANG.LANG API

Syntax

HTMLDB_LANG.LANG (
    p_primary_text_string    IN    VARCHAR2 DEFAULT NULL,
    p0                       IN    VARCHAR2 DEFAULT NULL,
    p1                       IN    VARCHAR2 DEFAULT NULL,
    p2                       IN    VARCHAR2 DEFAULT NULL,
    ...
    p9                       IN    VARCHAR2 DEFAULT NULL,
    p_primary_language       IN    VARCHAR2 DEFAULT NULL)
    RETURN VARCHAR2;

Parameters

Table 16-3 describes the parameters available in the HTMLDB_LANG.LANG.

Table 16-3 HTMLDB_LANG.LANG Parameters

Parameter Description
p_primary_string Text string of the primary language. This will be the value of the Translate From Text in the dynamic translation.
p0

...

p9

Dynamic substitution value. p0 corresponds to 0% in the in the translation string. p1 corresponds to 1% in the in the translation string. p2 corresponds to 2% in the in the translation string and so on.
p_primary_language Language code for the message to be retrieved. If not specified, Oracle HTML DB uses the current language for the user as defined in the Application Language Derived From attribute.

See Also: "Specifying the Primary Language for an Application"


Example

Suppose you have a table that defines all primary colors. You could define a dynamic message for each color and then apply the LANG function to the defined values in a query. For example:

SELECT HTMLDB_LANG.LANG(color)
  FROM my_colors

For example, suppose you were running the application in German andRED was a value for the color column in my_colors table. If you defined the German word for red, the previous example would return ROT.

About Oracle HTML DB Globalization Codes

If you are building a multilingual application, it is important to understand how Oracle HTML DB globalization codes impact the way in which your application runs. These codes are set automatically based on the application level Globalization attributes you select.

NLS_LANGUAGE and NLS_TERRITORY determine the default presentation of number, dates, and currency.

Table 16-4 describes the globalization codes in Oracle HTML DB.

Table 16-4 Oracle HTML DB Globalization Codes

Language Name Language Code NLS_LANGUAGE NLS_TERRITORY
Arabic ar ARABIC
Assamese as ASSAMESE INDIA
Bengali bn BANGLA
Bulgarian bg BULGARIAN BULGARIA
Catalan ca CATALAN CATALONIA
Chinese (China) zh-cn SIMPLIFIED CHINESE CHINA
Chinese (Hong Kong SAR) zh-hk TRADITIONAL CHINESE HONG KONG
Chinese (Singapore) zh-sg SIMPLIFIED CHINESE SINGAPORE
Chinese (Taiwan) zh-tw TRADITIONAL CHINESE TAIWAN
Chinese zh SIMPLIFIED CHINESE CHINA
Croatian hr CROATIAN CROATIA
Czech cs CZECH CZECH REPUBLIC
Danish da DANISH DENMARK
Dutch (Netherlands) nl DUTCH THE NETHERLANDS
English (United States) en-us AMERICAN AMERICA
English en ENGLISH
English en-gb ENGLISH (UNITED KINGDOM)
Estonian et ESTONIAN ESTONIA
Finnish fi FINNISH FINLAND
French (Canada) fr-ca CANADIAN FRENCH CANADA
French (France) fr FRENCH FRANCE
German (Germany) de GERMAN GERMANY
Greek el GREEK GREECE
Gujarati gu GUJARATI
Hebrew he HEBREW ISRAEL
Hindi hi HINDI INDIA
Hungarian hu HUNGARIAN HUNGARY
Icelandic is ICELANDIC ICELAND
Indonesian id INDONESIAN INDONESIA
Italian (Italy) it ITALIAN ITALY
Japanese ja JAPANESE JAPAN
Kannada kn KANNADA INDIA
Korean ko KOREAN KOREA
Latvian lv LATVIAN LATVIA
Lithuanian lt LITHUANIAN LITHUANIANA
Malay (Malaysia) ms MALAY MALAYSIA
Malayalam ml MALAYALAM
Marathi mr MARATHI
Norwegian no NORWEGIAN NORWAY
Oriya or ORIYA
Polish pl POLISH POLAND
Portuguese (Brazil) pt-br BRAZILIAN PORTUGUESE BRAZIL
Portuguese (Portugal) pt PORTUGUESE PORTUGAL
Punjabi pa PUNJABI
Romanian ro ROMANIAN ROMANIA
Russian ru RUSSIAN
Slovak sk SLOVAK SLOVAKIA
Slovenian sl SLOVENIAN SLOVENIA
Spanish es SPANISH SPAIN
Spanish (Mexico) es-mx MEXICAN SPANISH MEXICO
Swedish sv SWEDISH SWEDEN
Tamil ta TAMIL
Telugu te TELUGU
Thai th THAI THAILAND
Turkish tr TURKISH TURKEY
Ukrainian uk UKRAINIAN UKRAINE
Vietnamese vi VIETNAMESE VIETNAM

PK`I##PK(oUIOEBPS/what_new.htm$ What's New in Oracle HTML DB?

What's New in Oracle HTML DB?

This section describes new features of Oracle HTML DB release 1.6 and provides pointers to additional information.

Oracle HTML DB Release 1.6 New Features

PK M"$$PK(oUIOEBPS/demo.htmoI Running a Demonstration Application

3 Running a Demonstration Application

This section describes how to run and modify the demonstration applications that install with Oracle HTML DB. Running and analyzing how an application works is an effective way to better understand how you can use Oracle HTML DB to build your own applications.

This section contains the following topics:

Viewing and Installing a Demonstration Application

Oracle HTML DB installs with a number of demonstration applications. Use these applications to learn more about the different types of functionality you can include in your applications.

To view the demonstration applications included with Oracle HTML DB:

  1. Log in to Oracle HTML DB as described in "Logging in to Oracle HTML DB".

    The Workspace home page appears.

  2. From the Workspace Administration list, select Review Demonstration Applications.

    The Demonstration Applications page appears, displaying links to the following applications:

    • Sample Application offers a working demonstration that highlights basic design concepts

    • Collection Showcase demonstrates shopping cart concepts

    • Web Services serves an example of how you can use Web Services

    • Presidential Inaugural Addresses demonstrates Oracle Text

The Status column indicates whether or not an application is currently installed.

To install a demonstration application:

  1. Navigate to the Demonstration Applications page as described in the previous procedure.

  2. Scroll down to the application you wish to install, click Install.

  3. Follow the on-screen instructions.

Running a Demonstration Application

Oracle HTML DB installs with a number of demonstration applications. Once you have installed a demonstration application you can run it from the Demonstration Application page or from the Workspace home page.

By default, installing Sample Application creates two accounts, demo and admin. The default password for both accounts is the name of the current workspace in lowercase letters.

Running an Application from Demonstration Applications

The simplest way to run a demonstration application is navigate to the Demonstration Applications page.

To run a demonstration application from the Demonstration Applications page:

  1. Log in to Oracle HTML DB as described in "Logging in to Oracle HTML DB".

    The Workspace home page appears.

  2. From the Workspace Administration list, select Review Demonstration Applications.

  3. On the Demonstration Applications page, locate the application you wish to run.

  4. In the Action column, click Run.

  5. Enter the appropriate username and password and click Login

    • For User Name, enter either demo or admin

    • For Password, enter the name of the current workspace using all lowercase letters

Running an Application from the Workspace Home Page

Once you have installed a demonstration application, you can run it from Workspace home page.

To run a demonstration application from the Workspace home page:

  1. Log in to Oracle HTML DB as described in "Logging in to Oracle HTML DB".

    The Workspace home page appears.

  2. Locate the application you wish to run in the Applications list.

  3. Click the Run icon to the right of the application name.

  4. Enter the appropriate username and password and click Login

    1. For User Name, enter one of the following:

      • demo

      • admin

    2. For Password, enter the name of the current workspace using all lowercase letters.

Understanding Sample Application

Each demonstration application features a different set of functionality. This section describes the demonstration application, Sample Application.

As shown in Figure 3-1, Sample Application features an easy-to-use interface for viewing, updating, and searching order and customer information for electronic and computer products. Users can navigate between the pages using the Home, Customers, Products, Orders, and Charts tabs.

Figure 3-1 Sample Application, Home Page

Description of sampl_app_plain.gif follows


Sample Application demonstrates the following functionality:

  • Examples of ways to display summary information, including a dial chart and summary reports

  • Reports for viewing, updating, and adding customers, products, and orders

  • A Calendar report

  • SVG charts available in Oracle HTML DB including cluster bar, pie chart, and stacked bar

  • Printer friendly mode

The sections that follow describe specific functionality available on each page.

About the Home Page

As shown in Figure 3-1, the Home page contains four regions:

  • My Quota

  • My Top Orders

  • Sample Application 1.6

  • Tasks list

My Quota demonstrates the use of a new SVG chart called a Dial Chart. This chart displays a value based on an underlying SQL statement. Although not demonstrated in this example, you can enable an asynchronous refresh by editing the attributes of any SVG chart.

My Top Orders is a simple report based on a SQL query. This report displays a subset of the information that appears on the Orders page. Users can link to order details by selecting the Edit icon.

Sample Application 1.6 is a simple HTML region that displays static text. You can create this type a region to display explanatory information to users.

Tasks list contains an Oracle HTML DB list with links to other pages in Sample Application. Links available on the Home page Tasks list include:

  • About this Application links to an informational page that describes this application.

  • Enter a New Order links to a wizard for creating a new order.

  • Add a New Customer links to a form for entering new customer information.

  • Add a New Product links to a form for adding a new product.

About the Customers Page

As shown in Figure 3-2, the Customers page enables users to view and edit customer information. The Customers page consists of two main regions:

  • Customers

  • Top Customers

Figure 3-2 Sample Application, Customers Page

Description of customer.gif follows


Customers is an updatable report for tracking customer information. This region is also based on a SQL query. To search for a customer, type a customer name in the Search for field and click Go. To sort by customer name, click the column heading. A Sort icon appears to the right of the heading, Customer Name. To update existing customer information, click the Edit icon.

Top Customers ranks customers by order amount. This report is based on a SQL query which returns top customers based on their orders.

About the Products Page

As shown in Figure 3-3, the Products page enables users to view and edit product information. The Products page consists of two main regions:

  • Products

  • Top 10 Products

Figure 3-3 Sample Application, Products Page

Description of products.gif follows


Products displays an updatable report for tracking product information. This region is based on a SQL query which makes use of a custom function for displaying images stored in the database. To sort by product category, click the column heading. A Sort icon appears to the right of the heading. To edit a product description, click the Edit icon. To add a new product, click the Create Product button at the bottom of the page. Users can export the data in the Products report to a spreadsheet, by clicking Export to Spreadsheet.

Top 10 Products is also a SQL report. This report outlines the top ten products based on quantities sold.

About the Orders Page

The Orders page (see Figure 3-4) enables users to view and edit customer orders. The Orders page contains two regions:

  • My Orders

  • Order by Day

Figure 3-4 Sample Application, Orders Page

Description of orders.gif follows


My Orders is an Easy Report which summarizes the current orders in the system. To sort a column, click the column heading. A Sort icon appears next to column heading. To edit an existing order, click the Edit icon. To add a new order, click the Enter New Order button.

Order by Day is a Calendar report. This report displays the amount of an order on its corresponding date in a calendar. Users can select a calendar entry to view order details.

About the Charts Page

The Charts page illustrates three of the several types of SVG charts available in Oracle HTML DB: cluster bar, pie chart, and stacked bar. To view a chart, select a chart type.

About the Admin Page

The Admin page only displays if you log in to Sample Application using the user name admin. Sample Application makes use of a custom authentication scheme that stores user names and obfuscated passwords in a table. The Manage Users page enables you to manage additional users.

Note the this custom authentication scheme does not utilize any user names or passwords associated with Oracle HTML DB developers.

Viewing Pages in Printer Friendly Mode

Clicking Print in the upper right corner of the page displays the current page in Printer Friendly mode. When in Printer Friendly mode, the HTML DB engine displays all text within HTML form fields as text.

To enable your application to display in Printer Friendly mode, you need to create and then specify a Print Mode Page Template on the Edit Application Attributes page.

Modifying a Demonstration Application

Once you understand the type of functionality available in a demonstration application, the next step is to learn more about how each page is constructed. You edit an application using Application Builder. Using Application Builder you can edit existing pages in an application, add pages to an application, or create entirely new applications.

About the Developer Toolbar

When you log in to Oracle HTML DB having developer privileges and run an application, a Developer toolbar displays at the bottom of every page. As shown in Figure 3-5, the Developer toolbar offers a quick way to edit the currently running page, create a new page, control, or component, view session state, or turn edit links on or off.

Figure 3-5 Developer Toolbar in Sample Application

Description of d_toolbar_149.gif follows


The Developer toolbar consists of the following links:

  • Edit Application links you to the Application Builder home page. (See "Viewing a Page".)

  • Edit Page accesses the Page Definition for the currently running page. (See "Viewing a Page".)

  • New links to a wizard that enables you to create a new blank page, a component (report, chart, or form), a page control (region, button, or item), or a shared component (menu, list, or tab).

  • Session links you to session state information for the current page. (See "Viewing Session State".)

  • Debug runs the current page in debug mode. (See "Accessing Debug Mode".)

  • Show Edit Links toggles between Show Edit Links and Hide Edit Links. Clicking Show Edit Links displays edit links next to each object on the page that can be edited. Each edit link resembles two colons (::) and appears to the right of navigation bar items, tabs, region titles, buttons, and items. Clicking on the link displays another window in which to edit the object.

Editing a Demonstration Application

There are two common ways to edit a demonstration application:

  • From Demonstration Applications page, click Edit next to the desired application.

  • If you are running an application, click Edit Application on the Developer toolbar.

The Application Builder home page appears. As shown in Figure 3-6, the Application Builder home page displays the current application name and application ID, last update date, and parsing schema.

Figure 3-6 Application Builder Home Page

Description of bldr_home.gif follows


You can run the current application, edit application attributes, create shared components, export and import information, or create a new page by clicking the one of the following:

  • Run submits the pages in the current application to the HTML DB engine to render viewable HTML

  • Edit Attributes displays the Edit Application Attributes page

  • Shared Components links to a new page for building shared application components and user interface controls

  • Export/Install links you to the Export Import Wizard

  • Create Page links to a wizard for creating a new page

The Pages list displays at the bottom of the page. To access a specific page, select the page name. To search for a specific page number, enter a page number in the Find field and click Find.


See Also:


Viewing Underlying Database Objects

The HTML DB engine renders applications in real time based on data stored in database tables. You can view the database objects for any demonstration application in SQL Workshop.

To view the database objects used for an application:

  1. Navigate to the Workspace home page.

  2. Click the click the SQL Workshop icon.

    You view by schema and type and then by name. Under Database Browser, you can selecting existing database objects by selecting a database object type.

  3. Under Database Browser, select Tables.

  4. To create a search:

    • In Schema, select your workspace

    • In Type, select Table

    • In Search, type DEMO

    • Click Go

    All tables having names that contain the string DEMO appear.

  5. To view table details, click the View icon adjacent to the appropriate table name.

    The Object Detail page appears.

  6. Optionally, select a task from Tasks list on the right side of the page.

PK#ooPK(oUIOEBPS/build_app.htm Building an Application

8 Building an Application

This section describes how to use Application Builder to build an application and application components. It includes instructions for creating an application and adding pages as well as adding components (reports, charts, or forms), page controls (buttons, items, list of values), or a shared components (menus, lists, or tabs).

This section contains the following topics:

Creating an Application

You create a new application in Oracle HTML DB using the Create Application Wizard. You delete an application from the Application Builder home page.

Topics in this section include:

Creating a New Application

You can use the Create Application Wizard to create a new application having up to nine pages.

To create an application using the Create Application Wizard:

  1. Navigate to the Workspace home page.

  2. Click the Create Application button.

  3. Choose the method by which you want to create your application:

    • From Scratch. Enables you to define tabs, select a user interface (UI), and many other options.

    • Based on an Existing Application. Creates a copy of another application, including any authentication settings, but without any the pages. Select this option to create an application using the same user interface templates as an existing application.

    • Based on an Existing Table. Creates a complete application based on an existing table in your workspace. The resulting application includes a standard report, an insert form, an update form, a success form (indicates when a record is successfully inserted), an analysis menu page, analysis reports, analysis charts, and a login page.

    • Demonstration Application. Installs a demonstration application included with Oracle HTML DB.

    • Based on Spreadsheet. Creates an easily deployable application from a spreadsheet.

    • From an Application Export File. Uploads an application export file.

  4. Follow the on-screen instruction.

    Once you create an application the next step is to specify application attributes.

Deleting an Application

You can delete an application from the Application Builder home page, or while editing application attributes. If you delete an application you also delete all defined components (reports, charts, or forms), page controls (buttons, items, list of values), or a shared components (menus, lists, or tabs).

To delete an application from Application Builder home page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. When Application Builder appears, verify the application name and the application ID at the top of the page.

  4. From the Tasks list, select Delete this Application.

  5. Follow the on-screen instructions.

To delete an application while editing application attributes:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. When Application Builder appears, verify the application name and the application ID at the top of the page.

  4. Click the Edit Attributes icon.

    The Edit Application Attributes page appears.

  5. Verify the application ID and name.

  6. Click Delete at the top of the page.

Adding Additional Pages

You can add a new page or add a component to an existing page by running the Create Page Wizard. You can access this wizard on the Application Builder home page, the Page Definition, or by selecting the New... link on the Developer toolbar.

When you run the Create Page Wizard, you choose whether to create a blank page or a page with a component. Select Page with Component to create a page containing a report, a chart, a form, a wizard, a calendar, or a tree.


Note:

You can add a component (that is, a report, chart, form, wizard, a calendar, or tree) to an existing page using the Create Page Wizard. When prompted, specify an existing page number.

Topics in this section include:

Creating a Page from Application Builder

To create a new page from the Application Builder home page:

  1. Navigate to Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Create Page.

  4. Select the type of page you wish to create:

    • Blank Page

    • Page with Component

      Select Page with Component to create a page containing a report, a chart, a form, a wizard, a calendar, or a tree. Selecting this option creates complete pages containing multiple attributes. For example, the Report wizard generates one page containing one region and multiple buttons.

  5. Follow the on-screen instructions.

Creating a Page from the Page Definition

To create a new page while viewing a Page Definition:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. From the navigation bar at the top of the page, click the Create button.

  3. Select the type of page you wish to create:

    • Blank Page

    • Page with Component

      Select Page with Component to create a page containing a report, a chart, a form, a wizard, a calendar, or a tree. Selecting this option creates complete pages containing multiple attributes. For example, the Report wizard generates one page containing one region and multiple buttons.

  4. Follow the on-screen instructions.

Creating a Page from the Developer Toolbar

Users who log in to Oracle HTML DB having developer privileges have access to the Developer toolbar. The Developer toolbar displays at the bottom every page and offers a quick way create a new page.

To create a new page from the Developer toolbar:

  1. On the Developer toolbar, select New.

    The New Component Wizard appears.

  2. Select the type of page you want to create:

    • Page (Blank Page)

    • Component (Report, Form, Chart)

    • Page Control (Region, Item, Button)

    • Shared Control (Menu, List, Tab)

  3. Follow the on-screen instructions.

Running a Page

The HTML DB engine dynamically renders and process pages based on data stored in database tables. To view a rendered version of your application, you run or submit it to the HTML DB engine. As you create new pages you can run them individually, or run an entire application. You can run a page from numerous locations within Application Builder by clicking the Run icon. (See Figure 8-1.)

Figure 8-1 Run Icon on the Pages List

Description of run_ico_sm.gif follows


To run a specific page from the Pages list:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

    Application Builder appears. The list of pages for the selected application appears at the bottom of the page.

  3. From the Pages list, locate the page you wish to run and click the Run button in the far right column.

To run a specific page from the Page Definition:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Click the Run button in the upper right corner of the page.

To run an entire application:

  1. Navigate to the Workspace home page.

  2. Locate the application in the Applications list.

  3. Click the Run button in the far right column.

Grouping Pages

You can make the pages within your application easier to access by organizing them into page groups.

Topics in this section include:

Creating a Page Group

To create a page group:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. From the Tasks List on the right side of the page, select Manage Page Groups.

  4. On the Page Groups page, click Create.

  5. Enter a name, a description (optional), and click Create.

Assigning Pages to a Page Group

To assign pages to page group:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select the application.

  3. From the Tasks List on the right side of the page, select Manage Page Groups.

  4. From the Tasks list, select Report Unassigned Pages.

    The Unassigned Pages page appears.

  5. From Page Group, select a group to assign pages to.

  6. Select the pages to be assigned.

  7. Click Assigned Checked.

    Selecting the page number takes you to the Page Attributes page. Selecting the Page Name links to the Page Definition.

Viewing the Page Group Report

The Page Group Report offers a comprehensive list of which pages in an application are assigned to a group and which pages are unassigned.

To view the Page Group Report:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select the application.

  3. From the Tasks List on the right side of the page, select Manage Page Groups.

  4. On the Page Groups page, click Report Page Groups.

Locking and Unlocking Page

You can prevent conflicts during application development by locking pages of your application. By locking a page, you prevent other developers from editing it.

To lock a page of your application:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select the application.

  3. To lock pages from the Locked Pages page:

    1. From the Tasks List on the right side of the page, select Manage Page Locks.

    2. Select the appropriate pages and click Lock.

    3. Enter a comment in the Comment field.

    4. Click Lock Pages.

  4. To lock pages from the Pages list:

    1. Click the Lock icon in the Pages list.

    2. Enter a comment in the Comment field.

    3. Click Lock Pages.

  5. To lock pages from the Page Definition:

    1. Navigate to the Page Definition. (See "Viewing a Page Definition".)

    2. Click the Lock icon in the upper right corner above Shared Components.

      The Locked Pages page appears.

    3. Select the appropriate pages and click Lock.

    4. Enter a comment in the Comment field.

    5. Click Lock Pages.

Only the user who locked a page can unlock it.

To unlock a page of your application:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select the application.

  3. To unlock pages from the Locked Pages page:

    1. From the Tasks List on the right side of the page, select Manage Page Locks.

    2. Select the appropriate pages.

    3. Click UnLock.

  4. To unlock pages from the Pages list:

    1. Click the Lock icon in the Pages list.

      The Edit Page Lock page appears.

    2. Click UnLock.

  5. To unlock pages from the Page Definition:

    1. Navigate to the Page Definition. (See "Viewing a Page Definition".)

    2. Click the Lock icon in the upper right corner above Shared Components.

      The Locked Pages page appears.

    3. Select the appropriate pages.

    4. Click UnLock.

Note the Lock icon changes to reflect the lock status of a given page.

Accessing Alternative Locked Pages Views

You can access a number of different views of Locked Pages on the Locked Pages page.

To access different views of locked pages:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select the application.

  3. From the Tasks List on the right side of the page, select Manage Page Locks.

  4. From the Tasks list, select one of the following:

    • Show Locked Pages displays only locked pages within the current application

    • Show All Pages displays all pages within the current application

    • Show Unlocked Pages display only unlocked pages within the current application

    • Administer Locks enables workspace administrators to unlock any pages locked by a developer

Deleting a Page

You can delete a page from the Page Definition or while editing page attributes.

To delete a page from the Page Definition:

  1. Navigate to the Page Definition. (See "Viewing a Page Definition".)

  2. Verify the page name.

  3. From the navigation bar at the top of the page, click Delete.

  4. Follow the on-screen instructions.


See Also:

"Editing a Page Definition" for more information on editing page attributes

To delete a page while editing page attributes:

  1. Navigate to the Page Definition. (See "Viewing a Page Definition".)

  2. From the navigation bar at the top of the page, click Edit Attributes.

  3. Verify the application ID and page name.

  4. Click Delete.

  5. Follow the on-screen instructions.

Creating Reports

In Oracle HTML DB a report is the formatted result of a SQL query. You can generate reports by selecting and running a built-in query, or by defining a report region based on a SQL query.

Topics in this section include:

Creating a Report Using a Wizard

Oracle HTML DB includes the number of built-in wizards for generating reports.

To create a report using a wizard:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select the application.

    Application Builder appears.

  3. Click Create Page.

  4. Select Page with Component.

  5. Select Report.

  6. Select one of the following report types:

    • Easy Report - Does not require any SQL knowledge. Simply select the appropriate schema, table, columns, and result set display.

    • Report with Form - Builds a two page report and form combination. The first page enables users to specify the row to be updated. The second page includes a form for updating the selected table or view.

    • SQL Report - Creates a report based on a custom SQL SELECT statement or a PL/SQL function returning a SQL SELECT statement that you provide.

  7. Follow the on-screen instructions.

Editing Report Attributes

You can use the Report Attributes and Column Attributes pages to precisely control the look and feel of report pages. For example, you can use these attributes to alter column heading text, change column positioning, hide a column, create a sum of a column, or select a sort sequence.

On the Page Definition, you can access the Report Attributes page by clicking either Q or RPT adjacent to the report region you want to edit. Q indicates the report is a regular report and RPT indicates the report is an easy report. You can also navigate to the Report Attributes page by clicking the region name then selecting the Report Attributes tab.

To access the Report Attributes page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select the application.

  3. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  4. Under Regions, click Q next to the name of the report region you want to edit.

    The Report Attributes page appears.

    Figure 8-2 Report Attributes Page

    Description of rpt_att.gif follows


    Heading Type identifies how the heading was generated for the report. Use the Report Column Attributes section to control report column appearance and functionality. The Link column indicates whether a column link is currently defined. The Edit column indicates whether or not a column is currently updatable. The Edit column.

    Table 8-1 describes common report column edits.

    Table 8-1 Common Report Column Edits

    Description Developer Action
    Alter column display sequence. Click the up and down arrows.
    Alter heading alignment. Under Column Alignment, select a new column alignment.
    Change column heading text. Under Heading, enter a different heading text.
    Control which columns display. Click Show to indicate a column should display.
    Enable an unique sort sequence. Click Sort and select a sequence number from Sort Sequence.
    Enable the sum of a column. Click Sum to enable the sum of a column.

    You can further refine the attributes of a specific column on the Column Attributes page.

  5. To access the Column Attributes page, click the Edit icon adjacent to the appropriate column name.

    See online help for more information on a specific attribute.

Controlling Report Pagination

You control report pagination by:

  • Including a pagination substitution string in the report template

  • Making selections from Layout and Pagination on the Report Attributes page

You control how pagination displays by making selections from the Layout and Pagination attributes on the Report Attributes page.

To access the Layout and Pagination section of the Report Attributes page:

  1. Create a report. (See "Creating a Report Using a Wizard".)

  2. Under Regions, click the appropriate report attributes link (Q or RPT).

    The Report Attributes page appears.

  3. Scroll down to Layout and Pagination.

    You use the Layout and Pagination attributes to select a pagination style, determine where pagination displays, and specify the number of rows that display on each page. Table 8-2 describes the most commonly used Layout and Pagination attributes.

Table 8-2 Layout and Pagination Attributes

Attribute Description
Report Template Specifies a template to be applied to this report. Report templates provide control over the results of a row from your SQL query. You can choose from a number of default templates, or pick a custom build template.
Pagination Scheme Specifies a pagination scheme for this report.

Pagination provides the user with information about the number of rows and the current position within the result set. Pagination also defines the style of links or buttons used to navigate to the next or previous page.

For more information, see the help for this item.

Display Position Defines where pagination displays.

If you choose to display pagination above a report, the selected report template needs to support that type of display.

Number of Rows Defines the maximum number of rows to display on each page.
Strip HTML Specifies whether or not to remove HTML tags from the original column values for HTML expressions and column links.

If you select values from the database that already contain HTML tags, then those tags can cause conflicts with the HTML generated for your columns links or HTML expressions. When this option is enabled, only the actual data portion of your column value is used.


Including Pagination After the Rows in a Report

To include pagination after the rows in a report:

  1. Create a report. (See "Creating a Report Using a Wizard".)

    Next, select the appropriate Layout and Pagination attributes.

  2. Navigate to the Report Attributes page:

    1. Navigate to the Page Definition.

    2. Under Regions, click the appropriate report attributes link (Q or RPT)

      The Report Attributes page appears.

  3. Under Layout and Pagination, select the following:

    1. Report Template - Select a report template (optional).

    2. Pagination Scheme - Select a pagination scheme.

    3. Display Position - Select a display position.

    4. Number of Rows - Specify how many rows display on each page.

    5. Click Apply Changes.

  4. Edit the report template.

    1. Navigate to the Page Definition.

    2. Under Templates, select the report template name.

    3. Include the #PAGINATION# substitution string in the After Rows attribute.

    4. Click Apply Changes.

  5. Run the page.

Including Pagination Before the Rows in a Report

To include pagination after the rows in a report:

  1. Create a report. (See "Creating a Report Using a Wizard".)

    Next, select the appropriate Layout and Pagination attributes.

  2. Navigate to the Report Attributes page:

    1. Navigate to the Page Definition.

    2. Under Regions, click the appropriate report attributes link (Q or RPT).

      The Report Attributes page appears.

  3. Under Layout and Pagination:

    1. Report Template - Select a report template (optional).

    2. Pagination Scheme - Select a pagination scheme.

    3. Display Position - Select a position that contains the word "top."

    4. Number of Rows - Specify how many rows display on each page.

    5. Click Apply Changes.

  4. Edit the report template.

    1. Navigate to the Page Definition.

    2. Under Templates, select the report template name.

    3. Include the #TOP_PAGINATION# substitution string in the Before Rows attribute.

    4. Click Apply Changes.

  5. Run the page.

Enabling Column Sorting

You enable column sorting on the Report Attributes page.

To enable column sorting:

  1. Navigate to the Report Attributes page. (See "Editing Report Attributes".)

  2. Under Report Column Attributes, select the Sort check box adjacent to the columns to be sorted.

  3. From Sort Sequence, select a sequence number.

    Sort Sequence is optional. However, if there are one or more sort enabled columns, then at least one column needs a defined Sort Sequence.

  4. Scroll down to Sorting.

  5. Specify ascending and descending image attributes or click set defaults.

Exporting a Report as a CSV or XML File

You can create a link within a report that enables users to export the report as either a comma delimited file (.csv) or XML file. You specify an export format by selecting a report template.

To specify an export report template:

  1. Navigate to the appropriate Report Attributes page. (See "Editing Report Attributes".)

  2. Scroll down to Layout and Pagination.

  3. From the Report Template list, select one of the following:

    • export: CSV exports the report as a CSV file

    • export: XML exports the report as a XML file

    Selecting either option prevents the HTML DB engine from rendering the page and dumps the content to either a CSV or XML file.

    You can use the options under CSV Output to create a link that downloads the content of the report.

  4. Scroll down Report Export.

  5. From Enable SCV output, select Yes.

  6. (Optional) In the Separator and Enclosed By fields, define the separator and delimiter characters.

    The default Enclosed By by characters are a double quotes (" "). The default delimiter character is either a comma or a semicolon depending upon your current NLS settings.

  7. In the Link Label field, enter link text. This text will display in your report and enable users to invoke a download.

  8. (Optional) To specify a default export filename, enter a name in the Filename field.

    By default, the HTML DB engine creates an export filename by taking the region name and adding the appropriate filename extension (.csv or .xml).

  9. Click Apply Changes.

Creating a Column link

Use the Column Link attributes to create a link from a report to another page in your application or to a URL.

To create a column link to another page:

  1. Navigate to the appropriate Report Attributes page. (See "Editing Report Attributes".)

  2. Under Report Column Attributes, locate the column to contain the link.

  3. Click the Edit icon adjacent to the column name.

    The Column Attributes page appears.

  4. Scroll down to Column Link.

  5. To create a Column Link to another page:

    1. From Target, select Page in this Application.

    2. (Optional) In Link Attributes, specify additional column link attributes that will be included in the <a href= > tag (for example, a link target, classes, or styles).

    3. In Link Text, enter text to be displayed as a link, specify an image tag, or pick from the list of default images.

    4. In Page, specify the target page number. To reset pagination for this page, select Reset Pagination.

    5. In Request, specify the request to be used.

    6. In Clear Cache, specify the pages (that is, the page numbers) on which to clear cache. You can specify multiple pages by listing the page numbers in a comma delimited list.

    7. Use the Name and Value fields to specify session state for a specific item.

  6. Click Apply Changes.

To create a column link to a URL:

  1. Navigate to the appropriate Report Attributes page. (See "Editing Report Attributes".)

  2. Access the Column Attributes page by clicking the Edit icon adjacent to the appropriate column.

    The Column Attributes page appears.

  3. Scroll down to Column Link.

  4. Under Column Link, make the following selections

    1. From Target Type, select URL.

    2. In Link Text, enter text to be displayed as a link, select a substitution string.

    3. (Optional) In Link Attributes, specify additional column link attributes that will be included in the <a href= > tag (for example, a link target, classes, or styles).

    4. In URL, enter the appropriate address.

  5. Click Apply Changes.

Defining an Updatable Column

You can make a column updatable by editing Tabular Form Element attributes on the Column Attributes page. Note that the HTML DB engine can only perform updates if a multi row update is defined, or PL/SQL process is implemented to process updated data.

To define updatable column attributes:

  1. Navigate to the appropriate Report Attributes page. (See "Editing Report Attributes".)

  2. Access the Column Attributes page by clicking the Edit icon adjacent to the appropriate column.

    The Column Attributes page appears.

  3. Scroll down to Tabular Form Element.

  4. Under Tabular Form Element, make the following selections:

    1. From Display As, select a type of updatable column.

      Use this option to make a column updatable. Updates can only be performed if a multi row update is defined, or PL/SQL process is implemented to process updated data.

    2. From Date Picker Format Mask, make a selection if you selected the Display As type of Date Picker.

    3. In Element Width, specify the width of the form item.

    4. In Number of Rows, specify the height of a form item (applicable to text areas).

    5. In Element Attributes, define a style or standard form element attribute.

    6. In Element Option Attributes, specify form element attributes for items in a radio group or check box.

    7. From Default Type, identify the default type.

    8. In Default, identify the default source.

      Use Default Type and Default Source to add new rows to a tabular form. The HTML DB engine uses this setting to determine the default value for the column. Otherwise, the column is defined as NULL.

    9. From Reference Table Owner, identify the owner of the referenced table. Use this attribute to build User Interface Defaults for reports.

    10. In Reference Table Name, identify the table or view that contains the current report column.

    11. In Reference Column Name, identify the column name that this report column references

  5. Click Apply Changes.

Defining a Column as a List of Values

Report columns may be rendered as lists of values. For example, a column can be rendered using a select list or a popup list of values. Or, a column can also be rendered as read-only text based on a list of values.

This last approach is an effective strategy when creating display lookup values and is particularly useful in regular, non-updatable reports. This approach enables you to display the value of a column without having to write a SQL JOIN.

To render a report column as a list of values:

  1. Navigate to the appropriate Report Attributes page. (See "Editing Report Attributes".)

  2. Access the Column Attributes page by clicking the Edit icon adjacent to the appropriate column.

    The Column Attributes page appears.

  3. Scroll down to List of Values.

  4. From Named LOV, make a selection from the Named List of Values repository.

  5. To include a null value in a list of values:

    1. In Display Null, select Yes.

    2. In Null Text, specify the value that displays.

    A column may also have a value that does not display in its list of values.

  6. To define a value that does not display in the list of values:

    1. From Display Extra Value, select Yes.

      The extra value is used if the actual column value is not part of the LOV. In that situation, the actual value is shown. If you do not display extra values, you may end up with the wrong value and unintentionally and update your data incorrectly.

    2. In Null Value, specify the value that displays.

    3. If you have not selected a Named LOV, enter the query used to display a select list in the LOV Query field.

  7. If you have not selected a Named LOV, enter the query used to display a select list in LOV Query.

  8. Click Apply Changes.

Controlling When Columns Display

You can use the Authorization and Conditional Display column attributes to control when a column displays.

Authorization enables you to control access to resources (such as a report column) based on predefined user privileges. For example, you could create an authorization scheme in which only managers can view a specific report column. Before you can select an authorization scheme, you must first create it.

A condition is a small unit of logic that enables you to control the display of a column based on a predefined condition type. The condition evaluates to true or false based on the values you enter in the Expressions fields.

To specify Authorization and Conditional Display attributes:

  1. Navigate to the appropriate Report Attributes page. (See "Editing Report Attributes".)

  2. Access the Column Attributes page by clicking the Edit icon adjacent to the appropriate column.

    The Column Attributes page appears.

  3. Under Authorization, make a selection from the Authorization Scheme list.

  4. Under Conditional Display, make a selection from the Condition Type list and depending upon your selection, enter an expression or value in the appropriate Expression fields.

    If the authorization is successful and the condition type display evaluates to true, the column displays.

Controlling Column Breaks

You can control whether a specific column repeats and how column breaks appear when printed using Break Formatting attributes. For example, suppose your report displays employee information by department number. If multiple employees are members of the same department, you can increase the readability by specifying the department number only appears once.

To create this type of column break:

  1. Navigate to the appropriate Report Attributes page. (See "Editing Report Attributes".)

  2. Scroll down to Break Formatting.

  3. Make a selection from the Breaks list.

Creating Forms

You can include a variety of different types of forms in your applications. You can include forms that enable users to update just a single row in a table or multiple rows at once. Oracle HTML DB includes a number of wizards you can use to create forms automatically, or you can create forms manually.

Topics in this section include:

Creating a Form Using a Wizard

The easiest way to create a form is to use a wizard. For example, the Form on Table or View Wizard creates one item for each column in a table. It also includes the necessary buttons and processes required to insert, update, and delete rows from the table using a primary key. Each region has a defined name and display position all other attributes are items, buttons, processes, and branches.

To create a form using a wizard:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

    Application Builder appears.

  3. Click Create Page.

  4. Select Page with Component.

  5. Select Form.

  6. Under Forms, select a wizard described in Table 8-3.

    Table 8-3 Forms Wizards

    Wizard Description
    Form on a Procedure Builds a form based on stored procedure arguments. Use this approach when you have implemented logic or DML (Data Manipulation Language) in a stored procedure or package.
    Form on a SQL Query Creates a form based on the columns returned by a SQL query such as an equijoin.
    Form on a Table or View Creates a form that enables users to update a single row in a database table.
    Form on a Table with Report. 2 pages Creates two pages. One page displays a report. Each row provides a link to the second page to enable users to update each record.

    Note: This wizard does not support tables having more than 127 columns. Selecting more than 127 columns will generate an error.

    Form on Web Service Creates a page with items based on a Web service definition. This wizard creates a user input form, a process to call the Web service, and a submit button.

    See Also: "Creating a Form on a Web Service"

    Form and Report on Web Service Creates a page with items based on a Web service definition. This wizard creates a user input form, a process to call the Web service, a submit button, and displays the results returned in a report.

    See Also: "Creating an Input Form and Report on a Web Service"

    Master Detail Form Creates a form which displays a master row and multiple detail rows within a single HTML form. With this form, users can query, insert, update, and delete values from two tables or views.

    See Also: "Building a Master Detail Form"

    Summary Page Creates a read-only version of a form. Typically used to provide a confirmation page at the end of a wizard.
    Tabular Form Creates a form in which users can update multiple rows in a database.

    See Also: "Creating a Tabular Form"


  7. Follow the on-screen instructions.

Creating a Tabular Form

A tabular form enables users to update multiple rows in a table. The Tabular Form Wizard creates a form to perform update, insert, and delete operations on multiple rows in a database table.

To create a tabular form:

  1. From the Workspace home page, select the appropriate application.

  2. Click Create Page.

  3. Select Page with Component.

  4. Select Form.

  5. Select Tabular Form.

    The Tabular Form Wizard appears.

  6. On Identify Table/View Owner:

    1. Specify the table or view owner on which you want to base your tabular form.

    2. Select the type of tabular form you want to create.

    3. Select a table.

  7. On Identify Table/View Name, select a table.

  8. On Identify Columns to Display:

    1. Specify whether to use user interface defaults.

      User interface defaults enable you to assign default user interface properties to a table, column, or view within a specified schema.

    2. Select the columns (updatable and nonupdatable) to include in the form.

      You can modify the column order or your SQL query after you have created the page.

  9. On Identify Primary Key, select the Primary Key column and a foreign key column (if applicable).

  10. On Defaults for Primary and Foreign Keys, select a source type for the primary key column. Valid options include:

    • Existing trigger - Select this option if a trigger is already defined for the table. You do not need to define a primary key column source for existing columns. Existing columns already have a primary key.

    • Custom PL/SQL function - Select this option if the source is a PL/SQL function returning the key value.

    • Existing sequence - Select this option if an existing sequence is defined for the table. If that is the case, the sequence next value would be used.

  11. On Updatable Columns, select which columns should be updatable.

  12. On Identify Page and Region Attributes.

    1. Specify page and region information.

    2. Select a region template.

    3. Select a report template.

  13. On Identify Tab, specify a tab implementation for this page.

  14. On Button Labels, enter the display text to appear on the Cancel, Submit, Delete, and Add Row buttons.

  15. On Identify Branching, specify the pages to branch to after the user clicks the Submit and Cancel buttons.

  16. Click Finish.


Note:

Do not modify the select list of a SQL statement of a tabular form after it has been generated. Doing so can result in a checksum error when you alter data in the form.

Building a Master Detail Form

A master detail form reflects a one-to-many relationship between two tables in a database. Typically a master detail form displays a master row and multiple detail rows within a single HTML form. With this form, users can insert, update, and delete values from two tables or views.

To create a master detail form:

  1. From the Workspace home page, select the appropriate application.

  2. Click Create Page.

  3. Select Page with Component.

  4. Select Form.

  5. Select Master Detail Form.

    The Master Detail Wizard appears.

  6. On Define Master Table:

    1. Select a table or view owner

    2. Select a table or view name

    3. Select the columns to display

  7. On Define Detail Table:

    1. Specify to show only related tables

    2. Select the table or view owner

    3. Select the table or view name

    4. Select the columns to display

  8. On Define Primary Key, select the primary key column for the master table and then the primary key column for the detail table.

  9. On Define Master and Detail, define the relationships between master and detail tables.

  10. Specify the source for the master table and detail table primary key columns.

  11. On Define Master Options, specify whether to include master row navigation.

    If you include master row navigation, define navigation order columns. If a navigation order column is not defined, the master update form will navigate by the primary key column.

  12. On Choose Layout, specify the layout of the master detail pages.

    You can include the master detail as a tabular form on the same page, or add the master detail on a separate page.

  13. On Page Attributes, review and edit the master page and detail page information.

  14. On Identify Tabs, specify whether to include an optional tab set.

  15. Click Create.

Creating a Form Manually

You can also create a form manually by performing the following steps:

  • Create an HTML region (to serve as a container for your page items)

  • Create items to display in the region

  • Create processes and branches

To create a form manually:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Create an HTML region:

    • Under Regions, click Create

    • Select the region type HTML

    • Follow the on-screen instructions

  3. Start adding items to the page:

    • Under Items, click Create

    • Follow the on-screen instructions

Processing a Form

Once you create a form, the next step is to process the data a user types by inserting into or updating the underlying database tables or views. There are three ways to process a form:

Creating an Automatic Row (DML) Processing Process

One common way to implement a form is to manually create an Automatic Row Processing (DML) process. This approach offers three advantages. First, you are not required to provide any SQL coding. Second, Oracle HTML DB performs DML processing for you. Third, this process automatically performs lost update detection. Lost update detection ensures data integrity in applications where data can be accessed concurrently.

In order to implement this approach you need to:

  • Add items and define the Item Source Type as Database Column and specify a case-sensitive column name

  • Select the option Always overrides the cache value

To create an Automatic Row Processing (DML) process:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Processes, click the Create icon.

  3. Select the process type Data Manipulation.

  4. Select the process category Automatic Row Processing (DML).

  5. Specify the following process attributes:

    1. In the Name field, type a name to identify the process.

    2. In the Sequence field, specify a sequence number.

    3. From the Point list, select the appropriate processing point. In most instances, select Onload - After Header.

    4. From the Type list, select Automated Row Processing (DML).

  6. Follow the on-screen instructions.

Creating a Process that Contains One or More Insert Statements

In this approach to form handling, you create one or more processes to handle insert, update and delete actions. Instead of having the HTML DB engine handling everything transparently, you are in complete control.

For example, suppose you have a form with three items:

  • P1_ID - A hidden item to store the primary key of the currently displayed row in a table.

  • P1_FIRST_NAME - A text field for user input.

  • P1_LAST_NAME - A text field for user input.

Assume also there are three buttons labeled Insert, Update, and Delete. Also assume you have a table T which contains the columns id, first_name, and last_name. The table has a trigger which automatically populates the ID column when there is no value supplied.

To process the insert of a new row, you create a conditional process of type PL/SQL that executes when the user clicks the Insert button. For example:

BEGIN
  INSERT INTO T ( first_name, last_name )
     VALUES  (:P1_FIRST_NAME, :P1_LAST_NAME);
END; 

To process the update of a row, you create another conditional process of type PL/SQL. For example:

BEGIN
    UPDATE T
       SET first_name = :P1_FIRST_NAME,
           last_name = :P1_LAST_NAME
    WHERE ID = :P1_ID;
END; 

To process the deletion of a row, you create a conditional process that executes when the user clicks the Delete button. For example:

BEGIN
    DELETE FROM T
    WHERE ID = :P1_ID;
END;

Using a PL/SQL API to Process Form Values

For certain types of applications it is appropriate to centralize all access to tables in a single or few PL/SQL packages. If you have created a package to handle DML operations, you can call procedures and functions within this package from a After Submit PL/SQL process to process insert, update and delete requests.

Populating Forms

Oracle HTML DB populates a form on load, or when the HTML DB engine renders the page. You can populate a form in the following ways:

  • Create a process and define the type as Automated Row Fetch

  • Populate the form manually by referencing a hidden session state item

To create an Automated Row Fetch process:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Processes, click Create.

  3. Select the process type Data Manipulation.

  4. Select the process category Automatic Row Fetch.

  5. Specify the following process attributes:

    1. In the Name field, type a name to identify the process.

    2. In the Sequence field, specify a sequence number.

    3. From the Point list, select the appropriate processing point.

    4. From the Type list, select Automated Row Fetch.

  6. Follow the on-screen instructions.

You can also populate a form manually by referencing a hidden session state item. For example, the following code in an Oracle HTML DB process of type PL/SQL would set the values of ename and sal. The example also demonstrates how to manually populate a form by referencing a hidden session state item named P2_ID.

FOR C1 in (SELECT ename, sal
FROM emp WHERE ID=:P2_ID)
LOOP     
     :P2_ENAME := C1.ename;
     :P2_SAL := C1.sal;
END LOOP;

In this example:

  • C1 is an implicit cursor

  • The value of P2_ID has already been set

  • The process point for this process would be set to execute (or fire) on or before Onload - Before Regions

Validating User Input in Forms

You can use validations to check data a user types prior to processing. Once you create a validation and the associated error message, you can associate it with a specific item. You can choose to have validation error messages display inline (that is, on the page where the validation is performed) or on a separate error page.

Creating an inline error message involves these steps:

  • Create a new validation and specify error message text

  • Associate the validation with a specific item

To create a new validation:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Validations, click the Create icon.

  3. When the Create Validations Wizard appears, follow the on-screen instructions.

    Validations Types are divided into two categories:

    • Item. These validations start with the phrase "Item" and provide common checks you may want to perform on the item that the validation is associated with.

    • Code. These validations require you provide either a piece of PL/SQL code or SQL query that defines the validation logic. Use this type of validation to perform custom validations that require verifying values of more than one item or accessing additional database tables.

  4. Follow the on-screen instructions.


Note:

Validations may not contain more than 3,950 characters.

To associate an item with a validation and specify error message text:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Validations, select the validation item you want to associate.

    The attributes page for the validation appears.

  3. Scroll down to Error Messaging:

    • In Error message display location, verify the display location

    • In Associated Item, select the item you want to associate with this validation

  4. Click Apply Changes.

About Error Messaging

Error message display location identifies where a validation error message displays. Validation error messages can display on an error page or inline within the existing page. Inline error messages can display in a notification area (defined as part of the page template) or within the field label.

If you want to create a hard error that stops processing of any remaining validations, you must display the error on an error page.

Creating Charts

Oracle HTML DB includes built-in wizards for generating HTML and Scalable Vector Graphics (SVG) charts. Oracle HTML DB supports two types of graphical charts:

  • HTML

  • SVG

SVG is an XML-based language for Web graphics from the World Wide Web Consortium (W3C). SVG charts are defined using an embed tag. When evaluating whether a SVG chart is the appropriate chart type for your application remember that:

  • Some Web browsers do not support SVG charts

  • Most Web browsers that support SVG charts require users download an SVG plug-in

Topics in this section include:

About SVG Plug-in Support

The Adobe SVG plug-in can properly handle data encoded in UTF-8, UTF-16, ISO-8859-1, and US-ASCII. Encoding of an SVG chart is determined by the database access descriptor (DAD) database character set. If the DAD character set is not UTF8, AL32UTF8, AL16UTF16, WE8ISO8859P1, or US7ASCII, SVG charts may not render properly in the Adobe SVG plug-in.

About Creating Charts

You define a chart in Oracle HTML DB using a wizard. For most chart wizards, you select a chart type and provide a SQL query using the following syntax:

SELECT link, label, value
FROM   ...

Where:

  • link is a URL

  • label is the text that displays in the bar

  • value is the numeric column that defines the bar size

For example:

SELECT null, ename, sal
FROM   scott.emp
WHERE  deptno = :P101_DEPTNO

To create a dial chart, select a dial chart type and provide a SQL query using the following syntax:

SELECT value , maximum_value [ ,low_value [ ,high_value] ]
FROM   ...

Where:

  • value is the starting point on the dial

  • maximum_value is the possible highest point on the dial

  • low_value and high_value are the historical low and high values

For example:

select dbms_random.value(500, 1200), 1300, dbms_random.value(100, 200)
FROM DUAL

Table 8-4 describes the chart types available in Oracle HTML DB.

Table 8-4 Available Chart Types

Chart Type Description
Bar (HTML) Bar chart showing one data series with each data point represented by a bar.

HTML-based. Does not require a plug-in.

Bar, Horizontal Single series based bar chart oriented horizontally with each data point in series represented by a bar.

SVG-based. Requires a SVG plug-in.

Bar, Vertical Single series based bar chart oriented vertically with each data point in series represented by a bar.

SVG-based. Requires a SVG plug-in.

Cluster Bar, Horizontal Multiple series based bar chart oriented horizontally and clustered by a common variable with each data point in series represented by a bar (for example, Department sales total clustered by month of year).

SVG-based. Requires a SVG plug-in.

Cluster Bar, Vertical Multiple series based bar chart oriented vertically clustered by a common variable with each data point in series represented by a bar (for example, Department sales total clustered by month of year).

SVG-based. Requires a SVG plug-in.

Dial - Sweep Also known as an angular gauge, this chart shows either percentage of maximum value or absolute value compared to a maximum value represented as a solid area.

SVG-based. Requires a SVG plug-in.

Dial Also known as angular gauge, this chart shows either percentage of maximum value or absolute value compared to maximum value represented as a line.

SVG-based. Requires a SVG plug-in.

Line Multiple series based line chart oriented with each line representing all data points in the series.

SVG-based. Requires a SVG plug-in.

Pie Single series based pie chart with each slice representing a data point in the series.

SVG-based. Requires a SVG plug-in.

Stacked Bar, Horizontal Multiple series based bar chart oriented horizontally with each data point being an absolute value in series representing a segment of a single bar.

SVG-based. Requires a SVG plug-in.

Stacked Bar, Vertical Multiple series based bar chart oriented vertically with each data point being an absolute value in series representing a segment of a single bar.

SVG-based. Requires a SVG plug-in.

Stacked Percentage Bar, Horizontal Multiple series based bar chart oriented horizontally with each data point being an percentage of 100% of the series represented by a segment of a single bar.

SVG-based. Requires a SVG plug-in.

Stacked Percentage Bar, Vertical Multiple series based bar chart oriented vertically with each data point being an percentage of 100% of the series represented by a segment of a single bar

SVG-based. Requires a SVG plug-in.



Note:

Do not change the Type of an existing chart. Instead, delete the existing chart and then re-create it.

Creating a New Chart

How you create a chart depends upon whether you are adding the chart to an existing page, or adding a chart on a new page.

Adding a Chart to an Existing Page

To add a chart to an existing page:

  1. Navigate to the Page Definition.

  2. Under Regions, click the Create icon.

    The Create Region Wizard appears.

  3. Select Chart.

  4. Select the type of chart you wish to create. (See Table 8-4.)

  5. Follow the on-screen instructions.

Adding a Chart to a New Page

To create a chart on a new page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. Click Create Page.

  4. When prompted for the type of page to create, select Page with Component.

  5. Select the component type Chart.

  6. Select the type of chart you wish to create. (See Table 8-4.)

  7. Follow the on-screen instructions.

Editing Chart Attributes

Once you have created a chart you can alter its display by editing chart attributes on the chart attributes page.

To access the Chart Attributes page:

  1. Navigate to the Page Definition.

  2. Under Regions, click Chart next to the name of the chart region you wish to edit.

    The Chart Attributes page appears.

    Note that removing the chart title (that is, the Chart Title attribute) may negatively impact the location and display of the chart legend.

Understanding Chart CSS Classes

When you create a new chart, Oracle HTML DB renders it based on cascading style sheet (CSS) classes associated with the current theme. You can change the appearance of a chart by referencing another CSS or by overriding individual classes in the CSS section of the Edit Attributes page

The following sample contains the CSS classes for the dial chart in Sample Application. This example contains all the available CSS classes. Class names appear in boldface.

text{font-family:Verdana, Geneva, Arial, Helvetica, sans-serif;fill:#000000;}
tspan{font-family:Verdana, Geneva, Arial, Helvetica, sans-serif;fill:#000000;}
text.title{font-weight:bold;font-size:14;fill:#000000;}
text.moredatafound{font-size:12;}
rect.legend{fill:#EEEEEE;stroke:#000000;stroke-width:1;}
text.legend{font-size:10;}
#background{fill:#FFFFFF;stroke:none;}
rect.chartholderbackground{fill:#ffffff;stroke:#000000;stroke-width:1;}
#timestamp{text-anchor:start;font-size:9;}
text.tic{stroke:none;fill:#000000;font-size:12}
line.tic{stroke:#000000;stroke-width:1px;fill:none;}
#dial{stroke:#336699;stroke-width:2px;fill:#336699;fill-opacity:.5;}
#dial.alert{fill:#FF0000;fill-opacity:.5;}
#dialbackground{stroke:#000000;stroke-width:none;fill:none;filter:url(#MyFilter);}
#dialcenter{stroke:none;fill:#111111;filter:url(#MyFilter);}
#dialbackground-border{stroke:#DDDDDD;stroke-width:2px;fill:none;filter:url
(#MyFilter);}#low{stroke-width:3;stroke:#336699;}
#high{stroke-width:3;stroke:#FF0000;}
#XAxisTitle{letter-spacing:2;kerning:auto;font-size:14;fill:#000000;text-anchor:middle;}
#YAxisTitle{letter-spacing:2;kerning:auto;font-size:14;fill:#000000;text-anchor:middle;writing-mode:tb;}
.XAxisValue{font-size:8;fill:#000000;}
.YAxisValue{font-size:8;fill:#000000;text-anchor:end;}
.nodatafound{stroke:#000000;stroke-width:1;font-size:12;}
.AxisLine{stroke:#000000;stroke-width:2;fill:#FFFFFF;}
.GridLine{stroke:#000000;stroke-width:0.3;stroke-dasharray:2,4;fill:none;}
g.dataholder rect{stroke:#000000;stroke-width:0.5;}
.legenditem rect{stroke:#000000;stroke-width:0.5;}

Table 8-5 describes all supported CSS class. Note that certain classes only apply to specific chart types.

Table 8-5 Available Chart CSS Classes

Class Description
text Defines the appearance of text that displays in a chart.
tspan Defines the appearance of text that displays in a chart. tspan should match the definition of text.
text.title Overrides the default chart text. Use this class for title text.
text.moredatafound Defines the appearance of more datafound text.
rect.legend Creates the rectangular box that holds the chart legend.

For a remove the legend border, change rect.legend to the following:

rect.legend{fill:#CCCC99;stroke:none;} 

text.legend Defines the text that appears in the chart legend.
#background Creates the entire background for the SVG plug-in.

For a solid white background with no border, change #background to the following:

#background{fill:#FFFFFF;stroke:#FFFFFF;stroke-width:2;}

rect.chartholderbackground (Not applicable to pie and dial charts.) Creates the background of the rectangle that holds the chart data.

For a clear background, change rect.chartholderbackground to the following:

rect.chartholderbackground(display:none;)

#timestamp Only applicable if the Asynchronous Update chart attribute is set to Yes. Controls the appearance of the update timestamp test.

To disable the display of the timestamp, use defines #timestamp as follows in the Custom CSS, Inline attribute.

"#timestamp{display:none;}" 

See Also: "Enabling Asynchronous Updates"

text.tic (Dial charts only.) Defines the numbers on a dial chart.
line.tic (Dial charts only.) Defines the graduation mark that displays directly beneath the number on a dial chart.
#dial (Dial charts only.) Defines the value that displays on the dial chart.
#dial.alert (Dial charts only.) Defines a value (called an alert value) that renders on in a dial chart using a different display.
#dialbackground (Dial charts only.) Creates the background of a dial chart.
#dialcenter (Dial charts only.) Creates the center of the dial on a dial chart.
#dialbackground-border (Dial charts only.) Works in conjunction with #dialbackground to create specific graphic effect.
#low (Dial charts only.) Defines a historical low watermark of the data being displayed on a chart.
#high (Dial charts only.) Defines historical high watermark of the data being displayed on a chart.
#XAxisTitle Defines the title that appears on the X axis
#YAxisTitle Defines the title that appears on the Y axis.
.XAxisValue Defines the value that appears on the X axis.
.YAxisValue Defines the value that appears on the Y axis.
.AxisLabel Similar to axis value.
.nodatafound Defines the text element that displays if no information is available.
.AxisLine Indicates zero on charts that have negative values.
.GridLine Creates the horizontal and vertical lines on the chart.
g.dataholder rect Applies a blanket style to all data that displays in the chart.
.legenditem rect Applies a blanket style to all rectangular items in the legend.

Referencing a Custom Cascading Style Sheet

You can reference a custom cascading style sheet for a chart using the CSS section of the Chart Attributes page. When you reference an external CSS, you can reference it entirely or simply override specific styles.

To reference a custom chart CSS:

  1. Upload the CSS to Oracle HTML DB. (See "Uploading Cascading Style Sheets").

  2. Create a chart. (See "Creating a New Chart".)

  3. Navigate to the Page Definition.

  4. Under Regions, click Chart next to the region name.

    The Chart Attributes page appears.

  5. Scroll down to the CSS section.

  6. From Use Custom CSS, select Yes.

  7. To reference an external CSS exclusively:

    1. In Custom CSS, Link enter a link to a custom CSS. For example:

      #IMAGE_PREFIX#themes/theme_4/svg.css
      
      
    2. Specify that the CSS should be used exclusively. In Custom CSS, Inline enter the following:

      /**/
      
      
  8. To reference a custom CSS and override specific styles:

    1. In Custom CSS, Link enter a link to a custom style sheet. For example:

      #IMAGE_PREFIX#themes/theme_4/svg.css
      
      
    2. In Custom CSS, Inline, enter the custom CSS styles you want to override.

Specifying Custom CSS Styles Inline

You can override specific styles within the default CSS, using the Custom CSS, Inline attribute on the Chart Attributes page.

To override specific styles within the default CSS:

  1. Create a chart. (See "Creating a New Chart".)

  2. Navigate to the Page Definition.

  3. Under Regions, click Chart next to the region name.

    The Chart Attributes page appears.

  4. Scroll down to CSS.

  5. From Use Custom CSS, select Yes.

  6. In Custom CSS, Inline, enter the custom CSS styles you want to override.

Enabling Asynchronous Updates

You can create charts that monitor information by enabling the Asynchronous Update attribute on the Chart attributes page. Enabling this attribute updates the chart to reflect changes in the underlying data within a specified time interval.

To enable asynchronous updates:

  1. Create a chart. (See Creating a New Chart.)

  2. Navigate to the Page Definition.

  3. Under Regions, click Chart next to the region name.

    The Chart Attributes page appears.

  4. Scroll down to Refresh.

  5. From Asynchronous Update, select Yes.

  6. In Update Interval (Seconds), enter the interval in seconds between chart updates. For optimal performance, select an interval that is greater than 2 seconds.

When Asynchronous Update is enabled, a timestamp displays on the chart indicating that last update.

To disable the Asynchronous Update timestamp:

  1. Navigate to the Chart Attributes page.

  2. Locate the CSS section.

  3. From Use Custom CSS, select Yes.

  4. In Custom CSS, Inline edit #timestamp as follows:

    #timestamp{display:none;}
    

Displaying Charts in Other Languages

To display a chart in another language, you edit the text and tspan classes to reflect the correct language.

To display a chart in another language:

  1. Navigate to the Chart Attributes page. (See Editing Chart Attributes.)

  2. Scroll down to CSS.

  3. From Use Custom CSS, select Yes.

  4. In Custom CSS, Inline, edit the text and tspan classes to reflect the correct language. The following example demonstrates how to change a chart to Korean:

    text{font-family:Batang;fill:#000000;}
    tspan{font-family:Batang;fill:#000000;}
    
    

Creating Buttons

As you design your application you can use buttons to direct users to a specific page or URL, or to post or process information (for example, by creating Create, Cancel, Next, Previous, or Delete buttons).

Buttons can perform two different types of actions. A button can submit the page and then redirect to a URL. Alternately, a button can simply branch to a URL without submitting the page.

Topics in this section include:

Creating a Button Using a Wizard

You create a button by running the Create Button Wizard from the Page Definition. Each button resides in a region. A region is a area on a page that serves as a container for content.

To create a new button:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. If necessary, create an HTML region. (See "Customizing Regions".)

  3. Under Buttons, click the Create icon.

    The Create Button Wizard appears.

  4. Select a region to contain the button.

  5. Select a position for the button:

    • Create a button displayed among this region's items

    • Create a button in a region position

    Select Create a button displayed among this region's items to add a button to a region as if it was an item (for example, to add a button directly to the right of a form field).

  6. If you select Create a button in a region position:

    1. Specify the Button Name and Label.

    2. Select a Button Type: HTML Button (Default), Image, or Template Driven

      Select Button is Reset to create an Undo button. When enabled, this type of button resets the page values to the state they were in when the page was initially rendered.

    3. Select an Action.

      Selecting Submit page and redirect to URL submits the current page to the HTML DB engine whenever a user clicks the button.

      Selecting Redirect to URL without submitting page avoids submitting the page. Choose this action when submitting the page for processing is not necessary (for example, a Cancel button). This action avoids processing in the database and therefore reduces the load.

  7. If you select Create a button displayed among this region's items:

    1. Specify the Button Name and Sequence.

    2. Specify whether the button displays at the beginning of a new line or new field.

    3. Specify a Label.

    4. Enter the value of Request.

    5. Select the Button Style.

  8. Follow the on-screen instructions

Creating an HTML Button

Buttons can be placed in predefined region template position or among items in a form. To create an HTML button, select one of the following while running the Create Button Wizard:

  • Under Task, select Create a button in a region position

  • Under Button Type, select a button type and then HTML Button (default)

Creating Multiple Buttons

You can create multiple buttons within the same region at once using the Create Multiple Buttons Wizard.

To create multiple buttons at once:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. If necessary, create an HTML region. (See "Customizing Regions".)

  3. Under Buttons, click the Create icon.

    The Create Button Wizard appears.

  4. From the Tasks list, select Create Multiple Buttons.

    The Create Multiple Button Wizard appears.

  5. From Place Buttons in Region, select the region to contain the buttons.

  6. From Template, select a template.

  7. In HTML Attributes, Specify HTML attributes for these buttons. This text will be added to the HTML element definition. For example, you could set the class of a text button as follows:

    class="myclass"
    
    
  8. To quickly populate the remaining fields, select make a selection from the Quick Button list on the right side of the page.

  9. Click Create Buttons.

Understanding the Relationship Between Button Names and REQUEST

The name you give a button determines the value of the built-in attribute REQUEST. You can reference the value of REQUEST from within PL/SQL using the bind variable :REQUEST. By using this bind variable, you can conditionally process, validate, or branch based on which button the user clicks. You can also create processes that execute when the user clicks a button. You can also use a more complex condition as demonstrated in the following examples:

If :REQUEST in ('EDIT','DELETE') then ...
If :REQUEST != 'DELETE' then ...

These examples assume the existence of buttons named EDIT and DELETE. You can also use this syntax in PL/SQL Expression conditions. Be aware, however, that the button name case is preserved. In other words, if you name a button "LOGIN" then a request looking for the name "Login" will fail. For example:

<input type="BUTTON" value="Finish" onClick="javascript:doSubmit('Finish');">

Note that in this example Finish is the name of the REQUEST and this example is case-sensitive.

About Branching with Buttons

Each page can include any number of branches. A branch links to another page in your application or to a URL. The HTML DB engine considers branching at different times during page processing. You can choose to branch before processing, before computation, before validation, and after processing. Like any other control in Application Builder, branching can be conditional. For example, you can branch when a user clicks a button. When you create a branch, you associate it with a specific button. The branch will only be considered if a user clicks the button.

Displaying Buttons Conditionally

You can choose to have a button display conditionally by editing attributes on the Edit Pages Button page.

To have a button display conditionally:

  1. Create the button. (See "Creating a Button Using a Wizard".)

  2. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  3. Under Buttons, select the button name.

    The attributes page for the button appears.

  4. Scroll down to Conditional Button Display.

  5. Make a selection from the Condition Type list.

  6. Enter an expression in the fields provided.

  7. Click Apply Changes.

Creating Items

An item is part of an HTML form. An item can be a text field, text area, password, combobox, check box, and so on. Item attributes affect the display of items on a page. For example, these attributes can impact where a label displays, how large an item will be, and whether the item will display next to or below the previous item.

There are two types of items, page items and application items. Page items are placed on a page and have associated user interface properties, such as Display As, Label and Label Template. Application items are not associated with a page and therefore have no user interface properties. You can use an application item as a global variable.

Topics in this section include:

Creating a Page Level Item

You create a page level item by running the Create Item Wizard from the Page Definition.

To create a new page level item:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. If necessary, create an HTML region. (See "Customizing Regions".)

  3. Under Items, click the Create icon.

  4. Select an item type. (See "About Item Types".)

  5. Follow the on-screen instructions

About Item Naming Conventions

When specifying an item name, remember the following rules. Item names must:

  • Not use quotes

  • Begin with a letter or a numeral, and subsequent characters can be letters, numerals, or underscore characters

  • Be case insensitive

  • Should not exceed 30 characters

  • Cannot contain letters outside the base ASCII character set

About Item Types

When you create an item, you specify an item type. Once you create an item, these types appear on the Display As list on the Edit Page Item page. Table 8-6 describes available item types.

Table 8-6 Available Item Types

Item Type Description
Button Used to build forms in Oracle HTML DB. Use an Item Button when you want to place a button among other fields (or items) in a form. When clicked, this type of button will automatically switch the HTML DB engine to processing mode, enabling you to perform validations, execute processes, or branch the user to another page.
Display Only Oracle HTML DB uses HTML tables to render items. Use this item to control the layout of items in forms by closing a table and starting a new one.
Check box Displayed using a list of values. A list of values is required for items displayed as check boxes. The value corresponding to a checked box is returned in a single colon (:) delimited string.

The following example demonstrates how to create a single check box that returns YES. This example would display both a check box and a field label.

SELECT NULL display_text, 'YES' return_value FROM DUAL;

This example includes the additional text "Click to select."

SELECT 'Click to select' display_text, 'YES' return_value FROM DUAL;

See Also: "HTMLDB_UTIL" for information on breaking up returned values

Date Picker Displays a text field with a Calendar icon next to it. When clicked, this icon displays a small calendar from which the user can select a date and a time (optional).

If the format you need is not included in the Display As list, select Date Picker (use application format mask). When using a format mask, your application looks for the format in an item called PICK_DATE_FORMAT_MASK. Note that you need to populate this item before this item type will work.

See Also: "Populating an Alternative Date Picker Format"

File Browse Displays a text field with a "Browse..." button. This enables the user to locate a file on a local file system and upload it. Oracle HTML DB provides a table for these files to be uploaded to as well as an API to retrieve the files.
Hidden Renders an HTML hidden form element. Session state can be assigned and referenced just like a text field.
List Managers Based on a list of values. This item enables you to manage a list of items by selecting and adding to a list. The list of values display as a popup.
Multiple Select Renders as a multiselect HTML form element. When submitted, selected values are returned in a single colon delimited string. You can break up the values using the HTMLDB_UTIL API.

See Also: "HTMLDB_UTIL"

Password Renders as an HTML password form element.
Popup List of Values Renders as a text field with an icon next to it from which a user can select a value from a popup window. The list in the popup window is driven by a list of values. There are two types of Popup LOVs, one that fetches a set of rows when the window pops up and one that does not.

Popup LOV values must select two columns. For example:

SELECT ename, empno FROM emp

If one of the columns is an expression, remember to use an alias. For example:

SELECT ename||' '||job display_value, empno FROM emp

Radio Renders as an HTML radio group form element, based on a list of values. Choose Radiogroup with Submit to have the page submitted when the radio button is selected.

The following example displays employee names (ename), but returns employee numbers (empno):

SELECT ename, empno FROM emp

Select List Displays using a list of values. A list of values is required for items displayed as a select list. Select lists are rendered using the HTML form element <select>. The values in a select list are determined using a named list of values or a list of values defined at the item level. You may specify the NULL display value and NULL return value.

The following example would return employee names (ename) and employee numbers (empno) from the emp table. Note that column aliases are not required and are included in this example for clarity.

SELECT ename display_text, empno return_value FROM emp

Oracle HTML DB provides additional enhancements to a standard HTML select list:

  • Select List with Submit - Submits the page when the user changes its selected value. Upon submit, the REQUEST will be set to the name of the item that represents the select list, allowing you to execute conditional computations, validations, processes, and branches.

  • Select List with Redirect - Redirects the user back to the same page, setting ONLY the newly selected value of the select list in session state.

  • Select List Returning URL redirect - Based on a list of values with URLs as the return values. Changing the value of the select list causes the browser to redirect to the corresponding URL.

  • Select List with Branch to Page - Based on list of values with page numbers as return values. Changing the selected value in the select list causes the HTML DB engine to branch to the corresponding page.

Text Displays as an HTML text field containing a maximum of 30,000 bytes of text. You control the maximum length and display width by editing the Height and Width item attribute.
Text Area Renders as an HTML text area. This is no maximum length for an item displayed as a text area. You control the height and width by editing the Height and Width item attribute. Additional available Text Area Display As options include:
  • Text Area (auto height) - Varies the height based on the amount of text. Use this option to have a large text area when you have a lot of data and a smaller text area when you have little or no data.

  • Text Area with Counter - Includes a counter that displays the number of bytes entered in the field.

  • Text Area with Spell Checker - Provides a popup English language spell checker.

  • Text Area with HTML Editor - Provides basic text formatting controls. Note that these controls may not work in all Web browsers.

Text Available Text Control display options include:
  • Text Field - Renders as a text field.

  • Text Field (Disabled, does not save state) - Displays a read-only version of a display value from a list of values by using the item's value in session state to look up the corresponding display value in the associated list of values. The value displayed on the screen is not saved in session state upon submit.

  • Text Field (Disabled, saves state) - Displays a read-only version of a display value from a list of values by using the item's value in session state to look up the corresponding display value in the associated list of values.

  • Text Field (always submits page when Enter pressed) - Displays a read-only version of the value in session state. Upon submit, the value displayed is saved in session state.

  • Text Field with Calculator Popup - Renders as a text field with an icon next to. When clicked, the icon displays a small window containing a calculator. Calculations are placed back in the text field.


Referencing Item Values

You can reference item values stored in session state in regions, computations, processes, validation, and branches. Table 8-7 describes the supported syntax for referencing item values.

Table 8-7 Syntax for Referencing Item Values

Type Syntax Description
SQL :MY_ITEM Standard bind variable syntax for items no longer than 30 bytes. Use this syntax for references within a SQL query and within PL/SQL.
PL/SQL V('MY_ITEM') PL/SQL syntax referencing the item value using the V function.

See Also: "Oracle HTML DB APIs"

PL/SQL NV('MY_NUMERIC_ITEM') Standard PL/SQL syntax referencing the numeric item value using the NV function.

See Also: "Oracle HTML DB APIs"

Static Text &MY_ITEM Static text.
Static Text (exact) &MY_ITEM. Static text. Exact Substitution.

You can set the value of an item in your application using any of the following methods:

  • For page items, use the Source Attribute to set the item value.

    From the Page Definition, select the item name to view the Edit Page Item page. Scroll down to Source and edit the appropriate fields.

    You can also set the value of an item in any region based on PL/SQL or a process using the following syntax:

    BEGIN
     :MY_ITEM :=  'new value';
    END;
    
    
  • Pass the value on a URL reference using f?p syntax. For example:

    f?p=100:101:10636547268728380919::NO::MY_ITEM:ABC
    
    
  • Set the value using a computation. Computations are designed to set item values. For example:

    TO_CHAR(SYSDATE,'Day DD Month, YYYY');
    
    
  • Use the PL/SQL API to set an item value within a PL/SQL context. For example:

    HTMLDB_UTIL.SET_SESSION_STATE('MY_ITEM',SYSDATE);
    
    

Displaying Conditional or Read-only Items

You can choose to have an item display conditionally or as read-only by editing attributes on the Edit Pages Item page.

To display a conditional or read-only item:

  1. Create the item. (See "Creating a Page Level Item".)

  2. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  3. Under Items, select the item name.

    The attributes page for the item appears.

  4. To display an item conditionally:

    1. Scroll down to Conditional Display.

    2. Make a selection from the Condition Type list.

    3. Enter an expression in the fields provided.

  5. To make an item read-only:

    1. Scroll down to Read Only Display Settings.

    2. Make a selection from the Read Only Condition Type list.

    3. Enter an expression in the fields provided.

  6. Click Apply Changes.

Creating an Application Level Item

Application level items do not display, but are used as global variables to the application. To reference an application level item you must set a value by using an ON_NEW_INSTANCE computation.

To create a new application level item:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application name.

  3. When Application Builder appears, click Shared Components.

  4. Under Logic, select Items.

    The Application Items page appears.

  5. To create a new application item, click the Create icon.

  6. Follow the on-screen instructions.

Accessing Application Item History

You can view history of changes to application items by clicking History at the top of the Application Items page.

Populating an Alternative Date Picker Format

If you need to create a Date Picker item, but the format you need does not appear in the Display As list, you should select Date Picker (use application format mask). When an application uses this type of date picker, the HTML DB engine derives the date format from an item named PICK_DATE_FORMAT_MASK. You can populate this item in two ways:

  • By defining an application substitution string named PICK_DATE_FORMAT_MASK

  • By creating an application level item named PICK_DATE_FORMAT_MASK

Defining PICK_DATE_FORMAT_MASK as an Application Substitution String

One approach to populating PICK_DATE_FORMAT_MASK is to create an application substitution string. You define application level substitution strings on the Edit Application Attributes page. Remember that an application level substitution string is a static value and cannot be altered at runtime.

To define a new application substitution string named PICK_DATE_FORMAT_MASK:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

    Application Builder appears.

  3. Click the Edit Attributes icon.

  4. Scroll down to Static Substitution Strings.

  5. Create a new static substitution string named PICK_DATE_FORMAT_MASK:

    1. In Substitution String, enter the name PICK_DATE_FORMAT_MASK.

    2. In Substitution Value, enter a value for your for your date format (for example, Month DD, YYYY).

Defining an Application Level Item Named PICK_DATE_FORMAT_MASK

Another approach to populating PICK_DATE_FORMAT_MASK is to create an application level item named PICK_DATE_FORMAT_MASK. This approach enables you to control any items rendered as Date Picker (use application format mask) by simply setting the value of this item. Plus, you can set the value of PICK_DATE_FORMAT_MASK using a computation from anywhere within your application.

If you wish to provide the user with a list of date formats as preferences, you will need to create an application level item named PICK_DATE_FORMAT_MASK and then use a computation to set the value of this item based upon the user's selection.

Creating Lists of Values

A list of values (LOV) is a static or dynamic definition used to display a specific type of page item, such as popup lists of values, a select list, a check box, a radio group, or multiple select lists.

Topics in this section include:

Creating Named LOVs at the Application Level

You define named (or shared) LOVs at the application level by running the Create LOV Wizard and adding them to the Named List of Values repository. All LOVs can be defined as static or dynamic. Static lists are based on predefined pairs of display and return values. Dynamic lists are based on a SQL query you write that selects values from a table.

To create a named LOV:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application name.

  3. When Application Builder appears, click Shared Components.

  4. Under User Interface, select Lists of Values.

  5. To create a new LOV, click the Create icon.

  6. Follow the on-screen instructions.

    New named LOVs are added to the Named List of Values repository.

About Static LOVs

Static LOVs are based on a static list of display and return values you specify when you run the Create LOV Wizard. To create a static LOV you run the Create LOV Wizard and select the LOV type Static. Oracle HTML DB stores the display values, return values, and sort sequence you specify in the Named List of Values repository. Once you add a static LOV to the repository you can create an item and display it as a check box, radio group, select list, or popup list based on this definition.

About Popup LOVs

Using a popup LOV is a good choice for lists of values that are too large to return on a single page. Popup LOVs create an icon to the right of a standard text field. When the user clicks this icon, a popup window appears with a list of values represented as a series of links. When the user selects from this searchable list, the selected value will be placed in the text field. You control popup LOVs through templates. You can only specify one popup LOV template for each application.

Popup LOVs must be based on a query that selects two columns with different column aliases. For example:

SELECT ename name, empno id 
   FROM emp

Referencing Session State within a LOV

You can reference session state by using bind variables. In the following example, this LOV only works if the item called my_deptno contains a valid department number.

SELECT ename, empno FROM emp WHERE deptno = :my_deptno

Accessing LOV Reports

Application Builder includes a number of reports designed to help you better manage LOVs, including:

To access LOV reports:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application name.

  3. When Application Builder appears, click Shared Components.

  4. Under User Interface, select Lists of Values.

  5. Select one of the following buttons at the top of the page:

    • Edit all lists of values entries

    • Subscription

    • Utilization

    • History

  6. Follow the on-screen instructions.

Bulk Update LOV Data Values

Click Edit all lists of values entries to display the Bulk Update LOV Data Values page. Use this page to edit the display values of all static LOVs at once. To save your changes, click Apply Changes. To search for a specific name, enter keywords at the top of the page and click Go.

Subscribed LOVs

Click Subscription to display the Subscribed LOVs page. This page displays all subscribed LOVs in your application.

LOV Utilization

Click Utilization to display the LOV Utilization page. This page displays LOVs used in the current application. To edit an LOV, click the LOV name.

LOV Change History

Click History to display the LOV Change History page. This page displays a history of recently changed LOVs by date.

Creating Calendars

Oracle HTML DB includes a built-in wizard for generating a calendar. Once you specify the table on which the calendar is based you can create drill down links to information stored in specific columns.

Topics in this section include:

About Creating Calendars

Oracle HTML DB supports two calendar types:

  • Easy Calendar creates a calendar based on schema, table, and columns you specify. The wizard prompts you to select a date column and display column.

  • SQL Calendar creates a calendar based on a SQL query you provide. The SQL SELECT statement you provide must include at least two columns, a date column and display column.

The date column determines which days on the calendar will contain entries. The display column defines a specific row that will display a calendar date.

Supported Calendar Substitution Strings

Oracle HTML DB supports a number of date format substitution strings. You can view a complete list of supported substitution strings on the Calendar Templates page.

To view a list of supported substitution strings for calendars:

  1. Navigate to the appropriate calendar template.

  2. Expand the Substitution Stings list on the right side of the page.


See Also:

See "Viewing Templates"

Creating a New Calendar

How you create a calendar depends upon whether you are adding a calendar to an existing page, or adding a calendar on a new page.

Adding a Calendar to an Existing Page

To add a calendar to an existing page:

  1. Navigate to the Page Definition.

  2. Under Regions, click the Create icon.

    The Create Region Wizard appears.

  3. Select Calendar.

  4. Select the type of calendar you wish to create:

    • Easy Calendar creates a calendar based on the date column and display column you specify.

    • SQL Calendar creates a calendar based on a SQL query you provide.

  5. Follow the on-screen instructions.

Adding a Calendar to a New Page

To create a calendar on a new page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. Click Create Page.

  4. When prompted for the type of page to create, select Page with Component.

  5. Select the component type Calendar.

  6. Select the type of calendar you wish to create:

    • Easy Calendar creates a calendar based on the date column and display column you specify.

    • SQL Calendar creates a calendar based on a SQL query you provide.

  7. Follow the on-screen instructions.

Converting an Easy Calendar to a SQL Calendar

Creating an Easy Calendar is the simplest way to create a calendar in Oracle HTML DB. However, if you find the resulting calendar does not meet your needs, you can quickly convert it to SQL Calendar.

To convert an Easy Calendar to a SQL Calendar:

  1. Navigate to the Page Definition.

  2. Under Regions, click CAL next to the region name.

    The Calendar Attributes page appears.

  3. From the Tasks list, select Convert to SQL Based calendar.

    Converting an Easy Calendar to a SQL Calendar, adds a Region Source section to the Region Definition. The Region Source contains the original SQL query that creates the calendar. By having accessing the Region Source, you can easily edit the query to meet your needs.

Editing a Calendar Title

The title that appears at the top of calendar corresponds to the region title.

To alter the region title:

  1. Navigate to the Page Definition.

  2. Under Regions, select the region name.

    The Region Definition appears.

  3. Under Region, enter a new title.

  4. Click Apply Changes.

Editing Calendar Attributes

Once you have created a calendar you can alter how it appears by editing its attributes.

Topics in this section include:

Accessing the Calendar Attributes Page

To access the Calendar Attributes page:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Regions, click CAL next to the region name.

    The Calendar Attributes page appears. The topics that follow describe the specific sections of the Calendar Attributes page.

Calendar Display

Use Calendar Display to specify a calendar template, date columns, and general calendar formatting.

Calendar Template determines what template is used when the HTML DB engine renders a calendar. Date Column defines the column from the table or query containing the dates to be placed on the calendar. Display Column defines a specific row that displays on a calendar date.

To select another Display Column:

  1. Navigate to the appropriate Calendar Attributes page.

  2. Locate the Calendar Display section.

  3. To specify another display column, make a selection from the Display Column list.

  4. Click Apply Changes.

To specify a custom Display Column:

  1. Navigate to the appropriate Calendar Attributes page.

  2. Locate the Calendar Display section.

  3. From Display Type, select Custom.

  4. In Column Format enter a custom column format. You can use an HTML expression and supported substitution strings.

  5. Click Apply Changes.

Calendar Interval

Use Calendar Interval to define the dates which are included in the calendar.

Begin At Start Of Interval determines when the calendar should start. Selecting this option creates a calendar that spans an entire interval (for example, a month). For example:

  • If Begin at start of interval is selected, the date is June 15th, and the display is monthly, the resulting calendar spans from June 1st to June 30th.

  • If Begin at start of interval is not selected, the date is June 15th, and the display is monthly, the resulting calendar spans from June 15th to June 30th.

Date Item holds the date on which the calendar is based.

The next two attributes define which items hold the calendar start date and end date. You can use these attributes to create calendars that span multiple months at a time. Item Containing Start Date points to an item that holds the start date of the calendar. Item Containing End Date points to an item that holds the end date of calendar. Note that format of the date of either item must be YYYMMDD.

Start of Week determines the day of the week on which the calendar starts.

Column Link

Use Column link to create a link on the column in the calendar.

To create a column link to another page:

  1. Navigate to the appropriate Calendar Attributes page.

  2. Scroll down to Column Link.

  3. From Target is a, select Page in this Application.

  4. In Page, specify the target page number. To reset pagination for this page, select reset pagination for this page.

  5. In Request, specify the request to be used.

  6. In Clear Cache, specify the pages (that is, the page numbers) on which to clear cache. Specify multiple pages by listing the page numbers in a comma delimited list.

    You can set session state (that is, give a listed item a value) using the next two attributes:

  7. To set session state:

    1. Set these items - Enter a comma delimited list of item names for which you would like to set session state.

    2. With these values - Enter a comma delimited list of values for the items specified in the previous step.

      You can specify static values or substitution syntax (for example, &APP_ITEM_NAME.). Note that item values passed to f?p= in the URL may not contain a colon (:). Additionally, item values may not contain commas unless you enclose the entire value in backslash characters (for example, \1234,56\).

  8. Click Apply Changes.

To create a column link to a URL:

  1. Navigate to the appropriate Calendar Attributes page.

  2. Scroll down to Column Link.

  3. From Target is a, select URL.

  4. In URL, enter the appropriate address.

  5. Click Apply Changes.

Day Link

Use Day link to create link on a day in the calendar. This attribute creates a link on an actual numeral (or day) on the calendar.

To create a day link to another page:

  1. Navigate to the appropriate Calendar Attributes page.

  2. Scroll down to Day Link.

  3. From Target is a, select Page in this Application.

  4. In Page, specify the target page number.

    To reset pagination for this page, select reset pagination for this page.

  5. In Request, specify the request to be used.

  6. In Clear Cache, specify the pages (that is, the page numbers) on which to clear cache. Specify multiple pages by listing the page numbers in a comma delimited list.

    You can set session state (that is, give a listed item a value) using the next two attributes:

  7. To set session state:

    1. Set these items - Enter a comma delimited list of item names for which you would like to set session state.

    2. With these values - Enter a comma delimited list of values for the items specified in the previous step.

      You can specify static values or substitution syntax (for example, &APP_ITEM_NAME.). Note that item values passed to f?p= in the URL may not contain a colon (:). Additionally, item values may not contain commas unless you enclose the entire value in backslash characters (for example, \1234,56\).

  8. Click Apply Changes.

To create a day link to a URL:

  1. Navigate to the appropriate Calendar Attributes page.

  2. Scroll down to Day Link.

  3. From Target is a, select URL.

  4. In URL, enter the appropriate address.

  5. Click Apply Changes.

Utilizing Shortcuts

By using shortcuts you can avoid repetitive coding of HTML or PL/SQL functions. You can use a shortcut to define a page control such as a button, HTML text, a PL/SQL procedure, or HTML. Once defined, you can invoke a shortcut using specific syntax unique to the location in which the shortcut is used. Shortcuts can be referenced many times, thus reducing code redundancy.

This section contains the following topics:

About Shortcut Types

When you create a new shortcut, you must specify the type of shortcut you wish to create. Oracle HTML DB supports the following shortcut types:

  • PL/SQL Function Body

  • HTML Text

  • HTML Text with Escaped Special Characters

  • Image

  • Text with JavaScript Escaped Single Quotes

  • Message

  • Message with JavaScript Escaped Special Quotes

Text with JavaScript Escaped Single Quotes

Use this type of shortcut to reference a shortcut inside of a JavaScript literal string. This shortcut defines a text string. When the shortcut is referenced, it escapes the single quotes required for JavaScript.

Message

Use this type of shortcut to reference a translatable message at runtime. Note that since this shortcut does not have a shortcut body, the name of the shortcut must match the corresponding message name. At runtime, the name of the shortcut expands to the text of the translatable message for the current language.

Message with JavaScript Escaped Single Quotes

Use this type of shortcut to reference a shortcut inside of JavaScript literal string and reference a translatable message at runtime.

Defining Shortcuts

Before you can incorporate a shortcut in your application, you must define it and add it to the Shortcuts repository. You reference new shortcuts using the following syntax:

"MY_SHORTCUT"

Note that the shortcut name must be capitalized and enclosed in quotes.

To define a new shortcut:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application name.

  3. When Application Builder appears, click Shared Components.

  4. Under User Interface, select Shortcuts.

  5. Click Create.

  6. Select one of the following creation methods:

    • From Scratch

    • As a Copy of an Existing Shortcut

  7. Follow the on-screen instructions.

New shortcuts are added to the Shortcut repository and are available for use within the following locations:

Accessing Shortcut Reports

Application Builder includes a number of reports designed to help you better manage LOVs, including:

To access of report detailing recent shortcut changes:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application name.

  3. When Application Builder appears, click Shared Components.

  4. Under User Interface, select Shortcuts.

  5. Click Create.

  6. Follow the on-screen instructions.

Subscribed Shortcuts

Click Subscription to display the Subscribed Shortcuts page. This page displays all subscribed shortcuts in your application.

Shortcut History

Click History to display the Shortcut History page. This page displays a history of recently changed shortcuts by date.

Incorporating JavaScript into an Application

Adding JavaScript to a Web applications is a great way to add features that mimic those found client/server applications without sacrificing all of the benefits of Web deployment. Oracle HTML DB includes multiple built-in interfaces (or "hooks") especially designed for adding JavaScript.

Remember that JavaScript is not appropriate for data intensive validations. For example, to verify that a name is contained within a large database table, you would need to pull down every record to the client, creating a huge HTML document. In general, complex operations are much better suited for server-side HTML DB validations instead of JavaScript.

This section contains the following topics:

About Referencing Items Using JavaScript

When you reference an item, the best approach is to reference by ID. If you view the HTML source of an Oracle HTML DB page in a Web browser, you would notice that all items have an ID attribute. This ID corresponds to name of the item, not the item label. For example, if you create an item with the name P1_FIRST_NAME and a label of First Name, the ID will be P1_FIRST_NAME.

Knowing the item ID enables you to use the JavaScript function getElementById to get and set item attributes and values. The following example demonstrates how to reference an item by ID and display its value in an alert box.

<script language="JavaScript1.1" type="text/javascript">
  function firstName(){    
    alert('First Name is ' + document.getElementById('P1_FIRST_NAME').value );
  }
 // or a more generic version would be
  function displayValue(id){    
    alert('The Value is ' + document.getElementById(id).value );
  }
</script>
 
  // Then add the following to the "Form Element Attributes" Attribute of the item:
  onChange="javascript:displayValue('P1_FIRST_NAME');"

While it is possible to reference items using the HTML form element attribute name (represented in the previous example as form p_t01), this is strongly discouraged. Remember that the name attribute is dynamic and is determined at when a page is rendered. For example, suppose the first element rendered on a page is p_t01 and the second is p_t02. If you write a function that references p_t01 and then create a new item on the page that appears first, the item that was p_t01 will now be p_t02 and your function will break.

How to Incorporate JavaScript Functions

There are two primary places to include JavaScript functions:

  • In the HTML Header attribute of the page

  • In a .js file in the page template.


See Also:

"Text with JavaScript Escaped Single Quotes" for information on referencing a shortcut inside of a JavaScript literal string

Incorporating JavaScript in the HTML Header Attribute

One way to include JavaScript into your application is add it to the HTML Header attribute of the page. This is good approach for functions that are very specific to a page as well as a convenient way to test a function before you include it in the .js file.

You can add JavaScript functions to a page by simply entering the code into the HTML Header attribute of the Page Attributes page. For example, adding following would test function accessible from anywhere on the current page.

<script language="JavaScript1.1" type="text/javascript>
  function test(){
    alert('This is a test.');
  }
</script>


See Also:

"HTML Header"

Including JavaScript in a .js File in the Page Template

In a .js file in the page template. This is the most efficient approach since a .js file loads on the first page view of your application and is then cached by the browser.

The following demonstrates how to include a .js file in the header section of a page template.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
    <title>#TITLE#</title>
    #HEAD#
    <script src="#APP_IMAGES#custom.js" type="text/javascript"></script>
</head>
<body #ONLOAD#>#FORM_OPEN#


See Also:

"Page Templates"

Calling JavaScript from a Button

Calling a JavaScript from a button is a great way to confirm a request. Oracle HTML DB actually uses this technique for the delete operation of most objects. For example, when you delete a button, a JavaScript Alert Box appears asking you to confirm your request. Consider the following example:

<script language="JavaScript1.1" type="text/javascript">
  function deleteConfirm(msg)
  {
var confDel = msg;
if(confDel ==null)
  confDel= confirm("Would you like to perform this delete action?");
else
  confDel= confirm(msg);
  
if (confDel== true)
  doSubmit('Delete');
  }
</script>

This example creates a function to confirm a delete action and then calls that function from a button. Note that the function optionally submits the page and sets the value of the internal variable :REQUEST to Delete, thus performing the delete using a process that conditionally executes based on the value of request.

Note that when you create the button you would need to select Action Redirect to URL without submitting page. Then, you would specify a URL target such as the following:

javascript:confirmDelete('Would you like to perform this delete action?');

Creating Dependent Select Lists

You may use a select list to determine the range of values of another select list on the same page. You can achieve this functionality by having a driving select list submit values to a subsequent select list. You incorporate these values in the subsequent select list as a bind variable in the WHERE clause of its query.

You can have one LOV drive another LOV by:

  • Creating a basic form.

  • Defining two list of values. Note that the driving LOV must submit the page after a value is chosen.

  • Defining a branch that branches back to the current page.

Consider the following example. The first LOV enables the user to pick a state.

SELECT state_name d, state_id v
FROM states

The second LOV selects the country name and country ID based on the state selected in the first LOV.

SELECT county_name d, county_id v
  FROM counties
WHERE state_id = :Px_STATE_ID

Creating a Help Page

Oracle HTML DB includes built-in attributes to make creating help for your application quick and easy. Creating help for your application involves the following steps:

  • Create a dedicated help page and help region

  • Define page help text

  • Define item help text

  • Create a navigation bar icon to link to your help page

Help created in Oracle HTML DB displays on a dedicated help page. To access help, users click a link that takes them to a dedicated help page. This help page displays page and item help topics specific to the page they are viewing.

Topics in this section include:

Creating a Help Page and Region

The first step in creating a help for your application it to create a dedicated page and Help Text region.

To create a new Help Text region:

  1. Create new page for your help. (See "Adding Additional Pages".)

  2. Navigate to the Page Definition of your help page. (See "Viewing a Page".)

  3. Under Regions, the Create icon.

  4. When prompted to select a region type, select Help Text.

  5. Follow the on-screen instructions.

Defining Help Text

You define help text for a page or single item by editing attributes. Ideally, you would define these attributes as you create your application. For simplicity, however, the following procedures describe how to define this text after the fact.

To define page help text:

  1. Navigate to the Page Definition for the page for which you want to add page help. (See "Viewing a Page".)

  2. Click Edit Attributes to view the existing page attributes.

  3. Scroll down to Page Help Text.

  4. Enter your help text in the field provided.

  5. Click Apply Changes.

Repeat the previous procedure for each page requiring page help text.

To define item help text:

  1. Navigate to the Page Definition for the page for which you want to add item help.

  2. Under Items, click name of the item you want to edit.

  3. Scroll down to Help Text.

  4. Enter your help text in the field provided.

  5. Click Apply Change.

Repeat the previous procedure for each item requiring help text.

About the Item Help Text Report

If you are including item help in your application, you can edit multiple item help topics at once using the Bulk Edit Item Help report.

To view the Bulk Edit Item Help report:

  1. Navigate to the Workspace home page.

  2. Select an application name from the Applications list.

  3. From the Tasks list, select View Application Reports.

    Application Reports page appears.

  4. Select Item Help Text.

  5. Under Item Help Text column, make the appropriate edits.

  6. Click Apply Changes.

Creating a Help Navigation Bar Icon

Once you have created your help, the next step is to create a navigation bar icon so users can link to it.

To create a navigation bar icon:

  1. Navigate to the Page Definition. (See "Viewing a Page".)

  2. Under Navigation Bar, click the Create icon.

  3. Specify the appropriate NavBar entry attributes:

    • Sequence

    • Alt Tag Text

    • Icon Image Name

    • Image Height and Image Width

    • Text

    Specify the target location.

  4. To specify the target location:

    • From Target type, select Page in this application.

    • In Page, specify the page number.

    • In Request, type:

      &APP_PAGE_ID.
      
      

    By specifying substitution string &APP_PAGE_ID as the Request, you are instructing the HTML DB engine to display help text for the current page when the user clicks this icon.

PK0v;xPK(oUIOEBPS/datashop.htm[& Managing Data with Data Workshop

4 Managing Data with Data Workshop

This section describes how to use Data Workshop to import data and export data using a Web Browser.

This section contains the following topics:

About Data Workshop

Oracle HTML DB renders information stored in an Oracle database to create a collection of database-driven Web pages called an application. Using Data Workshop you can import data into and export data from the hosted database. Supported import formats include:

  • Text such as comma or tab delimited data

  • XML documents

  • Spreadsheets

Supported export formats include:

  • Text such as comma or tab delimited data

  • XML documents

To access Data Workshop:

  1. Click the Data Workshop icon on the Workspace home page. (See Figure 4-1.)

    Figure 4-1 Data Workshop Icon

    Description of htmldb_datico.gif follows


  2. Under Data Import and Data Export, click the appropriate link.

Importing Data

You can use Data Workshop to import text files, XML documents, and data stored in a spreadsheet into an Oracle database.

Topics in this section include:

Importing a Text File

For files less than 30KB, you can copy and paste tab delimited data directly into the Import Text Wizard. For files larger than 30KB, you must upload a separate file.

To load a text file:

  1. Click Data Workshop on the Workspace home page.

  2. Under Data Import, click Import Text Data.

    The Data Import Wizard appears.

  3. Under Import To, select either Existing table or New table.

  4. Under Import from, select either Upload file or Copy and paste.

  5. Follow the on-screen instructions.

Importing an XML Document

Data Workshop supports the import of XML documents adhering to the Canonical XML specification.

To import an XML document:

  1. Click Data Workshop on the Workspace home page.

  2. Under Data Import, click XML Import.

    The Import XML Wizard appears.

  3. Follow the on-screen instructions.

Importing Spreadsheet Data

You can load spreadsheet data by either copying and pasting text, or by importing a file. To copy and paste text, the spreadsheet file must be less than 30KB. For files larger than 30KB, you can import the file in a delimited format (such as comma delimited (.csv) or tab delimited), upload the file, and then load the data into a new or existing table.

To import spreadsheet data:

  1. Click Data Workshop on the Workspace home page.

  2. Under Data Import, click Import Spreadsheet Data.

    The Import Spreadsheet Data Wizard appears.

  3. Under Import to, select either Existing table or New table.

  4. Under Import from, select either Upload file or Copy and paste.

  5. Follow the on-screen instructions.

Exporting Data

You can also use Data Workshop to export the contents of a table to a text file or XML document.

Topics in this section include:

Exporting to a Text File

Use the Export Text Data Wizard to export the contents of a table to a text file. For example, you could export an entire table to a comma delimited file (.csv).

To export a table to a text file:

  1. Click Data Workshop on the Workspace home page.

  2. Under Data Export, click Export Text Data.

    The Export Text Data Wizard appears.

  3. Follow the on-screen instructions.

You select the schema and choose the table and columns to be exported. You can also specify the type of separator to be used to separate column values as well as whether column text strings are identified using single or double quotation marks.

Exporting to an XML Document

Use the Export XML Wizard to export the contents of a table to an XML document adhering to the Canonical XML specification.

To export a table to an XML document:

  1. Click Data Workshop on the Workspace home page.

  2. Under Data Import, click XML Export.

    The Export XML Wizard appears.

  3. Follow the on-screen instructions.

You select the schema and choose the table and columns to be exported.

PKa`&[&PK(oUIOEBPS/condition.htmRs Available Conditions

A Available Conditions

A condition is a small unit of logic that helps you control the display of regions, items, buttons, and tabs as well execute processes, computations and validations. When you apply a condition to a control or component, the condition is evaluated. Whether a condition passes or fails determines whether a control or component displays, or page processing executes.

You can specify conditions by selecting a condition type when you create the control (region, button, or item) or component (tab, list, or navigation bar), or by making a selection under the conditional display attribute.

Conditions Available in Oracle HTML DB

The following table describes some commonly used conditions. To view a complete listing of all available conditions for a given control or component, click the View icon to the right of the Conditional Display Type list. Shortcuts to common selections appear directly beneath the Type list. If your condition requires an expression, type it in the appropriate field.

Table A-1 describes the conditions available in Oracle HTML DB.

Table A-1 Available Conditions

Condition Description
Always Always returns true. Used primarily for the read-only conditions of a page item
Current Language != Expression 1 Verifies the language setting in which the client browser is not currently running. Evaluates to true if the current language is contained within the string entered in Expression 1.
Current Language = Expression Verifies the language setting in which the client browser is currently running. Evaluates to true if the current language matches the value entered in Expression 1.
Current Language is contained within Expression 1 Determines whether the browser current language is contained within a string. Evaluates to true if the current language matches the string entered in Expression 1.

For example, to check if the current language is either en-US or en-GB, choose this condition and enter the following string in Expression 1:

en-us,en-gb
Current Language is not contained within Expression 1 Verifies the application's current language is not contained within a specified string. Evaluates to true if the current language is not contained within the string entered in Expression 1.
Current page != Expression 1 Evaluates to true if the current page does not equal the page you specify in Expression 1.
Current Page != Page Submitted (this page was not the page posted) Determines if the specified page was not posted. Evaluates to true if the current page does not match the value entered in Expression 1.
Current page = Expression 1 Evaluates to true if the current page equals the page you specify in Expression 1.
Current Page = Page Submitted (this page was posted) Verifies the whether the specified page was posted. Evaluates to true if the current page matches the value entered in Expression 1.
Current Page is contained within Expression 1 (comma delimited list of pages) Verifies if the current page is part of the list of pages you specify in Expression 1. To check if the current page is in either page 1, 2, 3 or 4, select this condition type and enter the following string in Expression 1:
1,2,3,4
Current page is in Printer Friendly mode Only displays certain page control or components when the user has selected printer friendly mode. If the current page is in printer friendly mode, then the condition evaluates to true. Use f?p syntax to specify printer friendly mode.
Current page is not in Printer Friendly mode Hides page controls or components when printer friendly mode is selected. Use f?p syntax to specify printer friendly mode.

See Also: "Using f?p Syntax to Link Pages" for more information on f?p syntax

Current Page not in Expression 1 (comma delimited list of pages) Verifies if the current page is not part of the comma separated list of pages specified in Expression 1.
Exists (SQL query returns at least one row) This condition is expressed as a SQL query. If the query returns at least one row then the condition evaluates as true. For example:
select 1 from emp where deptno = :P101_DEPTNO

This example references item P101_DEPTNO as a bind variable. You can use bind variables a within an application processes and SQL query regions to reference item session state. If one or more employees are in the department identified by the value of P101_DEPTNO then the condition evaluates as true.

See Also: "About Bind Variables" for more information on bind variables

Never This condition type is hard wired to always fail. It is useful in temporarily preventing controls or components (such as regions, buttons, or items) from being rendered on a page, or to prevent processes, computations and validations from running.
NOT Exists (SQL query returns no rows) This condition is expressed as a SQL query. If the query does not return any rows, it evaluates as true.
PLSQL Expression A PL/SQL expression is any expression in valid PL/SQL syntax that evaluates to true or false. For example:
nvl(:MY_FLOW_ITEM,'NO') = 'YES'

If the value of MY_FLOW_ITEM is YES then the condition evaluates as true. Otherwise it evaluates as false.

PLSQL Function Body returning a boolean The body of a PL/SQL function that returns true or false. For example:
BEGIN
IF :P1_DAY = 'MONDAY' THEN
    RETURN TRUE;
ELSE
    RETURN FALSE;
END;

Request != Expression 1 REQUEST is an internal attribute that tracks of how a page is submitted. By default, when a page is submitted, the value of the application attribute REQUEST is set according the name of the object that caused the page to be submitted. For a regular button, REQUEST is set as the name of the button (such as CANCEL or SAVE) not the label of the button. You can also set request using f?p syntax.

For example, the event could be when a user clicks a button or selects a tab menu. Depending upon the event, you can perform different operations by referencing the value of the REQUEST application attribute.

This condition evaluates as true if REQUEST does not equal the value entered in Expression 1.

See Also: "Understanding URL Syntax", "REQUEST", and "Understanding the Relationship Between Button Names and REQUEST"

Request = Expression 1 This condition is the opposite of Request != Expression 1.

This condition evaluates as true if REQUEST equals the value entered in Expression 1. From PL/SQL you can also reference the application attribute using the following syntax:

V('REQUEST')

See Also: "Understanding URL Syntax", "REQUEST", and "Understanding the Relationship Between Button Names and REQUEST"

Request is contained within Expression 1 REQUEST is an internal application attribute that tracks of how a page is submitted. By default, when a page is submitted, the value of REQUEST is set according to the event that caused the page to be submitted. For example, the event could be when a user clicks a button or selects a tab. Depending upon the event, you can perform different operations by referencing the value of the REQUEST application attribute.

Use this condition to specify a list of allowed requests (such as SAVE or UPDATE) in Expression 1. The condition evaluates to true if the value of REQUEST is contained in the list.

See Also: "REQUEST", and "Understanding the Relationship Between Button Names and REQUEST"

Request is not contained within Expression 1 This condition is the opposite of Request is contained within Expression 1. Evaluates to true if the value of the REQUEST is not contained within Expression 1.

See Also: "REQUEST", and "Understanding the Relationship Between Button Names and REQUEST"

SQL Expression SQL Expressions are evaluated as a WHERE clause in a SQL statement. For example suppose your expression is :MY_ITEM = 'ABC'.

The HTML DB engine processes the following:

select 1 from dual where :MY_ITEM = 'ABC'

This condition evaluates to true if a row is returned.

SQL Reports (OK to show the back button) Use this condition for reports having pagination. It automatically determines when it is appropriate to include a button that pages back in the result set.
SQL Reports (OK to show the forward button) Use this condition for reports having pagination. It automatically determines when it is appropriate to include a button that pages forward in the result set.
Text in Expression 1 != Expression 2 (includes &amp;ITEM substitutions) Use this expression to compare two expressions containing strings. Either expression may contain references to session state using &MY_ITEM syntax.

See Also: "Using Substitution Strings" for more information on &MY_ITEM syntax

Text in Expression 1 = Expression 2 (includes &amp;ITEM substitutions) This condition is the opposite of Text in Expression 1 != Expression 2 (includes &amp;ITEM substitutions). Compares two expressions containing strings. Either expression may contain references to session state using the &ITEM. syntax.

To check if the item F100_P2_DAY_DATE equals "Wednesday", select this condition enter the following in Expression 1 and Expression 2:

  • Expression 1: F100_P2_DAY_DATE

  • Expression 2: Wednesday

See Also: "Using Substitution Strings" for more information on &MY_ITEM syntax

User is authenticated (not public) Verifies whether the current user was authenticated using one of the built-in authentication schemes or a custom authentication scheme.

See Also: "Providing Security Through Authorization" for more information on authentication

User is the public user (user has not authenticated) The public user is defined as an application attribute. To set the public user for a specific application, navigate to the Application Builder home page and click the edit link corresponding to your application.

A public user is a user used for multiple users. Sometimes applications have pages that are public and thus require authentication and log in. This condition returns true if the user is the public user (that is, the user is authenticated as themselves or some other user not equal to the public user identified in the application attribute Public User.

See Also: "Session Management"

Value of Item in Expression 1 != zero Verifies if the value of the item in Expression 1 does not equal zero.
Value of item in Expression 1 = Expression 2 Compares the value of an item with a specific string. Comparisons using this condition are case-sensitive.

For example, to verify whether the value of an item F100_P2_WORD is contained within the string "the quick brown fox", enter the following in the Expression 1 and Expression 2 fields:

  • Expression 1: F100_P2_WORD

  • Expression 2: the quick brown fox

Value of Item in Expression 1 = zero Verifies if the value of the item in Expression 1 does equal zero.
Value of item in Expression 1 contains no spaces Evaluate to true if the value of the item specified in Expression 1 contains no spaces.
Value of Item in Expression 1 is alphanumeric Evaluates to true when the string in Expression 1 contains only alphanumeric characters.
Value of Item in Expression 1 is contained within colon delimited list in Expression 2 Use this condition type to check whether a certain string is contained within the value of a session state item. Verifies whether the string specified in Expression 1 is contained in the value of the item specified in Expression 2.
Value of Item in Expression 1 is NOT contained within colon delimited list in Expression 2 Evaluates to true when the value specified in Expression 1 contains a string that lists elements delimited by colons.

To check if the item P1_TODAY is either "Monday", "Tuesday", or "Wednesday", select this condition and enter the following in Expression 1 and Expression 2:

  • Expression 1: P1_TODAY

  • Expression 2: Monday: Tuesday:Wednesday

Value of Item in Expression 1 is NOT NULL In Expression 1, enter the name (upper case) of the application or page item. Evaluates as true, if the current cache value of the item is not null and has a value. If not, the condition evaluates as false.
Value of Item in Expression 1 is NULL Evaluates as true if the item in Expression 1 has no value.
Value of Item in Expression 1 is NULL or zero Evaluates as true if the item in Expression is either NULL or zero.
Value of item in Expression 1 is numeric Evaluates to true if the value of the Item in Expression 1 is numeric.
Value of user preference in Expression 1 != Expression 2 This condition is the opposite of Value of user preference in Expression 1 = Expression 2. Evaluates to true if the name of the user preference specified in Expression 1 is not equal to the string in Expression 2.
Value of user preference in Expression 1 = Expression 2 Verifies the value of a user preferences. Evaluates to true if the name of the user preference specified in Expression 1 is equal to the string in Expression 2.
When any item in comma delimited list of items has changed Evaluates to true when the value of any non NULL session state item in the list of items specified in Expression 1 has changed.
When any item in comma delimited list of pages has changed Evaluates to true when the value of any non NULL session state item in the list of pages specified in Expression 1 has changed.
When any item in current application has changed This condition passes when the value of any non NULL session state item in the current application has changed.
When any item in current page has changed Evaluate to true when the value of any non NULL session state item in the current page has changed.
When any item in current session has changed Evaluates to true when the value of any non NULL session state item in the current session has changed.
When cgi_env DAD_NAME != Expression 1 This condition is the opposite of When cgi_env DAD_NAME = Expression 1.

Checks for the DAD (Database Access Descriptor) that is being used in the URL to call the current page in the application and compares it to Expression 1. Evaluate to true, when the DAD is not the same as Expression 1.

When cgi_env DAD_NAME = Expression 1 Checks for the DAD (Database Access Descriptor) that is being used in the URL to call the current page in the application and compares it to Expression 1. Evaluate to true, when the DAD is the same as Expression 1.
When cgi_env HTTP_HOST != Expression 1 This condition is the opposite of When cgi_env HTTP_HOST = Expression 1.

Checks for the value of the CGI environment variable HTTP_HOST that is the value returned by owa_util.get_cgi_env ('HTTP_HOST'). Evaluate to true, when this value is not equal to the string in Expression 1.

When cgi_env HTTP_HOST = Expression 1 Checks for the value of the CGI environment variable HTTP_HOST that is the value returned by owa_util.get_cgi_env ('HTTP_HOST'). Evaluate to true, when this value is equal to the string in Expression 1.
When cgi_env SERVER_NAME != Expression 1 This condition is the opposite of When cgi_env SERVER_NAME = Expression 1.

This condition checks for the value of the CGI environment variable SERVER_NAME, that is the value returned by owa_util.get_cgi_env ('SERVER_NAME'). Evaluate to true, when this value is not equal to the string in Expression 1.

When cgi_env SERVER_NAME = Expression 1 This condition checks for the value of the CGI environment variable SERVER_NAME, that is the value returned by owa_util.get_cgi_env ('SERVER_NAME'). Evaluate to true, when this value is equal to the string in Expression 1.

PK'?@WsRsPK(oUIOEBPS/blafdoc.css/* blafdoc.css */ /* Release 1.1.0 */ /* Copyright 2002, 2003 Oracle. All rights reserved. */ /* ========================================================================== */ BODY { font-family : Arial, Helvetica, Geneva, sans-serif; background-color : #FFFFFF; color : #000000; } BODY, P, TABLE, TD, TH, OL, UL, A, DL, DT, DD, BLOCKQUOTE, CAPTION { font-family : Arial, Helvetica, Geneva, sans-serif; font-size : small; } A:link { color : #663300; background-color : #FFFFFF; } A:active { color:#ff6600; background-color : #FFFFFF; } A:visited { color:#996633; background-color : #FFFFFF; } A.glossary-link { border-bottom : 1px dotted; text-decoration : none; } H1, H2, H3, H4 { font-family: Arial, Helvetica, Geneva, sans-serif; color: #336699; background-color : #FFFFFF; } H1 { font-size : 1.6em; font-weight: bold; border : solid #CCCC99; border-width : 0px 0px 1px 0px; width : 100%; } H2 { font-size:1.3em; font-weight: bold; } H3 { font-size:1.1em; font-weight: bold; } H4 { font-size:1em; font-weight: normal; } H1 A, H2 A, H3 A, H4 A { font-size: 100%; } PRE, CODE { font-family: Courier, "Courier New", monospace; font-size:1em; } CODE { color: #336699; } CODE .code-comment { color: #000000; } H1 A CODE, H2 A CODE, H3 A CODE, H4 A CODE { color: #336699; font-weight: bold; } A:link CODE { color: #663300; } A:active CODE { color: #ff6600; } A:visited CODE { color: #996633; } TABLE { font-size: small; } CAPTION { text-align : center; font-weight : bold; width: auto; } TD { vertical-align : top; } TH { font-weight: bold; text-align: left; vertical-align : bottom; color: #336699; background-color: #FFFFFF; } TABLE.table-border { border : 1px solid #CCCC99; } TABLE.table-border TD, TABLE.table-border TH { padding : 2px 4px 2px 4px; background-color: #FFFFFF; border : 1px solid #CCCC99; } TABLE.table-border TH.table-header-border-left, TABLE.table-border TH.table-header-border-middle, TABLE.table-border TH.table-header-border-right { background-color: #cccc99; color: #336699; } TABLE.table-border TH.table-header-border-left { border-left : 1px solid #CCCC99; border-right : 1px solid #FFFFFF; background-color: #cccc99; } TABLE.table-border TH.table-header-border-middle { border-left : 1px solid #FFFFFF; border-right : 1px solid #FFFFFF; background-color: #cccc99; } TABLE.table-border TH.table-header-border-right { border-left : 1px solid #FFFFFF; border-right : 1px solid #CCCC99; background-color: #cccc99; } SPAN.gui-object { font-weight: bold; } P.horizontal-rule { width : 100%; border : solid #CCCC99; border-width : 0px 0px 1px 0px; margin-bottom : 2em; } div.zz-skip-header { margin-bottom : 0px; margin-top : -2px; padding : 0px; text-align:center; line-height : 1px; } div.zz-skip-header a:link, div.zz-skip-header a:visited, div.zz-skip-header a:active { color:white; background-color:white; text-decoration:none; font-size:.1em; line-height : 1px; } TD.zz-nav-header-cell { text-align : left; font-size : small; width : 99%; color:#000000; background-color : #FFFFFF; font-weight : normal; vertical-align : top; margin-top : 0px; padding-top : 0px; } A.zz-nav-header-link { font-size : small; } TD.zz-nav-button-cell { text-align : center; width : 1%; vertical-align : top; padding-left : 4px; padding-right : 4px; margin-top : 0px; padding-top : 0px; } A.zz-nav-button-link { font-size : x-small; } DIV.zz-nav-footer-menu { width : 100%; text-align : center; margin-top : 1em; margin-bottom : 2em; } P.zz-legal-notice, A.zz-legal-notice-link { font-size : xx-small; /* display : none ; */ /* Uncomment this to hide the legal notice */ } P.notep1 { font-size:1em; font-weight: bold; font-family: Arial, Helvetica, sans-serif; } PKɃt$PK(oUIOEBPS/mg_wrkspc.htm Managing a Development Workspace

13 Managing a Development Workspace

In the Oracle HTML DB development environment, developers log in to a shared work area called a workspace. Users are divided into two primary roles: developer and workspace administrator.

Developers can create and edit applications as well as view developer activity, session state, workspace activity, application, and schema reports. Workspace administrators additionally can create and edit user accounts, manage groups, manage development services. This section describes how to access many of these reports and perform Workspace administrator tasks.

This section contains the following topics:

Understanding Administrator Roles

In an Oracle HTML DB development environment there are two different administrator roles:

  • Workspace administrator

  • Oracle HTML DB administrator

A Workspace administrator uses the Workspace Administration list, located on the Workspace home page, to manage their workspace. In contrast, an Oracle HTML DB administrator is a superuser that manages the entire hosted instance. In order to become a Workspace administrator, an existing administrator must give the developer administrator privileges on the Edit User Page.


See Also:

"Managing an Oracle HTML DB Hosted Service" for more information administering a workspace as an Oracle HTML DB administrator

About the Workspace Administration List

The Workspace Administration list displays on right side of the Workspace home page. Both developers and workspace administrators have access to the following links:

  • Change Password links to a page where users can change their workspace password.

  • Manage Workspace links to the Manage Workspace page. Users can click the icons on this page to view the Developer Activity Log, access tools and reports for managing sessions state, view workspace activity reports as well as view application and schema reports

  • About HTML DB links to an About page. The About page lists basic product information including the product version, schema compatibility, application owner, workspace information, current user name, language preference, and database version.

  • Review Demonstration Applications links to the Demonstration Applications page. Demonstration Applications contains links to sample applications that install with Oracle HTML DB. Users can install and run these demonstration applications to learn more about the different types of functionality you can include in Oracle HTML DB applications.

Additionally, workspace administrators have access to the Manage Users and Manage Service links.


See Also:


Changing Your Password

All users can change their password using the Change Password page.

To change your password:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Change Password.

  3. Type a new password in the Password field and then retype the password in the Confirm Password field.

  4. Click Apply Changes.


Note:

All users (developers and administrators) can use the Change Password link on the Oracle HTML DB home page to reset their password.

Monitoring Workspace and User Activity

Both developers and workspace administrators can monitor workspace utilization and user activity by selecting reports on the Monitor page. To view counts of application changes by developer users can access the Developer Activity Log.

This section contains the following topics:

Viewing Workspace and User Activity Reports

The Monitor page displays links to a variety of page and application reports, including top views, page view statistics, top application changes, and application change statistics.

To access the Monitor page:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

  3. Under Workspace Reporting, click Monitor Activity.

    The Monitor page is divided into the following sections:

    • Top Views

    • Page View Statistics

    • Top Changes

    • Application Change Statistics

  4. Select a report to review

Viewing Application Changes by Developer and Day

The Developer Activity Log displays counts of application changes by developer, by day, and application.

To view Developer Activity Log:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

  3. Under Administration Services, click Logs.

  4. Click Monitor Developer Activity Log.

  5. Specify a time frame, the appropriate number of rows, and click Go.

    By default, the Developer Activity by Developer by Day report appears.

  6. To view additional details, select a user ID.

  7. To view additional activity reports, click one of the following buttons at the top of the page:

    • Application Changes by Month

    • Application Changes by Day Report

    • Application Changes by Day Link Chart

Purging Log Files

The Developer Activity Log track changes to applications within the current workspace. Log entries older then one month are automatically deleted. You can manually purge developer logs and the External Count Clicks log on the Log files page.


See Also:

"Managing Logs" for more information deleting log files as an Oracle HTML DB administrator

Purging the Developer Activity Log

To purge the Developer Activity Log:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

  3. Under Administration Services, click Logs.

  4. Click Purge Dev. Log.

Purging the External Clicks Log

The External Clicks Log counts clicks from an Oracle HTML DB application to an external site. You can implement this functionality using COUNT_CLICK procedure.

To purge the External Clicks Log:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

  3. Under Administration Services, click Logs.

  4. Click Purge Click Log.

Viewing Application and Schema Reports

Application and schema reports are available to all users. Application Reports offer useful information about the size, scope, and content of the applications being developed in a workspace. Schema Reports offer summaries of database privileges by schema as well as a list of all database schemas available in the current workspace.

To view application and schema reports:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

    The Administration Services page appears.

  3. From the Tasks list on the right side of the page, select Application Reports.

    The Administrative Reports page appears.

  4. Select a report to review.

Managing Session State and User Preferences

A session is a logical construct that establishes persistence (or stateful behavior) across page views. Each session is assigned a unique ID which the HTML DB engine uses to store and retrieve an application's working set of data (or session state) before and after each page view. Sessions persist in the database until purged by an administrator.

Workspace administrators can purge session state or user preferences within their workspace on the Session State Management page. Developers can purge their session state and user preferences for the current session.

Topics in this section include:

Managing Session State and User Preferences for the Current Session

Workspace administrators and developers can use the Session State Management page to manage session state and user preferences for the current session.

To manage session state and user preferences for the current session:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

  3. Under Administration Services, click Session State.

  4. When the Session State Management page appears, click Report, with an option to purge your current session.

  5. Under Session State you can:

    • Reset the session state for the current session by clicking Purge Session State.

    • View information about the current session by clicking View Session State.

  6. Under User Preferences, you can:

    • View preferences for the current user, by clicking View Preferences.

    • Reset user preferences for the current user by clicking Reset Preferences.

Purging Recent Sessions by Age

Sessions are used to maintain user state. Workspace administrators can purge existing sessions by age.

To purge existing session by age:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

  3. Under Administration Services, click Session State.

  4. On the Session State Management page, select Purge existing sessions by age.

  5. Make a selection from the Sessions older than list.

  6. Click one of the following buttons:

    • Report Session. Generates a report detailing the total number of sessions for the workspace, the number of users, and the number of old sessions.

    • Purge Sessions. Purges existing sessions by age.

Viewing Session Details Prior to Removing Session State

Workspace administrators can determine whether to remove existing sessions by first reviewing session details on the Session State page.

To view session details prior to removing session state:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

  3. Under Administration Services, click Session State.

  4. On the Session State Management page, select Report recent sessions with drilldown to session details.

  5. Select a session ID.

  6. When Session Information appears, click either:

    • Remove State

    • Remove Session

Viewing Preferences for a Specific User

Workspace administrators view preferences for a specific user on the Preferences Report.

To view the Preferences Report:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

  3. Under Administration Services, click Session State.

  4. On the Session State Management page, select Report preferences for users.

    The Preferences Report page appears.

  5. To search for a specific user, enter a user name in the User field and click Go.

Purging Preferences for a Specific User

Workspace administrators purge preferences for a specific user on the Purge Preferences page.

To purge preferences for a specific user:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

  3. Under Administration Services, click Session State.

  4. On the Session State Management page, select Purge preferences for a selected user.

    The Purge Preferences page appears.

  5. Select a specific user in the User field and click Report.

    The User Preferences for the selected user appear.

  6. To purge the displayed user preferences, click Purge User Preferences.

Managing Users

Workspace administrators can create new user accounts, manage existing user accounts, and change user passwords. User accounts are particularly useful if you are using HTML DB Authentication. HTML DB Authentication checks the username and password against the Oracle HTML DB account repository. The Oracle HTML DB account repository contains account information that developers and administrators when logging in to Oracle HTML DB applications.

Topics in this section include:


See Also:

"About HTML DB Account Credentials" for more information on implementing HTML DB Authentication

Creating New User Accounts

Workspace administrators create new user accounts on the Create User page.

To create a new user account:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Users.

    The Manage Users page appears.

  3. Under Manage Users, click Create New User.

    The Create User page appears.

  4. Under User Identification, enter the appropriate information. Required fields are marked with a red asterisk (*).

  5. Under Developer Privileges, specify whether the user is a developer or an administrator.

    • User is a developer - These users can create and edit applications as well as view developer activity, session state, workspace activity, application, and schema reports.

    • User is an administrator - Workspace administrators additionally can create and edit user accounts, manage groups, alter passwords of users within the same workspace, and manage development services.

  6. Under User Groups, select an optional user group.

    You can use groups to restrict access to various parts of an application. Groups are primarily useful when using HTML DB Authentication.

  7. Click Create User or Create and Create Another.

Editing Existing User Accounts

Workspace administrators edit existing user accounts on the Edit User page.

To edit an existing a user account:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Users.

    The Manage Users page appears.

  3. Under Manage Users, click Edit Users.

    The Edit Users page appears. On the Edit Users page, you can:

    • Create a new user by clicking Create

    • Search for an existing user by entering a search condition in the Find field and clicking Go

  4. To edit a user account, click the Edit icon.

    The Edit User page appears.

  5. Under Developer Privileges, specify whether the user is a developer or an administrator.

    Developers having administrator privilege have access to all tools and reports available on the Workspace Administration list. These users can also alter passwords of users within the same workspace.

  6. Under User Groups, select an optional user group.

    You can use groups to restrict access to various parts of an application. Groups are primarily useful when using HTML DB Authentication.

  7. Follow the on-screen instructions.

Changing a User Password

Workspace administrators can change the password of any user in their workspace.

To change a user password:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Users.

    The Manage Users page appears.

  3. Under Manage Users, click Edit Users.

    The Edit Users page appears.

  4. Locate the appropriate user and click the Edit icon. You can search for an existing user by entering a search condition in the Find field and clicking Go.

    The Edit User page appears.

  5. Scroll down to Password, type a new password in the Password and Confirm Password fields, and click Apply Changes.

Managing Groups

Workspace administrators can create groups to restrict access to various parts of an application. Keep in mind, however, that groups are not portable over different authentication schemes. Groups are primarily useful when using HTML DB Authentication.

Topics in this section include:


See Also:

"About HTML DB Account Credentials" for more information on implementing HTML DB Authentication

Creating and Editing Groups

To create a new group:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Users.

  3. Under Manage Groups, Kclick Create New Group.

    The Create User Groups page appears.

  4. Specify a group name, description, and click Create Group.

To edit an existing group:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Users.

  3. Under Manage Groups, click Edit Groups.

    The Create User Groups page appears.

  4. Click the Edit icon next to the appropriate group.

  5. Make the appropriate change and click Apply Changes.

Viewing Group Assignment Reports

To view a report of user group assignments:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Users.

  3. Under Manage Groups, click Report User Group Assignments.

    The User Groups Assignments Report appears.

Adding Users to and Removing Users from a Group

To add a user from a group:

  1. Navigate to the Edit User page:

    1. Navigate to the Workspace home page.

    2. From the Workspace Administration list, select Manage Users.

    3. Under Manage Users, click Edit Users.

      The Edit Users page appears.

    4. To edit a user account, click the Edit icon.

      The Edit User page appears.

  2. To add a user to a group:

    1. Scroll down to User Groups.

    2. Select a group from the Groups list.

  3. To remove a user to a group:

    1. Scroll down to User Groups.

    2. Deselect the selected group in the Groups list.

Managing Development Services

Workspace administrators can use the Provisioning Services section of the Administration Services page to:

  • View information and reports describing the current workspace

  • Submit a request to the Oracle HTML DB administrator for a new database schema, additional storage, or to terminate workspace service

Topics in this section include:

Viewing Current Workspace Status

Workspace administrators can view current workspace status on the Manage Development Services page.

To view current workspace status:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

  3. Under Administration Services, click Manage Service.

    The Manage Development Services page appears.

  4. Select Report Utilization.

  5. Follow the on-screen instructions.

Requesting a Database Schema

To submit a request to the Oracle HTML DB administrator for a new database schema:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

  3. Under Administration Services, click Manage Service.

    The Manage Development Services page appears.

  4. Select Request Schema.

  5. Follow the on-screen instructions.

Requesting Additional Storage

To submit a request to the Oracle HTML DB administrator for additional storage space for your workspace:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

  3. Under Administration Services, click Manage Service.

    The Manage Development Services page appears.

  4. Select Request Storage.

  5. Follow the on-screen instructions.

Requesting Service Termination

To submit a request to the Oracle HTML DB administrator to terminate workspace service:

  1. Navigate to the Workspace home page.

  2. From the Workspace Administration list, select Manage Workspace.

  3. Under Administration Services, click Manage Service.

    The Manage Development Services page appears.

  4. Select Terminate Service.

  5. Follow the on-screen instructions and click Request Termination.

PK˾PK(oUIOEBPS/debug.htm7r Debugging an Application

11 Debugging an Application

This section describes a number of approaches to debugging your application including viewing Debug Mode, enabling SQL tracing, viewing page reports, and how to manually remove a control or a component to isolate a problem.

This section contains the following topics:

About Tuning Performance

For applications having a large number of concurrent users, maintaining optimal performance is critical. To optimize your application's performance, remember to utilize the following Oracle HTML DB features:

  • Use bind variables within your application whenever possible. You can reference session state values using bind variable syntax in SQL queries and application logic such as PL/SQL executed from processes and validations. Accessing session state using bind variables is the most efficient way to reference session state.

  • Include a #TIMING# substitution string in the region footer so that you can view the timing of each region.

Reviewing Session State

Many application are based on data contained within application controls. For example, buttons may display conditionally based on a value stored in session state. You can view current session state for your application by clicking the Session link on the Developer Toolbar.

Accessing Debug Mode

Viewing a page in Debug Mode is effective way to track what the HTML DB engine is doing as it renders a page. You access Debug mode by clicking the Debug link in the Developer Toolbar.

Debug Mode displays time codes that correspond to specific HTML DB engine actions. This can be useful if you want to determine when the engine is setting session state. The bottom of the page displays an augmented version of the Page Definition. In addition to enabling you to link to page and component attributes, you can view additional details about item names and computation and processing points. To exit Debug mode, click No Debug in the Developer Toolbar.

You can also use f?p syntax run an application in Debug mode. Simply call the page and set the Debug argument to YES. For example:

f?p=100:1:&SESSION::YES

Enabling SQL Tracing and Using TKPROF

Tracing your session can be a very effective way to debug an application. From a database perspective, each page request is a single database session. If you enable SQL tracing, then Oracle HTML DB creates a temporary file you can then analyze using the TKPROF utility.

You enable SQL tracing in Oracle HTML DB by using f?p syntax to set the argument p_trace=YES. For example, to trace the display of page 1 in application 100 you would use the syntax:

http:/.../f?p=100:1&p_trace=YES

To use the TKPROF utility:

  • Navigate to the directory in which the trace file is created.

  • Type the following to view instructions about using TKPROF utility:

    tkprof help=yes
    
    

See Also:

Oracle Database Performance Tuning Guide for more information on using the TKPROF program or contact your database administrator

Monitoring Application and Page Resource Use

Oracle HTML DB facilitates the monitoring of resources used by applications and pages by calling the package DBMS_APPLICATION_INFO. Whenever the HTML DB engine renders or processes a page, the module is set to HTML DB and includes the application ID and page number. Once set, you can query the V$SESSION and V$SQLAREA views to monitor transactions.

Viewing Oracle HTML DB Reports

When isolating an issue within a page, it is important to clearly understand the functions it is performing. To accomplish this goal, Oracle HTML DB includes a number of page and application reports.

To view page reports:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Click one of the following buttons at the top of the Page Definition:

    • Event View links to a report that details currently defined page controls and processes.

    • Object References displays a list of database objects referenced by the current page.

    • History displays a history of recently changed pages.

To view application reports:

  1. Navigate to the Workspace home page.

  2. Select an application name from the Applications list.

  3. From the Tasks list, select View Application Reports.

    Application Reports page appears.

  4. Select a report to review.

Debugging Problematic SQL Queries

If your query does not seem to be running correctly, try running it in SQL Plus or in SQL Workshop. Either approach will test your query outside of the context of your application, making it easier to determine what the problem is.

Removing Controls and Components to Isolate a Problem

If you have problems running a page, try removing controls and components one at time. Using this approach, you can quickly determine which control or component may be the source of your problem. You can disable a control or component by selecting the conditional display attribute NEVER.

To remove a control or component using conditional attributes:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Select the name of the control or component you wish to disable.

    The appropriate attributes page appears.

  3. Scroll down to the Conditional Display attribute and select NEVER from the Condition Type list.

  4. Click Apply Changes and return to the Page Definition.

  5. Try running the page again.

  6. Continue to remove controls or components until the page runs correctly.

PK77PK(oUIOEBPS/deploy.htm Deploying an Application

12 Deploying an Application

This section describes how to deploy an application.

This section contains the following topics:

About the Oracle HTML DB Application Development Life Cycle

When developing applications using Oracle HTML DB, you need to find a balance between two dramatically different development methodologies:

  • Iterative, rapid application development

  • Planned, linear style development

The first approach offers so much flexibility, you run the risk of never completing your project. In contrast, the second approach can yield applications that do not meet the needs of end users even if they meet the stated requirements on paper.

System Development Life Cycle Methodologies to Consider

The System Development Life Cycle (SDLC) is the overall process of developing software using a series of defined steps. There are a number of SDLC models that work well for developing applications in Oracle HTML DB.

The SDLC waterfall is probably the best known model. In this methodology, the development process is broken down into the following stages:

  1. Project Planning

  2. Requirements Definition

  3. Design

  4. Development

  5. Integration and Testing

  6. Installation and Acceptance

  7. Maintenance

This methodology is referred to as a waterfall since the output from one stage is the input for the next stage. One of the primary problems with this approach is that it is assumed that all requirements can be establish in advanced. Unfortunately, in the real world requirements often change and evolve during the development process.

The Oracle HTML DB development environment enables developers to take a more iterative approach to development. Unlike many other development environments, creating prototypes is easy. With Oracle HTML DB, developers can:

  • Use built-in wizards to quickly design an application user interface

  • Easily make protoypes available to users and gather feedback

  • Implement changes in real time, creating new prototypes instantly

Other methodologies what work well with Oracle HTML DB include:

  • Spiral - This approach is actually a series of short waterfall cycles. Each waterfall cycles yields new requirements and enables the development team to create a robust series of prototypes.

  • Rapid Application Development (RAD) Life Cycle - This approach has a heavy emphasis on creating a prototype that closely resembles the final product. Essentially the prototype is an essential part of the requirements phase. One disadvantage of this model is that the emphasis on prototyping can lead to scope creep. Developers can lose sight of their initial goals in the attempt to create the perfect application.

About Deploying an Application in Oracle HTML DB

Deploying an application from one Oracle HTML DB instance to another is a two part process:

  • First, you move the supporting database objects.

  • Second, you export the application definition and all associated files.

Deployment Options to Consider

When you develop an application in Oracle HTML DB, you create the application within a specific workspace. Each workspace has an unique ID and name. A common scenario is to create the application in a development instance and then deploy it to a production instance.

During the deployment process you would need to decide whether to use the existing application ID, the existing workspace, the existing database, or the existing Oracle HTTP Server, or create new ones. Deployment options to consider include:

  1. Do nothing. Send the URL and login information to users. This approach works well for applications with a small and tolerant user population.

  2. Same workspace and same schema. Export and then import the application and install it using a different application ID. The approach works well when there are few changes to the underlying objects, but frequent changes to the application functionality.

  3. Different workspace and same schema. Export and then import the application into a different workspace. This is an effective way to prevent a production application from being modified by developers.

  4. Different workspace and different schema. Export and then import the application into a different workspace and install it using a different schema.

  5. Different database with all its variations. Export and then import the application into a different Oracle HTML DB instance and install it using a different schema and database.

Whether to Copy the Workspace

Whether to copy an existing workspace really is a matter of preference. Keep in mind that the production version must have access to all the appropriate objects. For example, you might want to copy a workspace in the following situations:

  • When the application subscribes to other objects within the workspace.

  • When the application relies on Oracle HTML DB authentication. Copying the workspace would automatically migrate all the required user data.

Whether to Copy the Database

When determining whether to copy the database, remember that the schema against which the application runs must have access to the same objects as the development instance. The actual name of the schema is unimportant. You can change it during the import process.

About the Application ID

It is not necessary to have matching application IDs for a development version and production version of an application. In fact, as a best practice never hard code the application ID. Instead use the application alias (defined on the Edit Application Attributes page), or use a built-in substitution string (such as APP_ID and APP_ALIAS). Using a substitution string is the best approach since it enables you to change the application ID without impacting any application functionality.


See Also:

"Application Definition" for information on defining an application alias and "Built-in Substitution Strings" for information on using APP_ID and APP_ALIAS

Whether to Install a New Oracle HTTP Server

Installing Oracle HTML DB loads a new Oracle HTTP Server in a separate Oracle home. Additionally, the installer properly configures Oracle HTTP Server with a mod_plsql database access descriptor (DAD) and creates all virtual directory mappings.

Using a different Oracle HTTP Server configuration requires additional configuration. For example, you might want to:

  • Use a different Oracle HTTP Server from the one that installs with Oracle HTML DB

  • Use the Oracle HTTP Server that installs with Oracle Application Server Release 10g

  • Use the Oracle HTTP Server that installs with Oracle9i Application Server

All of these scenarios require you manually configure the mod_plsql DAD and map the directory from which Oracle HTML DB retrieves images.

You can also have a single Oracle HTTP Server serve pages for multiple Oracle HTML DB instances. In this configuration, all Oracle HTML DB instances must be the same version, map to the same image directory, and have a unique mod_plsql DAD.


See Also:

Oracle HTML DB How To Documents section of Oracle Technology Network for more information on implementing these configurations

Deploying an Application to Another Oracle HTML DB Instance

To move an application and related files from one instance of Oracle HTML DB to another, you must export the application definition and all associated files. Exporting your application definition is the first step toward deploying it outside of your development environment.

Topics in this section include:

How Exporting an Application Works

Whether you want to move an application to another workspace or just make a copy of it, the export process involves the following steps:

You can import an application into your workspace regardless of the workspace in which it was developed.

About Managing Database Objects

Before you export an application and the appropriate related files, you need to determine if you also need to migrate the database objects referenced by the application.

If the target Oracle HTML DB instance is different from the development environment, you will need to migrate the database objects referenced by the application. In many cases this process can be as simple as using Oracle database export and import utilities to copy the application schema from the development environment to target Oracle HTML DB instance. The following are two common scenarios where this approach will not work:

  • When the object development schema refers to tablespaces to which the target instance schema does not have access

  • When the development instance schema has sample data that you do not to want migrate to the target instance schema

If a database administrator or an Oracle HTML DB administrator is the person responsible for exporting Oracle HTML DB applications, be sure to clearly communicate if he or she:

  • Should include all data when exporting your application

  • Should not include data from specific tables you identify

Exporting an Application and Related Files

You export and import application definitions and all associated files using the Workspace, Application, CSS, Images, Script Files, Themes, and User Interface Defaults buttons located at the top the Export page.

Topics in this section include:

Exporting an Application

When you export a application, Oracle HTML DB generates a text file containing PL/SQL API calls.

To export an application:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Export/Import.

  4. When prompted to select a task, select Export and click Next.

  5. From the Application list, select an application

  6. From File Format, select how rows in the export file will be formatted:

    • Choose UNIX to have the resulting file contain rows delimited by line feeds.

    • Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

  7. From Build Status Override, select one of the following:

    • Run Application Only - Developers can only run an application

    • Run and Build Application - Developers can both run and edit an application

    Selecting Run Application Only is an effective way to protect an application from modifications from other developers. Note that if you select Run Application Only you cannot set the argument p_trace to Yes. Also, be aware that once you override the Build Status, you can only change it in Oracle HTML DB Administration Services.

  8. Use the As of field to export your application as it was previously defined. Specify the number of minutes in the field provided.

    This utility uses the DBMS_FLASHBACK package. Because the timestamp to System Change Number (SCN) mapping is refreshed approximately every five minutes, you may have to wait that amount of time to locate the version you are looking for. The time undo information is retained and influenced by the startup parameter UNDO_RETENTION (the default is three hours). However, this only influences the size of the undo tablespace. While two databases may have the same UNDO_RETENTION parameter, you will be able to go back further in time on a database with fewer transactions since it is not filling the undo tablespace, forcing older data to be archived.

  9. Click Export Application.

In addition to exporting the actual application file, you may also need to export other related files such cascading style sheets, images, and script files.

Exporting a Page in an Application

You can export a specific page within an application by clicking the Export button on the Page Definition. When exporting a page, remember that some pages may reference shared components. To export all pages within an application as well as application shared components, you need to export the entire application.

To export a page in an application:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. From the Applications list, select an application.

    Application Builder appears. The list of pages in the current application appears at the bottom of the page.

  3. From the Pages list, select a page.

    The Page Definition appears.

  4. On the Page Definition, click Export at the top of the page.

  5. From Page, select the page to be exported.

  6. From File Format, select how rows in the export file will be formatted:

    • Choose UNIX to have the resulting file contain rows delimited by line feeds.

    • Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

  7. Use the As of field to export a page as it was previously defined. Specify the number of minutes in the field provided.

    This utility uses the DBMS_FLASHBACK package. Because the timestamp to System Change Number (SCN) mapping is refreshed approximately every five minutes, you may have to wait that amount of time to locate the version you are looking for. The time undo information is retained and influenced by the startup parameter UNDO_RETENTION (the default is three hours). However, this only influences the size of the undo tablespace. While two databases may have the same UNDO_RETENTION parameter, you will be able to go back further in time on a database with fewer transactions since it is not filling the undo tablespace, forcing older data to be archived.

  8. Click Export Page.

Exporting Cascading Style Sheets

Use the Export Cascading Style Sheets utility to export cascading style sheets you imported.

To export related cascading style sheets:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Export/Import.

  4. When prompted to select a task, select Export and click Next.

  5. Click CSS at the top of the page.

  6. On the Export Cascading Style Sheets page:

    1. Select the cascading style sheets

    2. From File Format, select how rows in the export file will be formatted:

      • Choose UNIX to have the resulting file contain rows delimited by line feeds.

      • Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

  7. Click Export Style Sheets.

Exporting Images

Use the Export Images utility to export images you have imported.

To export related images:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Export/Import.

  4. When prompted to select a task, select Export and click Next.

  5. Click Images at the top of the page.

  6. On the Export Images page:

    1. Select application from which to export images.

      Be aware that selecting Workspace Images only exports those images in your repository that are not associated with a specific application. If all of your images are associated with specific applications then the workspace image export file will be empty.

    2. From File Format, select how rows in the export file will be formatted:

      • Choose UNIX to have the resulting file contain rows delimited by line feeds.

      • Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

  7. Click Export Images.

Exporting Static Files

Use the Export Static Files utility to export static files you have imported.

To export related static files:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Export/Import.

  4. When prompted to select a task, select Export and click Next.

  5. Click Files at the top of the page.

  6. On the Export Static Files page:

    1. Select the files to be exported.

    2. From File Format, select how rows in the export file will be formatted:

      • Choose UNIX to have the resulting file contain rows delimited by line feeds.

      • Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

  7. Click Export File(s).

Exporting Script Files

Use the Export Script Files utility to export script files from one Oracle HTML DB development instance to another.

To export script files:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Export/Import.

  4. When prompted to select a task, select Export and click Next.

  5. Click Script Files at the top of the page.

  6. On the Export Script Files page:

    1. Select the files to be exported.

    2. From File Format, select how rows in the export file will be formatted:

      • Choose UNIX to have the resulting file contain rows delimited by line feeds.

      • Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

  7. Click Export Script Files.

Exporting Themes

Use the Export Theme utility to export themes from one Oracle HTML DB development instance to a file.

To export an application theme from the Export page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Export/Import.

  4. When prompted to select a task, select Export and click Next.

  5. Click Themes at the top of the page.

  6. From Export Theme, select the theme to be exported.

  7. Click Export Theme.

To export an application theme from the Themes page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Shared Components.

  4. Under User Interface, select Themes and Templates.

    The Themes page appears.

  5. From the Tasks list, select Export.

    The Export page appears.

  6. Click Themes at the top of the page.

  7. From Export Theme, select the theme to be exported.

  8. Click Export Theme.

Exporting User Interface Defaults

Exporting User Interface Defaults is useful when you plan to develop on the target machine.

When you export User Interface Defaults, all User Interface Defaults for the selected schema are exported to a single SQL*Plus script. When prompted by your browser, save this file to your hard drive. The file contains an API call to create table hints by making calls to the application PL/SQL API. You can use this file to import User Interface Defaults to another database and Oracle HTML DB instance.

To export User Interface Defaults from SQL Workshop:

  1. Click SQL Workshop on the Workspace home page.

  2. Under SQL Workshop, select User Interface Defaults.

  3. From the Tasks list, select Import/Export User Interface Defaults.

  4. When prompted to select a task, select Export and click Next.

  5. Click User Interface Defaults at the top of the page.

  6. On the User Interface Defaults page:

    1. From Schema, select the schema that owns the table associated with the User Interface Defaults.

    2. From File Format, select how rows in the export file will be formatted:

      • Choose UNIX to have the resulting file contain rows delimited by line feeds.

      • Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

  7. Click Export.

To export User Interface Defaults from the Export page:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Export/Import.

  4. When prompted to select a task, select Export and click Next.

  5. Click User Interface Defaults at the top of the page.

  6. On the User Interface Defaults page:

    1. From Schema, select the schema that owns the table associated with the User Interface Defaults.

    2. From File Format, select how rows in the export file will be formatted:

      • Choose UNIX to have the resulting file contain rows delimited by line feeds.

      • Choose DOS to have the resulting file contain rows delimited by carriage returns and line feeds.

  7. Click Export.

Importing Export Files

Once you export an application and any related files, you need to import them into the target Oracle HTML DB instance before you can install them. Always import application first and then the related files.

To import an application and related files:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Export/Import.

  4. When prompted to select a task, select Import and click Next.

  5. In Import file, specify the file you are importing.

  6. From File Type, select the type of file you are importing and click Next.

    Once you have imported a file, you have the option to install it. You can also install it later from the Export Repository.

  7. To install an imported file, click Install. On the Application Install page:

    1. From Parse As Schema, select a schema.

      This is the schema against which all of the application's SQL and PL/SQL will be parsed.

    2. From Build Status Override, select one of the following:

      • Run Application Only - Developers can only run an application

      • Run and Build Application - Developers can both run and edit an application

      Selecting Run Application Only is an effective way to protect an application from modifications from other developers. Be aware that once you override the Build Status, you can only change it in Oracle HTML DB Administration Services.

    3. From Install As Application, select one of the following:

      • Reuse Application ID from Export File

      • Auto Assign New Application ID

      • Change Application ID

      Use these options to avoid application ID conflicts. These options come in handy when you need to have two versions of the same application in the same workspace. For example, if you are migrating an application to a production instance but still need to maintain development version.

    4. Click Install Application.

Installing Files from the Export Repository

Once you have imported files into the target Oracle HTML DB instance, you must install them before they can become active in Application Builder.

To install files stored in the Export Repository:

  1. Navigate to the Workspace home page.

  2. From the Applications list, select an application.

  3. On the Application Builder home page, click Export/Import.

  4. From the Navigate menu on the right side of the page, select View Repository.

  5. Select the file to be installed and click Install in the Action column adjacent to the appropriate file.

    1. From Parse As Schema, select a schema.

      This is the schema against which all of the application's SQL and PL/SQL will be parsed.

    2. From Build Status, select one of the following:

      • Run Application Only

      • Run and Build Application

      Select Run Application Only to run the application in the target instance, but make it inaccessible to developers.

    3. From Install As Application, select one of the following:

      • Reuse Application ID from Export File

      • Auto Assign New Application ID

      • Change Application ID

      Use these options to avoid application ID conflicts. These options come in handy when you need to have two versions of the same application in the same workspace. For example, if you are migrating an application to a production instance but still need to maintain development version.

    4. Click Install Application.

In addition to installing files, you can also use this page to delete a file from the Export Repository.

To delete a file from the Export Repository:

  1. Navigate to the Export Repository.

  2. Select the file to be deleted Delete Checked.

About Publishing the Application URL

Once you have deployed your application, loaded data, and created users, you can publish your production URL.

You can determine the URL to your application by positioning the mouse over the Run icon on the Application Builder home page. The URL displays in the status bar at the bottom of the page.

The Run icon gets its value from the Home link found under the Session Management section of the Application Attributes page. This link is only referenced by this icon and by applications that do not use the Oracle HTML DB Login API. Consider the following example:

http://htmldb.oracle.com/pls/otn/f?p=11563:1:3397731373043366363

Where:

  • htmldb.oracle.com is the URL of the server

  • pls is the indicator to use the mod_plsql cartridge

  • otn is the DAD name

  • f?p= is a prefix used by Oracle HTML DB

  • 11563 is application being called

  • 1 is the page within the application to be displayed

  • 3397731373043366363 is the session number

To run this example application, you would use the URL:

http://htmldb.oracle.com/pls/otn/f?p=11563:1

When each user logs in, he or she will receive an unique session number.

Using Build Options to Control Configuration

Build options enable you to conditionally display specific functionality within an application.

Build options have two possible values: INCLUDE and EXCLUDE. If you specify an attribute as being included, then the HTML DB engine considers it part of the application definition at runtime. Conversely, if you specify an attribute as being excluded then the HTML DB engine treats it as if it does not exist.

Topics in this section include:

Creating Build Options

To create a build option:

  1. Navigate to the Workspace home page.

  2. Select an application name from the Applications list.

  3. On the Application Builder home page, click Shared Components.

  4. Under Logic, select Build Options.

  5. To create a new build option, click Create.

  6. Follow the on-screen instructions.

    Once you create a build option, click the Edit icon to change it.

You can choose to enable or disable a build option on the appropriate attributes page. Most attributes pages contain a Configuration Management section where you can select defined build options.


See Also:

"Editing Application Attributes" and "Editing Page Attributes" for more information on specifying build options

Viewing Build Option Reports

Oracle HTML DB includes a report detailing build option utilization in the current application.

To view a report of build option utilization:

  1. Navigate to the Workspace home page.

  2. Select an application name from the Applications list.

  3. On the Application Builder home page, click Shared Components.

  4. Under Logic, select Build Options.

  5. On the Build Options page, click Utilization.

    This report displays build option utilization in the current application.

PK ĺPK(oUI OEBPS/toc.ncx* Oracle® HTML DB User's Guide, 10g Release 1 (10.1.6) Cover Title and Copyright Information Contents Send Us Your Comments Preface What's New in Oracle HTML DB? Part I Getting Started with Oracle HTML DB 1 What is Oracle HTML DB? 2 Quick Start 3 Running a Demonstration Application Part II Using Oracle HTML DB 4 Managing Data with Data Workshop 5 Managing Database Objects with SQL Workshop 6 Application Builder Concepts 7 Using Application Builder 8 Building an Application 9 Controlling Page Layout and User Interface 10 Adding Navigation 11 Debugging an Application 12 Deploying an Application 13 Managing a Development Workspace 14 Managing Security 15 Advanced Programming Techniques 16 Managing Globalization 17 Oracle HTML DB APIs Part III Administration 18 Managing an Oracle HTML DB Hosted Service A Available Conditions Index Copyright PK\c/*PK(oUIOEBPS/content.opf  Oracle® HTML DB User's Guide, 10g Release 1 (10.1.6) en-US B14303-02 Oracle Corporation Oracle Corporation Oracle® HTML DB User's Guide, 10g Release 1 (10.1.6) Describes how to use the Oracle HTML DB development environment to build and deploy database-centric Web applications. Oracle HTML DB turns a single Oracle database into a shared service by enabling multiple workgroups to build and access applications as if they were running in separate databases. PK={t PK(oUI OEBPS/toc.htm Table of Contents

Contents

Title and Copyright Information

Send Us Your Comments

Preface

Audience
Documentation Accessibility
Structure
Related Documents
Conventions

What's New in Oracle HTML DB?

Oracle HTML DB Release 1.6 New Features

Part I Getting Started with Oracle HTML DB

1 What is Oracle HTML DB?

About Oracle HTML DB
About Application Builder
About SQL Workshop
About Data Workshop

2 Quick Start

Understanding Oracle HTML DB User Roles
Logging in to Oracle HTML DB
Requesting a Workspace
Logging in to a Workspace
Resetting Your Password
Logging Out of Your Workspace
About the Oracle HTML DB User Interface
Navigating Using Breadcrumb Menus
Accessing Online Help
Creating an Application Using the Create Application Wizard
Running Your Application

3 Running a Demonstration Application

Viewing and Installing a Demonstration Application
Running a Demonstration Application
Running an Application from Demonstration Applications
Running an Application from the Workspace Home Page
Understanding Sample Application
About the Home Page
About the Customers Page
About the Products Page
About the Orders Page
About the Charts Page
About the Admin Page
Viewing Pages in Printer Friendly Mode
Modifying a Demonstration Application
About the Developer Toolbar
Editing a Demonstration Application
Viewing Underlying Database Objects

Part II Using Oracle HTML DB

4 Managing Data with Data Workshop

About Data Workshop
Importing Data
Importing a Text File
Importing an XML Document
Importing Spreadsheet Data
Exporting Data
Exporting to a Text File
Exporting to an XML Document

5 Managing Database Objects with SQL Workshop

About SQL Workshop
About Transaction Support
About Unsupported SQL*Plus Commands
Viewing Database Objects
Using the SQL Command Processor
About Command Termination
Using Explain Plan
Viewing Database Objects
Querying by Example
Managing Database Objects
Creating Database Objects
Dropping Database Objects
Restoring Dropped Database Objects
Using the SQL Script Repository
Managing Script Files in the SQL Script Repository
Uploading and Creating Script Files
About Script Termination
Using Parameters in a Script
Including SQL Queries in a Script
Exporting a Script File
Accessing Saved Commands in the SQL Archive
Accessing the SQL Command History
Generating DDL
Managing Control Files
Viewing the Control File Run History
Viewing Control File Job Status
Managing Tables
Managing User Interface Defaults
Viewing Tables Utilizing User Interface Defaults
Editing a Column Attributes
Editing Column-level Defaults
Viewing the Column Definition Report
Applying User Interface Defaults to a Table or View
Comparing User Interface Defaults Across Applications
About Exporting and Importing User Interface Defaults
Browsing the Data Dictionary

6 Application Builder Concepts

About the Workspace Home Page
What is Application Builder?
What is a Page?
About Page Rendering
About Page Processing
About Shared Components
Lists
Lists of Values
Menus
Navigation Bars
Tabs
Templates
How Page Processing and Page Rendering Work
Understanding Conditional Rendering and Processing
Current Page In Expression 1
Exists
PLSQL Expression
Verifying User Identity
Controlling Access to Controls and Components
Understanding Session State Management
Understanding Session IDs
Viewing Session State
Managing Session State Values
Referencing Session State
Setting Session State
Clearing Session State
Clearing Cache by Item
Clearing Cache by Page
Clearing Cache for an Entire Application
Clearing Cache for the Current User Session
About Bind Variables
Using Bind Variables in Regions Based on a SQL Query or LOV
Using Bind Variables in PL/SQL Procedures
Understanding URL Syntax
Using f?p Syntax to Link Pages
Calling a Page Using an Application and Page Alias
Calling a Page from a Button URL
Using Substitution Strings
Built-in Substitution Strings
APP_ALIAS
APP_ID
APP_IMAGES
APP_PAGE_ID
APP_SESSION
APP_UNIQUE_PAGE_ID
APP_USER
AUTHENTICATED_URL_PREFIX
BROWSER_LANGUAGE
CURRENT_PARENT_TAB_TEXT
DEBUG
HOME_LINK
IMAGE_PREFIX
HTML DB SCHEMA OWNER
PRINTER_FRIENDLY
LOGOUT_URL
PROXY SERVER
PUBLIC_URL_PREFIX
REQUEST
SQLERRM
SYSDATE_YYYYMMDD
WORKSPACE_IMAGES

7 Using Application Builder

Accessing Application Builder
About the Application Builder Home Page
Editing Application Attributes
Application Definition
Authorization
Session Management
Theme
Globalization
Application Availability
Global Notifications
Virtual Private Database (VPD)
Static Substitution Strings
Logo
Build Options
Application Template Defaults
Wizard Template Defaults
Application Comments
Viewing a Page
Viewing a Page Definition
Understanding the Page Definition
Additional Page Definition Features
Event View
Object References
Export
History
Using the Developer Toolbar
Editing a Page Definition
Accessing a Page Definition
Accessing a Summary View of Controls, Components, and Application Logic
Copying or Creating a New Control or Component
Editing Page Attributes
Page Identification
Primary Display Attributes
HTML Header
Page Header, Footer and Text Attributes
On Load JavaScript
Security
Duplicate Page Submission Checks
Configuration Management
On Error Text
Page Help Text
Comments
Understanding Page Rendering Controls
Regions
Buttons
Items
Page Computations
Page Processes
Understanding Page Processing Controls
Understanding Validations
Understanding Branching
Creating a Page Computation
Editing Computation Attributes
Defining a Computation Point and Computation Source
Creating Conditional Computations
Creating a Page Process
Editing Process Attributes
Working with Shared Components
Accessing Shared Components
Logic
Navigation
Security
User Interface
Translations
Files
About Themes and Templates
How Themes and Page Templates Effect User Interface
Viewing Application Reports
About the Database Object Dependencies Report
About the Region Source Report

8 Building an Application

Creating an Application
Creating a New Application
Deleting an Application
Adding Additional Pages
Creating a Page from Application Builder
Creating a Page from the Page Definition
Creating a Page from the Developer Toolbar
Running a Page
Grouping Pages
Creating a Page Group
Assigning Pages to a Page Group
Viewing the Page Group Report
Locking and Unlocking Page
Accessing Alternative Locked Pages Views
Deleting a Page
Creating Reports
Creating a Report Using a Wizard
Editing Report Attributes
Controlling Report Pagination
Including Pagination After the Rows in a Report
Including Pagination Before the Rows in a Report
Enabling Column Sorting
Exporting a Report as a CSV or XML File
Creating a Column link
Defining an Updatable Column
Defining a Column as a List of Values
Controlling When Columns Display
Controlling Column Breaks
Creating Forms
Creating a Form Using a Wizard
Creating a Tabular Form
Building a Master Detail Form
Creating a Form Manually
Processing a Form
Creating an Automatic Row (DML) Processing Process
Creating a Process that Contains One or More Insert Statements
Using a PL/SQL API to Process Form Values
Populating Forms
Validating User Input in Forms
About Error Messaging
Creating Charts
About SVG Plug-in Support
About Creating Charts
Creating a New Chart
Adding a Chart to an Existing Page
Adding a Chart to a New Page
Editing Chart Attributes
Understanding Chart CSS Classes
Referencing a Custom Cascading Style Sheet
Specifying Custom CSS Styles Inline
Enabling Asynchronous Updates
Displaying Charts in Other Languages
Creating Buttons
Creating a Button Using a Wizard
Creating an HTML Button
Creating Multiple Buttons
Understanding the Relationship Between Button Names and REQUEST
About Branching with Buttons
Displaying Buttons Conditionally
Creating Items
Creating a Page Level Item
About Item Naming Conventions
About Item Types
Referencing Item Values
Displaying Conditional or Read-only Items
Creating an Application Level Item
Accessing Application Item History
Populating an Alternative Date Picker Format
Defining PICK_DATE_FORMAT_MASK as an Application Substitution String
Defining an Application Level Item Named PICK_DATE_FORMAT_MASK
Creating Lists of Values
Creating Named LOVs at the Application Level
About Static LOVs
About Popup LOVs
Referencing Session State within a LOV
Accessing LOV Reports
Bulk Update LOV Data Values
Subscribed LOVs
LOV Utilization
LOV Change History
Creating Calendars
About Creating Calendars
Supported Calendar Substitution Strings
Creating a New Calendar
Adding a Calendar to an Existing Page
Adding a Calendar to a New Page
Converting an Easy Calendar to a SQL Calendar
Editing a Calendar Title
Editing Calendar Attributes
Accessing the Calendar Attributes Page
Calendar Display
Calendar Interval
Column Link
Day Link
Utilizing Shortcuts
About Shortcut Types
Text with JavaScript Escaped Single Quotes
Message
Message with JavaScript Escaped Single Quotes
Defining Shortcuts
Accessing Shortcut Reports
Subscribed Shortcuts
Shortcut History
Incorporating JavaScript into an Application
About Referencing Items Using JavaScript
How to Incorporate JavaScript Functions
Incorporating JavaScript in the HTML Header Attribute
Including JavaScript in a .js File in the Page Template
Calling JavaScript from a Button
Creating Dependent Select Lists
Creating a Help Page
Creating a Help Page and Region
Defining Help Text
About the Item Help Text Report
Creating a Help Navigation Bar Icon

9 Controlling Page Layout and User Interface

Understanding Page Layout
Displaying Components on Every Page of an Application
How Item Attributes Affect Page Layout
Customizing Regions
Creating a Region
How Region Attributes Affect Page Layout
Controlling Region Positioning
Specifying a Region Header and Footer
Enabling Users to Customize a Page
Incorporating Content from Other Web Sites
Managing Themes
Accessing the Themes Page
Changing Default Templates in a Theme
Creating a New Theme
Switching an Active Theme
Copying a Theme
Deleting a Theme
About Exporting and Importing Themes
Changing a Theme Identification Number
Viewing Theme Reports
Viewing All Templates in a Theme
Viewing Theme Template Counts
Viewing File References
Viewing Class References
Viewing Template Substitution Strings
Customizing Templates
About Cascading Style Sheets
Selecting a Default Page Template
Selecting a Page Level Template within a Theme
Selecting a Page Level Template for a Specific Page
Viewing Templates
Creating a New Template
Viewing Template Reports
Editing Templates
Button Templates
Button Template Attributes
Calendar Templates
Calendar Template Attributes
Label Templates
Label Template Attributes
List Templates
List Template Attributes
Menu Templates
Breadcrumb Style Menu Navigation
Menu Template Attributes
Page Templates
Supported Page Template Substitution Strings
Page Template Attributes
Popup LOV Templates
Popup List of Values Template Attributes
Region Templates
Region Template Attributes
Report Templates
About Generic Column Templates and Named Column Templates
Report Column Template Attributes for Generic Column Templates
Report Column Template Attributes for Named Column Templates
About Using JavaScript in Column Templates
Optimizing a Page for Printing
Setting a Print Mode Template for an Application
Using f?p Syntax to Toggle to Print Mode
Using Custom Cascading Style Sheets
Uploading Cascading Style Sheets
Referencing an Uploaded Cascading Style Sheet in the Page Template
Uploading Images
Referencing Images
Uploading Static Files
Creating a Multiple Column Layout
Creating Regions in Multiple Columns
Creating a Multiple Column Page Template
Rendering HTML Using Custom PL/SQL

10 Adding Navigation

Creating a Navigation Bar
Creating a Navigation Bar Entry
Managing Navigation Bar Entries
Creating Tabs
About Template Support
Using Tab Manager
Accessing Tab Manager
Creating a New Tab from the Page Definition
Editing Multiple Tabs at Once
Accessing Tab Reports
Standard Tab Utilization
Standard and Parent Tab History
Controlling Flow Using Branches
Creating Menus
About Breadcrumb Menus
Creating a Menu
Adding Options to a Menu
Adding a Menu to a Page
About Creating a Dynamic Menu
Editing Multiple Menu Names Simultaneously
Accessing Menu Reports
Menu Utilization Report
Recent Menu Option Changes
Creating Lists
Creating a List
Adding Items to a List
Adding a List to a Page
Editing Multiple List Entries Simultaneously
Accessing List Reports
List Utilization
Unused lists
List Definition and List Entry History
Creating Trees
Accessing Tree Reports
Tree Utilization
Tree History

11 Debugging an Application

About Tuning Performance
Reviewing Session State
Accessing Debug Mode
Enabling SQL Tracing and Using TKPROF
Monitoring Application and Page Resource Use
Viewing Oracle HTML DB Reports
Debugging Problematic SQL Queries
Removing Controls and Components to Isolate a Problem

12 Deploying an Application

About the Oracle HTML DB Application Development Life Cycle
System Development Life Cycle Methodologies to Consider
About Deploying an Application in Oracle HTML DB
Deployment Options to Consider
Whether to Copy the Workspace
Whether to Copy the Database
About the Application ID
Whether to Install a New Oracle HTTP Server
Deploying an Application to Another Oracle HTML DB Instance
How Exporting an Application Works
About Managing Database Objects
Exporting an Application and Related Files
Exporting an Application
Exporting a Page in an Application
Exporting Cascading Style Sheets
Exporting Images
Exporting Static Files
Exporting Script Files
Exporting Themes
Exporting User Interface Defaults
Importing Export Files
Installing Files from the Export Repository
About Publishing the Application URL
Using Build Options to Control Configuration
Creating Build Options
Viewing Build Option Reports

13 Managing a Development Workspace

Understanding Administrator Roles
About the Workspace Administration List
Changing Your Password
Monitoring Workspace and User Activity
Viewing Workspace and User Activity Reports
Viewing Application Changes by Developer and Day
Purging Log Files
Purging the Developer Activity Log
Purging the External Clicks Log
Viewing Application and Schema Reports
Managing Session State and User Preferences
Managing Session State and User Preferences for the Current Session
Purging Recent Sessions by Age
Viewing Session Details Prior to Removing Session State
Viewing Preferences for a Specific User
Purging Preferences for a Specific User
Managing Users
Creating New User Accounts
Editing Existing User Accounts
Changing a User Password
Managing Groups
Creating and Editing Groups
Viewing Group Assignment Reports
Adding Users to and Removing Users from a Group
Managing Development Services
Viewing Current Workspace Status
Requesting a Database Schema
Requesting Additional Storage
Requesting Service Termination

14 Managing Security

Escaping Special Characters Rendered from Session State
Understanding Security
Using the Security Navigation List
Establishing User Identity Through Authentication
Understanding How Authentication Works
Creating an Authentication Scheme
Using the Authentication Scheme Repository
Viewing the Current Authentication Scheme for an Application
About Preconfigured Authentication Schemes
About DAD Credentials Verification
About HTML DB Account Credentials
About LDAP Credentials Verification
About Single Sign-On Server Verification
About Creating an Authentication Scheme from Scratch
About Session Management Security
Building a Login Page
About Deep Linking
Providing Security Through Authorization
How Authorization Schemes Work
Creating an Authorization Scheme
About the Evaluation Point Attribute
About Resetting Authorization Scheme State
Attaching an Authorization Scheme to an Application, Page, or Components
Attaching an Authorization Scheme to an Application
Attaching an Authorization Scheme to a Page
Attaching an Authorization Scheme to a Control or Component
Viewing Authorization Scheme Utilization Reports

15 Advanced Programming Techniques

Sending E-mail from an Application
Sending E-mail Using a Background Job
Sending E-mail Manually by Calling HTMLDB_MAIL
Accessing Data with Database Links
Using Collections
About the HTMLDB_COLLECTION API
About Collection Naming
Creating a Collection
About the Parameter p_generate_md5
Truncating a Collection
Deleting a Collection
Deleting All Collections for the Current Application
Deleting All Collections in the Current Session
Adding Members to a Collection
About the Parameters p_generate_md5 and p_clob001
Updating Collection Members
Deleting a Collection Member
Determining Collection Status
Merging Collections
Managing Collections
Obtaining a Member Count
Resequencing a Collection
Verifying Whether a Collection Exists
Adjusting Member Sequence ID
Sorting Collection Members
Clearing Collection Session State
Running Background PL/SQL
Understanding the HTMLDB_PLSQL_JOB Package
About System Status Updates
Using a Process to Implement Background PL/SQL
Implementing Web Services
Understanding Web Service References
Accessing the Web Service References Page
Specifying an Application Proxy Server Address
Creating a Web Service Reference
Creating a Web Service Reference by Searching a UDDI Registry
Creating a Web Service Reference by Specifying a WSDL Document
Using the Web Service Reference Repository
Testing a Web Service Reference
Creating an Input Form and Report on a Web Service
Creating a Form and Report Directly After Creating a Reference
Creating a Form and Report by Adding a New Page
Creating a Form on a Web Service
Creating a Form Directly After Creating a Reference
Creating a Form by Adding a New Page
Invoking a Web Service as a Process
Displaying Web Service Results in a Report
Editing a Web Service Process
Viewing a Web Service Reference History
Managing User Preferences
Viewing User Preferences
Setting User Preferences
Setting User Preferences Using a Page Process
Setting the Source of an Item Based on a User Preference
Setting User Preferences Programatically
Resetting User Preferences Manually
Resetting Preferences Using a Page Process

16 Managing Globalization

About Translating an Application and Globalization Support
About Language Identification
Rule for Translating Applications in Oracle HTML DB
How Translated Applications Are Rendered
About Translatable Components
About Shortcuts that Support Translatable Messages
About Messages
About Dynamic Translation Text Strings
About Translating Templates
Specifying the Primary Language for an Application
Using Format Masks for Items
Translating Applications for Multibyte Languages
Understanding the Translation Process
Navigating to the Translate Application Page
Mapping Primary and Target Application IDs
Seeding and Exporting Text to a Translation File
Seeding Translatable Text
Exporting Text to a Translation File
Translating the XLIFF File
Uploading and Publishing a Translated XLIFF Document
Translating Messages Used in PL/SQL Procedures
Defining Translatable Messages
HTMLDB_LANG.MESSAGE API
Translating Data that Supports List of Values
Defining a Dynamic Translation
HTMLDB_LANG.LANG API
About Oracle HTML DB Globalization Codes

17 Oracle HTML DB APIs

HTMLDB_UTIL
CHANGE_CURRENT_USER_PW Procedure
CLEAR_APP_CACHE Procedure
CLEAR_PAGE_CACHE Procedure
CLEAR_USER_CACHE Procedure
COUNT_CLICK Procedure
CREATE_USER Procedure
CREATE_USER_GROUP Procedure
CURRENT_USER_IN_GROUP Function
EDIT_USER Procedure
EXPORT_USERS Procedure
FETCH_APP_ITEM Function
FETCH_USER Procedure
FIND_SECURITY_GROUP_ID Function
FIND_WORKSPACE Function
GET_ATTRIBUTE Function
GET_CURRENT_USER_ID Function
GET_DEFAULT_SCHEMA Function
GET_EMAIL Function
GET_FILE Procedure
GET_FILE_ID Function
GET_FIRST_NAME Function
GET_GROUPS_USER_BELONGS_TO Function
GET_GROUP_ID Function
GET_GROUP_NAME Function
GET_LAST_NAME Function
GET_USERNAME Function
GET_NUMERIC_SESSION_STATE Function
GET_PREFERENCE Function
GET_SESSION_STATE Function
GET_USER_ID Function
GET_USER_ROLES Function
IS_LOGIN_PASSWORD_VALID Function
IS_USERNAME_UNIQUE Function
PUBLIC_CHECK_AUTHORIZATION Function
REMOVE_PREFERENCE Procedure
REMOVE_SORT_PREFERENCES Procedure
REMOVE_USER Procedure
RESET_PW Procedure
RESET_AUTHORIZATIONS Procedure
SET_EMAIL Procedure
SET_FIRST_NAME Procedure
SET_LAST_NAME Procedure
SET_USERNAME Procedure
SET_PREFERENCE Procedure
SET_SESSION_STATE Procedure
STRING_TO_TABLE Function
TABLE_TO_STRING Function
URL_ENCODE Function
HTMLDB_MAIL
SEND Procedure
PUSH_QUEUE Procedure
HTMLDB_ITEM
CHECKBOX Function
DATE_POPUP Function
DISPLAY_AND_SAVE Function
HIDDEN Function
MD5_CHECKSUM Function
MD5_HIDDEN Function
MULTI_ROW_UPDATE Procedure
SELECT_LIST Function
SELECT_LIST_FROM_LOV Function
SELECT_LIST_FROM_LOV_XL Function
SELECT_LIST_FROM_QUERY Function
SELECT_LIST_FROM_QUERY_XL Function
TEXTAREA
TEXT Function
TEXT_FROM_LOV Function
TEXT_FROM_LOV_QUERY Function
RADIOGROUP Function
POPUP_FROM_LOV Function
POPUP_FROM_QUERY Function
POPUPKEY_FROM_LOV Function
POPUPKEY_FROM_QUERY Function
HTMLDB_APPLICATION
Referencing Arrays
Referencing Values Within an On Submit Process
Converting an Array to a Single Value
HTMLDB_CUSTOM_AUTH
APPLICATION_PAGE_ITEM_EXISTS Function
CURRENT_PAGE_IS_PUBLIC Function
DEFINE_USER_SESSION Procedure
GET_COOKIE_PROPS Procedure
GET_LDAP_PROPS Procedure
GET_NEXT_SESSION_ID Function
GET_SESSION_ID_FROM_COOKIE Function
GET_USERNAME Function
GET_SECURITY_GROUP_ID Function
GET_SESSION_ID Function
GET_USER Function
IS_SESSION_VALID Function
LOGIN Procedure
LOGOUT Procedure
POST_LOGIN Procedure
SESSION_ID_EXISTS Function
SET_USER Procedure
SET_SESSION_ID Procedure
SET_SESSION_ID_TO_NEXT_VALUE Procedure

Part III Administration

18 Managing an Oracle HTML DB Hosted Service

What is an Oracle HTML DB Administrator?
Logging in to Oracle HTML DB Administration Services
Determining the HTML DB Engine Schema
Managing the Schemas Associated with a Workspace
Understanding Oracle Default Schema Restrictions
Creating a Workspace
About Workspace Provisioning
Specifying a Provisioning Mode
Creating a Workspace Without a Request
Viewing Workspace Reports
Managing Service and Change Requests
Viewing a Pending Service or Change Request
Viewing a Pending Request from the Notifications List
Viewing a Request from the Workspace Utilization Report
Viewing Requests from the Service Requests Page
Viewing Requests from the Change Requests Page
Approving a Service or Change Request
Deleting an Existing Request
Managing Users in an Oracle HTML DB Instance
Purging Inactive Workspaces
Identifying Inactive Workspaces
Removing the Resources Associated with Inactive Workspaces
Deleting Inactive Workspaces
Removing a Workspace
Exporting and Importing a Workspace
Managing Logs
Deleting SQL Workshop Logs
Deleting Page View Activity Log Entries
Deleting Developer Activity Log Entries
Deleting Click Counting Log Entries
Deleting the HTML DB Mail Log Entries
Managing Session State
Purging Sessions by Age
Viewing Session Details Before Purging
Viewing Session Statistics Before Purging
Monitoring Activities
Managing Environment Preferences
Accessing the HTML DB Environment Preferences Page
About SERVICE_REQUEST_FLOW
Configuring Oracle HTML DB to Send Mail
Restricting User Access by IP Address
Disabling Access to Oracle HTML DB Administration Services
Disabling Access to Oracle HTML DB Internal Applications
Managing Application Build Status
Managing E-mail
Viewing the Mail Queue
Viewing the HTML DB Mail Log
Creating a Site-Specific Tasks List
Adding a New Task
Editing an Existing Task
Deleting a Task

A Available Conditions

Conditions Available in Oracle HTML DB

Index

PKǙIcYPK(oUIOEBPS/title.htm! Oracle HTML DB User's Guide, Release 1.6

Oracle® HTML DB

User's Guide

Release 1.6

Part No. B14303-02

March 2005


Oracle HTML DB User's Guide, Release 1.6

Part No. B14303-02

Copyright © 2003, 2005, Oracle. All rights reserved.

Primary Author:  Terri Winters

Contributors:  Carl Backstrom, Christina Cho, Michael Hichwa Joel Kallman, Sharon Kennedy, Syme Kutz, Sergio Leunissen, Raj Mattamal, Tyler Muth, Kris Rice, Marc Sewtz, Scott Spadafore, Scott Spendolini, and Jason Straub

The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose.

If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer Software--Restricted Rights (June 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065

The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party.

PKPK(oUI OEBPS/api.htm Oracle HTML DB APIs

17 Oracle HTML DB APIs

This section describes the APIs available in Oracle HTML DB.

This section contains the following topics:

HTMLDB_UTIL

The HTMLDB_UTIL package provides utilities you can use when programming in the Oracle HTML DB environment. You can use HTMLDB_UTIL to get and set session state, get files, check authorizations for users, reset different states for users, and also to get and set preferences for users.

Topics in this section include:

CHANGE_CURRENT_USER_PW Procedure

This procedure changes the password of the currently authenticated user, assuming HTML DB user accounts are in use.

Syntax

HTMLDB_UTIL.CHANGE_CURRENT_USER_PW(
    p_new_password IN VARCHAR2);

Parameters

Table 17-1 describes the parameters available in the CHANGE_CURRENT_USER_PW procedure.

Table 17-1 CHANGE_CURRENT_USER_PW Parameters

Parameter Description
p_new_password The new password value in clear text.

Example

BEGIN
HTMLDB_UTIL.CHANGE_CURRENT_USER_PW ('secret99');
END;

CLEAR_APP_CACHE Procedure

This procedure removes session state for a given application for the current session.

Syntax

HTMLDB_UTIL.CLEAR_APP_CACHE (
    p_app_id    IN    VARCHAR2 DEFAULT NULL);

Parameters

p_app_id is the ID of the application for which session state will be cleared for current session.

Example

BEGIN
        HTMLDB_UTIL.CLEAR_APP_CACHE('100');
END;

CLEAR_PAGE_CACHE Procedure

This procedure removes session state for a given page for the current session.

Syntax

HTMLDB_UTIL.CLEAR_PAGE_CACHE (
    p_page_id IN NUMBER DEFAULT NULL);

Parameters

p_page_id is the ID of the page in the current application for which session state will be cleared for current session.

Example

BEGIN
HTMLDB_UTIL.CLEAR_PAGE_CACHE('10');
END;

CLEAR_USER_CACHE Procedure

This procedure removes session state and application system preferences for the current user's session. Run this procedure if you reuse session IDs and want to run applications without the benefit of existing session state.

Syntax

HTMLDB_UTIL.CLEAR_USER_CACHE;

Example

BEGIN
       HTMLDB_UTIL.CLEAR_USER_CACHE;
END;

COUNT_CLICK Procedure

This procedure counts clicks from an Oracle HTML DB application to an external site. You can also use the shorthand version procedure Z in place of HTMLDB_UTIL.COUNT_CLICK.

Syntax

HTMLDB_UTIL.COUNT_CLICK (
    p_url         IN    VARCHAR2,
    p_cat         IN    VARCHAR2,
    p_id          IN    VARCHAR2    DEFAULT NULL,
    p_user        IN    VARCHAR2    DEFAULT NULL,
    p_workspace   IN    VARCHAR2    DEFAULT NULL);

Parameters

Table 17-2 describes the parameters available in the COUNT_CLICK procedure.

Table 17-2 COUNT_CLICK Parameters

Parameter Description
p_url The URL to redirect to.
p_cat A category to classify the click.
p_id Secondary ID to associate with the click (optional).
p_user The application user ID (optional).
p_workspace The workspace associated with the application (optional).

Example

BEGIN
htp.p('<a href=HTMLDB_UTIL.COUNT_CLICK?p_url=http://yahoo.com&p_cat=yahoo&p_workspace=NNN> Click</a>'); end; 

Where NNN equals your workspace ID.

CREATE_USER Procedure

This procedure creates a new account record in the HTML DB user account table. To execute this procedure, the current user must have administrative privileges.

Syntax

HTMLDB_UTIL.CREATE_USER(
    P_USER_ID                      NUMBER                  IN     DEFAULT NULL
    P_USER_NAME                    VARCHAR2                IN
    P_FIRST_NAME                   VARCHAR2                IN     DEFAULT NULL
    P_LAST_NAME                    VARCHAR2                IN     DEFAULT NULL
    P_DESCRIPTION                  VARCHAR2                IN     DEFAULT NULL
    P_EMAIL_ADDRESS                VARCHAR2                IN     DEFAULT NULL
    P_WEB_PASSWORD                 VARCHAR2                IN
    P_WEB_PASSWORD_FORMAT          VARCHAR2                IN     DEFAULT NULL
    P_GROUP_IDS                    VARCHAR2                IN     DEFAULT NULL
    P_DEVELOPER_PRIVS              VARCHAR2                IN     DEFAULT NULL
    P_DEFAULT_SCHEMA               VARCHAR2                IN     DEFAULT NULL
    P_ALLOW_ACCESS_TO_SCHEMAS      VARCHAR2                IN     DEFAULT NULL
    P_ATTRIBUTE_01                 VARCHAR2                IN     DEFAULT NULL
    P_ATTRIBUTE_02                 VARCHAR2                IN     DEFAULT NULL
    P_ATTRIBUTE_03                 VARCHAR2                IN     DEFAULT NULL
    P_ATTRIBUTE_04                 VARCHAR2                IN     DEFAULT NULL
    P_ATTRIBUTE_05                 VARCHAR2                IN     DEFAULT NULL
    P_ATTRIBUTE_06                 VARCHAR2                IN     DEFAULT NULL
    P_ATTRIBUTE_07                 VARCHAR2                IN     DEFAULT NULL
    P_ATTRIBUTE_08                 VARCHAR2                IN     DEFAULT NULL
    P_ATTRIBUTE_09                 VARCHAR2                IN     DEFAULT NULL
    P_ATTRIBUTE_10                 VARCHAR2                IN     DEFAULT NULL)

Parameters

Table 17-3 describes the parameters available in CREATE_USER procedure.

Table 17-3 CREATE_USER Procedure Parameters

Parameter Description
p_user_id Numeric primary key of user account.
p_user_name Alphanumeric name used for login.
p_first_name Informational.
p_last_name Informational.
p_description Informational.
p_email_address E-mail address.
p_web_address Clear text password.
p_group_ID Colon separated list of numeric group IDs.
p_developer_privs Colon separated list of developer privileges (only applies to Oracle HTML DB administrators).
p_default_schema A database schema assigned to user's workspace used by default for browsing.
p_allow_access_to_schemas A list of schemas assigned to user's workspace to which user is restricted.
p_attribute_01

...

p_attribute_10

Arbitrary text accessible with API.

Example

BEGIN
HTMLDB_UTIL.CREATE_USER 
    P_USER_NAME    => 'NEWUSER1',
    P_WEB_PASSWORD => 'secret99'); 
END;

CREATE_USER_GROUP Procedure

This procedure changes the password of the currently authenticated user, assuming HTML DB user accounts are in use. To execute this procedure, the current user must have administrative privilege in the workspace.

Syntax

HTMLDB_UTIL.CREATE_USER_GROUP(
    P_ID                       NUMBER                  IN
    P_GROUP_NAME               VARCHAR2                IN
    P_SECURITY_GROUP_ID        NUMBER                  IN
    P_GROUP_DESC               VARCHAR2                IN);

Parameter

Table 17-4 describes the parameters available in the CREATE_USER_GROUP procedure.

Table 17-4 CREATE_USER_GROUP Parameters

Parameter Description
p_id Primary key of group.
p_group_name Arbitrary name.
p_security_group_id Workspace ID.
p_group_desc Descriptive text.

Example

BEGINHTMLDB_UTIL.CREATE_USER_GROUP (
    p_id                => 0 - trigger will assign PK,
    p_group_name        => 'Managers',
    p_security_group_id => null, -- defaults to current workspace ID
    p_group_desc        => 'text');
END;

CURRENT_USER_IN_GROUP Function

This function returns a boolean result based on whether the current user is a member of the specified group. You may use the group name or group ID to identify the group.

Syntax

HTMLDB_UTIL.CURRENT_USER_IN_GROUP(
    p_group_name    IN VARCHAR2)
RETURN BOOLEAN;

HTMLDB_UTIL.CURRENT_USER_IN_GROUP(
    p_group_id    IN NUMBER)
RETURN BOOLEAN;

Parameters

Table 17-5 describes the parameters available in CURRENT_USER_IN_GROUP function.

Table 17-5 CURRENT_USER_IN_GROUP Parameters

Parameter Description
p_group_name Identifies the name of an existing group in the workspace.
p_group_id Identifies the numeric ID of an existing group in the workspace.

Example

DECLARE VAL BOOLEAN;
BEGIN
  VAL := HTMLDB_UTIL.CURRENT_USER_IN_GROUP(p_group_name=>'Managers');
END;

EDIT_USER Procedure

This procedure enables a user account record to be altered. To execute this procedure, the current user must have administrative privileges in the workspace.

Syntax

EDIT_USER (
    P_USER_ID                      NUMBER                  IN
    P_USER_NAME                    VARCHAR2                IN
    P_FIRST_NAME                   VARCHAR2                IN     DEFAULT
    P_LAST_NAME                    VARCHAR2                IN     DEFAULT
    P_WEB_PASSWORD                 VARCHAR2                IN     DEFAULT
    P_NEW_PASSWORD                 VARCHAR2                IN     DEFAULT
    P_EMAIL_ADDRESS                VARCHAR2                IN     DEFAULT
    P_START_DATE                   VARCHAR2                IN     DEFAULT
    P_END_DATE                     VARCHAR2                IN     DEFAULT
    P_EMPLOYEE_ID                  VARCHAR2                IN     DEFAULT
    P_ALLOW_ACCESS_TO_SCHEMAS      VARCHAR2                IN     DEFAULT
    P_PERSON_TYPE                  VARCHAR2                IN     DEFAULT
    P_DEFAULT_SCHEMA               VARCHAR2                IN     DEFAULT
    P_GROUP_IDS                    VARCHAR2                IN     DEFAULT
    P_DEVELOPER_ROLES              VARCHAR2                IN     DEFAULT
    P_DESCRIPTION                  VARCHAR2                IN     DEFAULTIN);

Parameters

Table 17-6 describes the parameters available in EDIT_USER procedure.

Table 17-6 EDIT_USER Parameters

Parameter Description
p_user_id Numeric primary key of user account.
p_user_name Alphanumeric name used for login.
p_first_name Informational.
p_last_name Informational.
p_web_password Clear text password,
p_start_date Unused.
p_end_date Unused.
p_employee_id Unused.
p_allow_access_to_schemas A list of schemas assigned to user's workspace to which user is restricted.
p_person_type Unused.
p_default_schema A database schema assigned to user's workspace used by default for browsing.
p_group_ids Colon separated list of numeric group IDs.
p_developer_privs Colon separated list of developer p.rivileges (only ADMIN: has meaning to HTML DB)
p_description Informational.

EXPORT_USERS Procedure

When called from an Oracle HTML DB page, this procedure produces an export file of the current workspace definition, workspace users, and workspace groups. To execute this procedure, the current user must have administrative privilege in the workspace.

Syntax

HTMLDB_UTIL.EXPORT_USERS(
    p_export_format in varchar2 default 'UNIX');

Parameters

Table 17-7 describes the parameters available in EXPORT_USERS procedure.

Table 17-7 EXPORT_USERS Parameters

Parameter Description
p_export_format Indicates how rows in the export file will be formatted. Specify 'UNIX' to have the resulting file contain rows delimited by line feeds. Specify 'DOS' to have the resulting file contain rows delimited by carriage returns and line feeds.

Example

BEGIN
  HTMLDB_UTIL.EXPORT_USERS;
END;

FETCH_APP_ITEM Function

This function fetches session state for the current or specified application in the current or specified session.

Syntax

HTMLDB_UTIL.FETCH_APP_ITEM(
    p_item    IN VARCHAR2,
    p_app     IN NUMBER DEFAULT NULL,
    p_session IN NUMBER DEFAULT NULL)
RETURN VARCHAR2;

Parameters

Table 17-8 describes the parameters available in the FETCH_APP_ITEM function.

Table 17-8 FETCH_APP_ITEM Parameters

Parameter Description
p_item The name of an application level item (not a page item) whose current value is to be fetched.
p_app The ID of the application that owns the item (leave null for current application).
p_session The session ID from which to obtain the value (leave null for current session)

Example

DECLARE VAL VARCHAR2(30);
BEGIN
VAL := HTMLDB_UTIL.FETCH_APP_ITEM (p_item=>'F300_NAME',p_app=>300);
END;

FETCH_USER Procedure

This procedure fetches a user account record. To execute this procedure, the current user must have administrative privileges in the workspace.

Syntax

FETCH_USER (
    P_USER_ID                      NUMBER                  IN
    P_WORKSPACE                    VARCHAR2                OUT
    P_USER_NAME                    VARCHAR2                OUT
    P_FIRST_NAME                   VARCHAR2                OUT
    P_LAST_NAME                    VARCHAR2                OUT
    P_WEB_PASSWORD                 VARCHAR2                OUT
    P_EMAIL_ADDRESS                VARCHAR2                OUT
    P_START_DATE                   VARCHAR2                OUT
    P_END_DATE                     VARCHAR2                OUT
    P_EMPLOYEE_ID                  VARCHAR2                OUT
    P_ALLOW_ACCESS_TO_SCHEMAS      VARCHAR2                OUT
    P_PERSON_TYPE                  VARCHAR2                OUT
    P_DEFAULT_SCHEMA               VARCHAR2                OUT
    P_GROUPS                       VARCHAR2                OUT
    P_DEVELOPER_ROLE               VARCHAR2                OUT);

Parameters

Table 17-9 describes the parameters available in the FETCH_USER procedure.

Table 17-9 Fetch_User Parameters

Parameter Description
p_user_id Numeric primary key of user account.
p_workspace The name of the workspace
p_user_name Alphanumeric name used for login.
p_first_name Informational.
p_last_name Informational.
p_description Informational.
p_email_address E-mail address.
p_start_date Unused.
p_end_date Unused.
p_employee_id Unused.
p_allow_access_to_schemas A list of schemas assigned to user's workspace to which user is restricted.
p_person_type Unused.
p_default_schema A database schema assigned to user's workspace used by default for browsing.
p_groups Unused.
p_developer_role Unused.

FIND_SECURITY_GROUP_ID Function

This function returns the numeric security group ID of the named workspace.

Syntax

HTMLDB_UTIL.FIND_SECURITY_GROUP_ID(
    p_workspace    IN VARCHAR2
RETURN NUMBER;

Parameters

p_workspace is the name of the workspace.

Example

DECLARE VAL NUMBER;
BEGIN
  VAL := HTMLDB_UTIL.FIND_SECURITY_GROUP_ID (p_workspace=>'DEMOS');
END;

FIND_WORKSPACE Function

This function returns the workspace name associated with a security group ID.

Syntax

HTMLDB_UTIL.FIND_WORKSPACE(
    p_security_group_id    IN VARCHAR2)
RETURN VARCHAR2;

Parameters

p_security_group_id is the security group ID of a workspace.

Example

DECLARE VAL NUMBER;
BEGIN
  VAL := HTMLDB_UTIL.FIND_ FIND_WORKSPACE (p_security_group_id =>'20');
END;

GET_ATTRIBUTE Function

This function returns the value of one of the attribute values (1 through 10) of a named user in the HTML DB accounts table.

Syntax

HTMLDB_UTIL.GET_ATTRIBUTE(
    P_USERNAME                IN VARCHAR2
    P_ATTRIBUTE_NUMBER        IN NUMBER)
RETURN VARCHAR2;

Parameters

Table 17-10 describes the parameters available in the GET_ATTRIBUTE function.

Table 17-10 GET_ATTRIBUTE Parameters

Parameter Description
p_username User name in the account.
p_attribute_number Number of attributes in the user record (1 through 10).

Example

DECLARE VAL VARCHAR2(30);
BEGIN
  VAL := HTMLDB_UTIL.GET_ATTRIBUTE (
                          p_username => 'SCOTT',
                          p_attribute_number => 1);
END;

GET_CURRENT_USER_ID Function

This function returns the numeric user ID of the current user.

Syntax

HTMLDB_UTIL.GET_CURRENT_USER_ID;
RETURN NUMBER;

Example

DECLARE VAL NUMBER;
BEGIN
  VAL := HTMLDB_UTIL.GET_CURRENT_USER_ID;
END;

GET_DEFAULT_SCHEMA Function

This function returns the default schema name associated with the current user.

Syntax

HTMLDB_UTIL.GET_DEFAULT_SCHEMA;
RETURN VARCHAR2;

Example

DECLARE VAL VARCHAR2;
BEGIN
  VAL := HTMLDB_UTIL. GET_DEFAULT_SCHEMA;
END;

GET_EMAIL Function

This function returns the e-mail address associated with the named user.

Syntax

HTMLDB_UTIL.GET_EMAIL(
   P_USERNAME IN VARCHAR2);
RETURN VARCHAR2;

Parameters

p_username is the user name in the account.

Example

DECLARE VAL VARCHAR2;
BEGIN
  VAL := HTMLDB_UTIL.GET_EMAIL(p_username => 'SCOTT');
END;

GET_FILE Procedure

This procedure downloads files from the Oracle HTML DB file repository.

Syntax

HTMLDB_UTIL.GET_FILE (
    p_file_id    IN   VARCHAR2,
    p_mime_type  IN   VARCHAR2 DEFAULT NULL,
    p_inline     IN   VARCHAR2 DEFAULT 'NO');

Parameters

Table 17-11 describes the parameters available in GET_FILE procedure.

Table 17-11 GET_FILE Parameters

Parameter Description
p_file_id ID in HTMLDB_APPLICATION_FILES of the file to be downloaded. HTMLDB_APPLICATION_FILES is a view on all files uploaded to your workspace. The following example demonstrates how to use HTMLDB_APPLICATION_FILES:
DECLARE
    l_file_id NUMBER;
BEGIN
        SELECT id INTO l_file_id FROM HTMLDB_APPLICATION_FILES
WHERE filename = 'myxml';
        --
        HTMLDB_UTIL.GET_FILE(
              p_file_id   => l_file_id, 
              p_mime_type => 'text/xml',
              p_inline    => 'YES');  
END;

p_mime_type Mime type of the file to download.
p_inline Valid values include YES and NO. YES to display inline in a browser. NO to download as attachment.

Example

BEGIN
        HTMLDB_UTIL.GET_FILE(
              p_file_id   => '8675309', 
              p_mime_type => 'text/xml',
              p_inline    => 'YES');    
END;

GET_FILE_ID Function

This function obtains the primary key of a file in the Oracle HTML DB file repository.

Syntax

HTMLDB_UTIL.GET_FILE_ID (
    p_fname    IN   VARCHAR2)
RETURN NUMBER;

Parameters

p_fname is NAME in HTMLDB_APPLICATION_FILES of the file to be downloaded. HTMLDB_APPLICATION_FILES is a view on all files uploaded to your workspace

Example

DECLARE
        l_name VARCHAR2(255);
        l_file_id NUMBER;
BEGIN
        SELECT name INTO l_name FROM HTMLDB_APPLICATION_FILES
        WHERE filename = 'F125.sql';
--
        l_file_id := HTMLDB_UTIL.GET_FILE_ID(p_fname => );
END;

GET_FIRST_NAME Function

This function returns the FIRST_NAME field stored in the named user account record.

Syntax

HTMLDB_UTIL.GET_FIRST_NAME
   P_USERNAME IN VARCHAR2);
RETURN VARCHAR2;

Parameters

p_username identifies the user name in the account.

Example

DECLARE VAL VARCHAR2;
BEGIN
  VAL := HTMLDB_UTIL.GET_FIRST_NAME(p_username => 'SCOTT');
END;

GET_GROUPS_USER_BELONGS_TO Function

This function returns a colon separated list of group names to which the named user is a member.

Syntax

HTMLDB_UTIL.GET_GROUPS_USER_BELONGS_TO(
   P_USERNAME IN VARCHAR2);
RETURN VARCHAR2;

Parameters

p_username identifies the user name in the account.

Example

DECLARE VAL VARCHAR2;
BEGIN
  VAL := HTMLDB_UTIL.GET_GROUPS_USER_BELONGS_TO(p_username => 'SCOTT');
END;

GET_GROUP_ID Function

This function returns the numeric ID of a named group in the workspace.

Syntax

HTMLDB_UTIL.GET_GROUP_ID(
   P_GROUP_NAME);
RETURN VARCHAR2;

Parameters

p_group_name identifies the user name in the account.

Example

DECLARE VAL NUMBER;
BEGIN
  VAL := HTMLDB_UTIL.GET_GROUP_ID(p_group_name => 'Managers');
END;

GET_GROUP_NAME Function

This function returns the name of a group identified by a numeric ID.

Syntax

HTMLDB_UTIL.GET_GROUP_NAME(
   P_GROUP_ID);
RETURN NUMBER;

Parameters

p_group_id identifies a numeric ID of a group in the workspace.

Example

DECLARE VAL VARCHAR2;
BEGIN
  VAL := HTMLDB_UTIL.GET_GROUP_NAME(p_group_id => 8922003);
END;

GET_LAST_NAME Function

This function returns the LAST_NAME field stored in the named user account record.

Syntax

HTMLDB_UTIL.GET_LAST_NAME(
   P_USERNAME IN VARCHAR2);
RETURN VARCHAR2;

Parameters

p_username is the user name in the user account record.

Example

DECLARE VAL VARCHAR2;
BEGIN
  VAL := HTMLDB_UTIL.GET_LAST_NAME(p_username => 'SCOTT');
END;

GET_USERNAME Function

This function returns the user name of a user account identified by a numeric ID.

Syntax

HTMLDB_UTIL.GET_USERNAME(
   P_USERID);
RETURN NUMBER;

Parameters

p_userid identifies the numeric ID of a user account in the workspace.

Example

DECLARE VAL VARCHAR2;
BEGIN
  VAL := HTMLDB_UTIL.GET_USERNAME(p_userid => 228922003);
END;

GET_NUMERIC_SESSION_STATE Function

This function returns a numeric value for a numeric item. You can use this function in Oracle HTML DB applications wherever you can use PL/SQL or SQL. You can also use the shorthand, function NV, in place of HTMLDB_UTIL.GET_NUMERIC_SESSION_STATE.

Syntax

HTMLDB_UTIL.GET_NUMERIC_SESSION_STATE (
    p_item     IN VARCHAR2) 
    RETURN NUMBER;

Parameters

p_item is the case insensitive name of the item for which you wish to have the session state fetched.

Example

DECLARE
      l_item_value    Number;
BEGIN
      l_item_value := HTMLDB_UTIL.GET_NUMERIC_SESSION_STATE('my_item');
END;

GET_PREFERENCE Function

This function retrieves the value of a previously saved preference for a given user.

Syntax

HTMLDB_UTIL.GET_PREFERENCE (
    p_preference  IN    VARCHAR2 DEFAULT NULL,
    p_user        IN    VARCHAR2 DEFAULT V('USER')) 
    RETURN VARCHAR2;

Parameters

Table 17-12 describes the parameters available in the GET_PREFERENCE function.

Table 17-12 GET_PREFERENCE Parameters

Parameter Description
p_preference Name of the preference to retrieve the value.
p_value Value of the preference.
p_user User for whom the preference is being retrieved.

Example

DECLARE
      l_default_view    VARCHAR2(255);
BEGIN
      l_default_view := HTMLDB_UTIL.GET_PREFERENCE(      
                   p_preference => 'default_view',
                   p_user       => :APP_USER);
END;

GET_SESSION_STATE Function

This function returns the value for an item. You can use this function in your Oracle HTML DB applications wherever you can use PL/SQL or SQL. You can also use the shorthand, function V, in place of HTMLDB_UTIL.GET_SESSION_STATE.

Syntax

HTMLDB_UTIL.GET_SESSION_STATE (
    p_item    IN   VARCHAR2) 
    RETURN VARCHAR2;

Parameters

p_item is the case insensitive name of the item for which you wish to fetch session state.

Example

DECLARE
      l_item_value  VARCHAR2(255);
BEGIN
      l_item_value := HTMLDB_UTIL.GET_SESSION_STATE('my_item');
END;

GET_USER_ID Function

This function returns the numeric ID of a named user in the workspace.

Syntax

HTMLDB_UTIL.GET_USER_ID(
   P_USERNAME);
RETURN VARCHAR2;

Parameters

p_username identifies the name of a user in the workspace.

Example

DECLARE VAL NUMBER;
BEGIN  VAL := HTMLDB_UTIL.GET_USER_ID(p_username => 'Managers');END;

GET_USER_ROLES Function

This function returns the DEVELOPER_ROLE field stored in the named user account record.

Syntax

HTMLDB_UTIL.GET_USER_ROLES(
   P_USERNAME IN VARCHAR2);
RETURN VARCHAR2;

Parameters

p_username identifies a user name in the account.

Example

DECLARE VAL VARCHAR2;
BEGIN
  VAL := HTMLDB_UTIL.GET_USER_ROLES(p_username=>'SCOTT');
END;

IS_LOGIN_PASSWORD_VALID Function

This function returns a boolean result based on the validity of the password for a named user account in the current workspace. Returns true if the password matches and false if the password does not match.

Syntax

HTMLDB_UTIL.IS_LOGIN_PASSWORD_VALID(
P_USERNAME IN VARCHAR2,
   P_PASSWORD IN VARCHAR2);
RETURN BOOLEAN;

Parameters

Table 17-13 describes the parameters available in the IS_LOGIN_PASSWORD_VALID function.

Table 17-13 IS_LOGIN_PASSWORD_VALID Parameters

Parameter Description
p_username User name in account
p_password Password to be compared with password stored in the account.

Example

DECLARE VAL BOOLEAN;
BEGIN
  VAL := HTMLDB_UTIL. IS_LOGIN_PASSWORD_VALID (
             p_username=>'SCOTT'
             p_password=>'tiger');
END;

IS_USERNAME_UNIQUE Function

This function returns a boolean result based on whether the named user account is unique in the workspace.

Syntax

HTMLDB_UTIL.IS_USERNAME_UNIQUE(
   P_USERNAME IN VARCHAR2);
RETURN BOOLEAN;

Parameters

p_username identifies the user name to be tested.

Example

DECLARE VAL BOOLEAN;
BEGIN
  VAL := HTMLDB_UTIL.IS_USERNAME_UNIQUE(
             p_username=>'SCOTT');
END;

PUBLIC_CHECK_AUTHORIZATION Function

Given the name of a security scheme, this function determines if the current user passes the security check.

Syntax

HTMLDB_UTIL.PUBLIC_CHECK_AUTHORIZATION (
    p_security_scheme    IN    VARCHAR2) 
    RETURN BOOLEAN;

Parameters

p_security_name is the name of the security scheme that determines if the user passes the security check.

Example

DECLARE
      l_check_security  boolean;
BEGIN
      l_check_security := HTMLDB_UTIL.PUBLIC_CHECK_AUTHORIZATION('my_auth_scheme');
END;

REMOVE_PREFERENCE Procedure

This function removes the preference for the supplied user.

Syntax

HTMLDB_UTIL.REMOVE_PREFERENCE(
    p_preference    IN    VARCHAR2 DEFAULT NULL,
    p_user          IN    VARCHAR2 DEFAULT V('USER'));

Parameters

Table 17-14 describes the parameters available in the REMOVE_PREFERENCE procedure.

Table 17-14 REMOVE_PREFERENCE Parameters

Parameter Description
p_preference Name of the preference to remove.
p_user User for whom the preference is for.

Example

BEGIN
       HTMLDB_UTIL.REMOVE_PREFERENCE(
                    p_preference => 'default_view',
                    p_user       => :APP_USER);    
END;

REMOVE_SORT_PREFERENCES Procedure

This procedure removes the user's column heading sorting preference value.

Syntax

HTMLDB_UTIL.REMOVE_SORT_PREFERENCES (
    p_user  IN 	VARCHAR2 DEFAULT V('USER'));

Parameters

p_user identifies the user for whom sorting preferences will be removed.

Example

BEGIN
      HTMLDB_UTIL.REMOVE_SORT_PREFERENCES(:APP_USER);
END;

REMOVE_USER Procedure

This procedure removes the user account identified by the primary key or a user name. To execute this procedure, the current user must have administrative privilege in the workspace.

Syntax

HTMLDB_UTIL.REMOVE_USER(
    p_user_id IN NUMBER,
    p_user_name IN VARCHAR2);

Parameters

Table 17-15 describes the parameters available in the REMOVE_USER procedure.

Table 17-15 REMOVE_USER Parameters

Parameter Description
p_user_id The numeric primary key of the user account record.
p_user_name The the user name of the user account.

Example


BEGIN
HTMLDB_UTIL.REMOVE_USER(p_user_id=>'99997');
END;

BEGIN
HTMLDB_UTIL.REMOVE_USER(p_user_name => 'SCOTT');
END;

RESET_PW Procedure

This procedure resets the password for a named user and emails it to them with a message. To execute this procedure, the current user must have administrative privilege in the workspace.

Syntax

HTMLDB_UTIL.RESET_PW(
    p_user IN VARCHAR2,
    p_msg  IN VARCHAR2);

Parameters

Table 17-16describes the parameters available in the RESET_PW procedure.

Table 17-16 RESET_PW Parameters

Parameter Description
p_user The user name of the user account
p_msg Message text to be emailed to user.

Example


BEGIN
HTMLDB_UTIL.REMOVE_USER(
    p_user => 'SCOTT',
    p_msg => 'Contact help desk at 555-1212 with questions');
END;

RESET_AUTHORIZATIONS Procedure

To increase performance, Oracle HTML DB caches security checks. You can use this procedure to undo caching thus requiring all security checks be revalidated for the current user. Use this procedure if you wish users to have the ability to change their responsibilities (their authorization profile) within your application.

Syntax

HTMLDB_UTIL.RESET_AUTHORIZATIONS; 

Example

BEGIN
HTMLDB_UTIL.RESET_AUTHORIZATIONS;
END;

SET_EMAIL Procedure

This procedure updates a user account with a new e-mail address. To execute this procedure, the current user must have administrative privileges in the workspace.

Syntax

HTMLDB_UTIL.SET_EMAIL(
    p_userid IN NUMBER,
    p_email  IN VARCHAR2);

Parameters

Table 17-17 describes the parameters available in the SET_EMAIL procedure.

Table 17-17 SET_EMAIL Parameters

Parameter Description
p_userid The numeric ID of the user account.
p_email The e-mail address to be saved in user account.

Example

BEGIN
HTMLDB_UTIL.SET_EMAIL(
    p_userid  => '888883232',
    P_email   => 'scott.scott@oracle.com');
END;

SET_FIRST_NAME Procedure

This procedure updates a user account with a new FIRST_NAME value. To execute this procedure, the current user must have administrative privileges in the workspace.

Syntax

HTMLDB_UTIL.SET_FIRST_NAME(
    p_userid      IN NUMBER,
    p_first_name  IN VARCHAR2);

Parameters

Table 17-19 describes the parameters available in the SET_FIRST_NAME procedure.

Table 17-18 SET_FIRST_NAME Parameters

Parameter Description
p_userid The numeric ID of the user account.
p_first_name FIRST_NAME value to be saved in user account.

Example

BEGIN	
HTMLDB_UTIL.SET_FIRST_NAME(
    p_userid       => '888883232',
    P_first_name   => 'Scott');
END;

SET_LAST_NAME Procedure

This procedure updates a user account with a new LAST_NAME value. To execute this procedure, the current user must have administrative privileges in the workspace.

Syntax

HTMLDB_UTIL.SET_LAST_NAME(
    p_userid      IN NUMBER,
    p_last_name  IN VARCHAR2);

Parameters

Table 17-19 describes the parameters available in the SET_LAST_NAME procedure.

Table 17-19 SET_LAST_NAME Parameters

Parameter Description
p_userid The numeric ID of the user account.
p_last_name LAST_NAME value to be saved in the user account.

Example

BEGIN	
HTMLDB_UTIL.SET_LAST_NAME(
    p_userid       => '888883232',
    p_last_name   => 'SMITH');
END;

SET_USERNAME Procedure

This procedure updates a user account with a new USER_NAME value. To execute this procedure, the current user must have administrative privileges in the workspace.

Syntax

HTMLDB_UTIL.USERNAME(
    p_userid      IN NUMBER,
    p_username    IN VARCHAR2);

Parameters

Table 17-20 describes the parameters available in the SET_USERNAME procedure.

Table 17-20 SET_USERNAME Parameters

Parameter Description
p_userid The numeric ID of the user account.
p_user_name USER_NAME value to be saved in the user account.

Example

BEGIN	
HTMLDB_UTIL.SET_USERNAME(
    p_userid       => '888883232',
    P_username   => 'USER-XRAY');
END;

SET_PREFERENCE Procedure

This procedure sets a preference that will persist beyond the user's current session.

Syntax

HTMLDB_UTIL.SET_PREFERENCE (
    p_preference   IN    VARCHAR2 DEFAULT NULL,
    p_value        IN    VARCHAR2 DEFAULT NULL,
    p_user         IN    VARCHAR2 DEFAULT NULL);

Parameters

Table 17-21 describes the parameters available in the SET_PREFERENCE procedure.

Table 17-21 SET_PREFERENCE Parameters

Parameter Description
p_preference Name of the preference (case-sensitive).
p_value Value of the preference.
p_user User for whom the preference is being set.

Example

BEGIN
       HTMLDB_UTIL.SET_PREFERENCE(        
             p_preference => 'default_view',
             p_value      => 'WEEKLY',      
             p_user       => :APP_USER); 
END;

SET_SESSION_STATE Procedure

This procedure sets session state for a current Oracle HTML DB session.

Syntax

HTMLDB_UTIL.SET_SESSION_STATE (
    p_name     IN    VARCHAR2 DEFAULT NULL,
    p_value    IN    VARCHAR2 DEFAULT NULL);

Parameters

Table 17-22 describes the parameters available in the SET_SESSION_STATE procedure.

Table 17-22 SET_SESSION_STATE Parameters

Parameter Description
p_name Name of the application or page level item for which you are setting sessions state.
p_value Value of session state to set.

Example

BEGIN
HTMLDB_UTIL.SET_SESSION_STATE('my_item','myvalue');
END;

STRING_TO_TABLE Function

Given a string, this function returns a PL/SQL array of type HTMLDB_APPLICATION_GLOBAL.VC_ARR2. This array is a VARCHAR2(32767) table.

Syntax

HTMLDB_UTIL.STRING_TO_TABLE (
    p_string       IN VARCHAR2,
    p_separator    IN VARCHAR2 DEFAULT ':') 
    RETURN HTMLDB_APPLICATION_GLOBAL.VC_ARR2;

Parameters

Table 17-23 describes the parameters available in the STRING_TO_TABLE function.

Table 17-23 STRING_TO_TABLE Parameters

Parameter Description
p_string String to be converted into a PL/SQL table of type HTMLDB_APPLICATION_GLOBAL.VC_ARR2.
p_separator String separator. The default is a colon.

Example

DECLARE
       l_vc_arr2    HTMLDB_APPLICATION_GLOBAL.VC_ARR2;
BEGIN
       l_vc_arr2 := HTMLDB_UTIL.STRING_TO_TABLE('One:Two:Three');
       FOR z IN 1..l_vc_arr2.count LOOP
             	htp.p(l_vc_arr2(z));
       END LOOP;
END;

TABLE_TO_STRING Function

Given a a PL/SQL table of type HTMLDB_APPLICATION_GLOBAL.VC_ARR2, this function returns a delimited string separated by the supplied separator, or by the default separator, a colon (:).

Syntax

HTMLDB_UTIL.TABLE_TO_STRING (
    p_table       IN     HTMLDB_APPLICATION_GLOBAL.VC_ARR2,
    p_string      IN     VARCHAR2 DEFAULT ':') 
    RETURN VARCHAR2;

Parameters

Table 17-24 describes the parameters available in the TABLE_TO_STRING function.

Table 17-24 TABLE_TO_STRING Parameters

Parameter Description
p_string String separator. Default separator is a colon (:).
p_table PL/SQL table that is to be converted into a delimited string.

Example

DECLARE
       l_string     VARCHAR2(255);
       l_vc_arr2    HTMLDB_APPLICATION_GLOBAL.VC_ARR2;
BEGIN
       l_vc_arr2 := HTMLDB_UTIL.STRING_TO_TABLE('One:Two:Three');

       l_string := HTMLDB_UTIL.TABLE_TO_STRING(l_vc_arr2);
END;

URL_ENCODE Function

This function encodes (into HEX) all special characters that include spaces, question marks, and ampersands.

Syntax

HTMLDB_UTIL.URL_ENCODE (
    p_url   IN    VARCHAR2) 
    RETURN VARCHAR2;

Parameters

p_string is the string you would like to have encoded.

Example

DECLARE
      l_url  VARCHAR2(255);
BEGIN
      l_url := HTMLDB_UTIL.URL_ENCODE('http://www.myurl.com?id=1&cat=foo');
END;

HTMLDB_MAIL

You can use the HTMLDB_MAIL package to send an e-mail from an Oracle HTML DB application. This package is built on top of the Oracle supplied UTL_SMTP package. Because of this dependence, the UTL_SMTP package must be installed and functioning in order to use HTMLDB_MAIL.


See Also:

PL/SQL Packages and Types Reference for more information about the UTL_SMTP package

HTMLDB_MAIL contains two procedures. Use HTMLDB_MAIL.SEND to send an outbound e-mail message from your application. Use HTMLDB_MAIL.PUSH_QUEUE to deliver mail messages stored in HTMLDB_MAIL_QUEUE.

Topics in this section include:


Note:

The most efficient approach to sending e-mail is to create a background job (using a DBMS_JOB package) to periodically send all mail messages stored in the active mail queue.

SEND Procedure

This procedure sends an outbound e-mail message from an application. Although you can use this procedure to pass in either a VARCHAR2 or a CLOB to p_body and p_body_html, the data types must be the same. In other words, you cannot pass a CLOB to P_BODY and a VARCHAR2 to p_body_html.

When using HTMLDB_MAIL.SEND, remember the following:

  • No single line may exceed 1000 characters. The SMTP/MIME specification dictates that no single line shall exceed 1000 characters. To comply with this restriction, you must add a carriage return or line feed characters to break up your p_body or p_body_html parameters into chunks of 1000 characters or less. Failing to do so will result in erroneous e-mail messages, including partial messages or messages with extraneous exclamation points.

  • Plain text and HTML e-mail content. Passing a value to p_body, but not p_body_html results in a plain text message. Passing a value to p_body and p_body_html yields a multi-part message that includes both plain text and HTML content. The settings and capabilities of the recipient's email client determine what displays. Although most modern e-mail clients can read a HTML formatted email, remember that some users disable this functionality to address security issues.

  • Avoid images. When referencing images in p_body_html using the <img /> tag, remember that the images must be accessible to the recipient's e-mail client in order for them to see the image.

    For example, suppose you reference an image on your network called hello.gif as follows:

    <img src="http://someserver.com/hello.gif" alt="Hello" />]
    
    

    In this example, the image is not attached to the email, but is referenced by the e-mail. For the recipient to see it, they must be able to access the image using a Web browser. If the image is inside a firewall and the recipient is outside of the firewall, the image will not display. For this reason, avoid using images. If you must include images, be sure to include the ALT attribute to provide a textual description in the event the image is not accessible.

Syntax

HTMLDB_MAIL.SEND(
    p_to                        IN    VARCHAR2,
    p_from                      IN    VARCHAR2,
    p_body                      IN  [ VARCHAR2 | CLOB ],
    p_body_html                 IN  [ VARCHAR2 | CLOB ] DEFAULT,
    p_subj                      IN    VARCHAR2 DEFAULT)
    p_cc                        IN    VARCHAR2 DEFAULT)
    p_bcc                       IN    VARCHAR2 DEFAULT);

Parameters

Table 17-25 describes the parameters available in the SEND procedure.

Table 17-25 Send Parameters

Parameter Description
p_to Valid e-mail address to which the e-mail will be sent (required). For multiple e-mail addresses, use a comma separated list.
p_from E-mail address from which the e-mail will be sent (required). This e-mail address must be a valid address. Otherwise, the message will not be sent.
p_body Body of the e-mail in plain text, not HTML (required). If a value is passed to p_body_html, then this is the only text the recipient sees. If a value is not passed to p_body_html, then this text only displays for e-mail clients that do not support HTML or have HTML disabled. A carriage return or line feed (CRLF) must be included every 1000 characters.
p_body_html Body of the e-mail in HTML format. This must be a full HTML document including the <html> and <body> tags. A single line cannot exceed 1000 characters without a carriage return or line feed (CRLF).
p_subj Subject of the e-mail.
p_cc Valid e-mail addresses to which the e-mail is copied. For multiple e-mail addresses, use a comma separated list.
p_bcc Valid e-mail addresses to which the e-mail is blind copied. For multiple e-mail addresses, use a comma separated list.

Examples

The following example demonstrates how to use HTMLDB_MAIL.SEND to send a plain text e-mail message from an application.

-- Example One: Plain Text only message
DECLARE
    l_body      CLOB;
BEGIN
    l_body := 'Thank you for your interest in the HTMLDB_MAIL 
package.'||utl_tcp.crlf||utl_tcp.crlf;
    l_body := l_body ||'  Sincerely,'||utl_tcp.crlf;
    l_body := l_body ||'  The HTMLDB Dev Team'||utl_tcp.crlf;
    htmldb_mail.send(
        p_to       => 'some_user@somewhere.com',   -- change to your email address
        p_from     => 'some_sender@somewhere.com', -- change to a real senders email address
        p_body     => l_body,
        p_subj     => 'HTMLDB_MAIL Package - Plain Text message');
END;
/

The following example demonstrates how to use HTMLDB_MAIL.SEND to send a HTML e-mail message from an application. Remember, you must include a carriage return or line feed (CRLF) every 1000 characters. The example that follows uses utl_tcp.crlf.

-- Example Two: Plain Text / HTML message
DECLARE
    l_body      CLOB;
    l_body_html CLOB;
BEGIN
    l_body := 'To view the content of this message, please use an HTML enabled mail client.'||utl_tcp.crlf;

    l_body_html := '<html>
                      <head>
                        <style type="text/css">
                          body{font-family: Arial, Helvetica, sans-serif;
                               font-size:10pt;
                               margin:30px;
                               background-color:#ffffff;}

                          span.sig{font-style:italic;
                                   font-weight:bold;
                                   color:#811919;}
                        </style>
                      </head>
                      <body>'||utl_tcp.crlf;
    l_body_html := l_body_html ||'<p>Thank you for your interest in the <strong>HTMLDB_MAIL</strong> package.</p>'||utl_tcp.crlf;
    l_body_html := l_body_html ||'  Sincerely,<br />'||utl_tcp.crlf;
    l_body_html := l_body_html ||'  <span class="sig">The HTMLDB Dev Team</span><br />'||utl_tcp.crlf;
    htmldb_mail.send(
     p_to        => 'some_user@somewhere.com',   -- change to your email address
     p_from      => 'some_sender@somewhere.com', -- change to a real senders email address
     p_body      => l_body,
     p_body_html => l_body_html,
     p_subj      => 'HTMLDB_MAIL Package - HTML formatted message');
END;
/

PUSH_QUEUE Procedure

Oracle HTML DB stores unsent e-mail messages in a table named HTMLDB_MAIL_QUEUE. You can manually deliver mail messages stored in this queue to the specified SMTP gateway by invoking the HTMLDB_MAIL.PUSH_QUEUE procedure. This procedure requires two input parameters:

  • p_smtp_hostname defines the hostname of your SMTP gateway

  • p_smtp_portno defines port number of your SMTP gateway (for example, 25)

Oracle HTML DB logs successfully submitted message in the table HTMLDB_MAIL_LOG with the timestamp reflecting your server's local time. Keep in mind, the most efficient approach to sending e-mail is to create a background job (using a DBMS_JOB package) to periodically send all mail messages stored in the active mail queue.

Syntax

HTMLDB_MAIL.PUSH_QUEUE(
    p_smtp_hostname             IN    VARCHAR2 DEFAULT,
    p_smtp_portno               IN    NUMBER   DEFAULT;

Parameters

Table 17-26 describes the parameters available in the HTMLDB_MAIL procedure.

Table 17-26 PUSH_QUEUE Parameters

Parameters Description
p_smtp_hostname SMTP gateway hostname.
p_smtp_portno SMTP gateway port number.

Example

The following example demonstrates the use of the HTMLDB_MAIL.PUSH_QUEUE procedure using a shell script. This example only applies to UNIX/LINUX installations. In this example, the SMTP gateway hostname is defined as smtp01.oracle.com and the SMTP gateway port number is 25.

SQLPLUS / <<EOF
FLOWS_010600.HTMLDB_MAIL.PUSH_QUEUE('smtp01.oracle.com','25');
DISCONNECT
EXIT
EOF

HTMLDB_ITEM

You can use the HTMLDB_ITEM package to create form elements dynamically based on a SQL query instead of creating individual items page by page.

Topics in this section include:

CHECKBOX Function

This function creates check boxes.

Syntax

HTMLDB_ITEM.CHECKBOX(
    p_idx                       IN    NUMBER,
    p_value                     IN    VARCHAR2 DEFAULT,
    p_attributes                IN    VARCHAR2 DEFAULT,
    p_checked_values            IN    VARCHAR2 DEFAULT,
    p_checked_values_delimitor  IN    VARCHAR2 DEFAULT)
    RETURN VARCHAR2;

Parameters

Table 17-27 describes the parameters available in the CHECKBOX function.

Table 17-27 CHECKBOX Parameters

Parameter Description
p_idx Number which determines which HTMLDB_APPLICATION global will be used. Valid range of values is 1 to 50. For example 1 creates F01 and 2 creates F02.
p_value Value of a check box, hidden field, or input form item.
p_attributes Controls HTML tag attributes (such as disabled).
p_checked_values Values to be checked by default.
p_checked_values_delimitor Delimits the values in the previous parameter, p_checked_values.

Examples of Default Check Box Behavior

The following example demonstrates how to create a selected check box for each employee in the emp table.

SELECT HTMLDB_ITEM.CHECKBOX(1,empno,'CHECKED') " ",
       ename,
       job
FROM   emp
ORDER BY 1

The next example demonstrates how to have all check boxes for employees display without being selected.

SELECT HTMLDB_ITEM.CHECKBOX(1,empno) " ",
       ename,
       job
FROM   emp
ORDER BY 1

The next example demonstrates how to select the check boxes for employees who work in department 10.

SELECT HTMLDB_ITEM.CHECKBOX(1,empno,DECODE(deptno,10,'CHECKED',null)) " ",
       ename,
       job
FROM   emp
ORDER BY 1

The next example demonstrates how to select the check boxes for employees who work in department 10 or department 20.

SELECT HTMLDB_ITEM.CHECKBOX(1,deptno,NULL,'10:20',':') " ",
       ename,
       job
FROM   emp
ORDER BY 1

Creating an On-Submit Process

If you are using check boxes in your application, you might need to create an On Submit process to perform a specific type of action on the selected rows. For example, you could have a Delete button that utilizes the following logic:

SELECT HTMLDB_ITEM.CHECKBOX(1,empno) " ",
       ename,
       job
FROM   emp
ORDER  by 1

Consider the following sample on-submit process:

FOR I in 1..HTMLDB_APPLICATION.G_F01.COUNT LOOP
    DELETE FROM emp WHERE empno = to_number(HTMLDB_APPLICATION.G_F01(i));
END LOOP;

DATE_POPUP Function

Use this function with forms that include date fields. DATE_POPUP dynamically generates a date field that has popup calendar button.

Syntax

HTMLDB_ITEM.DATE_POPUP(
    p_idx          IN    NUMBER,
    p_row          IN    NUMBER,
    p_value        IN    VARCHAR2 DEFAULT,
    p_date_format  IN    DATE DEFAULT,
    p_size         IN    NUMBER DEFAULT,
    p_maxlength    IN    NUMBER DEFAULT,
    p_attributes   IN    VARCHAR2 DEFAULT)
    RETURN VARCHAR2;

Parameters

Table 17-28 describes the parameters available in the DATE_POPUP function.

Table 17-28 DATE_POPUP Parameters

Parameter Description
p_idx Number which determines which HTMLDB_APPLICATION global will be used.Valid range of values is 1 to 50. For example 1 creates F01 and 2 creates F02.
p_row p_row is deprecated. Anything specified for this value will be ignored.
p_value Value of a field item.
p_date_format Valid database date format.
p_size Controls HTML tag attributes (such as disabled).
p_maxlength Determine the maximum number of enterable characters. Becomes the maxlength attribute of the <input > HTML tag.
p_attributes Extra HTML parameters you wish to add.


See Also:

Oracle Database SQL Reference for more information on the TO_CHAR or TO_DATE functions

Example

The following example demonstrates how to use HTMLDB_ITEM.DATE_POPUP to create popup calendar buttons for the hiredate column.

SELECT 
  empno, 
  HTMLDB_ITEM.HIDDEN(1,empno)||
  HTMLDB_ITEM.TEXT(2,ename) ename, 
  HTMLDB_ITEM.TEXT(3,job) job, 
  mgr, 
  HTMLDB_ITEM.DATE_POPUP(4,rownum,hiredate,'dd-mon-yyyy') hd,
  HTMLDB_ITEM.TEXT(5,sal) sal, 
  HTMLDB_ITEM.TEXT(6,comm) comm,
  deptno
FROM emp
ORDER BY 1

DISPLAY_AND_SAVE Function

Use this function to display an item as text, but save its value to session state.

Syntax

HTMLDB_ITEM.DISPLAY_AND_SAVE(
    p_idx         IN    NUMBER,
    p_value       IN    VARCHAR2 DEFAULT NULL
    p_item_id     IN    VARCHAR2 DEFAULT NULL,
    p_item_label  IN    VARCHAR2 DEFAULT NULL)
    RETURN VARCHAR2;

Parameters

Table 17-29 describes the parameters available in the DISPLAY_AND_SAVE.

Table 17-29 DISPLAY_AND_SAVE Parameters

Parameter Description
p_idx Number which determines which HTMLDB_APPLICATION global will be used.Valid range of values is 1 to 50. For example 1 creates F01 and 2 creates F02.
p_value Current value.
p_item_id HTML attribute ID for the <input> tag.
p_item_label Label of the text field item.

Example

The following example demonstrates how to use HTMLDB_ITEM.DISPLAY_AND_SAVE.

SELECT HTMLDB_ITEM.DISPLAY_AND_SAVE(10,empno) c FROM emp

HIDDEN Function

This function dynamically generates hidden form items.

Syntax

HTMLDB_ITEM.HIDDEN(
    p_idx     IN    NUMBER,
    p_value   IN    VARCHAR2 DEFAULT)
    RETURN VARCHAR2;

Parameters

Table 17-30 describes the parameters available in the HIDDEN function.

Table 17-30 HIDDEN Parameters

Parameter Description
p_idx Number to identify the item you wish to generate. The number will determine which G_FXX global is populated.

See Also: "HTMLDB_APPLICATION"

p_value Value of the hidden input form item.

Example

Typically, the primary key of a table is stored as a hidden column and used for subsequent update processing. Consider the following sample SLQ query:

SELECT
  empno, 
  HTMLDB_ITEM.HIDDEN(1,empno)||
  HTMLDB_ITEM.TEXT(2,ename) ename,
  HTMLDB_ITEM.TEXT(3,job) job, 
  mgr, 
  HTMLDB_ITEM.DATE_POPUP(4,rownum,hiredate,'dd-mon-yyyy') hiredate,
  HTMLDB_ITEM.TEXT(5,sal) sal, 
  HTMLDB_ITEM.TEXT(6,comm) comm, 
  deptno
FROM emp
ORDER BY 1

The previous query could use the following page process to process the results:

BEGIN 
  FOR i IN 1..HTMLDB_APPLICATION.G_F01.COUNT LOOP
    UPDATE emp
    SET
      ename=HTMLDB_APPLICATION.G_F02(i),
      job=HTMLDB_APPLICATION.G_F03(i),
      hiredate=to_date(HTMLDB_APPLICATION.G_F04(i),'dd-mon-yyyy'),
      sal=HTMLDB_APPLICATION.G_F05(i),
      comm=HTMLDB_APPLICATION.G_F06(i)
    WHERE empno=to_number(HTMLDB_APPLICATION.G_F01(i));
  END LOOP;
END;

Note that the G_F01 column (which corresponds to the hidden EMPNO) is used as the key to update each row.

MD5_CHECKSUM Function

This function passes values to HTMLDB_ITEM.MULTI_ROW_UPDATE and is used for lost update detection. Lost update detection ensures data integrity in applications where data can be accessed concurrently.

Syntax

HTMLDB_ITEM.MD5_CHECKSUM(
    p_value01   IN    VARCHAR2 DEFAULT,
    p_value02   IN    VARCHAR2 DEFAULT,
    p_value03   IN    VARCHAR2 DEFAULT,
    ...
    p_value50   IN    VARCHAR2 DEFAULT,
    p_col_sep   IN    VARCHAR2 DEFAULT)
    RETURN VARCHAR2;

Parameters

Table 17-32 describes the parameters available in the MD5_CHECKSUM function.

Table 17-31 MD5_HIDDEN Parameters

Parameter Description
p_value01

...

p_value50

Fifty available inputs. Parameters that are not supplied default to null.
p_col_sep String used to separate p_value inputs. Defaults to the pipe symbol (|).

Example

SELECT HTMLDB_ITEM.MD5_CHECKSUM(ename,job,sal)
FROM emp

MD5_HIDDEN Function

This function is used for lost update detection which ensures data integrity in applications where data can be accessed concurrently.

This function produces a hidden form field and includes 50 inputs. HTMLDB_ITEM.MD5_HIDDEN also produces an MD5 checksum using the Oracle database DBMS_OBFUSCATION_TOOLKIT:

UTL_RAW.CAST_TO_RAW(DBMS_OBFUSCATION_TOOLKIT.MD5())

An MD5 checksum provides data integrity through hashing and sequencing to assure that data is not altered or stolen as it is transmitted over a network

Syntax

HTMLDB_ITEM.MD5_HIDDEN(
    p_idx       IN    NUMBER,
    p_value01   IN    VARCHAR2 DEFAULT,
    p_value02   IN    VARCHAR2 DEFAULT,
    p_value03   IN    VARCHAR2 DEFAULT,
    ...
    p_value50   IN    VARCHAR2 DEFAULT,
    p_col_sep   IN    VARCHAR2 DEFAULT)
    RETURN VARCHAR2;

Parameters

Table 17-32 describes the parameters available in the MD5_HIDDEN function.

Table 17-32 MD5_HIDDEN Parameters

Parameter Description
p_idx Indicates the form element to be generated. For example, 1 equals F01 and 2 equals F02. Typically the p_idx parameter is constant for a given column.
p_value01

...

p_value50

Fifty available inputs. Parameters not supplied default to null.
p_col_sep String used to separate p_value inputs. Defaults to the pipe symbol (|).

Example

p_idx specifies the FXX form element to be generated. In the following example, 7 generates F07. Also note that an HTML hidden form element will be generated.

SELECT HTMLDB_ITEM.MD5_HIDDEN(7,ename,job,sal), ename, job, sal FROM emp

MULTI_ROW_UPDATE Procedure

Use this procedure within a Multi Row Update process type. This procedure takes a string containing a multiple row update definition in the following format:

OWNER:TABLE:pk_column1,pk_idx:pk_column2,pk_idx2|col,idx:col,idx...  

Syntax

HTMLDB_ITEM.MULTI_ROW_UPDATE(
    p_mru_string    IN    VARCHAR2 DEFAULT)
    RETURN VARCHAR2;

Example

To use this procedure indirectly within application level process, you need to create a query to generate a form of database data. The following example demonstrates how to create a multiple row update on the emp table.

SELECT 
empno,
HTMLDB_ITEM.HIDDEN(1,empno),
HTMLDB_ITEM.HIDDEN(2,deptno),
HTMLDB_ITEM.TEXT(3,ename),
HTMLDB_ITEM.SELECT_LIST_FROM_QUERY(4,job,'SELECT DISTINCT job FROM emp'),
HTMLDB_ITEM.TEXT(5,sal),
HTMLDB_ITEM.TEXT(7,comm),
HTMLDB_ITEM.MD5_CHECKSUM(ename,job,sal,comm),
deptno
FROM emp
WHERE deptno = 20

Note the call to HTMLDB_ITEM.MD5_CHECKSUM instead of HTMLDB_ITEM.MD5_HIDDEN. Since HTMLDB_ITEM.MULTI_ROW_UPDATE gets the checksum from HTMLDB_APPLICATION.G_FCS, you need to call HTMLDB_ITEM.MD5_CHECKSUM in order to populate HTMLDB_APPLICATION.G_FCS when the page is submitted. Additionally, the columns in HTMLDB_ITEM.MD5_CHECKSUM must be in the same order those in the MULTI_ROW_UPDATE process. These updates can then processed (or applied to the database) using an after submit page process of Multi Row Update in a string similar to the following:

SCOTT:emp:empno,1:deptno,2|ename,3:job,4:sal,5:comm,7:,:,:,:,

SELECT_LIST Function

This function dynamically generates a static select list. Similar to other functions available in the HTMLDB_ITEM package, these select list functions are designed to generate forms with F01 to F50 form array elements.

Syntax

HTMLDB_ITEM.SELECT_LIST(
    p_idx           IN   NUMBER,
    p_value         IN   VARCHAR2 DEFAULT,
    p_list_values   IN   VARCHAR2 DEFAULT,
    p_attributes    IN   VARCHAR2 DEFAULT,
    p_show_null     IN   VARCHAR2 DEFAULT,
    p_null_value    IN   VARCHAR2 DEFAULT,
    p_null_text     IN   VARCHAR2 DEFAULT,
    p_item_id       IN   VARCHAR2 DEFAULT,
    p_item_label    IN   VARCHAR2 DEFAULT,
    p_show_extra    IN   VARCHAR2 DEFAULT)
    RETURN VARCHAR2;

Parameters

Table 17-33 describes the parameters available in the SELECT_LIST function.

Table 17-33 SELECT_LIST Parameters

Parameter Description
p_idx Form element name. For example, 1 equals F01 and 2 equals F02. Typically the P_IDX parameter is constant for a given column.
p_value Current value. This value should be a value in the P_LIST_VALUES parameter.
p_list_values List of static values separated by commas. Display values and return values are separated by semicolons.

Note that this is only available in the SELECT_LIST function.

p_attributes Extra HTML parameters you wish to add.
p_show_null Extra select option to enable the NULL selection. Range of values is YES and NO.
p_null_value Value to be returned when a user selects the null option. Only relevant when P_SHOW_NULL equals YES.
p_item_id HTML attribute ID for the <input> tag.
p_item_label Label of the select list.
p_show_extra Show the current value even if the value of p_value is not located in the select list.

Example

The following example demonstrates a static select l