Oracle® Fusion Middleware Developer's Guide for Content Server 11g Release 1 (11.1.1) Part Number E10807-01 |
|
|
View PDF |
This section provides information about the files used in component creation and the directory structure used to store those files. It includes the following topics:
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 the 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 the 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 version="" jcharset=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
Each HDA file contains a header line and one or more sections. The header line identifies the 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 the 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.
The Properties Section and ResultSet Section are the two section types that are relevant to component development. These 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. ResultSets often represent 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 type is rarely used. The recommended practice is to define global environment variables in a configuration file in an Environment resource.
The following is an example of a Properties section in an HDA file.
@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 results 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 |
The Content Server uses some predefined ResultSets, so the following names should not be used for custom component tables:
The idc_components.hda file is a text file that tells the 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 to the new format.The following is an example of an idccs_components.hda file, listing 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
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
Custom resource files define your 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 |
These files are all discussed in detail in "Resources Detail".
In addition, a template.htm page is used by the Content Server to assemble web pages. See "Templates" for details about the template.hdm file.
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.
The Content Server caches data (such as variable values and lookup keys) internally in a DataBinder. All data in the DataBinder 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 DataBinder is evaluated in the following default order:
This precedence can be changed using Idoc Script functions. See the Oracle Fusion Middleware Idoc Script Reference Guide for details.
The @Properties LocalData
section in an HDA file maps to the LocalData of the DataBinder. The LocalData consists of name/value pairs.
The LocalData information is maintained only during the lifetime of the 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 is collected from the REQUEST_METHOD, CONTENT_LENGTH, and QUERY_STRING HTTP environment variables. As the service request is processed, the LocalData values can be added and changed.
Each @ResultSet
section of an HDA file maps to a named result in the DataBinder. A ResultSet becomes active when the ResultSet is looped on during page assembly. The 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 non-active ResultSet values are searched next.
Manifest files are used to upload or unpackage a component zip file on the Content Server. This file tells the 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 | Java Server Pages | DomainHome/ucm/short-product-id/weblayout/jsp |
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 the Content Server which resource files are included in the component.
For other entry types, the location can be a path (to specify all files in a particular subdirectory) or a path and 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 only be installed on Content Servers with the same installation directory path.
The following is an example of a manifest.hda file.
@ResultSet Manifest 2 entryType location component MyComponent/MyComponent.hda componentExtra MyComponent/readme.txt images MyComponent/ @end
Your custom components can include any type of file that the Content Server uses for functionality or to generate look-and-feel.
You can add customized files for your site to change the look or actions of the 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 Content Server interface.
Help: With the assistance of Consulting Services, help files can be customized for your content management system.
Classes: Java code can change or extend the functionality of the Content Server. Java class files must be packaged into directories before placing them in the DomainHome/ucm/short-product-id/classes/ directory.
A component zip file contains all files that define a Content Server component. It can be unpackaged to deploy the component on other Content Servers.
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 component directory within the data/components directory. These files hold the preference data as follows:
config.cfg: Contains the parameters that can be reconfigured after installation.
install.cfg: 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.
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, /Resources). The component_name.hda file (the definition file) is stored in the /component_name directory.