This chapter describes how to create custom components to use with Oracle WebCenter Content Server.
This chapter includes the following sections:
Custom components can alter defaults for your system, add new functionality, or streamline repetitive functions. You can create and use custom components to modify a Content Server instance without compromising the system integrity.
You can use the following types of resources to customize Content Server:
HTML includes
Dynamic data tables
String resources
Dynamic tables
Static tables
Queries
Services
Templates
Environment resources
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.
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 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.
Caution:
The placement of a super
tag will determine how the Idoc Script is evaluated.
Example 18-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@>
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 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 in any resource file that can contain dynamichtml
constructions.
Example 18-2 dynamicdata Resource
<@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.
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.
commatable Format <@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 pound sign-circumflex (#^
, and if you need to insert a pound sign (#
) that is followed by a pound sign or a circumflex, then enter the escape sequence pound sign-pound sign (##
).
Special Characters in Values <@dynamicdata SampleTable@> field1, field2 Â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 Content Server.
Example 18-3 htmltable Format
<@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@>
Use the following procedure to edit an existing dynamicdata
resource using the Component Wizard.
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. The following example shows a typical table declaration.
Table Properties in a Table Definition <@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
. shows a declaration specifying a table that is not to trim its values.
notrim Property <@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
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 the new value (using comma as the separator) to the current value. Each of the subvalues in the comma-separated list is assumed to be of the form key=value
with the =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 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 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 is fully merged before it is merged into this resource. (If those other resources also are using mergeOtherData
, then those merges are done first. The code has recursion detection.) If 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.
You can specify one or more of the following assembly properties in the properties-of-table
parameter in a dynamicdata
resource:
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.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 an asterisk (*), and an asterisk can be escaped by preceding it with a pound sign (#). If either a pound sign or an asterisk follows a pound sign, then the pound sign can be escaped by adding another pound sign (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.derivedColumnDef1,derivedColumnDef2,...
with each column definition being of the form fieldName:sourceField1+sourceField2+...
. The fieldName
value refers to the name of the field to be created, and the sourceFieldN
values refer to fields whose values 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.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
value from one specified in a prior table resource, then the value from the overlaying table resource 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 sortColumn
and sortParentColumn
. The value 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 available only 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.
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 ResultSet, 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 ResultSet 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 ResultSet, 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).
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
A string
resource defines locale-sensitive text strings that are used in error messages and on Content Server web pages and applets. Strings are resolved by 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 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 |
---|---|
|
|
|
line feed (ASCII 10) |
|
carriage return (ASCII 13) |
|
tab (ASCII 9) |
|
Eats white space until the next nonwhite space character. |
|
|
|
|
|
space (ASCII 32) |
|
ASCII character that a decimal number represents ( |
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. The following example shows prefixes for strings in several languages in a resource file.
Multiple Languages in the Same Resource File <@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 Content Server reads them correctly.
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 " |
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. |
" |
{n?text} |
If the value of the nth argument is not 1, substitute the text. |
{1} file{1?s} deleted |
{n?text1: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} |
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. |
Dynamic table resources are defined in the HDA file format. For more information and an example of an HDA ResultSet table, see Elements in HDA Files.
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.
Static tables, HTML includes, and strings can be present in the same HTM file.
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.
Use this procedure to edit an existing static table resource with the Component Wizard:
A query resource defines SQL queries, which are used to manage information in the 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 Content Server queries are defined in the QueryTable
table in the IdcHomeDir
/resources/core/tables/query.htm
file. You can 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 |
---|---|
|
Delete |
|
Insert |
|
Select |
|
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.
The standard QdocInfo
query, which Figure 18-1 shows, is defined in the IntradocDir
/core/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.
Example 18-4 shows the contents of a query.htm
file.
Example 18-4 query.htm File
<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>
A service resource defines a function or procedure that is performed by 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 a 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 Content Server or perform a specified function.
The standard 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. For more information about standard and special-purpose services that Content Server provides, see List of Oracle WebCenter Content Services in Oracle Fusion Middleware Services Reference for Oracle WebCenter Content.
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.
Figure 18-2 shows an example of a service definition.
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:
|
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 |
DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
|
Service type |
If the service is to be executed inside another service, this attribute is |
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 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) |
---|---|---|
|
Defines the type of action:
|
5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExists
|
|
Specifies the name of the action. |
5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist
|
|
Specifies parameters required by the action. If no parameters are required, leave this part empty (two colons in a row). |
5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist
|
|
Controls the results of queries to the database. This number is the sum of the following possible bit flags: No control mask =
|
5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist
|
|
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 Localized String Resolution. |
5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist
|
The DOC_INFO
service provides a good example of how services, queries, and templates work together. Figure 18-3 shows the actions that the DOC_INFO
service can take.
Example 18-5 shows the definition of the DOC_INFO
service in the IntradocDir
/config/resources/std_services.htm
file.
Example 18-5 DOC_INFO Service Definition in std_services.htm File
<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>DocSgervice 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>
The following table describes the attributes of the preceding DOC_INFO
service.
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.
|
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 Content Server system, it returns this error message string: Unable to retrieve information about the revision |
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 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 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 email 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 email 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:
|
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 Content Server system, it returns the error message string:
|
A template resource defines the names, types, and locations of custom template files to be loaded for the component.
The actual template pages are separate.htm
files that are referenced in the template resource file. Template HTM files contain the code that 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 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/template
s 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 Elements in HDA Files.
Merge rules are required for merging the new template definition into the IntradocTemplates table or SearchResultTemplates table. Typically, the merge is on the name column. The following example shows a MergeRules ResultSet for a template.
MergeRules ResultSet @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 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 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 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 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
value for 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
value for 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
).
Example 18-6 Custom Template Resource File
<?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
Template pages and report pages are also called presentation pages, because 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.
The template file for the standard Content Management page is doc_man.htm
. The following example shows the contents of this file.
The doc_man.htm File <$include std_doctype_html_decl$> <head> <$defaultPageTitle=lc("wwContentMgmt")$> <$include std_html_head_declarations$> </head> <$include body_def$> <$include std_page_begin$> <$include std_header$> <table border="0" cellpadding="2" cellspacing="2" width="450" summary=""> <$include std_doc_man_pages$> </table> <table cellpadding="7" cellspacing="7" summary=""> <$if showQuickHelp$> <tr><td><form><INPUT type=Button onClick="QuickHelp('<$getHelpPage("QH_DocMan")$>', 'QH_DocMan')" value="<$lc("wwQuickHelp")$>"></form></td></tr> <$endif$> </table> <$include std_page_end$> </body> </html>
In the example, the std_doctype_html_decl
include references the standard Content Server document type. The <head>
element references the page title, and the code for the head
section is built using the std_html_head_declarations
include code from the std_page.htm
resource file. Other elements of the page definition follow:
Page elements common to most Content Server web pages are built using the body_def
, std_page_begin
, and std_header
include code from the std_page.htm
resource file.
The links on the Content Management page are built using include code from the std_page.htm
resource file.
The <table>
element in the example defines whether a Quick Help button should appear on the Content Management page.
The code at the end of the page is built using the std_page_end
include code from the std_page.htm
resource file.
Figure 18-4 shows a Content Management page.
The template file for the standard Document Types report page is in the doc_types.htm
file. The following example shows the contents of this file.
The doc_types.htm File <$include std_doctype_html_decl$> <head> <$defaultPageTitle=lc("wwDocumentTypes")$> <$include std_html_head_declarations$> </head> <$include body_def$> <$include std_page_begin$> <$include std_header$> <!--Directory Title---> <table border="0" cellpadding="0" cellspacing="0" summary=""> <tr> <td width="75"><$if PageParent$><a href="<$PageParent$>"> <$strTrimWs(inc("open_folder_image"))$></a> <$endif$></td> <td colspan="2" width="390"><span class=title><$PageTitle$></span></td> </tr> </table> <$if IsSavedQuery$> <!---Parameters for historical reports--> <table border="0" cellpadding="0" cellspacing="0" summary=""> <tr> <td width="75" height="45"> </td><!---Indent--> <td><strong><span class=highlightField><$lc("wwReportCreated")$></span> <$ReportCreationDate$></strong></td> </tr> </table> <$endif$> <!--Directory Header---> <table border="0" cellspacing="0" summary=""> <tr> <td width="75" height="45"> </td><!---Indent--> <td colspan="2" width="390"><$HeaderText$></td> </tr> </table> <!---Doc types report--> <table border=0 cellpadding=0 cellspacing=0 summary=""> <tr><td> </td></tr> <tr> <td align=center width=<$StdPageWidth$>> <h1 class="underlinePageTitle"><$lc("wwDocumentTypes")$></h1> </td> </tr> <tr><td> </td></tr> <$if IsMultiPage$> <!---Navigation Bar--> <tr> <td width=565 align="center"><$include std_page_nav_bar$></td> </tr> <$endif$> <tr> <td> <table class="xuiTable" width=<$StdPageWidth$> summary="<$stripXml(lc("wwReportResultsTable"))$>"> <tr class="xuiAltHeader"> <td width=12% class="xuiAltHeader" scope="col"></td> <td width=29% class="xuiAltHeader" scope="col"><$lc("wwDocumentType")$></td> <td width=49% class="xuiAltHeader" scope="col"><$lc("wwDescription")$></td> <td width=12% class="xuiAltHeader" scope="col"><$lc("wwImageFileName")$></td> </tr> <$rowCount=0$> <$loop DocTypes$> <$if rowCount%2 == 0$> <$rowClass="xuiRow"$> <$else$> <$rowClass="xuiAltRow"$> <$endif$> <tr class="<$rowClass$>"> <!--Document types are localized to each instance, so we must use direct path to images directory.--> <td><img src="<$HttpWebRoot$>images/docgifs/<$dGif$>" alt="<$stripXml(lc("wwDoctypeIcon"))$>" border=0></td> <td><$dDocType$></td> <td><$dDescription$></td> <td><$dGif$></td> </tr> <$rowCount=rowCount+1$> <$endloop$> </table> </td> </tr> </table> <$include std_page_end$> </body> </html>
In the example, the std_doctype_html_decl
include references the standard Content Server document type. The <head>
element in the example references the page title and metadata, and the code for the head section is built using the std_html_head_declarations
include code from the std_page.htm
resource file. Other elements of the page definition follow:
Page elements common to most Content Server web pages are built using the body_def
, std_page_begin
, and std_header
include code from the std_page.htm
resource file.
The Directory Title
section in the example displays the open folder image, links it to the parent page, and displays the page title.
The Parameters for historical reports
section displays the original query date for a historical report.
The Directory Header
section displays the report description.
The Doc types report
section displays the table title.
The Navigation Bar
section displays the page navigation bar if a historical report requires more than one page.
In the next <table>
element, the first part displays the table column headers.
The last part of the <table>
element loops on the document types to create the rows of the report table.
The code at the end of the page is built using the std_page_end
include code from the std_page.htm
resource file.
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.
The following example shows the contents of an environment resource file.
Environment Resource File # 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 Configuration Variables in Oracle Fusion Middleware Configuration Reference for Oracle WebCenter Content.
Use the following procedure to edit an existing environment resource using the Component Wizard.
In the Component Wizard, open the component that contains the resource to edit.
Choose the resource file from the Custom Resource Definition list.
Click Launch Editor.
Modify the configuration variables in the text editor.
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.
You can use the Component Wizard to create a component definition file or make changes to it.
The following example shows a component definition file that points to an environment resource file called customhelp_environment.cfg
.
Example 18-7 Component Definition File for an Environment Resource
<?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
Before you can apply a custom component to Content Server, you need to restart it. You can restart Content Server by restarting the WebCenter Content Managed Server with the Administration Console, shutdown and startup scripts, or Fusion Middleware Control.
The following example shows how to restart WebCenter Content with the stopManagedWebLogic
and startManagedWebLogic
scripts.
For more information, see Managing System Processes in Oracle Fusion Middleware Administering Oracle WebCenter Content.
To restart the WebCenter Content Managed Server with scripts on the command line: