4 Changing the Look and Navigation of the Oracle Content Server Interface

This chapter provides information about the several different methods that you can use to change the look and navigation of the Oracle Content Server interface.

This chapter includes the following sections:

Tip:

In addition to the methods discussed here, you can also alter the metadata fields that are presented to users and modify the type of presentation used for check-in pages, search pages, and other user interfaces. For information about creating and modifying metadata fields and creating content profiles, see "Managing Repository Content" in Oracle Fusion Middleware Application Administrator's Guide for Content Server.

4.1 Modifying the Oracle Content Server Interface

This section describes how to modify the Oracle Content Server interface, in these subsections:

4.1.1 Skins and Layouts

Skins and layouts provide alternate color schemes and alternate navigation designs. The following sections describe the skins and layouts provided by default with Oracle Content Server:

4.1.1.1 Types of Skins and Layouts

Some skins and layouts are provided by default with Oracle Content Server. In addition, you can design custom skins and layouts. When you change the skin or layout, you change the look and feel of the interface. You can select a skin and layout from the options provided on the User Profile page.

The only skills required to create and modify skins or layouts is an understanding of HTML, Cascading Style Sheets, and JavaScript. After altering the appearance, the edited layouts and skins are published so that others in your environment can use them.

Note:

Only administrators can make new or custom skins. For more information about setting the default look and feel of the user interface, see Section 4.1.1.3, "Configuration Entries."
4.1.1.1.1 Skins

Skins define the color scheme and other aspects of appearance of the layout such as graphics, fonts, or font size. (the default skin is Oracle). You can design custom skins or modify the existing skins.

4.1.1.1.2 Layouts

Layouts define the navigation hierarchy display (the default layout is Trays) and custom layouts can be designed. Custom layouts change behavior and the look-and-feel systemwide. If you want your changes to apply only in limited situations, you might want to consider dynamic server pages.These layouts are provided:

  • Trays: This layout with the standard Oracle skin is the default interface. High-level navigation occurs through the navigation trays.

  • Top Menus: This layout provides an alternate look with top menus providing navigation.

4.1.1.2 Selecting Skins and Layouts

The User Personalization settings available on the User Profile page enable users to change the layout of Oracle Content Server or the skin.

Important:

This personalization functionality works with Internet Explorer 7+ or Mozilla Firefox 3+ and later versions.

To change the skin or layout, follow these steps:

  1. On the Oracle Content Server Home page, click your_user_name in the top menu bar. The User Profile page displays.

  2. On the Oracle Content Server User Profile page, select the desired skin and layout.

  3. Click Update, and view the changes.

4.1.1.3 Configuration Entries

These values can be placed in the IntradocDir/config/config.cfg file to alter the default behavior for the Oracle Content Server instance:

  • LmDefaultLayout: The name of the layout used by guests, and new users. The default is Trays, but it can be set to Top Menus.

  • LmDefaultSkin: The name of the skin used by guests, and new users. The default is Oracle.

4.1.1.4 Anonymous User Interface

The ExtranetLook component can be used to change the interface for users who log in as anonymous random users. An example of this is when a web site based on Oracle Content Server must be available to external customers without a login, but you want employees to be able to contribute content to that web site.

When Oracle Content Server is running on Oracle WebLogic Server, the ExtranetLook component alters privileges for certain pages so that they require write privilege to access. The component also makes small alterations to the static portal page to remove links that anonymous, random users should not see.

Note:

The ExtranetLook component does not provide form-based authentication for Oracle WebLogic Server or provide customizable error pages.

The ExtranetLook component is installed (disabled) with Oracle Content Server. To use the component you must enable it with the Component Manager.

You can customize your web pages to make it easy for customers to search for content, and then give employees a login that permits them to see the interface on login. To do the customization, modify the ExtranetLook.idoc file, which provides dynamic resource includes that can be customized based on user login. The IDOC file is checked in to the Oracle Content Server repository so it can be referenced by the Oracle Content Server templates.

The following files in the IntradocDir/data/users directory can be altered:

  • prompt_login.htm

  • access_denied.htm

  • report_error.htm

Use the following procedure to update the look-and-feel of the web site based on user login:

  1. Display the Web Layout Editor.

  2. From the Options menu, choose Update Portal.

  3. Modify the portal page as you wish. You can use dynamic resource includes based on user login to customize this page.

  4. Click OK.

  5. Customize the ExtranetLook.idoc file as desired.

  6. Check out the ExtranetLook content item from Oracle Content Server.

  7. Check in the revised ExtranetLook.idoc file to Oracle Content Server.

4.1.2 Customizing the Interface

The Top Menus and Trays layouts are included by default with the system. The two layouts have two skin options (Oracle and Oracle2). The layouts are written in JavaScript and the "look" of the skins is created using Cascading Style Sheets.

You can modify layouts and skins by altering the template files provided with Oracle Content Server or design new skins and layouts by creating components that can be shared with other users.

The following sections provide an overview of this process.

4.1.2.1 About Dynamic Publishing

When the Oracle Content Server starts, or when the PUBLISH_WEBLAYOUT_FILES service is run, the PublishedWeblayoutFiles table in the std_resource.htm file is used to publish files to the weblayout directory. To have your custom component use this publishing mechanism, create a template, and then merge a custom row that uses that template into the PublishedWeblayoutFiles table.

Other users who want to modify or customize your file can override your template or your row in the PublishedWeblayoutFiles table. If your template uses any resource includes, other users can override any of these includes or insert their own Idoc Script code using the standard super notation. When your component is disabled, the file is no longer published or modified and Oracle Content Server returns to its default state.

In addition to giving others an easy way to modify and add to your work, you can also construct these former static files using Idoc Script. For example, you can have the files change depending on the value of a custom configuration flag. You can use core Oracle Content Server objects and functionality by writing custom Idoc Script functions and referencing them from inside your template.

Because this Idoc Script is evaluated once during publishing, you cannot use Idoc Script as you would normally do from the IdcHomeDir/resources/core/idoc/std_page.idoc file. When a user requests that file, it has already been created, so the script used to create it did not have any access to the current service's DataBinder or any information about the current user.

This does limit the type of Idoc Script you can write in these files, so if you are writing CSS or JavaScript that needs information that dynamically changes with users or services, consider having the pages that need this code include the code inline. This increases the size of pages delivered by your web server and thus increases the amount of bandwidth used.

4.1.2.2 Creating New Layouts

This section describes the general steps needed to create and publish new layouts.

  1. Merge a table into the LmLayouts table in IdcHomeDir/resources/core/tables/std_resources.htm to define the new layout. Define the layout ID, label, and whether it is enabled (set to 1) or not.

  2. Merge a table into the PublishedWeblayoutFiles table in IdcHomeDir/resources/core/tables/std_resources.htm. This new table describes the files that are created from Oracle Content Server templates and then pushed out to the weblayout directory. Specify the necessary skin.css files to push out to each skin directory.

  3. Merge a table with the PublishStaticFiles table in std_resources.htm. This lists the directories that contain files, such as images, that should be published to the weblayout directory.

4.1.3 Optimizing the Use of Published Files

You can direct Oracle Content Server to bundle published files so they can be delivered as one, thus minimizing the number of page requests to the server. In addition, you can optimize file use by referencing published pages using Idoc Script.

The following sections describe how to optimize the use of published files:

4.1.3.1 Bundling Files

Multiple resources may be packaged together into units called bundles. A bundle is a single file containing one or more published resources. Only JavaScript and css resources should be bundled and only with other resources of the same type. Bundling helps reduce the client overhead when pages are loaded but increases client parse/compile/execute overhead. Generally, it is recommended to bundle resources that have some thematic similarity or are expected to be included at similar times. For example, if you know that resources A, B, and C are needed on every page, and resources D, E, and F are needed rarely but are all needed together, it is recommended to bundle A, B, and C together and to put D, E, and F into a separate bundle.

Almost all core Oracle Content Server JavaScript resources are bundled into one of two bundles: yuiBundle.js, which contains script provided by the third-party Yahoo User Interface library, and bundle.js, which contains the rest of the resources.

The PublishedBundles table is used for determining how resources are bundled. Essentially a bundle is identified by its target bundlePath, which is the path name to the bundle (relative to the weblayout directory), and a list of rules detailing which resource classes are included or excluded. A loadOrder value in this table applies only to the order in which the filtering rules are applied, not the order in which the resources appear in the bundle.

Note:

The bundling has changed since Oracle UCM 10g, which used a different table and had a loadOrder value that determined the order of resources in each bundle.

Static weblayout file contents are cached on client machines and on web proxies, significantly lowering the amount of server bandwidth they use. Therefore, the best practice is to use these types of files wherever possible.

However, each static weblayout file requested by the client's browser requires a round-trip to the server just to verify that the client has the most up-to-date version of the file. This occurs even if the file is cached. Therefore, as the number of these files grows, so does the number of downloads from the server for each page request.

To help minimize the number of round-trips, Oracle Content Server can bundle multiple published files so they are delivered as one. This feature can be disabled by setting the following configuration in the server's IntradocDir/config/config.cfg file:

BundlePublishedWeblayoutFiles=false

Bundling is accomplished by using the PublishedBundles table in the std_resources.htm file.

<@table PublishedBundles@>
<table border=1><caption><strong>
    <tr>
        <td>bundlePath</td>
        <td>includeClass</td>
        <td>excludeClass</td>
        <td>loadOrder</td>
    </tr>
    <tr>
        <td>resources/bundle.js</td>
        <td>javascript:common</td>
        <td></td>
        <td>128</td>
    </tr>
. . .
</table>
<@end@>

The columns in this table are as follows:

  • bundlePath: The eventual location where the bundle is published. This path is relative to the weblayout directory.

  • includeClass: This is used to determine which resources to include in a bundle.

  • excludeClass: This is used to determine which resources to exclude from a bundle.

  • loadOrder: The order in which the includeClass and excludeClass filters are applied.

In the previous example, files of the javascript:common class are published to a single bundle located at resources/layouts/commonBundle.js. The contents of all bundled files that match this class are appended to form a single file to be stored at that location.

4.1.3.2 Referencing Published Files

Most published files (both bundled and unbundled) must be directly referenced from within HTML to be included in a page. It can therefore be difficult to know exactly which files to include for a given situation, especially when bundling can be enabled or disabled by server administrators. A simple Idoc Script method can be used to easily and transparently include all of the files you need on a given page.

For example, if you write a page that includes all files associated with the javascript:common bundle (as described previously), then do not write HTML that includes all of the files mentioned in the first table in addition to the bundle mentioned in the second, the server is asked for each file. This negates the purpose of bundling because the server is pinged for each file whether it actually exists or not.

To correctly include these files on a page, use the following Idoc Script and include it from somewhere within the HEAD of the page:

<$exec createPublishedResourcesList("javascript:common")$>
<$loop PublishedResources$>
<script language="JavaScript" src="<$HttpWebRoot$><$PublishedResources.path$>" />
</script>
<$endloop$>

This code fragment includes all javascript:common files even if bundling is switched off. If javascript instead of javascript:common is passed, all files whose class starts with javascript are included.

This PublishedResources result set is sorted by loadOrder so files and bundles with the lowest loadOrder are included first. Files with a greater loadOrder can override JavaScript methods or CSS styles that were declared earlier.

4.2 Using Dynamic Server Pages to Alter the Navigation of Web Pages

This section describes how to use the building blocks necessary for creating dynamic server pages to alter the navigation of web pages.

This chapter includes the following sections:

4.2.1 About Dynamic Server Pages

Dynamic server pages are files that are checked in to Oracle Content Server and then used to generate web pages dynamically. Dynamic server pages are typically used to alter the look-and-feel and navigation of web pages. For example, dynamic server pages can be used to:

  • Create web pages to be published through Content Publisher

  • Implement HTML forms

  • Maintain a consistent look-and-feel throughout a web site

Dynamic server pages include the following file formats:

  • IDOC: A proprietary scripting language

  • HCST: Hypertext Content Server Template, similar to a standard Oracle Content Server template page stored in the IdcHomeDir/resources/core/templates directory.

  • HCSP: Hypertext Content Server Page, an HTML-compliant version of the HCST page, usually used for published content.

  • HCSF: Hypertext Content Server Form, similar to HCSP and HCST pages, but containing HTML form fields that can be filled out and submitted from a web browser

When you use dynamic server pages, Oracle Content Server assembles web pages dynamically using a custom template (HCST, HCSP, or HCSF file) that you have checked in to Oracle Content Server. The template calls HTML includes from a text file (IDOC file) you have also checked in to Oracle Content Server.

To make changes to the look-and-feel or navigation on a web page, you modify the HCS* template page, or the IDOC file, or both, and then check in the revised files as new revisions. Your changes are available immediately.

Using dynamic server pages with Oracle Content Server gives you these advantages:

  • You can introduce and test customizations quickly and easily. Simply checking in a revision of a dynamic server page implements the changes immediately—you do not have to restart Oracle Content Server.

  • Your web pages can make use of functionality not found in standard HTML. For example, HTML forms can be submitted directly to Oracle Content Server without the need for CGI scripts. Also, Idoc Script enables you to work directly with environment and state information about Oracle Content Server.

  • You do not have to install or keep track of component files. It can be difficult to maintain and troubleshoot components if they have a lot of files or your system is highly customized. Dynamic server pages are easier to work with because you can check in just a few content items that contain all of your customizations.

  • Customizations can be applied to individual pages. Dynamic server pages enable you to apply customizations to a single page rather than globally, leaving the standard Oracle Content Server page coding intact.

Keep the following constraints in mind when deciding whether to use dynamic server pages:

  • Dynamic server pages cannot be used to modify core functionality of Oracle Content Server. Dynamic server pages are most useful for customizing your web design and form pages.

  • Frequent revisions to dynamic server pages can result in a large number of obsolete content items. You should do as much work on a development system as possible before deploying to a production instance, and you may need to delete out-of-date pages regularly.

Figure 4-1 The Dynamic Server Page Process

Description of Figure 4-1 follows
Description of "Figure 4-1 The Dynamic Server Page Process"

4.2.2 Page Types

There are four types of dynamic server pages, which are identified in Oracle Content Server by their four-character file name extensions:

4.2.2.1 IDOC File

An IDOC file is a text file containing HTML includes that are called by HCST, HCSP, and HCSF pages.

For more information about includes, see Chapter 3, "Working with Standard, Server, and Custom Components."

4.2.2.2 HCST File

A Hypertext Content Server Template (HCST) file is a template page, similar to a standard Oracle Content Server template page, that is used as a framework for assembling a web page.

  • HCST pages are typically used when the content of the page itself is dynamic or where Oracle Content Server functionality is needed, such as on a search page, search results page, or custom check-in page.

  • Because this type of page consists mostly of dynamically assembled code, HCST files are not indexed in Oracle Content Server.

4.2.2.3 HCSP File

A Hypertext Content Server Page (HCSP) file is a published web page that displays actual web site content.

  • HCSP files are typically created either by generating the web page through Content Publisher using an HCST page as a template, or by submittal of a form in Oracle Content Server through an HCSF page.

  • Because this type of page contains web-viewable content, HCSP files are indexed in Oracle Content Server.

4.2.2.4 HCSF File

A Hypertext Content Server Form (HCSF) file is similar to an HCSP file, except that it contains HTML form fields that can be filled out and submitted from a web browser.

  • When a user fills out and submits a form from an HCSF page, an HCSP file is checked in as a separate content item with metadata defined by XML tags in the HCSF page.

  • Because this type of page contains web-viewable content, HCSF files are indexed in Oracle Content Server.

    For more information about HCSF pages, see Section 4.2.2.4, "HCSF File."

4.2.3 Creating Dynamic Server Pages

Although dynamic server pages are implemented in Oracle Content Server differently than custom components, you must be familiar with Oracle UCM component architecture concepts, particularly Oracle Content Server templates and HTML includes. For more information, see Chapter 3, "Working with Standard, Server, and Custom Components."

Use the following basic procedure to customize your Oracle Content Server instance using dynamic server pages:

  1. Create an IDOC file with custom includes.

  2. Check in the IDOC file to Oracle Content Server.

  3. Create an HCST, HCSP, or HCSF file that references the IDOC file.

  4. Check in the HCS* file to Oracle Content Server.

  5. Display the HCS* file in your web browser by searching for it in Oracle Content Server or linking to it from a published web page.

    Tip:

    Using dynamic server pages with Content Publisher can be a powerful tool for web publishing. For more information, see the Content Publisher documentation.

4.2.4 Syntax

Because the different types of dynamic server pages are interpreted and displayed differently, the Idoc Script in the files must be coded differently. The following table summarizes these differences.

File Type .idoc .hcst .hcsp .hcsf
Full Text Indexed? No No Yes Yes
Idoc Script Tags <$ … $> <$ … $> <!--$ … -->

[!--$ … --]

<!--$ … -->

[!--$ … --]

Comparison Operators Symbols (==) Symbols (==) Special operators (eq) Special operators (eq)
Special Characters Symbols (&) Symbols (&) Escape sequence (&amp;) Escape sequence (&amp;)
Referencing Metadata Required Required Required Required

Notes:

Idoc uses standard HTML include coding. For more information, see Section 3.5.1, "HTML Include."

HCST uses standard Oracle Content Server template coding. For more information, see Section 3.5.8.1, "Template and Report Pages."

Special coding is used with HCSP and HCSF to allow the page to be rendered both statically and dynamically, and full-text indexed.

4.2.4.1 Idoc Script Tags

For HCSP and HCSF pages, Idoc Script expressions are generally placed between HTML comment tags. When viewed statically, this allows a web browser to present the page content while ignoring any dynamic code that is used to format the content. This also enables the full-text indexing engine to successfully index the contents of these pages.

For example:

  • IDOC or HCST file: <$include MyIdocTag$>

  • HCSP or HCSF file: <!--$include MyIdocTag-->

In some situations, you may want to control the opening and closing of the HTML comment. In HCSP and HCSF files, this can be done by substituting other characters for the dash (-) in the closing tag of an Idoc Script expression.

For example:

<!--$a="ab"##> HTML comment remains open
<a href="<!--$myUrlAsVariable##>">MyUrl</a> Static view does not see this
<!--$dummy=""--> <!—Ended the comment area-->.

In the preceding example, the pound sign (#) is substituted for the dash (-).

Another option in HCSP and HCSF files is to substitute brackets ([ ]) for the opening and closing tags (< >) in the standard HTML comment tags. This allows an XHTML parser to properly identify all the script when viewed statically.

For example:

<!--$a="ab"--] HTML comment remains open
<a href="[!--$myUrlAsVariable--]">MyUrl</a> Static view does not see this
[!--$dummy=""--> <!—Ended the comment area-->.

4.2.4.2 Comparison Operators

For HCSP and HCSF pages, the standard comparison operators (such as ==) cannot be used because of their special meaning to HTML parsers. Use the following comparison operators in dynamic server pages.

IDOC or HCST File HCSP or HCSF File Description
== eq Tests for equality.
!= ne Tests for inequality.
< lt Tests if less than.
> gt Test if greater than.
<= le Tests if less or equal than.
>= ge Tests if greater or equal than.

For example, the following code evaluates whether the value of the variable count is greater than 10.

IDOC or HCST File HCSP or HCSF File
<$if count > 10$>
    <$"Count is greater than"$>
<$endif$>
<!--$if count gt 10-->
    <!--$"Count is greater than"-->
<!--$endif-->

4.2.4.3 Special Characters

For HCSP and HCSF pages, special characters such as the ampersand (&) cannot used because of their special meaning to HTML parsers. You must use the standard HTML/XML escape format (such as &amp; or &#038;).

Note:

It is especially important to use the &amp; escape character when you call the docLoadResourceIncludes function from an HCSP or HCSF page. For more information, see Section 4.2.5.1, "docLoadResourceIncludes Function."

For example, in Idoc Script, a quotation mark can be included in a string by preceding it with a backslash escape character. However, in an HCSP or HCSF page, the quotation mark character must be represented by an HTML escape character:

  • IDOC or HCST file: "Enter \"None\" in this field."

  • HCSP or HCSF file: "Enter &quot;None&quot; in this field."

In an HCST page, a line feed is inserted using \n. In an HCSP page, insert the line feed directly in the file or encode it in the XML using the numeric ASCII number for a line feed.

Note:

You can now substitute the word join for the & string join operator. For example, you can write [!--$a join b--] instead of [!--$a & b--]. The first is accepted by an XML parser inside an attribute of a tag, but the second is not.

4.2.4.4 Referencing Metadata

For dynamic server pages, several metadata values are stored with a ref: prefix, which makes them available to the page but does not replace ResultSet values. (This prevents "pollution" of ResultSets by dynamic server pages.)

When you reference any of the following metadata values on a dynamic server page, you must include the ref: prefix:

  • hasDocInfo

  • dDocName

  • dExtension

  • dSecurityGroup

  • isLatestRevision

  • dDocType

For example, the following statement determines if the document type is Page:

<$if strEquals(ref:dDocType,"Page"))$>

4.2.5 Idoc Script Functions

The following sections describe two special Idoc Script functions that are required for dynamic server pages:

4.2.5.1 docLoadResourceIncludes Function

To be able to use the HTML includes in an IDOC file, an HCS* file must call the docLoadResourceIncludes function. This function loads all the includes from the specified IDOC file for use in assembling the current page.

For example:

HCST file:

<$docLoadResourceIncludes("dDocName=system_std_page&RevisionSelectionMethod=Latest")$>

HCSP or HCSF file:

<!--$docLoadResourceIncludes("dDocName=system_std_page&amp;RevisionSelectionMethod=Latest")-->
4.2.5.1.1 Requirements for Calling the docLoadResourceIncludes Function
  • The native file for the specified content item must have an .idoc extension.

  • The docLoadResourceIncludes call must be placed before the first include call in the HCS* file. It is recommended that you place this function within the <HEAD> section of the page.

  • You must use the correct ampersand character when you call the docLoadResourceIncludes function from an HCS* page. For more information, see Section 4.2.4.3, "Special Characters."

4.2.5.1.2 Parameters

Use the following parameters with the docLoadResourceIncludes function to specify which IDOC file to call.

  • You must define either a dDocName or a dID; do not use both parameters together.

  • If you define a dDocName, you must define RevisionSelectionMethod to be Latest or LatestReleased.

  • If you define a dID, do not define a RevisionSelectionMethod, or define the RevisionSelectionMethod to be Specific.

    Parameter Description
    dDocName Specifies the Content ID of the IDOC file.

    This parameter should always be present when the Content ID is known. Error messages assume that it is present, as do other features such as forms.

    dID Specifies the unique ID number of a particular revision of the IDOC file.
    RevisionSelectionMethod Specifies which revision of the IDOC file to use.

    Latest—The latest checked in revision of the document is used (including revisions in a workflow).

    LatestReleased—The latest released revision of the document is used.

    Specific—Use only with dID.

    Rendition Specifies which rendition of the IDOC file to use.

    Primary—The primary (native) file. This is the default if no Rendition is specified.

    Web—The web-viewable file.

    Alternate—The alternate file.


4.2.5.2 executeService Function

The executeService function executes an Oracle Content Server service from within a dynamic server page. For example:

HCST file: <$executeService("GET_SEARCH_RESULTS")$>

HCSP or HCSF file: <!--$executeService("GET_SEARCH_RESULTS")-->

4.2.6 Development Recommendations

This section provides some guidelines to assist you in developing dynamic server pages. It includes the following sections:

4.2.6.1 General Tips

The following recommendations apply to the development of all types of dynamic server pages:

  • Keep templates as simple and free of code as possible. Strive to have only HTML includes in your templates, with all code and conditionals in an IDOC file. This is especially helpful for HCSF pages, where submitted forms also reflect changes made to the IDOC file.

  • Whenever you are customizing an Oracle Content Server instance, you should isolate your development efforts from your production system. Keep in mind that frequent revisions to dynamic server pages can result in a large number of obsolete content items. You should do as much work on a development system as possible before deploying to a production instance, and you may need to delete out-of-date pages regularly.

  • When you develop a web site using dynamic server pages, think of the development and contribution processes in terms of ownership:

    • Structure, including site design and navigation, is owned by the webmaster. When you use dynamic server pages, structure is contained in and controlled with includes that are defined in IDOC files.

    • Content, that is, the actual text of the web pages, is owned by the contributors. When you use dynamic server pages, content is contained primarily in HCSP files that make use of the includes in the IDOC files.

  • Using dynamic server pages with Content Publisher can be a powerful tool for web publishing. You can create content using Word documents or HCSF pages, and then use Content Publisher to convert the documents to published HCSP files. You can also use the "include before" and the "include after" options in the SCP template to insert additional Idoc Script includes.

  • If you publish dynamic server pages with Content Publisher, use the prefix option for easy identification of your documents.

  • Use a consistent naming convention. For example, for "system" level includes, you could name your IDOC file system_std_page, and then name each include in that file with the prefix system_. This makes locating the includes easier.

  • You may want to create a content type for each type of dynamic server page (such as HCSF_templates or submitted_forms).

  • In accordance with good coding practices, you should always put comments in dynamic server pages to document your customizations.

4.2.6.2 HCSF Tips

The following recommendations apply specifically to the development of HCSF pages:

  • When designing a form, consider how the template will be used:

    • Will this template change depending on the role of the user submitting the form?

    • Will the submitted content enter into a criteria workflow?

    • What default metadata values should be set?

    • Does the form contain ResultSets for multiple line entries?

  • To see the form parameters as they are passed from the web browser to the web server, filtered through Oracle Content Server, and then passed back to the web browser, change the METHOD attribute in the include code from a POST to a GET:

    <form name="<$formName$>" method="GET" action="<$HttpCgiPath$>">
    
  • If you add a form field called DataScript to a form being submitted, then any Idoc Script for that value is evaluated by Oracle Content Server when it processes the form.

4.2.7 HCSF Pages

In addition to following the standard formatting rules for Oracle Content Server templates and HTML forms, HCSF pages require several special sections and tags that enable Oracle Content Server to process them. The following subsections describe these special sections, in the order that they appear in a typical HCSF file:

For an example of a complete HCSF page, see Section 4.2.2.4, "HCSF File."

4.2.7.1 Load Section

The load section at the beginning of an HCSF page declares the file as an HTML file, loads an IDOC file, and loads other information about the page. The following example shows a typical load section:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<!--$docLoadResourceIncludes("dDocName=my_idoc_page&amp;RevisionSelectionMethod=Latest")-->
<meta NAME="idctype" CONTENT="form; version=1.0">
<!--$defaultPageTitle="Department News Form"-->
<!--$include std_html_head_declarations-->
</head>

The load section includes the items described in the following subsections:

4.2.7.1.1 HTML Declaration

The HTML declaration identifies the file as an HTML file using the following syntax:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
4.2.7.1.2 The docLoadResourceIncludes Function

The docLoadResourceIncludes function loads all the includes from the specified IDOC file for use in assembling the current page. For more information, see Section 4.2.7.1.2, "The docLoadResourceIncludes Function."

4.2.7.1.3 Meta Tag

The meta tag is used by Content Publisher to identify that this is a special type of page.

  • This tag is not required if the form is not being published through Content Publisher.

  • The meta tag must be placed inside the <HEAD> section of your HTML file.

  • Use the following syntax for the meta tag:

    <meta NAME="idctype" CONTENT="form; version=1.0">
    
4.2.7.1.4 Variables and Includes

The <HEAD> section of your HCSF page can contain variable definitions and HTML includes as necessary. For example, the following lines define the default page title and load the std_html_head_declarations code:

!--$defaultPageTitle="Department News Form"-->
<!--$include std_html_head_declarations-->

4.2.7.2 Data Section

The data section contains rules and metadata information that is used to process the form. There is a close relationship between the information in the data section and the presentation of the page:

The following subsections describe the Data Section:

4.2.7.2.1 Data Section Structure

The data section consists of XML tags that are placed between idcbegindata and idcenddata Idoc Script tags. For example:

<!--$idcbegindata-->
<idcformrules isFormFinished="0"/>
<model_number content="html">AB-123</model_number>
<revision>12</revision>
…
<!--$idcenddata-->
  • The data section must be placed inside the <BODY> section of your HTML file, before the beginning of the form section.

  • You can place Idoc Script variable definitions and includes before or after the data section, but not within it.

  • Two types of XML tags are used in the data section:

  • You can also use the following types of formatting in the data section:

4.2.7.2.2 The idcformrules Tag

The idcformrules tag defines Oracle Content Server rules in the data section. This tag requires one attribute, either isFormFinished or resultsets.

  • IsFormFinished Attribute: The isFormFinished attribute indicates whether the form can be submitted again or not.

    • Use the following format to specify that the form can be submitted again:

      <idcformrules isFormFinished="0"/>
      
    • Use the following format to specify that the form cannot be submitted again. This results in a read-only form:.

      <idcformrules isFormFinished="1"/>
      
  • resultsets Attribute: The resultsets attribute indicates which XML tags in the data section are interpreted as ResultSets.

    • This attribute specifies one or more XML tag names separated by commas. For example:

      <idcformrules resultsets="volume,chapter">
      
    • During delivery of an HCSF page to the user, Oracle Content Server reads the resultsets attribute and, if necessary, places empty ResultSets with the specified names into the DataBinder so they are available for merging.

      For more information about ResultSet formatting in the data section, see Section 4.2.7.2.7, "ResultSets."

4.2.7.2.3 Metadata Tags

Metadata tags specify the metadata values that appear in the form fields when the form is displayed in a browser. For example:

<model_number>AB-123</model_number>

Each metadata tag can be assigned a content attribute that indicates which type of content the tag contains. For example:

<model_number content="html">AB-123</model_number>
  • The value of the content attribute can be either html or text: Text indicates that the content of the tag should be interpreted strictly as text. HTML indicates that the content of the tag should be interpreted as HTML code.

  • If the content attribute is not specified for a metadata tag, it defaults to html.

  • Content Publisher ignores all other attributes except the content attribute.

4.2.7.2.4 Nested Tags

If you are not publishing HCSF pages through Content Publisher, you can use nested XML tags (also called nodes) within the data section. In the following example, the <section> tag is nested in the <chapter> tag:

<chapter title="Chapter 1">
This is the beginning of the chapter.
<section title="First Section">
This is the first section of the chapter.
</section>
</chapter>

Note:

Nested XML tags are not allowed in Content Publisher.
4.2.7.2.5 Referencing XML Tags
  • To refer to a nested tag, start with the root-level tag and use an exclamation point (!) between tag levels. For example:

    chapter!section
    
  • To refer to the attribute of any tag, use a colon (:) after the tag name. For example:

    chapter!section:title
    
  • If you reference a tag in the data section, the tag value can be merged back into the data section upon form submission only if one of the following are true:

    • The root tag has already been referenced in the data area.

    • The root tag is referenced in an ExtraRootNodes form element.

    • A prefix part of the tag is referenced as a ResultSet in the resultsets form element.

  • Default values can be specified by applying the :default suffix to a tag path. Note that default elements may contain Idoc Script for further evaluation. For example, to specify a default dDocTitle:

    <input type=hidden name="dDocTitle:default" value="<$'MyTitle ' & dateCurrent()$>">0
    
4.2.7.2.6 Form Elements
  • The ExtraRootNodes form element enables you to add tags by creating an Idoc Script variable and then appending the tag names to it, rather than specifying the tags in the data section of the form. At the end of your form, you can substitute a string value in place of the ExtraRootNodes value to be merged back into the data section.

  • The resultsets form element enables you to add a tag as a ResultSet, rather than specifying the ResultSet in the data section.

  • Both the ExtraRootNodes and resultset form elements take a comma-delimited list of tags.

  • For example, the following form elements add the mychapters!chapter tag as a valid ResultSet if it is not already defined in the idcformrules resultsets attribute. It also adds, if necessary, the root tag mychapters.

    <input type=hidden name="resultsets" value="mychapters!chapter">
    <input type=hidden name="ExtraRootNodes" value="mychapters">
    
4.2.7.2.7 ResultSets

You can define a ResultSet using XML tags within the data section.

  • You must use the resultsets attribute of the idcformrules tag to specify a ResultSet.

  • The tags must be completely qualified, and the full reference path from the root node must be used.

  • The columns in the ResultSet are the tag content and the tag attributes.

  • For information about limitations on repeating and nesting XML tags in a ResultSet, see Example 4-2 and Example 4-3.

Example 4-1 Two ResultSets Defined by XML Tags

In the following example, two ResultSets named volume and chapter are defined by XML tags:

<idcformrules resultsets="volume,chapter">
<volume title="First Volume">
    Volume content here
</volume>
<chapter title="First Chapter">
    Chapter content here
</chapter>

This evaluates into two ResultSets with two columns each:

@ResultSet volume
2
volume
volume:title
Volume content here
First Volume
@end
@ResultSet chapter
2
chapter
chapter:title
Chapter content here
First Chapter
@end

Example 4-2 Repeated Tags in a ResultSet

If you are not publishing HCSF pages through Content Publisher, you can use repeated tags within a ResultSet in the data section. Repeated tags are typically useful for looping over code to create the ResultSet.

  • Repeated tags are not allowed unless they are part of a ResultSet.

  • Repeated XML tags are not allowed in Content Publisher.

In the following example, the chapter tag is repeated in the chapter ResultSet:

<idcformrules resultsets="chapter">
<chapter title="First Chapter">
    Some content here
</chapter>
<chapter title="Second Chapter">
    More content here
</chapter>

This evaluates into a ResultSet with two columns and two rows:

@ResultSet chapter
2
chapter
chapter:title
Some content here
First Chapter
More content here
Second Chapter
@end

Example 4-3 Nested Tags in a ResultSet

A ResultSet can have nested tags, but the nested tags may not be repeated within a parent tag. For example, an additional <section> tag would not be allowed within the first <chapter> tag:

<idcformrules resultsets="chapter">
<chapter title="First Chapter">
    Some content here
    <section title="First Section of First Chapter">
    Section content
    </section>
</chapter>
<chapter title="Second Chapter">
    More content here
</chapter>

This evaluates into a ResultSet with four columns and four rows (the last two cells are blank):

@ResultSet chapter
4
chapter
chapter:title
chapter!section
chapter!section:title
Some content here
First Chapter
Section Content
First Section of First Chapter
More content here
Second Chapter


@end

Example 4-4 Editing a ResultSet

  • Updating a specific field in a ResultSet requires that you indicate the ResultSet row number in the request parameter. The # character is used by Oracle Content Server to indicate a specific row. If you do not specify a row with the # character, then a row is appended. If you specify a row # that does not yet exist, then empty rows are added sufficiently to provide a row to be edited.

    For example, to update the first row (row 0) of the ResultSet, you might use the following code:

    <input type="text" name="comment#0"
        value="new comment">
    <input type="text" name="comment!title#0"
        value="new title"
    
  • Insert new fields into a ResultSet by using the exclamation point character (!). For example, to insert author and title fields into the comment ResultSet, name the input fields comment!author and comment!title. If those fields are not in the ResultSet, they are added when the form is submitted.

  • To delete a row in a ResultSet, empty all the values so they are blank. For example, to delete the first row entirely:

    <input type="hidden" name="comment#0" value="">
    <input type="hidden" name="comment!title#0" value="">
    <input type="hidden" name="comment!date#0" value="">
    <input type="hidden" name="comment!author#0" value="">
    

    Another method for deleting rows from a ResultSet is to set the DeleteRows form element to a list of comma-delimited pairs of ResultSet name and row number. For example, to delete row 2 from the comment ResultSet and row 5 from the book ResultSet, the DeleteRows form element would be set to the following comma-delimited pairs:

    comment:2,book:5.
    

4.2.7.3 Form Section

The form section contains the code for presentation of the HTML form elements and any other functionality that the page requires. The form properties, form fields, and form buttons are placed in an HTML table to control the formatting of the assembled web page.

For code examples, see Section 4.2.8.3, "Common Code for Forms."

4.2.7.3.1 Form Begin

The form section begins with the following Idoc Script:

<!--$formName="HTMLForm"-->
<!--$include std_html_form_submit_start-->

The std_html_form_submit_start include in the std_page.idoc resource file contains the following code, which creates a standard HTML form using a POST method, sets the IdcService to SUBMIT_HTML_FORM, and sets the dID variable to the value of the current HCSF page:

<form name="<$formName$>" method="POST"action="<$HttpCgiPath$>">7
<input type=hidden name="IdcService"value="SUBMIT_HTML_FORM">
<input type=hidden name="dID" value="<$SourceID$>">
4.2.7.3.2 Form Properties

The form table typically begins with the following property definitions, which create the fields as form fields, allow the fields to be edited, and set the size of the field caption area:

<!--$isFormSubmit=1,isEditMode=1-->
<!--$captionFieldWidth=200, captionEntryWidth=80-->
4.2.7.3.3 Form Fields

The following lines are typically used to create each input field:

<!--$eval("<$product_name:maxLength=250$>")-->
<!--$fieldName="model", fieldCaption="Model Number"-->
<!--$include std_display_field-->

Note:

Some fields may require additional code for proper display. For example, you might need to override the standard std_memo_entry include to increase the size of text areas. You can do this by defining a custom include in the IDOC file:
<@dynamicalhtml std_memo_entry@>
<textarea name="<$fieldName$>" rows=15 cols=50 wrap=virtual><$fieldValue$></textarea>
<@end@>
  • DataScript: If you add a form field called DataScript to a form being submitted, then any Idoc Script for that value is evaluated by Oracle Content Server when it processes the form.

    Example 4-5 Changing a Value in a Specific Column and Row in a Second Table When You Update a Row in the First Table

    There are two tables (coming from the data island inside the hcsp form) with an entry in one table that references entries in the other table. Your goal is to change a value in a specific column and row in the second table when you update a row in the first table.

    To accomplish this value change, you can write javascript to set the DataScript value with Idoc script:

    modifyRowAndColumn(row, column, value) 
    { 
    document.myform.DataScript = "<$setValue('#local', 'table2!'"+ column + "#'"+ row + 
    "','" + value + "')$>"; 
    } 
    

    Then, when you call the function with column = "myColumn" and row="1" and value = "Test" while submitting the update form, the resulting DataScript value before submit would be as follows:

    DataScript.value = <$setValue('#local', 'table2!myColumn#1', 'Test')$> 
    

    The result would be the column table2!myColumn in row 1 of the table table2 would be updated with the value Test after the form was submitted.

    Another way of saying this is that the DataScript can allow arbitrary edits of other entries in the data island without having to actually create HTML form fields that reference their names.

4.2.7.3.4 Form Buttons

The following lines are typically used to create the form submission and reset buttons:

<input type=submit name=Submit value=" Submit ">
<input type=reset name=Reset value="Reset">
4.2.7.3.5 Form End

After all the form elements and default values have been defined, the form must end with a </form> tag.

4.2.8 Working with Dynamic Server Pages

The following subsections present examples that show how the dynamic server pages work together to modify Oracle Content Server behavior:

4.2.8.1 HCST and HCSP Example

Example 4-6 shows how to create simple HCST and HCSP pages.

Example 4-6 Creating an HCST Page and HCSP Page

  1. Create an IDOC file with a custom include.

    Figure 4-2 Custom Include

    The figure shows custom include code.
  2. Save the file as helloworld.idoc.

  3. Check in the IDOC file to Oracle Content Server with a Content ID of helloworld. The IDOC file is now available to any HCS* pages that reference it.

  4. Create an HCST file that references the HelloWorld include:

    Figure 4-3 HCST File Referencing Custom Include

    Description of Figure 4-3 follows
    Description of "Figure 4-3 HCST File Referencing Custom Include"

  5. Save the file as helloworld.hcst.

  6. Check in the HCST file to Oracle Content Server.

  7. Create an HCSP file that references the HelloWorld include:

    Figure 4-4 HCSP File Referencing Custom Include

    Description of Figure 4-4 follows
    Description of "Figure 4-4 HCSP File Referencing Custom Include"

  8. Save the file as helloworld.hcsp.

  9. Check in the HCSP file to Oracle Content Server.

  10. Search for the helloworld content items in Oracle Content Server.

  11. Display the HCST file and HCSP files in your web browser. They should both look like the example in Figure 4-5.

    Figure 4-5 HelloWorld Content Item Displayed in a Web Browser

    Description of Figure 4-5 follows
    Description of "Figure 4-5 HelloWorld Content Item Displayed in a Web Browser"

4.2.8.2 HCSF Example

Example 4-7 shows a typical HCSF page and its associated IDOC file. This example creates a form that users can fill out and submit to enter product descriptions as content items.

Example 4-7 HCSF Example

  1. Create an HCSF file that references an IDOC file named form_std_page, as Figure 4-6 shows.

    Figure 4-6 Product Description Form HCSF File

    This figure shows a product description form HCSF.
  2. Save the file as product_form.hcsf.

  3. Check in the HCSF file to Oracle Content Server.

  4. Create an IDOC file with custom includes, as Figure 4-7 shows.

    Figure 4-7 IDOC File with Custom Includes

    This figure shows an IDOC file with custom includes.
    This figure shows an IDOC file with custom includes.
  5. Save the file as form_std_page.idoc.

  6. Check in the IDOC file to Oracle Content Server with a Content ID of form_std_page. (This is the name that is referenced by the HCSF page.)

  7. Search for the HCSF content item in Oracle Content Server.

  8. Click the link to display the form to create an HCSF page in your web browser. The form should look like the sample in Figure 4-8.

    Figure 4-8 Form to Create HCSF Page Displayed in a Web Browser

    Surrounding text describes Figure 4-8 .
  9. Fill out the form with some sample values, and click Submit.

    A content item is created as an HCSP page.

  10. Search for the HCSP page in Oracle Content Server.

  11. Click the link to display the HCSP page in your web browser. Figure 4-9 shows how it should look.

    Figure 4-9 Link Displaying an HCSP Page

    Surrounding text describes Figure 4-9 .

4.2.8.3 Common Code for Forms

This section describes some of the features that are commonly used in HCSF pages and associated IDOC files.

4.2.8.3.1 Retrieving File Information

Executing the service DOC_INFO_SIMPLE makes metadata from a specific file available to the page. For example:

<$dID=SourceID$>
<$executeService("DOC_INFO_SIMPLE")$>
4.2.8.3.2 Referencing the File Extension

Use the following statement to determine whether the form is submitted (hcsp) or unsubmitted (hcsf):

<$if (strEquals(ref:dExtension,"hcsf"))$>
    <$isHcsf=1$>
<$else$>
    <$isHcsp=1$>
<$endif$>

For information about the ref: prefix, see Section 4.2.4.4, "Referencing Metadata."

4.2.8.3.3 Defining Form Information

The following code defines the form name and the standard include to start an HTML form:

<$formName="HTMLForm"$>
<$include std_html_form_submit_start$>

The following is typical code that defines form properties:

<table border=0 width=100%>
<$isEditMode=1,isFormSubmit=1$>
<$captionFieldWidth="25%", captionEntryWidth="75%"$>
4.2.8.3.4 Defining Form Fields

Use standard Idoc Script variables and the std_display_field include to display the form fields. For example:

<$fieldName="news_author",fieldDefault=dUser,fieldCaption="Author",isRequired=1,requiredMsg = "Please specify the author."$>
<$include std_display_field$>

Some fields might require extra code to display the field correctly. For example, the standard text area for a memo field is 3 rows by 40 columns, but you might need to override the standard include to increase the size of the text area:

  • Standard std_memo_entry Include

<@dynamichtml std_memo_entry@>
    <textarea name="<$fieldName$>" rows=3 cols=40 wrap=virtual> <$fieldValue$></textarea>
<@end@>
  • Custom std_memo_entry Include

<@dynamichtml std_memo_entry@>
    <textarea name=<$fieldName$> rows=15 cols=50 wrap=virtual><$fieldValue$></textarea>
<@end@>
4.2.8.3.5 Defining Hidden Fields

You can specify metadata for a submitted form (hcsp) by defining a hidden field, which contributors cannot change. For example, use the following code to assign the document type News_Forms to each submitted form:

<input type=hidden name="dDocType" value="News_Forms">

To specify the security group of the submitted forms:

<input type=hidden name="dSecurityGroup" value="Public">
4.2.8.3.6 Submitting the Form

When a form is submitted, you may want to call a Java function to perform additional validation or processing. For example:

<input type=button name=Submit value="Save" onClick="postCheckIn(this.form)">