3 Working with Standard, Server, and Custom Components

This chapter describes how to work with Oracle Universal Content Management (Oracle UCM) components, which are programs used to modify Oracle Content Server functionality.

This chapter includes the following sections:

• Section 3.1, "Components Overview"

• Section 3.2, "About Directories and Files"

• Section 3.3, "Development Recommendations"

• Section 3.4, "Component File Detail"

• Section 3.5, "Resources Detail"

• Section 3.6, "Installing Components"

3.1 Components Overview

Components are modular programs designed to interact with Oracle Content Server at runtime. Standard components, system components, and custom components are included with Oracle Content Server to add or change the core functionality of the standard Oracle Content Server instance. You can create and use custom components to modify an Oracle Content Server instance without compromising the system integrity. Custom components can alter defaults for your system, add new functionality, or streamline repetitive functions.

This section provides an overview of component management and the files and directory structure associated with components. It covers these topics:

• Section 3.1.1, "Component Wizard"

• Section 3.1.2, "Advanced Component Manager"

• Section 3.1.3, "ComponentTool"

• Section 3.1.4, "Component Files Overview"

• Section 3.1.5, "Enabling and Disabling Components"

3.1.1 Component Wizard

The Component Wizard utility automates the process of creating custom components, including creating and editing all the files necessary for custom components. You can also use the Component Wizard to modify existing components and to package and unpackage components for use on Oracle Content Server instances.

The Component Wizard is discussed in more detail in the Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.

Figure 3-1 Component Wizard Interface

To access the Component Wizard

• UNIX operating system: Run ComponentWizard, stored in DomainHome/ucm/short-product-id/bin/.

  The Component Wizard main page is displayed.

• Windows operating system: From the Start menu, choose the instance name, then Utilities, and then Component Wizard.

  The Component Wizard main page is displayed.

3.1.2 Advanced Component Manager

The Advanced Component Manager provides a way to manage custom components in Oracle Content Server. By using the Advanced Component Manager, you can easily enable or disable components or add new components to Oracle Content Server.

The Advanced Component Manager is discussed in more detail in the Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.

To use the Advanced Component Manager:

1. In the Administration tray or menu, choose Admin Server.

   The Admin Server displays the Component Manager page, which has lists of enabled and disabled components.

2. In the first paragraph on the Component Manager page, click advanced component manager.

3. On the Advanced Component Manager page, you can do these tasks:

   • View lists of enabled and disabled components by categories and other filters

   • Select a component to view details about it

   • Enable components

   • Disable components

   • Install custom components

   • Uninstall custom components

Figure 3-2 Advanced Component Manager Page

3.1.3 ComponentTool

ComponentTool is a command-line utility for installing, enabling, and disabling components in Oracle Content Server. After installing a component, ComponentTool automatically enables it. ComponentTool is located in the DomainHome/ucm/cs/bin directory.

3.1.4 Component Files Overview

When you define a custom component, you create or make changes to the following files:

• The idcshort-product-id_components.hda file, which tells Oracle Content Server what components are enabled and where to find the definition file for each component.

• The component definition (or glue) file, which tells Oracle Content Server where to find the resources for the custom component.

• Different custom resource files, which define your customization to standard Oracle Content Server resources.

• Template files, which define custom template pages.

• Other files which contain customization to Oracle Content Server graphics, Java code, help files, and so on.

For more detailed information about these files, see Section 3.2, "About Directories and Files."

Any type of file can be included in a component, but the following file formats are used most often:

• HDA

• HTM

• CFG

• Java CLASS

If you build or unpackage components in the Component Wizard, or upload and download components in the Component Manager, you work with the following files:

• A compressed ZIP file used to deploy a component on other Oracle Content Server instances.

• A manifest.hda file that tells Oracle Content Server where to place the files that are unpackaged or uploaded from a component ZIP file.

3.1.5 Enabling and Disabling Components

By definition, a component is enabled when it is properly defined in the Components ResultSet in the idc_components.hda file. A component is disabled if there is no entry or the entry is not formatted correctly.

There are several ways to enable or disable a component:

• ComponentTool: Run DomainHome/ucm/short-product-id/bin/ComponentTool to enable or disable a component. For example, ComponentTool -enable component_name

• Component Wizard: Choose Enable or Disable from the Options menu. For more information, see Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.

• Component Manager: Select the checkbox next to a component name to enable a server component specified on the Component Manager screen. Clear the checkbox next to a component name to disable a server component on the Component Manager screen. For more information, see Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.

• Advanced Component Manager: On the Advanced Component Manager page, select a component name, and click Disable to disable the component, or click Enable to enable the component.

3.2 About Directories and Files

This section provides information about the files used in component creation and the directory structure used to store those files. It includes the following sections:

• Section 3.2.1, "HDA Files"

• Section 3.2.2, "Custom Resource Files"

• Section 3.2.3, "Data Binder"

• Section 3.2.4, "Manifest File"

• Section 3.2.5, "Other Files"

• Section 3.2.6, "Typical Directory Structure"

3.2.1 HDA Files

A HyperData File (HDA) is used to define properties and tabular data in a simple, structured ASCII file format. It is a text file that is used by Oracle Content Server to determine which components are enabled and disabled and where to find the definition files for that component.

The HDA file format is useful for data that changes frequently because the compact size and simple format make data communication faster and easier for Oracle Content Server.

The HDA file type is used to define the following component files:

• Components file (idc_components.hda)

• Component definition file

• Manifest file

• Dynamic table resource file

• Template resource file

The following example file is an idccs_components.hda file that points to a component called customhelp.

<?hda charset=Cp1252 encoding=iso-8859-1?>
@Properties LocalData
blDateFormat=M/d{/yy} {h:mm[:ss] {aa}[zzz]}!tAmerica/Chicago!mAM,PM
@end
@ResultSet Components
2
name
location
customhelp
custom/customhelp/customhelp.hda
@end

3.2.1.1 Elements in HDA Files

Each HDA file contains a header line and one or more sections. The header line identifies the Oracle Content Server version, character set, and Java encoding for the HDA file. If an HDA file contains double-byte (Asian language) characters, the correct character set and encoding must be specified so that Oracle Content Server can read the file properly. The header line is not required for single-byte characters, but it is a good practice to include it in your HDA files.

Two types of sections, Properties and ResultSet, are relevant to component development. These sections are used to define the properties of the file (name, location, and so on) and the ResultSet, which defines a table or columns and rows of data. A ResultSet often represents the results of a query. All other sections tags are for internal application use only.

Comments are not allowed within a section of an HDA file. However, you can place comments in the HDA file before the first section, between sections, or after the last section. Blank lines within a section of an HDA file are interpreted as a NULL value. Blank lines before the first section, between sections, or after the last section are ignored. None of the section types are mandatory in an HDA file, so unused sections can be deleted.

• The Properties section contains a group of name/value pairs. For a custom component, the most common name for a Properties section is LocalData, which means that the name/value pairs are valid only for the current HDA file.

  You can also define global name/value pairs in a Properties section called Environment, but this section is rarely used. The recommended practice is to define global environment variables in a configuration file, such as config.cfg.

  An example of a Properties section in an HDA file follows:

  @Properties LocalData
  PageLastChanged=952094472723
  LocationInfo=Directory,Public,
  IsJava=1
  refreshSubMonikers=
  PageUrl=/intradoc/groups/public/pages/index.htm
  LastChanged=-1
  TemplatePage=DIRECTORY_PAGE
  IdcService=PAGE_HANDLER
  LinkSelectedIndex=0
  PageName=index
  HeaderText=This is a sample page.  The Page Name must remain index.  The Page Properties for this index page should be customized.
  PageFunction=SavePage
  dSecurityGroup=Public
  restrictByGroup=1
  PageType=Directory
  PageTitle=Oracle Content Server Index Page
  @end
  

• Each ResultSet section of an HDA file defines a table or columns and rows of data. A ResultSet can be used to pass information to a database or to represent the result of a database query. A ResultSet section has the following structure:

  • The first line defines the name of the ResultSet table, using the format @ResultSet resultset_name.

  • The second line defines the number of columns.

  • The next n lines define the column names.

  • The remaining lines define the values in each cell of the table.

  • The last line of the section ends the table, using the format @end.

  The following example shows a ResultSet called Scores that has 4 columns and 3 rows.

  @ResultSet Scores
  4
  name
  match1
  match2
  match3
  Margaret
  68
  67
  72
  Sylvia
  70
  66
  70
  Barb
  72
  71
  69
  @end
  

  The following table shows the ResultSet data in a columnar form. A ResultSet can be given any name.

  name	match1	match2	match3
  Margaret	68	67	72
  Sylvia	70	66	70
  Barb	72	71	69

  
  

  Oracle Content Server uses some predefined ResultSets with the following names, which should not be used for custom component table.

  ResultSet Name	Location	Purpose
  Components	IntradocDir/data/components/idccustom-name_components.hda	Defines the name and location of any custom components you have created. You must specify the short product ID (cs, ibr, urm) for custom-name.
  IntradocReports	IdcHomeDir/resources/core/reports/reports.hda	Specifies the default report templates for Oracle Content Server.
  IntradocTemplates	IdcHomeDir/resources/core/templates/templates.hda	Specifies all of the default templates for Oracle Content Server (except for search results and report templates).
  ResourceDefinition	DomainHome/ucm/short-product-id/custom/component_name/component_name.hda	Defines resources for a custom component.
  SearchResultTemplates	IdcHomeDir/resources/core/templates/templates.hda	Specifies the default search results templates for Oracle Content Server.

  
  

3.2.1.2 The idc_components.hda File

The idc_components.hda file is a text file that tells Oracle Content Server which components are enabled and where to find the definition file for each component.

The idc_components.hda file is always stored in the IntradocDir/data/components directory. The Component Wizard, Component Manager, and ComponentTool can be used to make changes to this file if needed.

Note:

As of release 11gR1, the components.hda file and edit_components.hda file have been combined into one file called idcshort-product-name_components.hda. If the Admin Server does not find the idcshort-product-name_components.hda file but does find the legacy files, then it will migrate the data from the legacy file and create an idcshort-product-name_components.hda file containing the appropriate data.

The following example of an idccs_components.hda file lists several enabled components, such as schema, configuration migration, and SOAP.

@properties LocalData
blDateFormat=M/d/yy 
@end
@ResultSet Components
2
name
location
SchemaDCL
custom/SchemaDCL/SchemaDCL.hda
ConfigMigrationUtility
custom/ConfigMigrationUtility/Cmu.hda
Soap
custom/Soap/Soap.hda
@end

3.2.1.3 Component Definition Files

A component definition file points to the custom resources that you have defined. This file specifies information about custom resources, ResultSets, and merge rules. Because it serves as the "glue" that holds a component together, the component definition file is sometimes called the glue file.

The definition file for a component is typically named component_name.hda, and is located in the DomainHome/ucm/short-product-id/custom/component_name directory. The Component Wizard can be used to create and make changes to a definition file.

Note:

Do not confuse the idcshort-product-name_components.hda file with the component_name.hda file. The idcshort-product-name_components.hda file is used to track all installed components. The component_name.hda file contains information that is specific to a single component.

The following example of a component definition file points to an environment resource file called customhelp_environment.cfg.

<?hda version="5.1.1 (build011203)" jcharset=Cp1252 encoding=iso-8859-1?>
@Properties LocalData
blDateFormat=M/d{/yy} {h:mm[:ss] {aa}[zzz]}!tAmerica/Chicago!mAM,PM
blFieldTypes=
@end
@ResultSet ResourceDefinition
4
type
filename
tables
loadOrder
environment
customhelp_environment.cfg
null
1
@end

3.2.2 Custom Resource Files

Custom resource files define your Oracle Content Server customization. They are usually HDA files but some are HTM files.

The custom resource files for a component are typically located in the DomainHome/ucm/short-product-id/custom/component_name directory. Some resource files may be placed in subdirectories such as resources/core/templates.

The following table describes these resources.

Resource Type	File Type	Contents
HTML include	HTM	"Include" definitions
String	HTM	Localized string definitions
Dynamic table	HDA	Tables for data that changes often
Static table	HTM	Tables for data that seldom changes
Query	HTM	Tables that define queries
Service	HTM	Tables that define service scripts
Template	HDA	Tables that specify location and file name for template pages
Environment	CFG	Configuration variable name/value pairs

For more detailed information about these files, see Section 3.5, "Resources Detail."

In addition, a template.htm page is used by Oracle Content Server to assemble web pages. For more detailed information about the template.hdm file, see Section 3.5.8, "Templates."

A ResultSet HTM table file is used by other resources. A ResultSet table in an HTM file is similar to the ResultSet of an HDA file, except that it uses HTML table tags to lay out the data. Static table resources, service resources, and query resources all use this table format.

A ResultSet table in an HTM file begins with <@table table_name@> and ends with <@end@>. The markup between the start and end tags is an HTML table. Unlike a ResultSet in an HDA file, the number of columns is implied by the table tags.

Any HTML syntax that does not define the data structure is ignored when the table is loaded. Therefore, HTML comments are allowed within tables in an HTM file, and HTML style attributes can be used to improve the presentation of the data in a web browser.

3.2.3 Data Binder

Oracle Content Server caches data (such as variable values and lookup keys) internally in a data binder. All data in the data binder is categorized according to where it came from and how it was created. When a value is required to fulfill a service request, the data in the data binder is evaluated in the following default order:

1. LocalData

2. ResultSets

3. Environment

This precedence can be changed using Idoc Script functions. For more information, see the Oracle Fusion Middleware Idoc Script Reference Guide.

3.2.3.1 LocalData

The @Properties LocalData section in an HDA file maps to the LocalData of the DataBinder. The LocalData information consists of name/value pairs.

LocalData information is maintained only during the lifetime of the Oracle Content Server request and response. Unlike information about the server environment, which rarely changes, the LocalData information for each request is dynamic.

From the point of view of an HTTP request, the initial LocalData information is collected from the REQUEST_METHOD, CONTENT_LENGTH, and QUERY_STRING HTTP environment variables. As the service request is processed, the LocalData name/value pairs can be added and changed.

3.2.3.2 ResultSets

Each @ResultSet section of an HDA file maps to a named result in the DataBinder. Some result sets can be made active, thus taking precedence over other ResultSets during a value search. A ResultSet becomes active when the ResultSet is looped on during page assembly. An active ResultSet take precedence over any other ResultSets during a value search of the DataBinder. When a service request requires data and the value is not found in the LocalData or an active ResultSet, the remaining ResultSets (those that are not active) are searched next.

3.2.3.3 Environment

Environment values are placed in the DataBinder as name/value pairs, which are defined in configuration files such as IntradocDir/config/config.cfg, intradoc.cfg, and environment-type resource files.

3.2.4 Manifest File

Manifest files are used to upload or unpackage a component ZIP file on Oracle Content Server. This file tells Oracle Content Server where to place the individual files that are included in the component ZIP file. A manifest file is created automatically when you build a component in the Component Wizard, or when you download a component using the Admin Server Advanced Component Manager.

All manifest files must be called manifest.hda. The manifest.hda file is included in the component ZIP file along with the other component files. It must be at the top level of the ZIP file directory structure.

The manifest.hda file contains a ResultSet table called Manifest, which consists of two columns:

• The entryType column defines the type of entry in the manifest file.

  Entry Type	Description	Default Path
  Classes	Java class files	DomainHome/ucm/short-product-id/classes
  Common	Common files	DomainHome/ucm/short-product-id/weblayout/common
  Component	Component resource files	DomainHome/ucm/short-product-id/custom
  ComponentExtra	Associated files, such as a readme	DomainHome/ucm/short-product-id/custom
  Help	Online help files	DomainHome/ucm/short-product-id/weblayout/help
  Images	Graphics files	DomainHome/ucm/short-product-id/weblayout/images
  Jsp	JavaServer Pages	DomainHome/ucm/short-product-id/weblayout/jsp

  
  

  Caution:

  Avoid using the entry types Common, Help, Images, and Jsp because they are deprecated in Oracle UCM 11g. Oracle UCM has a publishing engine that pushes files into the weblayout directory from components. If you want the same behavior as in a previous release, use the publishing engine; otherwise, the publishing engine may place files directly into the weblayout directory from a custom component, overwriting existing files. The overwritten files could be permanently lost.

• The location column defines the directory where the files associated with the entry are installed and specifies the file name for some entry types.

  • For a Component entry type, the location is the path and file name for the definition file. The definition file then tells Oracle Content Server which resource files are included in the component.

  • For other entry types, the location can be a path without a file name (to specify all files in a particular subdirectory) or a path with a file name (to specify an individual file).

  • The location should be a path relative to the DomainHome/ucm/short-product-id/custom directory. You can use an absolute path, but then the component can be installed only on Oracle Content Server instances with the same installation directory path.

An example of a manifest.hda file follows:

@ResultSet Manifest
2
entryType
location
component
MyComponent/MyComponent.hda
componentExtra
MyComponent/readme.txt
images
MyComponent/
@end

3.2.5 Other Files

Your custom components can include any type of file that Oracle Content Server uses for functionality or to generate its look and feel.

3.2.5.1 Customized Site Files

You can add customized files for your site to change the look or actions of Oracle Content Server. For example, the following types of files are often referenced in custom resources:

• Graphics

  Replace the icons, backgrounds, and logos that constitute the standard Oracle Content Server interface.

• Help

  With the assistance of Consulting Services, you can customize help files for your content management system.

• Classes

  Java code can change or extend the functionality of Oracle Content Server. Java class files must be packaged into directories for placement in the DomainHome/ucm/short-product-id/classes directory.

Caution:

Avoid placing Graphics and Help files in the weblayout directory manually because your files may be overwritten by the Oracle UCM 11g publishing engine, which pushes files into the weblayout directory from components. If you want the same behavior as in a previous release, use the publishing engine; otherwise, the publishing engine may place files in this directory directly from a custom component, overwriting existing files. The overwritten files could be permanently lost. If you need to place these files in the weblayout directory manually, contact Oracle Consulting Services.

3.2.5.2 Component ZIP File

A component ZIP file contains all files that define an Oracle Content Server component. It can be unpackaged to deploy the component on other Oracle Content Server instances.

3.2.5.3 Custom Installation Parameter Files

When you define one or more custom installation parameters, several additional files are created in addition to the files that compose the basic component file structure.

If installation parameters are created for the component, then during the component installation process the component installer automatically places two files in the directory for the component within the data/components directory. These files hold the preference data as follows:

• The config.cfg file: Contains the parameters that can be reconfigured after installation.

• The install.cfg file: Contains the preference data definitions and prompt answers.

• Backup ZIP file: A backup file that is created if the component is currently installed and is being reinstalled.

3.2.6 Typical Directory Structure

If you use the Component Wizard to create custom components, your files are stored in the appropriate directory.

Different component directories are established for each custom component in the DomainHome/ucm/short-product-id/custom directory. Within each component directory, separate subdirectories are established for reports, templates, and resources, all named appropriately (for example, component_name/resources/). The component_name.hda file (the definition file) is stored in the component_name directory.

3.3 Development Recommendations

The following sections provide some guidelines to assist you in developing custom components:

• Section 3.3.1, "Creating a Component"

• Section 3.3.2, "Working with Component Files"

• Section 3.3.3, "Using a Development Instance"

• Section 3.3.4, "Component File Organization"

• Section 3.3.5, "Naming Conventions"

For more detailed information about creating or modifying components, see Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server or online help.

3.3.1 Creating a Component

To create and enable a custom component, follow this basic procedure:

1. Create a definition file.

2. Add a reference to the definition file in the idcshort-product-id_components.hda file to enable the component.

3. Restart Oracle Content Server to apply the component.

4. Create resources and other files to define your customization. A good approach is to copy, rename, and modify standard Oracle Content Server files to create your custom resource files.

5. Test and revise your customization as necessary. You may need to restart Oracle Content Server to apply your changes.

6. If you want to package the component for later use or for deployment on other Oracle Content Servers instances, build the component and create a component ZIP file.

3.3.2 Working with Component Files

Two tools are available for working with component files:

• Component Wizard

  The Component Wizard is an Oracle Content Server utility that can help you create and edit component files. You can also use the Component Wizard to package, unpackage, enable, and disable components. For more information about using this utility, see Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.

• Text editor

  Because most component files are plain text files, you can create and edit the files in your favorite text editor.

You should use the Component Wizard as much as possible when working with custom components.

The Component Wizard does several tasks for you and minimizes the amount of work you need to do in a text editor. Using the Component Wizard helps you follow the recommended file structure and naming conventions. The Component Wizard automatically adds a readme text file when you build a component, thus helping you to document your customization. You should also include comments within your component files.

For information about using the Component Wizard to create components, see Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.

3.3.3 Using a Development Instance

Whenever you are customizing Oracle Content Server, you should isolate your development efforts from your production system. Remember to include the same custom metadata fields on your development instance as you have defined for your production instance.

When you have successfully tested your modifications on a development instance, use the Component Wizard to build a component ZIP file and then unpackage the component on your production system.

Remember to restart Oracle Content Server after enabling or disabling a component.

If you are having problems with your Oracle Content Server instance after you have installed a custom component, disable the component and restart the instance. If this fixes the problem, you probably need to troubleshoot your component. If the problem is not fixed, you may need to remove the component completely using the Component Wizard to determine whether there is a problem with the component or with the Oracle Content Server instance.

3.3.4 Component File Organization

To keep your custom components organized, follow these file structure guidelines. For more information, see Section 3.2.6, "Typical Directory Structure."

Note:

If you use the Component Wizard, it creates component directories for you and places the component files in the correct directories.

Place each custom component in its own directory within a directory called DomainHome/ucm/short-product-id/custom. If your custom component includes resource-type or template-type resources, or both, the component directory should have subdirectories that follow the structure of the IdcHomeDir/data/resources/core directory:

• resources to hold HTML include and table resource files

• resources/lang to hold string resource files

• templates to hold template files

• reports to hold report files

Keep the following points in mind when considering files and their organization:

• Place the definition file for each custom component at the top level of the component's directory.

• When referring to other files within a component, use relative path names instead of absolute path names. Using relative path names enables you to move the component to a different location without having to edit all of the files in the component.

• Oracle Content Server is a Java-based application, so forward slashes must be used in all path names.

• Custom components do not have to be stored on the same computer as Oracle Content Server, but all component files must be accessible to your Oracle Content Server instance.

• Images and other objects that are referenced by Oracle Content Server web pages must reside somewhere in the DomainHome/ucm/short-product-id/weblayout directory (so they can be accessed by the web server).

3.3.5 Naming Conventions

To keep your component files organized and ensure that the files work properly in Oracle Content Server, follow these naming conventions for directories, individual files, and file contents.

• You should give all of your component directories and files unique and meaningful names. Keep in mind that as each component is loaded into Oracle Content Server, it overrides any resources with the same file names, so you should use duplicate file names only if you want certain components to take precedence.

• If you are copying a standard Oracle Content Server file, a common practice is to place the prefix custom_ in front of the original file name. This ensures that you do not overwrite any default templates, and your customization is easy to identify.

• HTM file types should have an .htm extension, and HDA file types should have an .hda extension.

• If you are creating a new component file with a text editor, like WordPad, place the file name within quotation marks in the Save dialog box so the proper file extension is assigned to it (for example, myfile.hda). Failure to use quotation marks to define the file name may result in a file name such as myfile.hda.txt.

• Oracle Content Server is case sensitive even if your file system is not. For example, if a file is named My_Template, Oracle Content Server does not recognize case variations such as my_template or MY_TEMPLATE.

• For localized string resources, you must follow the standard file naming conventions for Oracle Content Server to recognize the strings. You should also use the standard two-character prefix (cs, sy, ap, or ww) when naming your custom strings. For more information, see Section 2.3.6, "Localized String Resolution."

3.4 Component File Detail

This section discusses the HDA file type and the component definition (glue) file in more detail, in the following subsections:

• Section 3.4.1, "The idc_components.hda File"

• Section 3.4.2, "Component Definition (Glue) File"

The information in this section is intended as reference material and should not be used to create files manually. You should always use the Component Wizard to create your component files.

3.4.1 The idc_components.hda File

The idc_components.hda file tells Oracle Content Server which components are enabled and where to find the component definition (glue) file for each component. In 11g Release 1 (11.1.1), this file has three forms, one for each of the Oracle UCM products: idccs_components.hda (for Oracle Content Server), idcibr_components.hda (for Oracle Inbound Refinery), and idcurm_components.hda (for Oracle Universal Records Management). The file is always stored in the IntradocDir/data/components directory.

3.4.1.1 Contents of idc_components.hda

The idc_components.hda file always includes a ResultSet called Components that defines the name and file path of each definition file. You can use the Component Wizard or the Component Manager to make changes to the components HDA file. For more information, see Section 3.1.5, "Enabling and Disabling Components."

In the following example of an idccs_components.hda file, two components called MyComponent and CustomHelp are enabled.

<?hda version="5.1.1 (build011203)" jcharset=Cp1252 encoding=iso-8859-1?>
@Properties LocalData
blDateFormat=M/d{/yy} {h:mm[:ss] {aa}[zzz]}!tAmerica/Chicago!mAM,PM
blFieldTypes=
@end
@ResultSet Components
2
name
location
MyComponent
custom/MultiCheckin/my_component.hda
CustomHelp
custom/customhelp/customhelp.hda
@end

3.4.1.2 Components ResultSet

The order that components are listed in the Components ResultSet determines the order that components are loaded when you start Oracle Content Server. If a component listed later in the ResultSet has a resource with the same name as an earlier component, the resource in the later component takes precedence.

A Components ResultSet has two columns:

• The name column provides a descriptive name for each component, which is used in the Component Wizard, Component Manager, and Oracle Content Server error messages.

• The location column defines the location of the definition file for each component. The location can be an absolute path or can be a path relative to the Oracle Content Server installation directory.

  Note:

  Always use forward slashes in the location path.

3.4.2 Component Definition (Glue) File

A component definition file, or glue file, points to the custom resources that you have defined. The definition file for a component is named component_name.hda, and is typically located in the DomainHome/ucm/short-product-id/custom/component_name directory. The Component Wizard can be used to create and make changes to a definition file.

A definition file contains a ResourceDefinition ResultSet and may contain a MergeRules ResultSet, a Filters ResultSet, a ClassAliases ResultSet, or any combination of these ResultSets.

The following example shows a typical component definition file.

<?hda jcharset=UTF8 encoding=utf-8?>
@Properties LocalData
classpath=$COMPONENT_DIR/classes.jar
ComponentName=Custom DCL Component
serverVersion=7.3
version=2010_10_22
@end
@ResultSet ResourceDefinition
4
type
filename
tables
loadOrder
template
dcl_templates.hda
DCLCustomTemplates
1
resource
dcl_resource.htm
null
1
resource
dcl_upper_clmns_map.htm
DCLColumnTranslationTable
1
resource
dcl_data_sources.htm
dclDataSources
1
service
dcl_services.htm
CustomServices
1
query
dcl_query.htm
CustomQueryTable
1
resource
dcl_checkin_tables.hda
null
1
@end

@ResultSet MergeRules
3
fromTable
toTable
column
DCLCustomTemplates
IntradocTemplates
name
DCLColumnTranslationTable
ColumnTranslation
alias
DCLDataSources
DataSources
name
CustomDCLServiceQueries
ListBoxServiceQueries
dataSource
@end

@ResultSet Filters
4
type
location
parameter
loadOrder
loadMetaOptionsLists
intradoc.server.ExecuteSubServiceFilter
GET_CHOICE_LIST_SUB
1
@end

3.4.2.1 ResourceDefinition ResultSet

The ResourceDefinition ResultSet table defines the type, file name, table names, and load order of custom resources.

3.4.2.1.1 Example of ResourceDefinition ResultSet

The following example shows the structure of a ResourceDefinition ResultSet:

@ResultSet ResourceDefinition
4
type
filename
tables
loadOrder
template
dcl_templates.hda
DCLCustomTemplates
1
resource
dcl_resource.htm
null
1
resource
dcl_upper_clmns_map.htm
DCLColumnTranslationTable
1
resource
dcl_data_sources.htm
dclDataSources
1
service
dcl_services.htm
CustomServices
1
query
dcl_query.htm
CustomQueryTable
1
resource
dcl_checkin_tables.hda
null
1
@end

3.4.2.1.2 ResourceDefinition ResultSet Columns

A ResourceDefinition ResultSet consists of four columns:

• The type column defines the resource type, which must be one of the following values:

  • resource, which points to an HTML include (HTM), string (HTM), dynamic table (HDA), or static table (HTM) resource file.

  • environment, which points to an environment resource (CFG) file.

  • template, which points to a template resource (HDA) file.

  • query, which points to a query resource (HTM) file.

  • service, which points to a service resource (HTM) file.

• The filename column defines the path and file name of the custom resource file. This can be an absolute path or a relative path. Relative paths are relative to the DomainHome/ucm/short-product-id/custom/component_name directory.

• The tables column defines the ResultSet tables to be loaded from the resource file. ResultSet names are separated with a comma. If the resource file does not include ResultSets, this value is null. For example, HTML include resources do not include table definitions, so the value for the tables column is always null for an HTML include file.

• The loadOrder column defines the order in which the resource is loaded. Resources are loaded in ascending order, starting with resources that have a loadOrder of 1. If multiple resources have the same loadOrder, the resources are loaded in the order they are listed in the ResourceDefinition ResultSet. If there are multiple resources with the same name, the last resource loaded is the one used by the system. Normally, you should set the loadOrder to 1, unless there is a particular reason to always load one resource after the others.

3.4.2.2 MergeRules ResultSet

The MergeRules ResultSet table identifies new tables that are defined in a custom component, and specifies which existing tables the new data is loaded into. MergeRules are required for custom template resources but are optional for custom dynamic table and static table resources. MergeRules are not required for custom service, query, HTML include, string, and environment resources.

3.4.2.2.1 Example of MergeRules ResultSet

The following example shows a MergeRules ResultSet.

@ResultSet MergeRules
4
fromTable
toTable
column
loadOrder
DCLCustomTemplates
IntradocTemplates
name
1
DCLColumnTranslationTable
ColumnTranslation
alias
1
DCLDataSources
DataSources
name
1
CustomDCLServiceQueries
ListBoxServiceQueries
dataSource
1
@end

3.4.2.2.2 MergeRules ResultSet Columns

A MergeRules ResultSet consists of three columns:

• The fromTable column specifies a table that was loaded by a custom resource and contains new data to be merged with the existing data. To properly perform a merge, the fromTable table must have the same number of columns and the same column names as the toTable table.

• The toTable column specifies the name of the existing table into which the new data is merged. Usually, the toTable value is one of the standard Oracle Content Server tables, such as IntradocTemplates or QueryTable.

• The column column specifies the name of the table column that Oracle Content Server uses to compare and update data.

  • Oracle Content Server compares the values of column in fromTable and toTable. For each fromTable value that is identical to a value currently in toTable, the row in toTable is replaced by the row in fromTable. For each fromTable value that is not identical to a value currently in toTable, a new row is added to toTable and populated with the data from the row of fromTable.

  • The column value is usually name. Setting this value to null defaults to the first column, which is generally a name column.

3.4.2.3 Filters ResultSet

The Filters ResultSet table defines filters, which are used to execute custom Java code when certain Oracle Content Server events are triggered, such as when new content is checked in or when the server first starts. The following example shows a typical Filters ResultSet.

@ResultSet Filters
4
type
location
parameter
loadOrder
loadMetaOptionsLists
intradoc.server.ExecuteSubServiceFilter
GET_CHOICE_LIST_SUB
1
@end

3.4.2.4 ClassAliases ResultSet

The ClassAliases ResultSet table points to custom Java class files, which are used to extend the functionality of an entire Oracle Content Server Java class. The following example shows a typical ClassAliases ResultSet.

@ResultSet ClassAliases
2
classname
location
WorkflowDocImplementor
WorkflowCheck.CriteriaWorkflowImplementor
@end

3.5 Resources Detail

The information in this section is intended as reference material and should not be used to create any resource files manually. You should always use the Component Wizard to create your resource files.

Resources are the files that define and implement the actual customization you make to Oracle Content Server. Resources can be snippets of HTML code, dynamic page elements, queries that gather data from the database, services that perform Oracle Content Server actions, or special code to conditionally format information.

The custom resource files for a component are typically located in the DomainHome/ucm/short-product-id/custom/component_name directory. If your component has more than a few resources, it is easier to maintain the files if you place them in subdirectories (such as component_name/resources or component_name/templates) within the component directory.

There are two ways to create and edit a resource file:

• Component Wizard: You can add, edit, or remove a resource file from a component using the Component Wizard. The Component Wizard provides code for predefined resources that you can use as a starting point for creating custom resources. You can also open resource files in a text editor from within the Component Wizard. Each resource type described in this section includes step-by-step instructions for using the Component Wizard to create and edit that type of resource.

• Manual editing: After creating a resource file with the Component Wizard, you can open the resource file in a text editor and edit the code manually, if necessary.

For more information, see Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server or online help.

Note:

You must restart Oracle Content Server after changing a resource file.

The following sections discuss these resource categories:

• Section 3.5.1, "HTML Include"

• Section 3.5.2, "Dynamic Data Tables"

• Section 3.5.3, "String"

• Section 3.5.4, "Dynamic Tables"

• Section 3.5.5, "Static Tables"

• Section 3.5.6, "Query"

• Section 3.5.7, "Service"

• Section 3.5.8, "Templates"

• Section 3.5.9, "Environment"

3.5.1 HTML Include

An include is defined within <@dynamichtml name@> and <@end@> tags in an HTM resource file. The include is then called using this syntax:

<$include name$>

Includes can contain Idoc Script and valid HTML code, including JavaScript, Java applets, cascading style sheets, and comments. Includes can be defined in the same file as they are called from, or they can be defined in a separate HTM file. Standard HTML includes are defined in the IdcHomeDir/resources/core/idoc files.

HTML includes, strings, and static tables can be present in the same HTM file. An HTML include resource does not require merge rules.

3.5.1.1 The Super Tag

The super tag is used to define exceptions to an existing HTML include. The super tag tells the include to start with an existing include and then add to it or modify using the specified code.

The super tag is particularly useful when making a small customization to large includes or when you customize standard code that is likely to change from one software version to the next. When you upgrade to a new version of Oracle Content Server, the super tag ensures that your components are using the most recent version of the include, modifying only the specific code you need to customize your instance.

The super tag uses the following syntax:

<@dynamichtml my_resource@>
    <$include super.my_resource$>
    exception code
<@end@>

You can use the super tag to refer to a standard include or a custom include. The super tag incorporates the include that was loaded last.

Note:

The placement of a super tag will determine how the Idoc Script is evaluated.

Example 3-1 Super Tag

In this example, a component defines the my_resource include as follows:

<@dynamichtml my_resource@>
    <$a = 1, b = 2$>
<@end@>

Another component that is loaded later enhances the my_resource include using the super tag. The result of the following enhancement is that a is assigned the value 1 and b is assigned the value 3:

<@dynamichtml my_resource@>
    <$include super.my_resource$>
    <!--Change "b" but not "a" -->
    <$b = 3$>
<@end@>

3.5.1.2 Editing an HTML Include Resource

Use the following procedure to edit an existing HTML include resource using the Component Wizard.

1. In the Component Wizard, open the component that contains the resource to edit.

2. Select the resource in the Custom Resource Definition list.

3. If the resource file contains multiple types of resources, click the Includes tab on the right.

4. Modify the includes in the Custom HTML Includes list.

   • To edit an existing include, select the include, click Edit, modify the code, and then click OK.

   • To add an include to the resource file, click Add.

   • To remove an include, select the include, click Delete, and then click Yes to confirm.

3.5.2 Dynamic Data Tables

A dynamic data table resource is a dynamicdata table. This type of resource enables you to define tables of data from within Idoc Script to load an HTML table definition, interface menu actions, or information about metadata fields or from within Java code as an alternative to static tables loaded into SharedObjects.

While tables loaded into SharedObjects are static and rarely change, a lot of code within Oracle Content Server will modify the contents of a dynamicdata table when it is loaded into a user's context. You can use dynamicdata resources to display different data to users depending on anything from their security attributes to the specific actions they are performing. Components can do targeted merging into tables created with this resource type, and Idoc Script pages can select and sort rows.

You can declare a dynamicdata resource as follows in any resource file that can contain dynamichtml constructions:

<@dynamicdata NameOfTable@>
<?formatoftable properties-of-table?>
table-data
<@end@>

A dynamicdata table is defined within <@dynamicdata name@> and <@end@> tags in a resource file. To reference dynamicdata tables, you need to use the Idoc Script functions whose names begin with dd, such as ddLoadResultSet, which loads a merged dynamicdata table and creates a ResultSet in the current data binder.

The IdcHomeDir/resources/core/idoc files define standard dynamicdata resources.

3.5.2.1 Specifying Table Formats

For the formatoftable parameter in a dynamicdata resource, you can specify either of two format types:

• commatable

• htmltable

The default format is commatable.

commatable

The commatable format is for tables with values that do not have line feeds or carriage returns. In this format, you enter a comma-separated list of field names on one line followed by a comma-separated list of values on the following lines, one line for each field, as in this example:

<@dynamicdata SampleTable@>
<?commatable?>
col1,   col2
val1_1, val1_2
val2_1, val2_2
<@end@>

If you need to insert a comma (,) into a value, then use a circumflex (^) instead of the comma. If you need to insert a circumflex, then enter the escape sequence hash-circumflex (#^, and if you need to insert a hash (#) that is followed by a hash or a circumflex, then enter the escape sequence hash-hash (##). For example:

<@dynamicdata SampleTable@>
field1, field2
A^B,    C##^D#^E#F^G
<@end@>

This dynamicdata resource would load a table row whose value for field1 would be A,B and for field2 would be C#^D^E#F,G.

You cannot escape line feeds or carriage returns. If you need to specify a value that contains either of those characters, then you should use the htmltable format.

htmltable

The htmltable format is the same as the format used for static HTML table constructs in Oracle Content Server. For example:

<@dynamicdata SampleTable@>
<?htmltable?>
<table>
<tr>
        <td>col1</td>
        <td>col2</td>
</tr>
<tr>
        <td>val11</td>
        <td>val12</td>
</tr>
<tr>
        <td>val21</td>
        <td>val22</td>
</tr>
</table>
<@end@>

3.5.2.2 Editing a Dynamic Data Table Resource

Use the following procedure to edit an existing dynamicdata resource using the Component Wizard.

1. In the Component Wizard, open the component that contains the resource to edit.

2. Select the resource in the Custom Resource Definition list.

3. If the resource file contains multiple types of resources, click the Includes tab on the right.

4. You can modify any of the dynamicdata tables in the custom resource definition, add a dynamicdata table, or remove a dynamicdata table:

   • To edit an existing dynamicdata table, choose the table, click Edit, modify the code, and then click OK.

   • To add a dynamicdata table to the resource file, click Add.

   • To remove a dynamicdata table, choose the table, click Delete, and then click Yes to confirm.

3.5.2.3 Specifying Table Properties

The properties-of-table parameter in a dynamicdata resource has this format:

field1="value1" field2="value2" . . .

The properties are like attributes defined in an XML node. For example, here is a typical table declaration:

<@dynamicdata ExampleTable@>
<?commatable mergeField="fieldA" indexedColumns="fieldA,fieldB"?>
fieldA, fieldB
1,      2
3,      4
<@end@>

The quotation marks that enclose the values are optional for values that have no spaces, and you can use either single or double quotation marks. Also, the default property value is "1", so you can omit the assignment of a value for a table property if it is "1".

Omitting the value is useful for Boolean properties such a notrim and mergeBlanks. For example, the following declaration specifies a table that is not to trim its values:

<@dynamicdata ExampleTable@>
<?commatable mergeField="fieldA" indexedColumns="fieldA,fieldB" notrim?>
fieldA, fieldB
1, 2
3, 4
<@end@>

In this example, the space would not be trimmed before the 2 or the 4. (Field names are always trimmed.)

You can specify the following kinds of table properties:

• Merge properties

• Assembly properties

• Sort properties

• Filter and dynamicdata table properties

3.5.2.3.1 Merge Properties

The dynamicdata tables can be merged together automatically, which is part of the power of using these tables. If two dynamicdata tables have the same name but are in separate resource files, they will be automatically merged. You can use the mergeOtherData option to merge another existing table into the current existing table. Using this technique, you can build very complicated tables all merged from various other tables. This merging can improve the readability of the data and enable you to have some tables as subsets of other tables.

You can specify one or more of the following merge properties in the properties-of-table parameter in a dynamicdata resource:

• mergeKey -- The name of the field to do a merge on. This value applies to both this and the existing tables when doing an overlay unless mergeNewKey is set in which case it only applies to the existing table. If this value is not set, then the merge key defaults to the first column of this table. If the mergeKey refers to a column in the existing table that does not exist, then the result will be to append this table to the existing table unless the mergeRule is set to a value that dictates a different outcome. This property has merge scope.

• mergeNewKey -- The name of the field in this table to use as a basis of comparison with the mergeKey column in the existing table. The default is to be the value of mergeKey. This property has merge scope.

• mergeRule -- The rule to use when performing a merge of two tables. This property has three possible values, the default being merge. This property has merge scope.

• merge -- Merge using the mergeKey (and if specified, the mergeNewKey) properties to perform the merge.

• mergenoappend -- Perform the merge, but do not append any new rows. If there is no valid merge to perform (for example, if the mergeKey does not refer to a valid column in the existing table), then the result is to not perform a merge at all and the overlaying table has no effect on the final result.

• replace -- Replace the existing table with this table. This option has the outcome of suppressing any prior table resource. This would be similar to not using the super include in a dynamichtml resource.

• mergeBlanks -- By default, when values are merged from this table to the existing table, any values that are blank in this table do not replace the overlaid value in the existing table. This allows for targeted replacement of column values in the existing table by this table. But if this option is enabled (set without a value, or set with the value 1 or true) then blanks in this table replace non-blank values in the existing table. The default is 0 (or false) and the property has merge scope.

• mergeAppendColumns -- This is a comma-separated list of columns in this table. For any column mentioned in the list, column values in this table for that column do not replace values in the existing table for that column but instead append or replace (using comma as the separator) the new value to the current value. Each of the subvalues in the comma separated list is assumed to be of the form key=value with =value part being optional. If this table has the same key in its comma separated list, then that key=value pair will replace the value in the existing table. For example, if the existing table has a column value of the form a=1,b=2 and this table has the value b=3,c=4 then the merged result will be a=1,b=3,c=4. This property has merge scope.

• cssStyleMergeAppendFormat -- This is a boolean property and changes the separator values used for the mergeAppendColumns property. Normally the value of a field mentioned in the mergeAppendColumns is a comma separated list of name equal value pairs with the equal operator (=) being the assignment operator. If this property is enabled, then the lists separator becomes a semi-colon (;) and the name value pairs use a colon (:) for the assignment. So instead of the field value looking like A=1,B=2 it would instead be A:1;B:2. The default is false and the property has merge scope.

• wildcard -- Normally when a merge is performed, the merge test is a case insensitive match comparison. When this option is enabled, the comparison is a standard Oracle Content Server wildcard match (* = 0 or more of any character, ? = any single character). Typically the option is used with mergeNewKey being set to a column different from mergeKey and in many cases the mergeKey does not even refer to a valid column in this table. The default is 0 (or false) and the property has merge scope.

• mergeOtherData -- A comma separated list of other dynamicdata resources to merge into this one. Each of the other dynamicdata resources are fully merged before they are merged into this resource (if those other resources also are using mergeOtherData, then those merges are done first -- the code does have recursion detection). If the one of the referenced dynamicdata resources has multiple definitions in multiple files, then the merge keys used to merge into this resource are the ones defined that is highest in merge order (the one that is merged into last) for that other resource. If this dynamicdata resource (the one that has the mergeOtherData property on it) has multiple definitions in multiple files, the mergeOtherData parameter is produced by merging all the referenced named resources from all the resources in the merge stack. The default is null and has global scope.

3.5.2.3.2 Assembly Properties

You can specify one or more of the following assembly properties in the properties-of-table parameter in a dynamicdata resource:

• notrim -- This option only applies to the commatable format. Normally, all the values that are parsed for a table resource are trimmed. Setting this option prevents the values from being trimmed. It is presumed that this will be a rarely used option. The default is 0 (or false) and the property has local table scope.

• indexedColumns -- This property lists columns that should be optimized for indexed lookup. Specialized Idoc Script functions exist to take advantage of the any of the indexed columns. When a lookup is done against an indexed column, the column name and a value must be specified. A filtered table consisting of just the rows whose values for the indexed column match (case insensitive) the value passed in to the function is returned. Note that these indexed column lookups are all computed at load/merge time and stored in a hash table for fast retrieval. The list of indexed column values for all the overlaying tables are merged together and the index computations are done after the merge is finished. This property has global table scope.

• countColumn -- This value specifies a column in the fully merged table into which the values of a row count is put. The count starts at 1 and increments for each row in the table. Any existing values in that column of the merged table are replaced by the count value. This property can be used to create a quick unique key for each row. The default value for this property is "count", so any table with the column name "count" that does not specify a different countColumn will automatically have counter values put into that column. If the value of this property does not match a column name in the final merged table, then it is ignored. If an overlaying table resource specifies a different countColumn from one specified in a prior table resource, then the overlaying one will be used. The property has global table scope.

• defaultValues -- This property specifies a comma-separated list of default values to apply to the table. Each default value in this list is of the format fieldname:value. If the value is an empty string then the colon can be dropped. For example, the string field1:val1,field2:val2,field3 specifies the default value val1 for field1, val2 for field2, and the empty string for field3. A colon can be escaped with a star (*) and a star can be escaped by preceding it with a hash (#). If either a hash or a star follows a hash, then the hash can be escaped by adding another hash (see the similar rule for escaping commas given earlier). If a field specified in a default value construction does not exist in the final merged table, then it is added as a new field and given the default value for all rows in that table. If the field exists, then the default value will override any blank values in that table for that field. The definitions of defaultValues from the newer overlaying tables are collated with the active definition of the existing table. If there is a conflict in the definition of a particular default value, the newer overlaying table wins. The default for this property is null and it has global table scope.

• derivedColumns -- This property specifies columns to be built up from values from other columns. The general syntax is a comma separated list of derived column definitions of the form derivedColumnDef1,derivedColumnDef2,... with each column definition being of the form fieldName:sourceField1+sourceField2+.... The fieldName refers to the name of the field to be created and the sourceFieldN refer to fields whose value will be sourced to create the derived column. The derived value will hold the values of the source fields separated by a double colon (::). If the derived column exists and has a non empty value, then it is not replaced. As with the defaultValues property, there is a second pass after the final table is assembled to determine whether any derived values still need to be filled in. The most typical usage for derived columns is to allow one dynamicdata resource to use multiple columns for specifying a merge criteria instead of just one. The derived column is used as the target of a merge and is defined in the definition of the existing table. The derived column definitions are inherited into the newer overlaying tables and if there is a conflict in definition of a particular derived column then the newer table's definition wins. Otherwise, the definitions of derived columns from the existing and new tables are collated together. The default value for this property is null and it has global table scope.

3.5.2.3.3 Sort Properties

You can specify one or more of the following sort properties in the properties-of-table parameter in a dynamicdata resource:

• sortColumn -- Specifies a column to sort on. If an overlaying table resource specifies a different sortColumn from one specified in a prior table resource, then the overlaying one will be used. If the name of the column does not match any column name in the final merged table, then no sort is performed. The default value is "sortOrder". So creating a column with this name will cause the table to be automatically sorted. This property has global table scope

• sortType -- Specifies what data type should be assumed for the column being sorted. This type applies to both the sortColumn and the sortParentColumn. The values can be "int", "string", or "date". The default value for this property is "int". Rules for overlaying tables both specifying this property are identical to sortColumn. This property has global table scope.

• sortOrder -- Specifies what sort order to use when performing a sort. The possible values are "asc" (for ascending) and "desc" (for descending). The default is "asc". Rules for overlaying tables both specifying this property are identical to sortColumn. This property has global table scope.

• sortIsTree -- Specifies whether the sort is actually a tree sort with a sortParentColumn being sorted along with the sortChildColumn. The assumption is that the child to parent row mapping relationship is done by using the child row's value in the sortParentColumn to the find the parent row with a matching value in its sortChildColumn field. The sort is performed so that the top level parents are sorted first, then the children of each parent are sorted as a subgroup for each parent and so on recursively for all the children of the children. The default value is 0 (or false). Rules for overlaying tables both specifying this property are identical to sortColumn. This property has global table scope.

• sortParentColumn -- This value must be specified if the sortIsTree option is enabled. If the value of this property is missing or specifies an invalid column, then the sortIsTree option is ignored and has no effect. For more information about what it does, see the preceding description of the sortIsTree property. The default for the sortParentColumn property is null. Rules for overlaying tables both specifying this property are identical to sortColumn. This property has global scope.

• sortChildColumn -- This value must be specified if the sortIsTree option is enabled. If the value of this property is missing or specifies an invalid column, then the sortIsTree option is ignored and has no effect. For more information about what it does, see the preceding description of the sortIsTree property. The default for the sortChildColumn property is null. Rules for overlaying tables both specifying this property are identical to sortColumn. This property has global scope.

• sortNestLevelColumn -- This value is only available if the sortIsTree option is enabled. If the value of this property references an invalid column then it has no effect. If a valid column is specified, then that column will get an integer value that specifies its nest level (starting at 0). The nest level is defined as the number of immediate parents that have to be traversed before reaching a parent that itself has no parent. The default value for this property is "nestLevel" and it has global scope.

3.5.2.3.4 Filter and Include Properties

You can specify one or more of the following filter and include properties in the properties-of-table parameter in a dynamicdata resource:

• filterInclude -- This property specifies an include to be executed for each row of a table (or subtable if an indexed column is being used to select a subtable). This execution will happen when the table is loaded into the current user's context. Its main purpose is either to create a side effect or to determine if the row should be excluded. To prevent the row from being loaded into the final result set, you can set the variable ddSkipRow to 1 (<$ddSkipRow=1$>). During execution of this include, the table is made active, allowing for easy access and replacement of values in the table. The default value of this property is null, and it has global scope.

• includeColumns -- This property specifies a comma-separated list of columns whose row values are the names of resource includes to be executed. After the resource includes are executed, the result is fed back into the result set to become the new value for that column for that row. The timing and rules for execution are similar to filterInclude except that includeColumns cannot suppress the loading of a row. If a filter include is specified and there are active include columns, then during the looping of the temporary active result set, the include column values are executed first and then the filter include. If one of the specified include columns in not present in the final merged table, then it will have no effect. Empty values in an include column are ignored. The includeColumns attribute is commonly combined with the defaultValues attribute to create columns whose values are derived from other columns. The default value of this property is null, and it has global scope.

  Note:

  Using includeColumns may not be as useful as it first appears. The resource includes are executed at the time the Idoc Script function is executed to load the table, but a component that customizes output may determine the value for the column only after further processing (after other tables are merged into this table, summaries of row statistics are calculated, and so on).

3.5.2.4 Using Dynamicdata Idoc Script Functions

For dynamic data tables, you can use the following dynamicdata Idoc Script functions:

• ddAppendIndexedColumnResultSet

• ddAppendResultSet

• ddApplyTableSortToResultSet

• ddGetFieldList

• ddIncludePreserveValues

• ddLoadIndexedColumnResultSet

• ddLoadResultSet

• ddMergeIndexedColumnResultSet

• ddMergeResultSet

• ddMergeUsingIndexedKey

• ddSetLocal

• ddSetLocalByColumnsFromFirstRow

• ddSetLocalByColumnsFromFirstRowIndexed

• ddSetLocalEmpty

• ddSetLocalEmptyByColumns

3.5.3 String

A string resource defines locale-sensitive text strings that are used in error messages and on Oracle Content Server web pages and applets. Strings are resolved by Oracle Content Server each time a web page is assembled, an applet is started, or an error message is displayed.

A string is defined in an HTM file using the following format:

<@stringID=Text string@>

A string is called from an HTM template file using the following Idoc Script format:

<$lc("wwStringID")$>

Note:

On Oracle Content Server web pages, you should use only the strings in the ww_strings.htm file.

Standard English strings are defined in the IdcHomeDir/resources/core/lang directory. Strings for other supported languages are provided by the Localization component.

HTML includes, strings, and static tables can be present in the same HTM file. A string resource does not require merge rules.

You must use HTML escape encoding to include the following special characters in a string value.

Escape Sequence	Character
&at;	@
\&lf;	line feed (ASCII 10)
\&cr;	carriage return (ASCII 13)
\&tab;	tab (ASCII 9)
\&eatws;	Eats white space until the next non-white space character.
\&lt;	< (less than)
\&gt;	> (greater than)
\&sp;	space (ASCII 32)
\&#xxx;	ASCII character represented by decimal number xxx

You can specify strings for multiple languages in the same resource file using the language identifier prefix, if the languages all have single-byte characters or all have multibyte characters. For example:

<@myString=Thank you@>
<@es.myString=Gracias@>
<@fr.myString=Merci@>
<@de.myString=Danke@>

Caution:

Do not specify single-byte strings and multibyte strings in the same resource file. You should create separate resource files for single-byte and multibyte strings.

If you are specifying multibyte strings in your custom string resource, ensure that the character set specification on your HTML pages changes to the appropriate encoding. Resource files should have a correct http-equiv charset tag so that Oracle Content Server reads them correctly.

3.5.3.1 String Parameters

Text strings can contain variable parameters, which are specified by placing the parameter argument inside curly braces (for example, {1}). When a string is localized, the arguments are passed along with the string ID and the ExecutionContext value that contains the locale information. The following table describes the syntax for parameterized strings.

Syntax	Meaning	Examples
{{}	Opening curly brace. (Note that only the opening curly brace must be expressed as a literal.)	{{}Text in braces}
{n}	Substitute the nth argument.	Content ID {1} not found
{ni}	Substitute the nth argument, formatted as an integer.	dID {1i} does not exist
{nx}	Substitute the nth argument, formatted as an integer in hexadecimal.
{nd}	Substitute the nth argument, formatted as a date.	The release date is {1d}
{nD}	Substitute the nth argument, formatted as a date. The argument should be ODBC-formatted.	The release date is {1D}
{nt}	Substitute the nth argument, formatted as a date and time.	The release date is {1t}
{ne}	Substitute the nth argument, formatted as elapsed time.
{nT}	Substitute the nth argument, formatted as a date and time. The argument should be ODBC-formatted.	The release date is {1T}
{nfm}	Substitute the nth argument, formatted as a float with m decimal places.	The distance is {1f3} miles.
{nk}	Substitute a localized string using the nth argument as the string ID.	Unable to find {1k} revision of {2}
{nm}	Localize the nth argument as if it were a string-stack message. (For example, the argument could include concatenated text strings and localized string IDs.)	Indexing internal error: {1m}
{nl}	Substitute the nth argument as a list. The argument must be a list with commas (,) and carets (^) as the separators.	Add-ons: {1l}
{nK}	Takes a list of localization key names, separated by commas, and localizes each key into a list.	Unsupported byte feature(s): {1K}
{nM}	Takes a list of message strings and localizes each message into a list.	{1q} component, version {2q}, provides older versions of features than are currently enabled. {3M}
{nq}	If the nth argument is non-null and nonzero in length, substitute the argument in quotation marks. Otherwise, substitute the string "syUndefined".	Content item {1q} was not successfully checked in
{no}	Performs ordinal substitution on the nth argument. For example, 1st, 2nd, 3rd, and so on. The argument must be an integer.	"I am {1o}." with the argument 7 would localize into "I am 7th."
{n?text}	If the value of the nth argument is not 1, substitute the text.	{1} file{1?s} deleted
{n?text1:text2}	If the value of the nth argument is not 1, substitute text1. If the value of the nth argument is 1, substitute text2. The (n?) function can be extended with as many substitution variables as required. The last variable in the list always corresponds to a value of 1.	There {1?are:is} currently {1} active search{1?es}.
{n?text1:text2:text3}	If the value of the nth argument is not 1 or 2, substitute text1. If the value of the nth argument is 2, substitute text2. If the value of the nth argument is 1, substitute text3. The (n?) function can be extended with as many substitution variables as required. The last variable in the list always corresponds to a value of 1.	Contact {1?their:her:his} supervisor.

3.5.3.2 Editing a String Resource

Use the following procedure to edit an existing string resource using the Component Wizard.

1. In the Component Wizard, open the component that contains the resource to edit.

2. Select the resource in the Custom Resource Definition list.

3. If the resource file contains multiple types of resources, click the Strings tab on the right.

4. Modify the strings in the Custom Strings list.

   • To edit an existing string, select the string, click Edit, modify the string text, and then click OK.

   • To add a string to the resource file, click Add.

   • To remove a string, select the string, click Delete, and then click Yes to confirm.

3.5.4 Dynamic Tables

Dynamic table resources are defined in the HDA file format. For more information and an example of an HDA ResultSet table, see Section 3.2.1.1, "Elements in HDA Files."

3.5.4.1 Merge Rules for Dynamic Tables

Merge rules are required for a dynamic table resource if data from the custom resource replaces data in an existing table. Merge rules are not required if data from the custom resource is to be placed in a new table.

3.5.4.2 Editing a Dynamic Table Resource

Use the following procedure to edit an existing dynamic table resource using the Component Wizard.

1. In the Component Wizard, open the component that contains the resource to edit.

2. Select the resource file in the Custom Resource Definition list.

3. Click Launch Editor.

4. Modify the table in the text editor.

5. Save and close the resource file.

   Changes are reflected on the right of the Resource Definition tab.

3.5.5 Static Tables

Static tables, HTML includes, and strings can be present in the same HTM file.

3.5.5.1 Merge Rules for Static Tables

Merge rules are required for a static table resource if data from the custom resource replaces data in an existing table. Merge rules are not required if data from the custom resource is to be placed in a new table.

3.5.5.2 Editing a Static Table Resource

Use this procedure to edit an existing static table resource with the Component Wizard.

1. In the Component Wizard, open the component that contains the resource to edit.

2. Select the resource file in the Custom Resource Definition list.

3. Click Launch Editor.

4. Modify the table in the text editor.

5. Save and close the resource file. Changes are reflected in the Resource Tables list.

3.5.6 Query

A query resource defines SQL queries, which are used to manage information in the Oracle Content Server database. Queries are used with service scripts to perform tasks such as adding to, deleting, and retrieving data from the database.

The standard Oracle Content Server queries are defined in the QueryTable table in the IdcHomeDir/resources/core/tables/query.htm file. You also find special-purpose queries in the indexer.htm and workflow.htm files that are stored in the IdcHomeDir/resources/core/tables directory. Merge rules are not required for a query resource.

A query resource is defined in an HTM file using a ResultSet table with three columns: name, queryStr, and parameters.

• The name column defines the name for each query. To override an existing query, use the same name for your custom query. To add a new query, use a unique query name. When naming a new query, identify the type of query by starting the name with one of the following characters.

  First Character	Query Type
  D	Delete
  I	Insert
  Q	Select
  U	Update

  
  

• The queryStr column defines the query expression. Query expressions are in standard SQL syntax. If there are any parameter values to pass to the database, their place is held with a question mark (?) as an escape character.

• The parameters column defines the parameters that are passed to the query from a service. A request from a web browser calls a service, which in turn calls the query. It is the responsibility of the web browser to provide the values for the query parameters, which are standard HTTP parameters The browser can pass query parameters from the URL or from FORM elements in the web page. For example, the QdocInfo query requires the dID (revision ID) to be passed as a parameter, so the value is obtained from the service request URL.

3.5.6.1 Query Example

The following example shows the standard QdocInfo query as defined in the IntradocDir/shared/config/resources/query.htm file. This query obtains the metadata information to display on the DOC_INFO template page, which is the page displayed when a user clicks the Information icon on a search results page.

The parameter passed from the web browser URL is the dID, which is the unique identification number for the content item revision. The query expression selects the data that matches the dID for the primary revision from the Revisions, Documents, and DocMeta database tables, if the revision does not have the DELETED status.

Figure 3-3 Standard QDocInfo Query

<HTML>
<HEAD>
<META HTTP-EQUIV='Content-Type' content='text/html; charset=iso-8859-1'>
<TITLE>Query Definition Resources</TITLE>
</HEAD>
<BODY>
<@table QueryTable@>
<table border=1><caption><strong>Query Definition Table</strong></caption>
<tr>
    <td>name</td>
    <td>queryStr</td>
    <td>parameters</td>
</tr>
<tr>
    <td>QdocInfo</td>
    <td>SELECT Revisions.*, Documents.*, DocMeta.*
    FROM Revisions, Documents, DocMeta
    WHERE Revisions.dID=? AND Revisions.dID=Documents.dID AND DocMeta.dID = Documents.dID AND Revisions.dStatus<>'DELETED' AND Documents.dIsPrimary<>0</td>
    <td>dID int</td>
</tr>
</table>
<@end@>
</BODY>
</HTML>

3.5.6.2 Editing a Query Resource

Use the following procedure to edit a query resource using the Component Wizard.

1. In the Component Wizard, open the component that contains the resource to edit.

2. Select the resource in the Custom Resource Definition list.

3. If there are multiple tables in the resource, select the query table to edit from the Table Name list.

4. Modify the selected query table.

   • To add a query to the table, click Add.

   • To edit an existing query, select the query, click Edit, modify the query expression or parameters or both, and then click OK.

   • To remove a query, select the query, click Delete, and then click Yes to confirm.

3.5.7 Service

A service resource defines a function or procedure that is performed by Oracle Content Server. A service call can be performed from either the client or server side, so services can be performed on behalf of the web browser client or within the system itself. For example:

• Client-side request: When you click a Search link on an Oracle Content Server web page, the standard search page is delivered to your web browser by the GET_DOC_PAGE service, using the following URL segment:

  IdcService=GET_DOC_PAGE&Action=GetTemplatePage&Page=STANDARD_QUERY_PAGE
  

• Server-side request: You can use the START_SEARCH_INDEX service to update or rebuild the search index automatically in a background thread.

Services are the only way a client can communicate with the server or access the database. Any program or HTML page can use services to request information from Oracle Content Server or perform a specified function.

Important:

This section provides an overview of custom service resources. For more information about Oracle Content Server services, see Oracle Fusion Middleware Services Reference Guide for Oracle Universal Content Management.

The standard Oracle Content Server services are defined in the StandardServices table in the IdcHomeDir/resources/core/tables/std_services.htm file. You can also find special-purpose services in the workflow.htm file in the IdcHomeDir/resources/core/tables directory.

Services depend on other resource definitions to perform their functions. Any service that returns HTML requires a template to be specified. A common exception is the PING_SERVER service, which does not return a page to the browser.

Most services use a query. A common exception is the SEARCH service, which sends a request directly to the search collection. Merge rules are not required for a service resource.

The following table row is an example of a service definition.

Figure 3-4 Service Definition Example

A service resource is defined in an HTM file using a ResultSet table with the following three columns:

• The Name column defines the name for each service. For client-side service requests, this is the name called in the URL. To override an existing service, use the same name for your custom service. To add a new service, use a unique service name.

• The Attributes column defines the following attributes for each service.

  Attribute	Description	Example (attributes from the DELETE_DOC service)
  Service class	Determines, in part, what actions can be performed by the service.	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Access level	Assigns a user access level to the service. This number is the sum of the following possible bit flags: READ_PRIVILEGE = 1 WRITE_PRIVILEGE = 2 DELETE_PRIVILEGE = 4 ADMIN_PRIVILEGE = 8 GLOBAL_PRIVILEGE = 16 SCRIPTABLE_SERVICE=32	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Template page	Specifies the template that presents the results of the service. If the results of the service do not require presentation, this attribute is null.	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Service type	If the service is to be executed inside another service, this attribute is SubService; otherwise, this attribute is null.	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Subjects notified	Specifies the subjects (subsystems) to be notified by the service. If no subjects are notified, this attribute is null.	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Error message	Defines the error message returned by the service if no action error message overrides it. This can be either an actual text string or a reference to a locale-sensitive string. For more information, see Section 2.3.6, "Localized String Resolution."	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)

  
  

• The Actions column defines the actions for each service. An action is an operation to be performed as part of a service script. The action can execute an SQL statement, perform a query, run code, cache the results of a query, or load an option list. Each service includes one or more actions, which specify what happens upon execution.

  The <br> tags in the Actions column are for browser display purposes only, so they are optional. However, the </td> tag must occur immediately after the actions, without a line break in between. An action is defined using the following format:

  type:name:parameters:control mask:error message
  

  Section	Description	Example (first action from the DELETE_DOC service)
  Type	Defines the type of action: QUERY_TYPE = 1 EXECUTE_TYPE = 2 CODE_TYPE = 3 OPTION_TYPE = 4 CACHE_RESULT_TYPE = 5	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExists
  Name	Specifies the name of the action.	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist
  Parameters	Specifies parameters required by the action. If no parameters are required, leave this part empty (two colons appear in a row).	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist
  Control mask	Controls the results of queries to the database. This number is the sum of the following possible bit flags: No control mask = 0 CONTROL_IGNORE_ERROR = 1 CONTROL_MUST_EXIST = 2 CONTROL_BEGIN_TRAN = 4 CONTROL_COMMIT_TRAN = 8 CONTROL_MUST_NOT_EXIST = 16	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist
  Error message	Defines the error message to be displayed by this action. This error message overrides the error message provided as an attribute of the service. This can be either an actual text string or a reference to a locale-sensitive string. For more information, see Section 2.3.6, "Localized String Resolution."	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist

  
  

3.5.7.1 Service Example

The DOC_INFO service provides a good example of how services, queries, and templates work together. The following figures show the DOC_INFO service definition from the IntradocDir/config/resources/std_services.htm file.

Figure 3-5 DOC_INFO Service

    <HTML>
    <HEAD>
    <META HTTP-EQUIV='Content-Type' content='text/html; charset=iso-8859-1'>
    <TITLE>Standard Scripted Services</TITLE>
    </HEAD>
    <BODY>
    <@table StandardServices@>
    <table border=1><caption><strong>Scripts For Standard Services</strong></caption>
    <tr>
    <td>Name</td><td>Attributes</td><td>Actions</td>
    </tr>
    <tr>
    <td>DOC_INFO</td>
    <td>DocService
        33
        DOC_INFO
        null
        null<br>
        !csUnableToGetRevInfo</td>
    <td>5:QdocInfo:DOC_INFO:2:!csItemNoLongerExists2
        3:mapNamedResultSetValues:DOC_INFO,dStatus,dStatus,dDocTitle,dDocTitle:0:null
        3:checkSecurity:DOC_INFO:0:!csUnableToGetRevInfo2(dDocName)
        3:getDocFormats:QdocFormats:0:null
        3:getURLAbsolute::0:null
        3:getUserMailAddress:dDocAuthor,AuthorAddress:0:null
        3:getUserMailAddress:dCheckoutUser,CheckoutUserAddress:0:null
        3:getWorkflowInfo:WF_INFO:0:null
        3:getDocSubscriptionInfo:QisSubscribed:0:null
        5:QrevHistory:REVISION_HISTORY:0:!csUnableToGetRevHistory(dDocName)</td>
    </tr>
    </table>
    <@end@>
    </BODY>
    </HTML>

3.5.7.1.1 Attributes

The following table describes the attributes of the DOC_INFO service shown previously.

Attribute	Value	Description
Service class	DocService	This service is providing information about a content item.
Access level	33	32 = This service can be executed with the executeService Idoc Script function. 1 = The user requesting the service must have Read privilege on the content item.
Template page	DOC_INFO	This service uses the DOC_INFO template (doc_info.htm file). The results from the actions are merged with this template and presented to the user.
Service type	null	This service is not a subservice.
Subjects notified	null	No subjects are affected by this service.
Error Message	!csUnableToGetRevInfo	If this service fails on an English Oracle Content Server system, it returns this error message string: Unable to retrieve information about the revision

3.5.7.1.2 Actions

The DOC_INFO service executes the following actions:

• 5:QdocInfo:DOC_INFO:2:!csItemNoLongerExists2

  Action Definition	Description
  5	Cached query action that retrieves information from the database using a query.
  QDocInfo	This action retrieves content item information using the QDocInfo query in the query.htm file.
  DOC_INFO	The result of the query is assigned to the parameter DOC_INFO and stored for later use.
  2	The CONTROL_MUST_EXIST control mask specifies that either the query must return a record, or the action fails.
  !csItemNoLongerExists2	If this action fails on an English Oracle Content Server system, it returns this error message string: This content item no longer exists

  
  

• 3:mapNamedResultSetValues:DOC_INFO,dStatus,dStatus,dDocTitle,dDocTitle:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  mapNamedResultSetValues	This action retrieves the values of dStatus and dDocTitle from the first row of the DOC_INFO ResultSet and stores them in the local data. (This increases speed and ensures that the correct values are used.)
  DOC_INFO,dStatus,dStatus,dDocTitle,dDocTitle	Parameters required for the mapNamedResultSetValues action.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:checkSecurity:DOC_INFO:0:!csUnableToGetRevInfo2(dDocName)

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  checkSecurity	This action retrieves the data assigned to the DOC_INFO parameter and evaluates the assigned security level to verify that the user is authorized to perform this action.
  DOC_INFO	Parameter that contains the security information to be evaluated by the checkSecurity action.
  0	No control mask is specified.
  !csUnableToGetRevInfo2(dDocName)	If this action fails on an English Oracle Content Server system, it returns this error message string: Unable to retrieve information for ''{dDocName}."

  
  

• 3:getDocFormats:QdocFormats:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getDocFormats	This action retrieves the file formats for the content item using the QdocFormats query in the query.htm file. A comma-delimited list of the file formats is stored in the local data as dDocFormats.
  QdocFormats	Specifies the query used to retrieve the file formats.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getURLAbsolute::0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getURLAbsolute	This action resolves the URL of the content item and stores it in the local data as DocUrl.
  blank	This action takes no parameters.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getUserMailAddress:dDocAuthor,AuthorAddress:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getUserMailAddress	This action resolves the e-mail address of the content item author.
  dDocAuthor,AuthorAddress	This action passes dDocAuthor and AuthorAddress as parameters.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getUserMailAddress:dCheckoutUser,CheckoutUserAddress:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getUserMailAddress	This action resolves the e-mail address of the user who has the content item checked out.
  dCheckoutUser,CheckoutUserAddress	This action passes dCheckoutUser and CheckoutUserAddress as parameters.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getWorkflowInfo:WF_INFO:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getWorkflowInfo	This action evaluates whether the content item is part of a workflow. If the WF_INFO ResultSet exists, then workflow information is merged into the DOC_INFO template.
  WF_INFO	This action passes WF_INFO as a parameter.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getDocSubscriptionInfo:QisSubscribed:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getDocSubscriptionInfo	This action evaluates if the current user has subscribed to the content item: If the user is subscribed, an Unsubscribe button is displayed. If the user is not subscribed, a Subscribe button is displayed.
  QisSubscribed	Specifies the query used to retrieve the subscription information.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 5:QrevHistory:REVISION_HISTORY:0:!csUnableToGetRevHistory(dDocName)

  Action Definition	Description
  5	Cached query action that retrieves information from the database using a query.
  QrevHistory	This action retrieves revision history information using the QrevHistory query in the query.htm file.
  REVISION_HISTORY	The result the query is assigned to the parameter REVISION_HISTORY. The DOC_INFO template uses this parameter in a loop to present information about each revision.
  0	No control mask is specified.
  !csUnableToGetRevHistory(dDocName)	If this action fails on an English Oracle Content Server system, it returns the error message string: Unable to retrieve revision history for ''{dDocName}.''

  
  

3.5.7.2 Editing a Service Resource

Use the following procedure to edit a service resource using the Component Wizard.

1. In the Component Wizard, open the component that contains the resource to edit.

2. Select the resource in the Custom Resource Definition list.

3. If there are multiple tables in the resource, select the service table to edit from the Table Name list.

4. Modify the selected service table.

   • To add a service to the table, click Add.

   • To edit an existing service, select the service, click Edit, modify the service attributes or actions or both, and then click OK.

   • To remove a service, select the service, click Delete, and then click Yes to confirm.

3.5.8 Templates

A template resource defines the names, types, and locations of custom template files to be loaded for the component.

The actual template pages (.htm files) are separate files that are referenced in the template resource file. Template HTM files contain the code that the Oracle Content Server uses to assemble web pages. HTML markup in a template file defines the basic layout of the page, while Idoc Script in a template file generates additional HTML code for the web page at the time of the page request. Because HTM template files contain a large amount of script that is not resolved by Oracle Content Server until the final page is assembled, these files are not viewable web pages.

The template type of HTM file is used to define the following component files:

• Template pages: Standard template pages are located in the IdcHomeDir/resources/core/templates directory.

• Report pages: Standard report pages are located in the IdcHomeDir/resources/core/reports directory.

A template resource (templates.hda) is defined in the HDA file format. The standard templates are defined in the IdcHomeDir/resources/core/templates/templates.hda file. For more information and an example of an HDA ResultSet table, see Section 3.2.1.1, "Elements in HDA Files."

Merge rules are required to merge the new template definition into the IntradocTemplates table or the SearchResultTemplates table. Typically, the merge is on the name column. The following example shows a MergeRules ResultSet for a template.

@ResultSet MergeRules
4
fromTable
toTable
column
loadOrder
MultiCheckinTemplates
IntradocTemplates
name
1
@end

The standard templates.hda file defines three ResultSet tables:

• The IntradocTemplates ResultSet table defines the template pages for all Oracle Content Server web pages except search results pages. This table consists of five columns:

  • The name column defines the name for each template page. This name is how the template is referenced in the Oracle Content Server CGI URLs and in code.

  • The class column defines the general category of the template. The most common class type is Document.

  • The formtype column defines the specific type of functionality the page is intended to achieve. The formtype is typically the same as the name of the form, except in lowercase characters.

  • The filename column defines the path and file name of the template file. The location can be an absolute path or can be relative to the template resource file when the template page is in the same directory as the template resource file.

  • The description column defines a description of the template.

• The VerifyTemplates ResultSet table is no longer used by Oracle Content Server, but this table remains in the templates.hda file as legacy code for reverse compatibility.

• The SearchResultTemplates table defines the template pages for search results pages. Template pages define how query results are displayed on the search results pages in the Library. Query result pages are a special type of search results page. This table consists of six columns:

  • The name column defines the name for each template page. This name is how the template is referenced in the Oracle Content Server CGI URLs, in code, and in the Web Layout Editor utility.

    Note:

    The StandardResults template (search_results.htm file) is typically used as the global template for standard search results pages and the query results pages in the Library. You can create a new template or change the "flexdata" of the StandardResults template through the Web Layout Editor, but these changes are saved in a separate file (IntradocDir/data/results/custom_results.hda) rather than in the SearchResultTemplates table in the templates.hda file.

  • The formtype column defines the specific type of functionality the page is intended to achieve. ResultsPage is the only form type currently supported for search results pages.

  • The filename column defines the path and file name of the template file. The location can be an absolute path or can be relative to the template resource file when the template page is in the same directory as the template resource file.

  • The outfilename column is for future use; the value is always null.

  • The flexdata column defines the metadata to be displayed for each row on the search results page. The format of text in the flexdata column follows:

    Text1 "text 1 contents"%<Tab>Text2 "text 2 contents"%
    

    In the format, the Text1 value appears on the first line in each search results row, and the Text2 value appears on the second line. <Tab> represents a literal tab character.

    Idoc Script can be used to define the contents in the flexdata field. You can also change the flexdata of the StandardResults template through the Web Layout Editor, but these changes are saved in a separate file (IntradocDir/data/results/custom_results.hda) rather than in the SearchResultTemplates table in the templates.hda file.

  • The description column defines a description of the template.

The following example shows a custom template resource file that points to a custom Content Management page (multicheckin_doc_man.htm) and a custom search results page (MultiCheckin_search_results.htm).

<?hda version="5.1.1 (build011203)" jcharset=Cp1252 encoding=iso-8859-1?>
@Properties LocalData
blDateFormat=M/d{/yy} {h:mm[:ss] {aa}[zzz]}!tAmerica/Chicago!mAM,PM
blFieldTypes=
@end
@ResultSet MultiCheckinTemplates
5
name
class
formtype
filename
description
DOC_MANAGEMENT_LINKS
DocManagement
DocManagementLinks
multicheckin_doc_man.htm
Page containing links to various document management functions
@end
@ResultSet MultiCheckin_2
6
name
formtype
filename
outfilename
flexdata
description
StandardResults
SearchResultsPage
MultiCheckin_search_results.htm
null
Text2 <$dDocTitle$> <$dInDate$>%       Text1 <$dDocName$>%
apStandardResultsDesc
@end

3.5.8.1 Template and Report Pages

Template pages and report pages are also called presentation pages, because Oracle Content Server uses them to assemble, format, and present the results of a web page request.

The standard template pages are located in the IdcHomeDir/resources/core/templates directory. The standard report pages are located in the IdcHomeDir/resource/core/reports directory.

3.5.8.1.1 Template Page Example

The following example shows the template file for the standard Content Management page (doc_man.htm).

Figure 3-6 Template Page Example

Description of "Figure 3-6 Template Page Example"

3.5.8.1.2 Report Page Example

The following example shows the template file for the standard Document Types report page (doc_types.htm).

Figure 3-7 Report Page Example

Description of "Figure 3-7 Report Page Example"

3.5.8.2 Editing a Template Resource

Use the following procedure to edit an existing template resource using the Component Wizard.

1. In the Component Wizard, open the component that contains the resource to edit.

2. Select the resource in the Custom Resource Definition list.

3. To remove a template definition table or edit a template definition manually, click Launch Editor in the Custom Resource Definition area.

4. If there are multiple tables in the resource, select the template table to edit from the Table Name list.

5. Modify the selected template table.

   • To add a template definition to the table, click Add.

   • To edit an existing template definition, select the definition, click Edit, modify the parameters, and then click OK.

   • To remove a template definition, select the definition, click Delete, and then click Yes to confirm.

3.5.9 Environment

An environment resource defines configuration variables, either by creating new variable values or replacing existing values. Because custom resources are loaded after the standard config.cfg file is loaded, the variable values defined in the custom environment resource replace the original variable values.

An environment resource is defined in a CFG file using a name/value pair format:

variable_name=value

After defining a variable value, you can reference the variable in templates and other resource files with the following Idoc Script tag:

<$variable_name$>

Environment resource files can include comment lines, which are designated with a # symbol:

#Set this variable to true to enable the function.

3.5.9.1 Environment Resource Example

Example 3-2 shows the contents of an environment resource file.

Example 3-2 Environment Resource

# Use this to turn on or off alternate row coloring
nsUseColoredRows=0

# These are the nested search field definitions.

nsFld1Caption=Document Text
nsFld1Name=
nsFld1Type=FullText
nsFld1OptionKey=
#
nsFld2Caption=Text
nsFld2Name=xtext
nsFld2Type=Text
nsFld2OptionKey=
#
nsFld3Caption=Date
nsFld3Name=xdate
nsFld3Type=Date
nsFld3OptionKey=
#
nsFld4Caption=Integer
nsFld4Name=xinteger
nsFld4Type=Int
nsFld4OptionKey=
#
nsFld5Caption=Option List
nsFld5Name=xoptionlist
nsFld5Type=OptionList
nsFld5OptionKey=optionlistList
#
nsFld6Caption=Info Topic
nsFld6Name=xwfsInfoTopic
nsFld6Type=OptionList
nsFld6OptionKey=wfsInfoTopicList

The colored_search_resource.htm template resource file in the Nested Search component references the nsUseColoredRows variable as follows:

<$if isTrue(#active.nsUseColoredRows)$>
    <$useColoredRows=1, bkgHighlight=1$>
<$endif$>

Standard configuration variables are defined in the IntradocDir/config/config.cfg file. For a complete list of configuration variables, see the Oracle Fusion Middleware Idoc Script Reference Guide.

3.5.9.2 Editing an Environment Resource

Use the following procedure to edit an existing environment resource using the Component Wizard.

1. In the Component Wizard, open the component that contains the resource to edit.

2. Select the resource file in the Custom Resource Definition list.

3. Click Launch Editor.

4. Modify the configuration variables in the text editor.

5. Save and close the resource file.

   Changes are reflected in the Custom Environment Parameters list.

   Note:

   The configuration settings might not appear in the Custom Environment Parameters list in the order they actually appear in the resource file. For easier viewing, launch the text editor.

3.6 Installing Components

Server components for Oracle Content Server are installed by default, however, custom components and components downloaded from Oracle Technology Network must be installed and enabled before they can be used.

Note:

If you need only to enable or disable an installed component, see Section 3.1.5, "Enabling and Disabling Components."

You can install components using one the methods that the following subsections describe:

• Section 3.6.1, "Installing a Component with Component Manager"

• Section 3.6.2, "Installing a Component with Component Wizard"

• Section 3.6.3, "Installing a Component with ComponentTool"

Before installing a component, you must first download it to your instance. A component cannot be downloaded unless it meets the following requirements:

• The component must exist outside of the IdcHomeDir/system directory (that is, DomainHome/ucm/idc/system). This excludes all packaged components unless a patch has been uploaded to a component.

• The component must have a ZIP file with the appropriate name and be located inside the custom component or core component directory.

3.6.1 Installing a Component with Component Manager

Follow these steps to install the component using the Component Manager:

1. Select Admin Server from the Administration tray.

   The Admin Server page is displayed with the Advanced Component Manager screen.

2. Click the Browse button, and find the ZIP file that was downloaded and saved.

3. Highlight the component name, and click Open.

4. Click Install. A message is displayed, detailing what will be installed.

5. Click Continue to continue with installation or Cancel to stop installation.

6. If you click Continue, a message appears after successful installation. You can select one of two options:

   • To enable the component and restart Oracle Content Server.

   • To return to the Component Manager, where you can continue adding components. When done, highlight the components you want to enable, and click Enable. When finished enabling components, restart the server.

3.6.2 Installing a Component with Component Wizard

Follow these steps to install the component using the Component Wizard:

1. Start the Component Wizard:

   • (Windows operating system) From the Start menu, choose Programs, then Oracle Content Server, then your server instance, then Utilities, and then Component Wizard.

   • (UNIX operating system) Run the ComponentWizard script in the DomainHome/ucm/cs/bin directory.

   The Component Wizard main screen and the Component List screen are displayed.

2. On the Component List screen, click Install.

   The Install screen is displayed.

1. Click Select.

2. Navigate to the ZIP file that was downloaded and saved, and select it.

3. Click Open.

   The ZIP file contents are added to the Install screen list.

4. Click OK. You are prompted to enable the component.

5. Click Yes. The component is listed as enabled on the Component List screen.

6. Exit the Component Wizard.

7. Restart Oracle Content Server.

Depending on the component being installed, a new menu option appears in the Administration tray or on the Admin Applet page. Some components simply extend existing functionality and do not appear as separate new options. For more information, see the component's documentation.

3.6.3 Installing a Component with ComponentTool

Run the ComponentTool utility and specify the ZIP file for the component to install and enable:

DomainHome/ucm/cs/bin/ComponentTool path_to_file/component.zip