Idoc Script is the server-side custom scripting language for the Oracle Content Server system. It 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.
Idoc Script is used primarily for the presentation of HTML templates and configuration settings.
This chapter includes the following sections:
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. Many parameters in service requests also begin with upper case 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". 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 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 lower-case letter d. All custom metadata database column names created by the Oracle Content Server system begin with the lower-case letter x.
Idoc Script follows these basic syntax rules:
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. For more information, see the Oracle Fusion Middleware Developer's Guide for Oracle Universal Content Management.
You can use standard HTML comments or Idoc Script comments in Idoc Script code. An Idoc Script comment begins with [[% and closes with %]]. For example:
<!-- HTML Comment --> [[%My Comment%]]
The comment syntax also can be used 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 %]]
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 Oracle Content Server applets and customizations.
An include defines pieces of code that are used to build the Oracle 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 Oracle Fusion Middleware Developer's Guide for Oracle Universal Content Management.
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 ucm_home_dir/idc/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.
For more information, see the following sections:
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 is an example of code located in the ucm_home_dir/idc/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, ucm_home_dir/idc/resources/core/templates/pne_home_page.htm) contain the following Idoc Script code near the top of the page:
<$include body_def$>
When the Oracle 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.
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 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.
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 multiplesuper 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 Oracle 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.
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 variable enables you to define and substitute variable values.
The following sections describe how to work with Idoc Script variables:
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 Chapter 3, "Master List: Idoc Script by Type."
You can reference a variable in templates and other resource files with the following Idoc Script tag:
<$variable_name$>
A value can be assigned to a variable using the 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.
Idoc Script supports multiple clauses separated by commas in one script block.
For example, you can use <$a=1,b=2$> rather than two separate statements: <$a=1$> and <$b=2$>.
The following structure can be used to evaluate the existence of a variable:
<$if variable_name$>
If the variable is defined, 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 Section 2.3.4.1, "Conditional Example."
When a variable value is required to fulfill a service request, the data cached in the DataBinder is evaluated in the following default order:
LocalData
Active ResultSets
Non-active ResultSets
Environment
For more information on the DataBinder, see the Oracle Fusion Middleware Developer's Guide for Oracle Universal Content Management.
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.
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 Section 3.5, "Global 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 ucm_home_dir/data/users/profiles/us/username/ directories.
The following global functions reference user topic files:
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 ucm_home_dir/shared/config/resources/std_page.htm resource file). If the portalDesignLink property in the ucm_home_dir/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$>
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:
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 are true-->
<$endif$>
A condition expression can be any Idoc Script function or variable.
For more information, see Section 2.3.2.5, "Referencing a Variable 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)$>
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 XXXXXXXXXXXX_cannot_cross-reference to a marker on a para in a bable_XXXXXXXXXXXXXX prefix. The result is true if the value is not null and is either a nonempty string or a nonzero integer.
For an example of conditional code, see Section 2.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.
Loop structures allow you to execute the same code a variable number of times. Looping can be accomplished in two ways with Idoc Script:
For information on exiting and ending a loop structure, see Section 2.3.5.5, "Ending a Loop."
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.
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$>
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>
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.
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$>
You can use Idoc Script in several areas of the administration interface, including:
In the Workflow Admin tool, you can use Idoc Script to define the following:
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 Section 3.8.1, "Workflows."
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.
For more information, see Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.
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. For more information, see Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.
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.
For more information, see Oracle Fusion Middleware System Administrator's Guide for Oracle Content Server.
When you set values in the SystemProperties utility, in the Admin Server, or in the Local Configuration or Shared Configuration screens of the Inbound Refinery, you are actually setting Idoc Script configuration variables. For more information, see the documentation for these applications.
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:
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 Section 2.3.1, "Includes." |
| super | <$include super.<include>$> | Starts with the existing version of the include code. For more information, see Section 2.3.1.2, "Super Tag." |
Oracle 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:
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, the first line below is equivalent to the last two lines:
<$varA="stringA", varB ="stringB"$> <$exec varA="stringA"$> <$exec varB="stringB"$>
For more information, see exec.
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.
For more information, see eval.
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.
For more information, see Chapter 2, "Includes" and include.
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.
For more information, see inc.
Idoc Script supports several operators. This section describes the following:
Use the following comparison operators 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 Oracle Fusion Middleware Developer's Guide for Oracle Universal Content Management.
| 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.
Use the following special string operators to concatenate and compare strings:
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*"$>
Important:
To perform advanced string operations, use strEquals, strReplace, or other string-related global functions. For a list, see "Strings".The like operator recognizes the following wildcard symbols:
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:
Use the following Boolean operators to perform logical evaluations:
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.
This section includes these topics:
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 field names begin with a d. For example, dDocAuthor.
Custom field names begin with an x. For example, xDepartment.
When you create a custom metadata field in the Configuration Manager, the x is automatically added to the beginning of your field name.
Important:
In all cases, internal metadata field names are case sensitive.This section describes the standard metadata fields that the Oracle Content Server system stores for each content item. The fields are grouped as follows:
The following metadata fields are the most commonly used in customizing the interface. These fields appear by default on checkin and search pages.
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.
In addition to the Common Metadata Fields, the following metadata is stored for content items:
An option list is a set of values that can be selected for a metadata field. The following topics describe the use of option lists:
The Oracle 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.
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. |
To create an option list, you can use one of the following methods:
Use the optList function to generate a basic option list. Note that this only produces output 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>
These code samples are equivalent. Typically, you would use the rsMakeFromList function when you want to parse or evaluate the list options.
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:
For example, the following statement determines if the document type is Page:
<$if strEquals(ref:dDocType,"Page"))$>
For more information, see Oracle Fusion Middleware Developer's Guide for Oracle Universal Content Management.
You can use a MergeInclude to format your results from an Oracle 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 Oracle 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 then add 'IsJava=1' 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 Oracle 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 Oracle 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 Weblayout 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 Oracle 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.
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.