4 Using Idoc Script Variables and Functions with Oracle WebCenter Content

This chapter describes the different types of Idoc Script variables and functions and how you can use them with Oracle WebCenter Content. You can use the Idoc Script Custom Scripting Language to customize Oracle WebCenter Content Server. Idoc Script enables you to reference variables, conditionally include content in HTML pages, and loop over results returned from queries. Because Idoc Script is evaluated on the server side rather than the client side, page elements are processed after the browser has made a request, but before the requested page is returned to the client.

This chapter includes the following sections:

4.1 Using Different Types of Idoc Script Variables and Functions

You can use the several different types of Idoc Script variables and functions to customize Content Server:

4.1.1 Conditional Dynamic Variables

Some Idoc Script dynamic variables are conditional and can only be used within a conditional statement such as if, while, elseif, or loop. These variables have the following special features:

  • Conditional variables are internal flags that are gettable but not settable.
  • Conditional variables will only provide a Boolean response and do not return a value such as a string or integer.
  • Conditional variables will not accept the #active keyword prefix. Thus, an error report is printed to the debug output if the variable is not found.

Idoc Script Functions and Variables, describes these conditional dynamic variables:

4.1.2 Dynamic Variables

A dynamic variable is evaluated on each occurrence of the variable. Each time the variable is encountered, the value is recalculated from code. (In contrast, a value variable is evaluated once at the beginning of the service call, and that value is used throughout the service call. See Value Variables.) Dynamic variables generally return a value, such as a string or an integer.

Idoc Script Functions and Variables, describes this dynamic variable:

4.1.3 Environment Variables

Web server variables are the CGI environment variables that are set when the server executes the gateway program. To pass data about the information request from the server to the script, the server uses command-line arguments and environment variables. These environment variables can be used to output information to a log file or can be used within Idoc Script statements and as part of evaluations.

For example, this Idoc Script statement evaluates whether the remote host address matches a specific string:

<$if strEquals("207.0.0.1",REMOTE_HOST)$>

This HTML and Idoc Script markup displays a list of web server environment information on the page:

<P>HTTP_INTERNETUSER=<$HTTP_INTERNETUSER$></P>
<P>REMOTE_HOST=<$REMOTE_HOST$></P>
<P>SCRIPT_NAME=<$SCRIPT_NAME$></P>

Idoc Script Functions and Variables, describes these web server variables:

4.1.4 Global Functions

Idoc Script has many built-in global functions. Functions perform actions, including string comparison and manipulation routines, date formatting, and ResultSet manipulation. Some functions also return results, such as the results of calculations or comparisons.

Information is passed to functions by enclosing the information in parentheses after the name of the function. Pieces of information that are passed to a function are called parameters. Some functions do not take parameters; some functions take one parameter; some take several. There are also functions for which the number of parameters depends on how the function is being used.

In addition to the built-in global functions, you can define new global functions, including custom classes, with Java code. For more information, see Getting Started with Content Server Components, and Creating Custom Components.

Idoc Script Functions and Variables, describes these Idoc Script built-in global functions:

4.1.5 Page Variables

Page variables are set on a particular web page to enable specific page attributes or functionality. A page variable applies only to the page on which it is set.

This section includes the following topics:

4.1.5.1 Page Display Variables

Page variables that affect page display are typically set near the top of the page. Page display variables should be used as read-only variables; setting or changing the value of any of these variables will typically change the way all metadata is displayed on the page, which in most cases is not the desired effect.

Where a listed variable name references another document, it means the variable can be set in Idoc Script or in the URL for a web page.

Idoc Script Functions and Variables, describes these page display variables:

4.1.5.2 Field Display Variables

Field display variables can be grouped into the following types:

4.1.5.2.1 Field Information Variables

The following variables define information about a metadata field. The variable values are loaded or computed for each metadata field.

Idoc Script Functions and Variables, describes these field information variables:

Example

The std_prepare_metafield_include include in the resource file IdcHomeDir/resources/core/std_page.htm loads a number of field information variables from the local data in preparation for displaying the current metadata field.

<@dynamichtml std_prepare_metafield_include@>
<!--Prepare for presenting field-->
<$fieldName=dName, fieldCaption=dCaption, fieldDefault=dDefaultValue$>
<$fieldType=dType, fieldIsOptionList=dIsOptionList, fieldOptionListType=dOptionListType$>
<@end@>
4.1.5.2.2 Common Field Display Variables

There are several commonly used page variables that affect the display of metadata fields. These variables can be set using different syntaxes at different places on a page, depending on how they are being used.

Note:

The Profiles and Rules engine in the Configuration Manager applet duplicates this functionality with less code.

The following formats can be used to set a special field display variable:

  • Name/Value pair: The variable is set using the standard variable=value format. For example, isHidden=1. This format is typically used to set the display of the current metadata field at the point in the page where the field is being generated by looped code.
  • FieldName:Variable format: The variable is set by defining it as a parameter for the metadata field it applies to. For example, myMetadata:isHidden. This format is typically used at the top of a page to set the global display of a particular metadata field.

If a common field display variable is set at the top of a template page, it should be placed before the <HEAD> tag. Placing the variable in or after the <HEAD></HEAD> section will result in the field being displayed (or not displayed) as you intended, but the JavaScript validation code in the header will still be evaluated, so an … is not an object error will be thrown when you attempt to display a checkin page.

Idoc Script Functions and Variables

Alternative Methods to Display Metadata Fields

If these common field display variables are not sufficient to provide the required flexibility, the entire implementation of a metadata field can be replaced by setting the field variable to the name of a resource include that should be used instead (for example, myField:include=customInclude).

The standard implementation is referred to by the variable defaultFieldInclude, whose value is different depending on whether the field is being generated on a checkin/update, query, or info page. It also varies considerably based on the type of field being displayed. If the standard field include is overridden, then the new implementation must take into consideration all the issues of the different pages, including JavaScript validation and the Upload applet.

Use this approach only as a last resort. It is preferable to extend existing functionality and set local variables to have custom functionality.

If you use the include tag in this way to insert custom HTML code for a special metadata field, you must place the include statement after the </HEAD> tag on the page. If you place it before the </HEAD> tag, the system will insert your custom HTML code into the header and attempt to read it as JavaScript.

4.1.5.2.3 Other Field Display Variables

A number of other variables are available to affect the display of metadata fields. Generally, these are used to define the display of a metadata field depending on which field is currently being generated and the value of related common field display variables.

Idoc Script Functions and Variables, describes these other field display variables:

Example

This example shows how the compute_std_field_overrides include in the IdcHomeDir/resources/core/templates/std_page.htm resource file determines if the field currently being generated is hidden, information only, excluded, and/or relocated. This code is looped over during generation of each metadata field on a page.

<@dynamichtml compute_std_field_overrides@>
<$isCustomHidden = getValue("#active", fieldName & ":isHidden")$>
<$if isHidden or isCustomHidden$>
    <$isFieldHidden = 1$>
<$else$>
    <$isFieldHidden = ""$>
<$endif$>
<$isCustomInfo = getValue("#active", fieldName & ":isInfoOnly")$>
<$if isInfo or isCustomInfo or isFieldHidden or isInfoOnly$>
    <$isFieldInfoOnly = 1$>
<$else$>
    <$isFieldInfoOnly = ""$>
<$endif$>
<$isCustomExcluded = getValue("#active", fieldName & ":isExcluded")$>
<$isCustomRelocated = getValue("#active", fieldName & ":isRelocated")$>
<$if isCustomExcluded or (isCustomRelocated and not isRelocated) or isExcluded or (isFieldHidden and not isFormSubmit)$>
    <$isFieldExcluded = 1$>
<$endif$>
<@end@>

4.1.6 Read-Only Variables

Read-only variables can be used to gather information about the current template, the user who is currently logged in, or other current settings. These variables are read-only and cannot be assigned a value.

4.1.6.1 Template Read-Only Variables

Template-related read-only variables make it possible to create conditional content in a template based on the identity of the template. These predefined variables allow you to display the class, file path, name, or type of any template on a Content Server web page. This is particularly useful while you are developing your website.

Idoc Script Functions and Variables, describes these read-only variables that are related to templates:

Example

In this example, the internal name of the template appears under the Administration link in the left sidebar of all Content Server web pages. To accomplish this change, the predefined TemplateName variable was added to the pne_nav_admin_links include that defines the Administration links.

The following is an example of using the TemplateName predefined variable to display the internal template name on a web page.

<$if IsSubAdmin$>
<tr>
    <td>
        <a href="<$HttpCgiPath$>?IdcService=GET_ADMIN_PAGE&Action=
           GetTemplatePage&Page=ADMIN_LINKS"
        OnMouseOver="imgAct('admin')"
        OnMouseOut="imgInact('admin')">
        <img src="<$HttpImagesRoot$>
           <$button_admin_grey_ish_image$>" width="<$navImageWidth$>"         height="<$navImageHeight$>" name="admin" border="0"         alt="<$lc("wwProductAdministration", ProductID)$>"></a>
    </td>
        <td>
        <a class=pneHeader href="<$HttpCgiPath$>?IdcService=GET_ADMIN_
              PAGE&Action=GetTemplatePage&Page=ADMIN_LINKS"
        OnMouseOver="imgAct('admin')"
        OnMouseOut="imgInact('admin')">
        <$lc("wwAdministration")$></a>
    </td>
</tr>
<tr>
    <td colspan=2><font color=#FFFFFF style="Arial"
        size="-1"><$TemplateName$></font></td>
</tr>
<$endif$>
4.1.6.2 User Read-Only Variables

User-related read-only variables make it possible to gather information about the current user.

Idoc Script Functions and Variables, describes these read-only variables that are related to users:

4.1.6.3 Content Read-Only Variable

One content-related read-only variable, SourceID, described in Idoc Script Functions and Variables, makes it possible to retrieve the content ID of the current dynamic server page.

This variable returns the same value as ref:dID.

4.1.6.4 Other Read-Only Variable

The SafeDir read-only variable, described in Idoc Script Functions and Variables, is set only as an internal flag. It can be retrieved but not set directly.

4.1.7 Settable Variables

Settable variables can be set within script or used within a CGI string. For example, the variable IsPageDebug can be used as a parameter for a service call to display debug trace information on a page. Setting one of these variables can change the content of the page.

Idoc Script Functions and Variables, describes these settable variables:

4.1.8 Workflows

Idoc Script includes predefined functions and variables that are used specifically for workflows.

For a detailed description of how workflows are implemented in Content Server, see Managing Workflows in Oracle Fusion Middleware Managing Oracle WebCenter Content.

The following points summarize the use of Idoc Script in workflows:

  • Workflow jumps are initiated through the evaluation of Idoc Script that is defined for a particular step event (entry, update, or exit).

  • As a revision moves from step to step, the system creates a companion file that maintains information about the state of the revision in the workflow. You can use the wfGet() and wfSet() functions to code data into the companion file, as needed. Along with user-defined options, the system also maintains the history of what steps the revision has been to, the last entry time, and the number of times a revision has entered a particular workflow step.

    • Global state information is maintained as the revision moves from step to step.

    • Localized state information is stored with the step and becomes available when a revision is at that step.

  • The companion file uses keys to keep track of workflow state information. The syntax for a key is:

    step_name@workflow_name.variable=value
    

    For example, the following keys define the value of the entry count and last entry variables for the Editor step of a workflow called Marketing:

    Editor@Marketing.entryCount=1
    Editor@Marketing.lastEntryTs={ts '2002-05-28 16:57:00'}
    
  • All workflow script evaluation occurs inside a database transaction. The result is that any serious errors or aborts that are encountered cause no change to either the database or the companion file. This also means that no Idoc Script workflow function should take more than a negligible amount of time. Consequently, to trigger an external process, an Idoc Script function should be written to execute in a separate thread.

    Caution:

    If you are using Idoc Script or custom components to load workflow information into the local data, keep in mind that there is a risk of data pollution. This is particularly important if you are loading information for a different revision than the current one.

4.1.9 Value Variables

A value variable is evaluated once at the beginning of a service call and that value is used throughout the service call. The variable is then reevaluated on each new service call. In contrast, a dynamic variable is evaluated on each occurrence of the variable. For example, the value variable isNew evaluates whether the content item is new or a revision when performing a check in. That evaluation is used throughout the call to the checkin service.

Idoc Script Functions and Variables, describes these value variables:

4.2 Using Idoc Script Variables and Functions with Different Features of Oracle WebCenter Content

You can use Idoc Script variables and functions with different features of Oracle WebCenter Content. Idoc Script Functions and Variables, describes the Idoc Script variables and functions.

For information about system configuration variables that you can use in the WebCenter Content config.cfg file, intradoc.cfg file, and other .cfg files, see Configuration Variables in Oracle Fusion Middleware Configuration Reference for Oracle WebCenter Content.

You can use Idoc Script variables and functions with these Oracle WebCenter Content features:

4.2.1 Batch Loader

The following Idoc Script variable, described in Idoc Script Functions and Variables, is related to the Batch Loader utility:

For information about other Idoc Script configuration variables that are related to the Batch Loader utility, see Batch Loader in the Oracle Fusion Middleware Configuration Reference for Oracle WebCenter Content.

4.2.4 Content Profiles

The following Idoc Script functions are used to manage content profiles:

4.2.6 Conversion

You can use some Idoc Script variables with these conversion products:

4.2.6.1 Inbound Refinery

The following Idoc Script variable is related to the Oracle WebCenter Content: Inbound Refinery system:

4.2.6.2 Dynamic Converter

The following Idoc Script variables and function are related to the Dynamic Converter:

4.2.7 Database

The following Idoc Script function is related to databases:

4.2.9 Debugging

The following Idoc Script variables and functions are related to debugging:

For information about other Idoc Script configuration variables that are related to debugging, see Debugging in the Oracle Fusion Middleware Configuration Reference for Oracle WebCenter Content.

4.2.13 Idoc Script

The following Idoc Script functions are not related to any specific functionality:

4.2.13.1 Keywords

The following Idoc Script variables are related to keywords:

4.2.14 Indexing

The following Idoc Script variables and function are related to indexing:

4.2.15 Localization

The following Idoc Script variables and functions are related to localization:

4.2.17 Personalization

The following Idoc Script functions are related to user topic (personalization) files:

4.2.19 Schemas

The following Idoc Script functions are related to schemas.

A schema is republished whenever a change occurs that might affect the relationship between the parts of the schema. These settings relate to publishing factors:

4.2.23 Templates

The following Idoc Script variables are related to templates:

4.2.26 Workflow

The following sections list Idoc Script variables and functions that are related to workflows:

4.2.26.1 Global Function

The following Idoc Script global function is related to workflows: