3 Introduction to the Idoc Script Custom Scripting Language

This chapter describes the Idoc Script Custom Scripting Language, which you can use to customize Oracle WebCenter Content Server. Idoc Script is the server-side custom scripting language for the Content Server system. Idoc Script is used primarily for the presentation of HTML templates and configuration settings.

This chapter includes the following sections:

• Idoc Naming Conventions

• Idoc Script Syntax

• Idoc Script Uses

• Special Keywords

• Operators

• Metadata Fields

• Merge Includes for Formatting Results

• Scoped Local Variables

3.1 Idoc Naming Conventions

Idoc variables (sometimes called configuration variables or environment variables) can be used in Idoc Script and in configuration files.

In general, if the variable is part of a configuration, it begins with a capital letter. Those variables specified in the config.cfg file or intradoc.cfg file usually have an initial capital letter. For an example, see DefaultFilterInputFormat in the Oracle Fusion Middleware Configuration Reference for Oracle WebCenter Content. Many parameters in service requests also begin with uppercase letters.

Variables defined on a page, such as those that are derived and then used in files such as std_page.htm, begin with a lowercase letter. For an example, see executeService Function in Idoc Script Functions. The variables are calculated from environment variables or service variables, then used for presentation.

If a variable is used to define an object, it begins with lowercase letters designating the type of object it is defining. For an example of a workflow-specific variable, see wfSet() in Idoc Script Functions and Variables. In addition, all functions start with a lowercase letter and many start with a prefix to describe the type of function. For example, most string manipulation functions begin with str, or ResultSet functions begin with rs.

All database column names that are not custom metadata fields begin with the lowercase letter d. All custom metadata database column names created by the Content Server system begin with the lowercase letter x.

3.2 Idoc Script Syntax

Idoc Script follows these basic syntax rules:

• Idoc Script Tags

• Idoc Script Comments

3.2.1 Idoc Script Tags

Idoc Script commands begin with <$ and end with $> delimiters. For example:

<$dDocTitle$>
<$if UseGuiWinLook and isTrue(UseGuiWinLook)$>

If you are using Idoc Script in an HCSP or HCSF page, you must use the syntax <!‐‐$script‐‐> for Idoc Script tags.

3.2.2 Idoc Script Comments

You can use standard HTML comments or Idoc Script comments in Idoc Script code. An Idoc Script comment begins with [[% and closes with %]] delimiters. For example:

<!-- HTML Comment -->
[[%My Comment%]]

An HTML comment is parsed as plain text to the Idoc Script engine. The engine only looks for Idoc Script constructs. If you want the comment to appear in the generated page, use the HTML/XML comment syntax; otherwise, Idoc Script comment syntax is recommended.

If you are writing Idoc Script that generates other Idoc Script and you want the source page to look readable, you can use the comment syntax to comment out dynamichtml constructs and other resource specifiers, such as string resources, in Idoc Script resource files. For example:

[[% Commenting out resource includes
<@dynamichtml myinclude@>
<@end@>
End comment %]]

3.3 Idoc Script Uses

There are six basic uses for Idoc Script:

• Includes enable you to reuse pieces of Idoc Script and HTML code.

• Variables enable you to define and substitute variable values.

• Functions enable you to perform actions, including string comparison and manipulation routines, date formatting, and ResultSet manipulation.

• Conditionals enable you to evaluate if and else clauses to include or exclude code from an assembled page.

• Looping enables you to repeat code for each row in a ResultSet that is returned from a query.

• The Administration Interface enables you to use Idoc Script in Content Server applets and customizations.

3.3.1 Includes

An include defines pieces of code that are used to build the Content Server web pages. Includes are defined once in a resource file and then referenced by as many template files as necessary. The system leverages includes very heavily.

Includes make it easier for you to customize your instance using component architecture and dynamic server pages. For more information on includes and customization, see Creating an IDOC File with Custom Includes for Dynamic Server Pages.

• An include is defined in an HTM resource file using the following format:

  <@dynamichtml name@>
      code
  <@end@>
  

• An include is called from an HTM template file using the following Idoc Script format:

  <$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 file.

• Standard includes are defined in the wcc_home_dir/shared/config/resources/std_page.htm file IdcHomeDir/resources/core/idoc/std_page.idoc file.

• HDA and CFG files are not script enabled, therefore using an include statement in either of these types of files is not supported.

The includes are global, available to all parts of the system. Dynamic scripting pages in HCSP files can use includes. The .idoc files can do localized includes that are not global. HCSP files can call both global includes or localized includes with the proper syntax.An include can override an existing include, if one of the same name exists.

For more information, see the following sections:

• Include Example

• Super Tag

• Super Tag Example

3.3.1.1 Include Example

One of the most common includes is the body definition element <@dynamichtml body_def>. This include sets the page background color, the color of hyperlinks, and the background image. The following example shows code located in the wcc_home_dir/shared/config/resources/std_page.htmIdcHomeDir/resources/core/idoc/std_page.idoc file:

<@dynamichtml body_def@>
<!--Background image defined as part of body tag--->
<body
    <$if background_image$>
        background="<$HttpImagesRoot$><$background_image$>"
    <$elseif colorBackground$>
        bgcolor="<$colorBackground$>"
    <$endif$>
    <$if xpedioLook$>
        link="#663399" vlink="#CC9900"
    <$else$>
        link="#000000" vlink="#CE9A63" alink="#9C3000"
    <$endif$>
    marginwidth="0" marginheight="0" topmargin="0" leftmargin="0"
>
<@end@>

Most of the standard template resource files (for example, IdcHomeDir/resources/core/templates/pne_home_page.htm), contain the following Idoc Script code near the top of the page:

(for example, wcc_home_dir/shared/config/templates/pne_home_page.htm)

<$include body_def$>

When the Content Server system resolves a template page containing this code, it looks for the <@dynamichtml body_def@> definition and replaces the placeholder code with the code in the definition.

3.3.1.2 Super Tag

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

• 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.

• The resource name defined after super should match the include name in which you include super. In the preceding syntax example, my_resource is the include name, so the matching call should be super.my_resource.

• You can specify multiple super tags to call an include that was loaded earlier than the last version. For example, to make an exception to the standard body_def include in two different components, you can use the following syntax in the one that is loaded last:

  <$include super.super.body_def$>

  Caution:

  If you use multiple super tags in one include, ensure that you know where the resources are loaded from and the order they are loaded in.

• The super tag is particularly useful when making small customizations 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 software, the super tag ensures that your components are using the most recent version of the include, modifying only the specific code you require to customize your instance.

3.3.1.3 Super Tag Example

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.3.2 Variables

A variable enables you to define and substitute variable values.

The following sections describe how to work with Idoc Script variables:

• Variable Creation

• Variable References

• Variable Values

• Comma Separators

• Variable Reference in a Conditional

• Variable Reference Search Order

• Regular Variables

3.3.2.1 Variable Creation

Idoc Script variables are created in one of the following ways:

• Many variables are predefined.

• You can define your own custom variables.

• Some variable values must be generated using queries and services. Some variable information is not automatically available from the database, so it must be asked for by defining a query and service.

For more information on the types of Idoc Script variables, see Using Idoc Script Variables and Functions with Oracle WebCenter Content.

3.3.2.2 Variable References

You can reference a variable in templates and other resource files with the following Idoc Script tag:

<$variable_name$>

When you reference a variable name like this, the generated page will replace the Idoc Script tag with the value of that variable, at the time it was referenced.

3.3.2.3 Variable Values

• A value can be assigned to a variable using this structure:

  <$variable=value$>
  

  For example, <$i=0$> assigns the value of 0 to the variable i.

• Variable values can also be defined in an environment resource (CFG) file using the following name/value pair format:

  variable=value
  

  For example, standard configuration variables are defined in the IntradocDir/config/config.cfg file.

  Note:

  Not all configuration variable values set by code are listed in the IntradocDir/config/config.cfg file by default.

3.3.2.4 Comma Separators

Idoc Script supports multiple clauses separated by commas in one script block in variable references.

For example, you can use <$a=1,b=2$> rather than two separate statements: <$a=1$> and <$b=2$>.

3.3.2.5 Variable Reference in a Conditional

The following structure can be used to evaluate the existence of a variable:

<$if variable_name$>

If the variable is defined and not empty, this conditional is evaluated as TRUE. If the variable is not defined or it is defined as an empty (null) string, it is evaluated as FALSE.

For an example of how this type of reference is typically used, see Conditional Example.

3.3.2.6 Variable Reference Search Order

When a variable is referenced to fulfill a service request, the substituted value will be the first match found in the DataBinder from the following default order:

1. LocalData

2. Active ResultSets

3. Nonactive ResultSets

4. Environment

For example, if a particular variable exists in the environment but is also the name of a field in the active ResultSet, the value in the current row of the active ResultSet will be used.

3.3.2.7 Regular Variables

A regular variable that does not have special evaluation logic (such as Conditional Dynamic Variables) is equivalent to using the #active keyword prefix.

For example, the tag <$variable$> is equivalent to <$#active.variable$>. However, if #active is not explicitly stated and the variable is not found, an error report is printed to the debug output.

The #active qualifier means that a variable reference searches the DataBinder, as described in Variable Reference Search Order, whereas #env lets you select only from the environment, and #local always references LocalData. The difference between explicitly using #active versus without the prefix is that an error is reported only when (1) you are not using any qualifier and (2) the variable reference is not found in the DataBinder.

3.3.3 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.

For a list of Idoc Script functions, see Global Functions.

3.3.3.1 Personalization Functions

Personalization functions refer to user properties that are defined in personalization files, also called user topic files. Each user's User Profile settings, personal links in the left navigation bar, and workflow in queue information are all defined in user topic files, which are HDA files located in the WC_CONTENT_ORACLE_HOME/data/users/profiles/us/username/ directories.

The following global functions reference user topic files:

• utGetValue()

• utLoad()

• utLoadResultSet()

For example, the Portal Design link in a user's left navigation bar is generated from the following code in the pne_nav_userprofile_links include (located in the WC_CONTENT_ORACLE_HOME/shared/config/resources/std_page.htm resource file). If the portalDesignLink property in the WC_CONTENT_ORACLE_HOME/data/users/profiles/us/username/pne_portal.hda file is TRUE, the link is displayed:

<$if utGetValue("pne_portal", "portalDesignLink") == 1$>
    <$hasUserProfileLinks=1$>
    <tr>
    <td colspan=2 nowrap align="left">
        <a class=pneLink href="<$HttpCgiPath$>?IdcService=GET_PORTAL_PAGE&Action=GetTemplatePage&Page=PNE_PORTAL_DESIGN_PAGE">
        <$lc("wwPortalDesign")$></a>
    <td>
    </tr>
<$endif$>

3.3.4 Conditionals

A conditional enables you to use if and else clauses to include or exclude code from an assembled page.

• Use the following Idoc Script keywords to evaluate conditions:
  • <$if condition$>
  • <$else$>
  • <$elseif condition$>
  • <$endif$>
• Conditional clauses use this general structure:

  <$if conditionA$>
      <!--Code if conditionA is true-->
  <$elseif conditionB$>
      <!--Code if conditionB is true-->
  <$else$>
      <!--Code if neither conditionA nor conditionB is true-->
  <$endif$>
  

• A condition expression can be any Idoc Script function or variable.

  For more information, see Variable Reference in a Conditional.

• Boolean Operators can be used to combine conditional clauses. For example, you can use the and operator as follows:

  <$if UseBellevueLook and isTrue(UseBellevueLook)$>
  

  The first expression tests whether the variable exists and is not empty, and the second expression checks to see if the value of that variable evaluates to 1 or if it starts with t or y (case-insensitive). If you just have the second clause, it may generate an error if the variable is not set, or empty. An equivalent expression follows:

  <$if isTrue(#active.UseBellevueLook)$>
  

• If the condition expression is the name of a ResultSet available for inclusion in the HTML page, the conditional clause returns true if the ResultSet has at least one row. This ensures that a template page presents information for a ResultSet only if there are rows in the ResultSet.
• A conditional clause that does not trigger special computation is evaluated using the #active prefix. The result is true if the value is not null and is either a nonempty string or a nonzero integer.

3.3.4.1 Conditional Example

In this example, a table cell <td> is defined depending on the value of the variable xDepartment:

<$if xDepartment$>
    <td><$xDepartment$></td>
<$else$>
    <td>Department is not defined.</td>
<$endif$>
<$xDepartment=""$>

• If the value of xDepartment is defined, then the table cell contains the value of xDepartment.
• If the value of xDepartment is not defined or is an empty (null) string, a message is written as the content of the table cell.
• The last line of code clears the xDepartment variable by resetting it to an empty string.

3.3.5 Looping

Loop structures allow you to execute the same code a variable number of times. Looping can be accomplished in two ways with Idoc Script:

• ResultSet Looping

• While Looping

For information on exiting and ending a loop structure, see End a Loop.

3.3.5.1 ResultSet Looping

ResultSet looping repeats a set of code for each row in a ResultSet that is returned from a query. The name of the ResultSet to be looped is specified as a variable using the following syntax:

<$loop ResultSet_name$>
    code
<$endloop$>

• The code between the <$loop$> and <$endloop$> tags is repeated once for each row in the ResultSet.

• When inside a ResultSet loop, you can retrieve values from the ResultSet using the getValue() function. Substitution of values depends on which row is currently being accessed in the loop.

• When inside a ResultSet loop, that ResultSet becomes active and has priority over other ResultSets when evaluating variables and conditional statements.

• Infinite loops with ResultSet loops are not possible (finite lists), whereas while loops can cause infinite loops.

• You cannot use the <$loop$> tag to loop over a variable that points to a ResultSet. Instead you must loop over the ResultSet manually using the rsFirst() and rsNext() functions.

  For example, you cannot use the following code to loop over a ResultSet:

  <$name="SearchResults"$>
  <$loop name$>
      <!--output code-->
  <$endloop$>
  

  Instead, you must use the following code:

  <$name="SearchResults"$>
  <$rsFirst(name)$>
  <$loopwhile getValue(name, "#isRowPresent")$>
      <!--output code-->
      <$rsNext(name)$>
  <$endloop$>

3.3.5.2 ResultSet Looping Example

In this example, a search results table is created by looping over the SearchResults ResultSet, which was generated by the GET_SEARCH_RESULTS service.

<$QueryText="dDocType <matches> 'ADACCT'"$>
<$executeService("GET_SEARCH_RESULTS")$>
<table>
    <tr>
        <td>Title</td><td>Author</td>
    </tr>
<$loop SearchResults$>
    <tr>
        <td><a href="<$SearchResults.URL$>"><$SearchResults.dDocTitle$></a></td>
        <td><$SearchResults.dDocAuthor$></td>
    </tr>
<$endloop$>
</table>

3.3.5.3 While Looping

While looping enables you to create a conditional loop. The syntax for a while loop is:

<$loopwhile condition$>
    code
<$endloop$>

• If the result of the condition expression is true, the code between the <$loopwhile$> and <$endloop$> tags is executed.

• After all of the code in the loop has been executed, control returns to the top of the loop, where the condition expression is evaluated again.

  • If the result is true, the code is executed again.

  • If the code if the result is false, the loop is exited.

3.3.5.4 While Looping Example

In this example, a variable named abc is increased by 2 during each pass through the loop. On the sixth pass (when abc equals 10), the condition expression is no longer true, so the loop is exited.

<$abc=0$>
<$loopwhile abc<10$>
    <$abc=(abc+2)$>
<$endloop$>

3.3.5.5 End a Loop

There are two Idoc Script tags that will terminate a ResultSet loop or while loop:

• <$endloop$> returns control to the beginning of the loop for the next pass. All loops must be closed with an <$endloop$> tag.

• <$break$> causes the innermost loop to be exited. Control resumes with the first statement following the end of the loop.

3.3.6 Administration Interface

You can use Idoc Script in several areas of the administration interface, including:

• Workflow Admin
• Web Layout Editor
• Batch Loader
• Archiver
• System Properties
• Email

3.3.6.1 Workflow Admin

In the Workflow Admin tool, you can use Idoc Script to define the following items:

• Step events

• Jump messages

• Extra exit conditions

• Tokens

• Custom effects for jumps

For example, the following step entry script sends documents in the Secure security group to the next step in the workflow:

<$if dSecurityGroup like "Secure"$>
    <$wfSet("wfJumpName", "New")$>
    <$wfSet("wfJumpTargetStep", wfCurrentStep(1))$>
    <$wfSet("wfJumpEntryNotifyOff", "0")$>
<$endif$>

For more information, see Workflows.

3.3.6.2 Web Layout Editor

In the Web Layout Editor, you can use Idoc Script in the page titles, page descriptions, URL descriptions, query result pages, and content queries. For example:

• You can use Idoc Script tags in the query results page definition to specify the contents of each row in a search results table.

• To set the search results to return all content items up to 7 days, you could define the search query to be:

  dInDate > '<$dateCurrent(-7)$>'
  

• To define a report that returns results based on the current user, you could define User Name is <$UserName$> as part of the report query expression.

See Administration Interface in Oracle Fusion Middleware Administering Oracle WebCenter Content.

3.3.6.3 Batch Loader

In the Batch Loader, you can use Idoc Script in a mapping file, which tells the BatchBuilder utility how to determine the metadata for file records.

3.3.6.4 Archiver

In Archiver, you can use Idoc Script in the following areas:

• Export query values. For example, to archive content more than one year old, you could use <$dateCurrent(-365)$> as the Release Date value.
• Value map output values. For example, to set the expiration date one week in the future for all imported revisions, you could use <dateCurrent(7)$> as the Output value.

3.3.6.5 System Properties

When you set values in the System Properties utility, through the General Configuration page of the Content Server instance or in the Local Configuration or Shared Configuration pages of the Oracle WebCenter Content: Inbound Refinery instance, you are actually setting Idoc Script configuration variables. For more information, see Oracle Fusion Middleware Administering Oracle WebCenter Content.

3.3.6.6 Email

You can use Idoc Script to customize the subject line and body of a notification email. For example:

Hello, <$UserName$>. Content item <$dDocName$> requires your review.

3.4 Special Keywords

The following keywords have special meaning in Idoc Script.

Keyword	Example	Description
#active	<$#active.variable$>	Retrieves the value of the specified variable from the DataBinder, searching in the following default order: Active ResultSets Local data All other ResultSets Environment Does not send an error report to the debug output if the variable is not found.
#local	<$#local.variable$>	Retrieves the value of the specified variable from the local data. Does not send an error report to the debug output if the variable is not found.
#env	<$#env.variable$>	Retrieves the value of the specified variable from the environment settings. Does not send an error report to the debug output if the variable is not found.
exec	<$exec expression$>	Executes an expression and suppresses the output (does not display the expression on the page). In earlier versions of Idoc Script, the exec keyword was required to suppress the value of any variable from appearing in the output file. In the current version, the exec keyword is needed only to suppress an expression from appearing in the output file.
include	<$include ResourceName$>	Includes the code from the specified resource. For more information, see Includes.
super	<$include super.<include>$>	Starts with the existing version of the include code. For more information, see Super Tag.

3.4.1 Keywords Versus Functions

Content Server pages use the include and exec special keywords and the inc and eval functions extensively. This section describes the differences between these commands and gives examples of how to use them.

The include and exec keywords are standalone commands that operate on defined parameters, but cannot take a variable as a parameter. The inc and eval functions have similar purposes, but they can take variables for parameters, which enables you to dynamically create Idoc Script code depending on the value of the variables.

The following sections describe these keywords and functions in detail:

• exec Keyword

• eval Function

• include Keyword

• inc Function

3.4.1.1 exec Keyword

The exec keyword executes an Idoc Script expression and suppresses the output (does not display the expression on the page). It is primarily used to set variables without writing anything to the page.

In earlier versions of Idoc Script, the exec keyword was required to suppress the value of any variable from appearing in the output file. In the current version, the exec keyword is needed only to suppress an expression from appearing in the output.

For example, if you used the following expression, the output value, 0 or 1, would appear in the output file:

<$rsFirst(name)$>

Instead, you can use the exec keyword before the expression to suppress the output:

<$exec rsFirst(name)$>

You can also use exec to suppress the output from rsNext:

<$exec rsNext(name)$>

See exec in Idoc Script Functions and Variables.

3.4.1.2 eval Function

The eval function evaluates an expression as if it were actual Idoc Script.

In the following example, a variable named one is assigned the string Company Name, and a variable named two is assigned a string that includes variable one.

<$one="Company Name"$>
<$two="Welcome to <$one$>"$>
<$one$><br>
<$two$><br>
<$eval(two)$>

In the page output, variable one presents the string Company Name, variable two presents the string Welcome to <$one$>, and the function eval(two) presents the string Welcome to Company Name.

Note that the string to be evaluated must have the Idoc Script delimiters <$ $> around it, otherwise it will not be evaluated as Idoc Script.

Also note that too much content generated dynamically in this manner can slow down page display. If the eval function is used frequently on a page, it may be more efficient to put the code in an include and use the inc function in conjunction with the eval function.

See eval() in Idoc Script Functions and Variables.

3.4.1.3 include Keyword

The include keyword is the standard way in which chunks of code are incorporated into the current page. Because include is a keyword, it cannot take a variable as a parameter-the parameter must be the name of an include that already exists.

See Includes, and include in Idoc Script Functions and Variables.

3.4.1.4 inc Function

The inc function does the same thing as the include keyword, except that it can take a variable as the parameter. This function is most useful for dynamically changing which include will be used depending on the current value of a variable.

For example, say you want to execute some Idoc Script for some, but not all, of your custom metadata fields. You could dynamically create includes based on the field names (such as specific_include_xComments) by executing this Idoc Script:

<$loop DocMetaDefinition$>
    <$myInclude = "specific_include_" & dName$>
    <$exec inc(myInclude)$>
<$endloop$>

Note the use of the exec Keyword, which suppresses the output of the include specified by the inc function. If you do not use exec before the inc function, the HTML inside the specified include will be displayed on the page.

Note that if the specific_include_xComments does not exist, this code will not throw an error because the output is not being displayed.

See inc() in Idoc Script Functions and Variables.

3.5 Operators

Idoc Script supports several operators.

• Comparison Operators

• Special String Operators

• Numeric Operators

• Boolean Operators

3.5.1 Comparison Operators

Use the following comparison operators to compare the value of two operands and return a true or false value based on the result of the comparison. These operators can be used to compare integers and Boolean values in Idoc Script.

If you are using Idoc Script in an HCSP or HCSF page, you must use special comparison operators. For more information, see Comparison Operators.

Operator	Description	Example
==	equality	<$if 2 == 3$> evaluates to false
!=	inequality	<$if 2 != 3$> evaluates to true
<	less than	<$if 2 < 2$> evaluates to false
<=	less than or equal	<$if 2 <= 2$> evaluates to true
>	greater than	<$if 3 > 2$> evaluates to true
>=	greater than or equal	<$if 3 >= 2$> evaluates to true

These are numeric operators that are useful with strings only in special cases where the string data has some valid numeric meaning, such as dates (which convert to milliseconds when used with the standard comparison operators).

• For string concatenation, string inclusion, and simple string comparison, use the Special String Operators.
• To perform advanced string operations, use strEquals(), strReplace(), or other string-related global functions.

3.5.2 Special String Operators

Use the following special string operators to concatenate and compare strings.

Operator	Description	Example
&	The string join operator performs string concatenation. Use this operator to create script that produces Idoc Script for a resource include.	<$"<$include " & VariableInclude & "$>"$> evaluates to <$include VariableName$>
like	The string comparison operator compares two strings. The first string is compared against the pattern of the second string. (The second string can use asterisk and question mark characters as wildcards.) This operator is not case sensitive.	Evaluates to FALSE: <$if "cart" like "car"$> Evaluates to TRUE: <$if "cart" like "car?"$> Evaluates to TRUE: <$if "carton" like "car*"$> Evaluates to TRUE: <$if "Carton" like "car*"$>
|	The string inclusion operator separates multiple options, performing a logical OR function.	Evaluates to TRUE: <$if "car" like "car|truck|van"$>

For example, to determine whether the variable a has the prefix car or contains the substring truck, this expression could be used:

<$if a like "car*|*truck*"$>

Note:

To perform advanced string operations, use strEquals(), strReplace(), or other string-related global functions.

The like operator recognizes the following wildcard symbols.

Wildcard	Description	Example
*	Matches 0 or more characters.	grow* matches grow, grows, growth, and growing *car matches car, scar, and motorcar s*o matches so, solo, and soprano
?	Matches exactly one character.	grow? matches grows and growl but not growth grow?? matches growth but not grows or growing b?d matches bad, bed, bid, and bud

3.5.3 Numeric Operators

Use the following numeric operators to perform arithmetic operations. These operators are for use on integers evaluating to integers or on floats evaluating to floats.

Operator	Description	Example
+	Addition operator.	<$a=(b+2)$>
-	Subtraction operator.	<$a=(b-2)$>
*	Multiplication operator.	<$a=(b*2)$>
/	Division operator.	<$a=(b/2)$>
%	Modulus operator. Provides the remainder of two values divided into each other.	<$a=(b%2)$>

3.5.4 Boolean Operators

Use the following Boolean operators to perform logical evaluations.

Operator	Description	Example
and	If both operands have nonzero values or are true, the result is 1. If either operand equals 0 or is false, the result is 0.	<$if 3>2 and 4>3$> evaluates to 1
or	If either operand has a nonzero value or is true, the result is 1. If both operands equal 0 or are false, the result is 0.	<$if 3>2 or 3>4$> evaluates to 1
not	If the operand equals 0 or is false, the result is 1. If the operand has a nonzero value or is true, the result is 0.	<$if not 3=4$> evaluates to 1

Boolean operators evaluate from left to right. If the value of the first operand is sufficient to determine the result of the operation, the second operand is not evaluated.

3.6 Metadata Fields

This section includes these topics:

• Metadata Field Naming

• Standard Metadata Fields

• Option Lists

• Metadata References in Dynamic Server Pages

3.6.1 Metadata Field Naming

Each metadata field has an internal field name, which is used in code. In addition, many fields have descriptive captions which are shown on web pages.

• Use field captions when displaying metadata to the user.

• Use internal field names when batch loading files or scripting dynamic server pages (.hcst,.hcsp, and .hcsf pages).

• All internal metadata field names begin with either a d or an x:

  • Predefined or core field names begin with a d. For example, dDocAuthor.

  • Custom or add-on field names begin with an x. For example, xDepartment.

  Note:

  Add-on components from Oracle and custom components made by customers all start with x.

• When you create a custom metadata field in the Configuration Manager, the x is automatically added to the beginning of your field name.

  Note:

  In all cases, internal metadata field names are case sensitive.

3.6.2 Standard Metadata Fields

This section describes the standard metadata fields that the Content Server system stores for each content item. The fields are grouped as follows:

• Common Metadata Fields

• Other Fields

3.6.2.1 Common Metadata Fields

The following metadata fields are the most commonly used in customizing the interface. These fields appear by default on checkin and search pages.

Note:

Add-on components, of which there are many, are not listed here. For example, the FrameworkFolders component is enabled in many configurations of Content Server, but FrameworkFolders fields are not in the list.

Do not confuse the content ID (dDocName) with the dID. The dID is an internally generated integer that refers to a specific revision of a content item.

Internal Field Name	Standard Field Caption	Description
dDocAccount	Account	Security account.
dDocAuthor	Author	User who checked in the revision.
xComments	Comments	Explanatory comments.
dDocName	Content ID	Unique content item identifier.
dOutDate	Expiration Date	Date the revision becomes unavailable for searching or viewing.
dInDate	Release Date	Date the revision is scheduled to become available for searching and viewing (see also dCreateDate and dReleaseDate).
dRevLabel	Revision	Revision label (see also dRevisionID).
dSecurityGroup	Security Group	Security group.
dDocTitle	Title	Descriptive title.
dDocType	Type	Content type.

3.6.2.2 Other Fields

In addition to values of the Common Metadata Fields, the following metadata is stored for content items.

Internal Field Name	Standard Field Caption	Description
dCheckoutUser	Checked Out By (Content Information page)	User who checked out the revision.
dCreateDate	None	Date on which the revision was checked in.
dDocFormats	Formats (Content Information page)	Formats of the primary and alternate files.
dDocID	None	Unique rendition identifier.
dExtension	None	File extension of the primary file.
dFileSize	None	Size of the primary file (in bytes).
dFlag1	None	Not used.
dFormat	Format (checkin page, Allow override format on checkin enabled)	Format of the primary file.
dID	None	Unique revision identifier.
dIndexerState	None	State of the revision in an Indexer cycle. Possible values follow: X: The revision has been processed by the rebuild cycle. Y: The revision has been processed by the rebuild cycle. A, B, C, or D: Values generated at run time that can be assigned to any of the following states: Loading the revision for the active update cycle. Indexing the revision for the active update cycle. Loading the revision for the rebuild cycle. Indexing the revision for the rebuild cycle. The specific definitions of these values are stored in the DomainHome/ucm/cs/search/cyclesymbols.hda file.
dIsCheckedOut	None	Indicates whether the revision is checked out. 0: Not checked out 1: Checked out
dIsPrimary	None	Indicates the type of file, primary or alternate. 0: Alternate file 1: Primary file
dIsWebFormat	None	Indicates whether the file is the web-viewable file in the weblayout directory. 0: Not web-viewable file 1: Web-viewable file
dLocation	None	Not used.
dMessage	None (Content Information page)	Indicates the success or reason for failure for indexing or conversion.
dOriginalName	Get Native File (Content Information page) Original File (revision checkin page)	Original file name of the native file.
dProcessingState	None	Conversion status of the revision. Possible values follow: I: Incomplete Conversion; an error occurred in the conversion after a valid web-viewable file was produced and the file was full-text indexed. Y: Converted; the revision was converted successfully and the web-viewable file is available. P: Refinery PassThru; the Inbound Refinery system failed to convert the revision and passed the native file through to the web. F: Failed; the revision is deleted, locked, or corrupted, or an indexing error occurred. C: Processing; the revision is being converted by Inbound Refinery. M: MetaData Only; full-text indexing was bypassed and only the revision's metadata was indexed.
dReleaseDate	None	Date on which the revision was released.
dReleaseState	None	Release status of a revision: N: New, not yet indexed E: In a workflow R: Processing, preparing for indexing I: Currently being indexed; the file has been renamed to the released name Y: Released U: Released, but needs to be updated in the index O: Old revision
dRendition1	None	Indicates whether the file is a thumbnail rendition. Possible values are: null: File is not a thumbnail rendition T: File is a thumbnail rendition
dRendition2	None	Not used.
dRevClassID	None	Internal integer that corresponds to the content ID (dDocName). Used to enhance query response times.
dRevisionID	None	Internal revision number that increments by 1 for each revision of a content item, regardless of the value of dRevLabel.
dStatus	Status (Content Information page)	State of a revision in the system. Possible values are: GENWWW: The file is being converted to web-viewable format or is being indexed, or has failed conversion or indexing. DONE: The file is waiting to be released on its specified Release Date. RELEASED: The revision is available. REVIEW: The revision is in a workflow and is being reviewed. EDIT: The revision is at the initial contribution step of a workflow. PENDING: The revision is in a Basic workflow and is waiting for approval of all revisions in the workflow. EXPIRED: The revision is no longer available for viewing. The revision was not deleted, but it can be accessed only by an administrator. DELETED: The revision has been deleted and is waiting to be completely removed during the next indexing cycle.
dWebExtension	None	File extension of the web-viewable file.

3.6.3 Option Lists

An option list is a set of values that can be selected for a metadata field. Option lists can be formed from queries (dynamically built from the DB), or they can be hard coded and stored in Content Server files (HDA) on the file system.

The following topics describe the use of option lists:

• Internal Option Lists

• Option List Script

• Methods for Creating an Option List

3.6.3.1 Internal Option Lists

The Content Server system maintains the following internal option lists by default.

Metadata Field	Option List
Author (dDocAuthor)	docAuthors
Security Group (dSecurityGroup)	securityGroups
Type (dDocType)	docTypes
Account (dDocAccount)	docAccounts
Role (dRole)	roles

The securityGroups and docAccounts option lists are filtered according to the current user's permissions.

3.6.3.2 Option List Script

The following Idoc Script variables and functions are used to generate and enable option lists.

Variable or Function	Description
optList() function	Generates the option list for a metadata field.
optionListName variable	Specifies the name of an option list.
fieldIsOptionList variable	Specifies that a metadata field has an option list.
fieldOptionListType variable	Specifies the type of option list (strict, combo, multi, or access).
hasOptionList variable	Set to the value of the fieldIsOptionList variable. This variable is used in conditional statements.
defaultOptionListScript variable	Defines a piece of Idoc Script that displays a standard option list field.
optionListScript variable	Overrides the standard implementation of option list fields (as defined by the defaultOptionListScript variable).
optionsAllowPreselect variable	Specifies that a metadata field option list can be prefilled with its last value.
addEmptyOption variable	Specifies that the first value in the option list is blank.
optionListResultSet variable	Specifies a ResultSet that contains option list values.
optionListKey variable	Specifies the name of a ResultSet column that contains option list values.
optionListValueInclude variable	Specifies an include that defines the values for an option list.

3.6.3.3 Methods for Creating an Option List

To create an option list, you can use one of the following methods:

• Use the optList() function to generate a basic option list. This function produces output only when used with a service that calls loadMetaOptionsList.

  For example, this code displays a list of possible authors as an HTML option list:

  <select name="dDocAuthors">
      <$optList docAuthors$>
  </select>
  

• Use the rsMakeFromList() function to turn the option list into a ResultSet, and then loop over the ResultSet.

  For example, this code creates a ResultSet called Authors from the docAuthors option list, and loops over the ResultSet to create an HTML option list. (Because the column name is not specified as a parameter for rsMakeFromList, the column name defaults to row.)

  <$rsMakeFromList("Authors","docAuthors")$>
  <select name="dDocAuthors">
      <$loop Authors$>
          <option><$row$>
  <$endloop$>
  </select>
  

  This code sample is equivalent to the sample produced by using the optList function. Typically, you would use the rsMakeFromList function when you want to parse or evaluate the list options.

• Use the Configuration Manager applet to create an option list, without writing any code.

3.6.4 Metadata References in Dynamic Server Pages

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

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

• hasDocInfo

• dDocName

• dExtension

• dSecurityGroup

• isLatestRevision

• dDocType

• dID

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

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

For more information, see Altering the Appearance and Navigation of Web Pages.

3.7 Merge Includes for Formatting Results

You can use a MergeInclude to format your results from a Content Server request based on an Idoc Script include, rather than an entire template page.

A MergeInclude is a feature often used to integrate ASP pages using the IdcCommandX ActiveX module. The Content Server architecture is essentially a modular, secure, service-based application with multiple interfaces, although its architecture was designed to optimize the web interface. Services such as GET_SEARCH_RESULTS will generate response data based on the QueryString passed, and the user's security credentials. This response data is internally represented in the form of a HDA file. To see this in action, simply perform a search and then add 'IsJava=1' or 'IsSoap=1' (for XML-formatted data) to the URL. You can now see how data is internally represented for the response.

Because this HDA representation is not particularly useful for web-based users, we use Idoc Script includes and templates to format the response into a readable HTML page. A user can modify how this HTML is displayed by changing the template or a few resource includes with a component.

However, to retrieve only a small portion of this search result (for example, to display it on an ASP, JSP, or PHP page where the majority of the code is not Idoc Script), or have an IFRAME or DIV element pop up and display the results, or to dynamically change how to display the results, you can simply add these parameters to your URL:

MergeInclude=my_custom_include&IsJava=1

This will cause the Content Server system to bypass formatting the response according to the template that is specified in the service. It will instead format the response based on the Idoc Script in my_custom_include. For example, if you executed a search, then added the above line to the URL, and the include looked like this in your component:

<@dynamichtml my_custom_include@>
<html>
<table width=300>
<tr>
    <td><b>Name</b></td>
    <td><b>Title (Author)</b></td>
</tr>
<$loop SearchResults$>
<tr><td><a href="<$URL$>"><$dDocName$></a></td>
    <td><$dDocTitle$> (<$dDocAuthor$>)</td></tr>
<$endloop$>
</table>
</html>
<@end@>

This would display a search result page devoid of all images and formatting that you may not need. Consequently, you can format any Content Server response with any Idoc Script include that you want. In theory, the Idoc Script include can contain any kind of formatting that you want: XML, WML, or simply plain text.

For example, if you wanted to return search results in a format that can be read in an Excel Spreadsheet, you could create a resource include that returns a comma-delimited list of entries. You could then save the returned file to your hard drive, and then open it up in Excel. Another useful trick would be to create a resource include that formats the response into a record set that can be read in as a file by the IdcCommandX utility, or the BatchLoader. Such an include could be used with a search result, or an Active Report created with the Web Layout Editor, to build up batch files specific to arbitrary queries against the database or against the search index.

• MergeInclude variables are cached differently than normal resource includes. Therefore, you must restart the Content Server instance if you make changes to the resource include. This can be bypassed if you execute a docLoadResourceInclude() function to dynamically load different includes from within the MergeInclude.

• The content type of the returned data is 'text/plain' and not 'text/html' for data returned by a MergeInclude. Some clients (such as Internet Explorer and many versions of Netscape) still display plain text as html if you have valid HTML in the response, others clients may not. If you experience problems, you may need to manually set the content type when you link to it.

3.8 Scoped Local Variables

Scoped local variables are a special kind of local variable, used to override how metadata is drawn to the page. These variables are scoped to a specific metadata field by separating them with a colon.

For example, to hide the title and comments fields, you would set the following flags:

dDocTitle:isHidden=1
xComments:isHidden=1

These flags must be set early in the page in the URL or by overriding the include std_doc_page_definitions.

In the following list, all flags affect the display of the field xFieldName:

• xFieldName:groupHeader: This is set in Content Profiles if this field is the first field in a group. It contains the HTML and Idoc Script to use for the group header.

• xFieldName:hasOptionList: Allows the field to contain a custom option list, instead of using the default option list. Must be used with the xFieldName:optionListName variable or xFieldName:optionListScript variable.

• xFieldName:include: Used to set the value for fieldInclude to the name of a custom resource include. This resource will be used throughout the page, including the JavaScript and the HTML. This flag is used rarely. If needed, use the std_namevalue_field include file as a guide for making a custom include.

• xFieldName:isExcluded: Set to true to exclude a field from the page completely. It will not be displayed as a field, or as a hidden input field. The field will be completely absent from the page.

• xFieldName:isHidden: Set to TRUE to hide a field on the page. On pages with form posts, the field will still be present. However, it will only exist as a hidden INPUT field. The value of the field will be blank, unless xFieldName or fieldValue is defined. This will enable you to create pages with default values that cannot be changed.

• xFieldName:isInfoOnly: Set to TRUE to display only the value of a field. This is used instead of xFieldName:isHidden to show the user what default values are being submitted.

• xFieldName:isRelocated: Set to TRUE to stop the automatic display of a field on the HTML page. By default, all fields on the page have a specific order. To reorder them, you must set this flag, then display the field manually.

  <!-- hide the comments field -->
  <$xComments:isRelocated = 1$>
  <$loop DocMetaDefinition$>
  <$strTrimWs(inc("std_meta_field_display"))$>
  <$endloop$>
  <!-- now turn off relocation, and display it -->
  <$xComments:isRelocated = ""$>
  <$fieldName="xComments", fieldCaption="Comments", fieldType="Memo"$>
  <$include std_display_field$>
  

• xFieldName:isRequired: Set to TRUE to turn this field into a required field. This flag must be set in std_doc_page_definitions, before the JavaScript validation code is drawn to the page.

• xFieldName:maxLength: Similar to fieldWidth, this sets the maximum length of a text input field. This is usually greater than fieldWidth, and must be less than the width of the field in the database.

• xFieldName:noSchema: Set to TRUE to disable a schema option list for a field. Required if you want to generate option lists in a custom, dynamic way.

• xFieldName:optionListName: This flag can only be set if a field is an option list. You can override which option list to use to display values:

  <$xCountry:hasOptionList = 1$>
  <$xCountry:noSchema = 1$>
  <$xCountry:optionListName = "securityGroups"$>
  <$loop DocMetaDefinition$>
  <$strTrimWs(inc("std_meta_field_display"))$>
  <$endloop$>
  

• xFieldName:optionListScript: Similar to optionListName, except it can be used to render Idoc Script instead of explicitly defined option lists. This allows the option list to be drawn with a ResultSet instead:

  <$xCountry:hasOptionList = 1$>
  <$xCountry:noSchema = 1$>
  <$xCountry:optionListScript =
  "<$rsMakeFromList('GROUPS', 'securityGroups')$>" &
  "<select>\n" &
  "<$loop GROUPS$>" &
  " <option><$row$>" &
  "<$endloop$>\n" &
  "</select>"$>
  <$loop DocMetaDefinition$>
  <$strTrimWs(inc("std_meta_field_display"))$>
  <$endloop$>
  

• xFieldName:rowClass: Used in std_nameentry_row. It sets a Cascading Style Sheet class for the table row that contains this field.

  <$xComments:rowClass="xuiPageTitleText"$>
  <$loop DocMetaDefinition$>
  <$strTrimWs(inc("std_meta_field_display"))$>
  <$endloop$>
  

• xFieldName:rowStyle: Same as rowClass, but this can be used to create inline styles. For example, to hide the Comments field with DHTML, use the following code:

  <$xComments:rowStyle="display:none"$>
  <$loop DocMetaDefinition$>
  <$strTrimWs(inc("std_meta_field_display"))$>
  <$endloop$>
  

  This is useful when you want to hide and display fields dynamically without a page reload.