3.5 Resources Detail

3.5.1 HTML Include

An include is defined within <@dynamichtml name@> and <@end@> tags in an HTM resource file. The include is then called using the syntax <$include name$>.

Includes can contain Idoc Script and valid HTML code, including JavaScript, Java applets, cascading style sheets, and comments. Includes can be defined in the same file as they are called from, or they can be defined in a separate HTM file. Standard HTML includes are defined in the IdcHomeDir/resources/core/idoc files.

HTML includes, strings, and static tables can be present in the same HTM file. An HTML include resource does not require merge rules.

<@dynamichtml my_resource@>
    <$include super.my_resource$>
    exception code
<@end@>

<@dynamichtml my_resource@>
    <$a = 1, b = 2$>
<@end@>

<@dynamichtml my_resource@>
    <$include super.my_resource$>
    <!--Change "b" but not "a" -->
    <$b = 3$>
<@end@>

3.5.2 String

A string resource defines locale-sensitive text strings that are used in error messages and on Content Server Web pages and applets. Strings are resolved by the Content Server each time a Web page is assembled, an applet is started, or an error message is displayed.

A string is defined in an HTM file using the following format:

<@stringID=Text string@>

A string is called from an HTM template file using the following Idoc Script format:

<$lc("wwStringID")$>

Standard English strings are defined in the IdcHomeDir/resources/core/lang/ directory. Strings for other supported languages are provided by the Localization component.

HTML includes, strings, and static tables can be present in the same HTM file. A string resource does not require merge rules.

You must use HTML escape encoding to include the following special characters in a string value:

You can specify strings for multiple languages in the same resource file using the language identifier prefix, if the languages are all single-byte or all multibyte. For example:

<@myString=Thank you@>
<@es.myString=Gracias@>
<@fr.myString=Merci@>
<@de.myString=Danke@>

If you are specifying multibyte strings in your custom string resource, ensure that the character set specification on your HTML pages changes to the appropriate encoding. Resource files should have a correct http-equiv charset tag so that Content Server reads them correctly.

3.5.3 Dynamic Tables

Dynamic table resources are defined in the HDA file format. See "Elements in HDA Files" for more information and an example of an HDA ResultSet table. Merge rules are required for a dynamic table resource if data from the custom resource replaces data in an existing table. Merge rules are not required if data from the custom resource is to be placed in a new table.

3.5.4 Static Tables

Static tables, HTML includes, and strings can be present in the same HTM file. Merge rules are required for a static table resource if data from the custom resource replaces data in an existing table. Merge rules are not required if data from the custom resource is to be placed in a new table.

3.5.5 Query

A query resource defines SQL queries, which are used to manage information in the Content Server database. Queries are used with service scripts to perform tasks such as adding to, deleting, and retrieving data from the database.

The standard Content Server queries are defined in the QueryTable table in the IdcHomeDir/resources/core/tables/query.htm file. You also find special-purpose queries in the indexer.htm and workflow.htm files that are stored in the IdcHomeDir/resources/core/tables/ directory. Merge rules are not required for a query resource.

A query resource is defined in an HTM file using a ResultSet table with three columns: name, queryStr, and parameters.

• The name column defines the name for each query. To override an existing query, use the same name for your custom query. To add a new query, use a unique query name. When naming a new query, identify the type of query by starting the name with one of the following characters:

  First Character	Query Type
  D	Delete
  I	Insert
  Q	Select
  U	Update

  
  

• The queryStr column defines the query expression. Query expressions are in standard SQL syntax. If there are any parameter values to pass to the database, their place is held with a question mark (?) as an escape character.

• The parameters column defines the parameters that are passed to the query from a service. A request from a web browser calls a service, which in turn calls the query. It is the responsibility of the web browser to provide the values for the query parameters, which are standard HTTP parameters The browser can pass query parameters from the URL or from FORM elements in the web page. For example, the QdocInfo query requires the dID (revision ID) to be passed as a parameter, so the value is obtained from the service request URL.

The following example shows the standard QdocInfo query as defined in the <instance_dir>/shared/config/resources/query.htm file. This query obtains the metadata information to display on the DOC_INFO template page, which is the page displayed when a user clicks the information icon on a search results page.

The parameter passed from the web browser URL is the dID, which is the unique identification number for the content item revision. The query expression selects the data for the primary revision from the Revisions, Documents, and DocMeta database tables that matches the dID, if the revision does not have "Deleted" status.

Figure 3-3 Standard QDocInfo query

<HTML>
<HEAD>
<META HTTP-EQUIV='Content-Type' content='text/html; charset=iso-8859-1'>
<TITLE>Query Definition Resources</TITLE>
</HEAD>
<BODY>
<@table QueryTable@>
<table border=1><caption><strong>Query Definition Table</strong></caption>
<tr>
    <td>name</td>
    <td>queryStr</td>
    <td>parameters</td>
</tr>
<tr>
    <td>QdocInfo</td>
    <td>SELECT Revisions.*, Documents.*, DocMeta.*
    FROM Revisions, Documents, DocMeta
    WHERE Revisions.dID=? AND Revisions.dID=Documents.dID AND DocMeta.dID = Documents.dID AND Revisions.dStatus<>'DELETED' AND Documents.dIsPrimary<>0</td>
    <td>dID int</td>
</tr>
</table>
<@end@>
</BODY>
</HTML>

3.5.6 Service

A service resource defines a function or procedure that is performed by the Content Server. A service call can be performed from either the client or server side, so services can be performed on behalf of the Web browser client or within the system itself. For example:

• Client-side request: When you click a "Search" link on a Content Server Web page, the standard search page is delivered to your Web browser by the GET_DOC_PAGE service using the following URL segment:

  IdcService=GET_DOC_PAGE&Action=GetTemplatePage&Page=STANDARD_QUERY_PAGE
  

• Server-side request: You can use the START_SEARCH_INDEX service to update or rebuild the search index automatically in a background thread.

Services are the only way a client can communicate with the server or access the database. Any program or HTML page can use services to request information from the Content Server or perform a specified function.

The standard Content Server services are defined in the StandardServices table in the IdcHomeDir/resources/core/tables/std_services.htm file. You can also find special-purpose services in the workflow.htm file in the IdcHomeDir/resources/core/tables/ directory.

Services depend on other resource definitions to perform their functions. Any service that returns HTML requires a template to be specified. A common exception is the PING_SERVER service, which does not return a page to the browser.

Most services use a query. A common exception is the SEARCH service, which sends a request directly to the search collection. Merge rules are not required for a service resource.

The following table row is an example of a service definition.

Figure 3-4 Service Definition Example

A service resource is defined in an HTM file using a ResultSet table with the following three columns:

• The Name column defines the name for each service. For client-side service requests, this is the name called in the URL. To override an existing service, use the same name for your custom service. To add a new service, use a unique service name.

• The Attributes column defines the following attributes for each service:

  Attribute	Description	Example (attributes from the DELETE_DOC service)
  Service class	Determines, in part, what actions can be performed by the service.	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Access level	Assigns a user access level to the service. This number is the sum of the following possible bit flags: READ_PRIVILEGE = 1 WRITE_PRIVILEGE = 2 DELETE_PRIVILEGE = 4 ADMIN_PRIVILEGE = 8 GLOBAL_PRIVILEGE = 16 SCRIPTABLE_SERVICE=32	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Template page	Specifies the template that presents the results of the service. If the results of the service do not require presentation, this attribute is null.	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Service type	If the service is to be executed inside another service, this attribute is SubService; otherwise, this attribute is null.	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Subjects notified	Specifies the subjects (subsystems) to be notified by the service. If no subjects are notified, this attribute is null.	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)
  Error message	Defines the error message returned by the service if no action error message overrides it. This can be either an actual text string or a reference to a locale-sensitive string (see Resolving Localized Strings in Customizing Content Server for more information).	DocService 4 MSG_PAGE null documents !csUnableToDeleteItem(dDocName)

  
  

• The Actions column defines the actions for each service. An action is an operation to be performed as part of a service script. Actions can execute an SQL statement, perform a query, run code, cache the results of a query, or load an option list. Each service includes one or more actions, which specify what happens upon execution.

  The <br> tags in the Actions column are for browser display purposes only, so they are optional. However, the </td> tag must occur immediately after the actions, without a line break in between. An action is defined using the following format:

  type:name:parameters:control mask:error message
  

  Section	Description	Example (first action from the DELETE_DOC service)
  Type	Defines the type of action: QUERY_TYPE = 1 EXECUTE_TYPE = 2 CODE_TYPE = 3 OPTION_TYPE = 4 CACHE_RESULT_TYPE = 5	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExists
  Name	Specifies the name of the action.	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist
  Parameters	Specifies parameters required by the action. If no parameters are required, leave this part empty (two colons appear in a row).	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist
  Control mask	Controls the results of queries to the database. This number is the sum of the following possible bit flags: No control mask = 0 CONTROL_IGNORE_ERROR = 1 CONTROL_MUST_EXIST = 2 CONTROL_BEGIN_TRAN = 4 CONTROL_COMMIT_TRAN = 8 CONTROL_MUST_NOT_EXIST = 16	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist
  Error message	Defines the error message to be displayed by this action. This error message overrides the error message provided as an attribute of the service. This can be either an actual text string or a reference to a locale-sensitive string (see Resolving Localized Strings in Customizing Content Server for more information).	5:QdocInfo:DOC_INFO:6:!csUnableToDeleteItem(dDocName)!csRevisionNoLongerExist

  
  

3.5.6.1 Service Example

The DOC_INFO service provides a good example of how services, queries, and templates work together. The following figures show the DOC_INFO service definition from the <instance_dir>/config/resources/std_services.htm file.

Figure 3-5 DOC_INFO service

<HTML>
    <HEAD>
    <META HTTP-EQUIV='Content-Type' content='text/html; charset=iso-8859-1'>
    <TITLE>Standard Scripted Services</TITLE>
    </HEAD>
    <BODY>
    <@table StandardServices@>
    <table border=1><caption><strong>Scripts For Standard Services</strong></caption>
    <tr>
    <td>Name</td><td>Attributes</td><td>Actions</td>
    </tr>
    <tr>
    <td>DOC_INFO</td>
    <td>DocService
        33
        DOC_INFO
        null
        null<br>
        !csUnableToGetRevInfo</td>
    <td>5:QdocInfo:DOC_INFO:2:!csItemNoLongerExists2
        3:mapNamedResultSetValues:DOC_INFO,dStatus,dStatus,dDocTitle,dDocTitle:0:null
        3:checkSecurity:DOC_INFO:0:!csUnableToGetRevInfo2(dDocName)
        3:getDocFormats:QdocFormats:0:null
        3:getURLAbsolute::0:null
        3:getUserMailAddress:dDocAuthor,AuthorAddress:0:null
        3:getUserMailAddress:dCheckoutUser,CheckoutUserAddress:0:null
        3:getWorkflowInfo:WF_INFO:0:null
        3:getDocSubscriptionInfo:QisSubscribed:0:null
        5:QrevHistory:REVISION_HISTORY:0:!csUnableToGetRevHistory(dDocName)</td>
    </tr>
    </table>
    <@end@>
    </BODY>
    </HTML>

3.5.6.1.1 Attributes

The following table describes the attributes of the DOC_INFO service shown previously.

Attribute	Value	Description
Service class	DocService	This service is providing information about a content item.
Access level	33	32 = This service can be executed with the executeService Idoc Script function. 1 = The user requesting the service must have Read privilege on the content item.
Template page	DOC_INFO	This service uses the DOC_INFO template (doc_info.htm file). The results from the actions are merged with this template and presented to the user.
Service type	null	This service is not a subservice.
Subjects notified	null	No subjects are affected by this service.
Error Message	!csUnableToGetRevInfo	If this service fails on an English Content Server system, it returns the error message string: Unable to retrieve information about the revision

3.5.6.1.2 Actions

The DOC_INFO service executes the following actions:

• 5:QdocInfo:DOC_INFO:2:!csItemNoLongerExists2

  Action Definition	Description
  5	Cached query action that retrieves information from the database using a query.
  QDocInfo	This action retrieves content item information using the QDocInfo query in the query.htm file.
  DOC_INFO	The result of the query is assigned to the parameter DOC_INFO and stored for later use.
  2	The CONTROL_MUST_EXIST control mask specifies that the query must return a record, or the action fails.
  !csItemNoLongerExists2	If this action fails on an English Content Server system, it returns the error message string: This content item no longer exists

  
  

• 3:mapNamedResultSetValues:DOC_INFO,dStatus,dStatus,dDocTitle,dDocTitle:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  mapNamedResultSetValues	This action retrieves the values of dStatus and dDocTitle from the first row of the DOC_INFO ResultSet and stores them in the local data. (This increases speed and ensures that the correct values are used.)
  DOC_INFO,dStatus,dStatus,dDocTitle,dDocTitle	Parameters required for the mapNamedResultSetValues action.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:checkSecurity:DOC_INFO:0:!csUnableToGetRevInfo2(dDocName)

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  checkSecurity	This action retrieves the data assigned to the DOC_INFO parameter and evaluates the assigned security level to verify that the user is authorized to perform this action.
  DOC_INFO	Parameter that contains the security information to be evaluated by the checkSecurity action.
  0	No control mask is specified.
  !csUnableToGetRevInfo2(dDocName)	If this action fails on an English Content Server system, it returns the error message string: Unable to retrieve information for ''{dDocName}."

  
  

• 3:getDocFormats:QdocFormats:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getDocFormats	This action retrieves the file formats for the content item using the QdocFormats query in the query.htm file. A comma-delimited list of the file formats is stored in the local data as dDocFormats.
  QdocFormats	Specifies the query used to retrieve the file formats.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getURLAbsolute::0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getURLAbsolute	This action resolves the URL of the content item and stores it in the local data as DocUrl.
  blank	This action takes no parameters.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getUserMailAddress:dDocAuthor,AuthorAddress:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getUserMailAddress	This action resolves the e-mail address of the content item author.
  dDocAuthor,AuthorAddress	This action passes dDocAuthor and AuthorAddress as parameters.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getUserMailAddress:dCheckoutUser,CheckoutUserAddress:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getUserMailAddress	This action resolves the e-mail address of the user who has the content item checked out.
  dCheckoutUser,CheckoutUserAddress	This action passes dCheckoutUser and CheckoutUserAddress as parameters.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getWorkflowInfo:WF_INFO:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getWorkflowInfo	This action evaluates whether the content item is part of a workflow. If the WF_INFO ResultSet exists, then workflow information is merged into the DOC_INFO template.
  WF_INFO	This action passes WF_INFO as a parameter.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 3:getDocSubscriptionInfo:QisSubscribed:0:null

  Action Definition	Description
  3	Java method action specifying a module that is a part of the Java class implementing the service.
  getDocSubscriptionInfo	This action evaluates if the current user has subscribed to the content item: If the user is subscribed, an Unsubscribe button is displayed. If the user is not subscribed, a Subscribe button is displayed.
  QisSubscribed	Specifies the query used to retrieve the subscription information.
  0	No control mask is specified.
  null	No error message is specified.

  
  

• 5:QrevHistory:REVISION_HISTORY:0:!csUnableToGetRevHistory(dDocName)

  Action Definition	Description
  5	Cached query action that retrieves information from the database using a query.
  QrevHistory	This action retrieves revision history information using the QrevHistory query in the query.htm file.
  REVISION_HISTORY	The result the query is assigned to the parameter REVISION_HISTORY. The DOC_INFO template uses this parameter in a loop to present information about each revision.
  0	No control mask is specified.
  !csUnableToGetRevHistory(dDocName)	If this action fails on an English Content Server system, it returns the error message string: Unable to retrieve revision history for ''{dDocName}.''

  
  

3.5.7 Templates

A template resource defines the names, types, and locations of custom template files to be loaded for the component.

The actual template pages (.htm files) are separate files that are referenced in the template resource file. Template HTM files contain the code that the Content Server uses to assemble web pages. HTML markup in a template file defines the basic layout of the page, while Idoc Script in a template file generates additional HTML code for the Web page at the time of the page request. Because HTM template files contain a large amount of script that is not resolved by the Content Server until the final page is assembled, these files are not viewable Web pages.

The template type of HTM file is used to define the following component files:

• Template pages: Standard template pages are located in the IdcHomeDir/resources/core/templates/ directory.

• Report pages: Standard report pages are located in the IdcHomeDir/resources/core/reports/ directory.

A template resource (templates.hda) is defined in the HDA file format. See "Elements in HDA Files" for more information and an example of an HDA ResultSet table. The standard templates are defined in the IdcHomeDir/resources/core/templates/templates.hda file.

Merge rules are required to merge the new template definition into the IntradocTemplates table or the SearchResultTemplates table. Typically, the merge is on the name column. The following is an example of a MergeRules ResultSet for a template.

@ResultSet MergeRules
4
fromTable
toTable
column
loadOrder
MultiCheckinTemplates
IntradocTemplates
name
1
@end

The standard templates.hda file defines three ResultSet tables:

• The IntradocTemplates ResultSet table defines the template pages for all Content Server Web pages except search results pages. This table consists of five columns:

  • The name column defines the name for each template page. This name is how the template is referenced in the Content Server CGI URLs and in code.

  • The class column defines the general category of the template. The most common class type is Document.

  • The formtype column defines the specific type of functionality the page is intended to achieve. The formtype is typically the same as the name of the form, except in lowercase characters.

  • The filename column defines the path and file name of the template file. The location can be an absolute path or can be relative to the template resource file when the template page is in the same directory as the template resource file.

  • The description column defines a description of the template.

• The Verify Template. The Content Server no longer uses the VerityTemplates ResultSet table. However, this table remains in the templates.hda file as legacy code for reverse compatibility.

• The SearchResultTemplates table defines the template pages for search results pages. SearchResultTemplates define how query results are displayed on the search results pages in the Library. Query result pages are a special type of search results page. This table consists of six columns:

  • The name column defines the name for each template page. This name is how the template is referenced in the Content Server CGI URLs, in code, and in the Web Layout Editor utility.

    Note:

    The StandardResults template (search_results.htm file) is typically used as the global template for standard search results pages and the query results pages in the Library. You can create a new template or change the "flexdata" of the StandardResults template through the Web Layout Editor, but these changes are saved in a separate file (IntradocDir/data/results/custom_results.hda) rather than in the SearchResultTemplates table in the templates.hda file.

  • The formtype column defines the specific type of functionality the page is intended to achieve. ResultsPage is the only form type currently supported for search results pages.

  • The filename column defines the path and file name of the template file. The location can be an absolute path or can be relative to the template resource file when the template page is in the same directory as the template resource file.

  • The outfilename column is for future use; the value is always null.

  • The flexdata column defines the metadata to be displayed for each row on the search results page. The format of text in the flexdata column is:

    Text1 "text 1 contents"%<Tab>Text2 "text 2 contents"%
    

    where Text1 contents appear on the first line, and Text2 contents appear on the second line in each search results row. <Tab> represents a literal tab character.

    Idoc Script can be used to define the contents in the flexdata field. You can also change the flexdata of the StandardResults template through the Web Layout Editor, but these changes are saved in a separate file (IntradocDir/data/results/custom_results.hda) rather than in the SearchResultTemplates table in the templates.hda file.

  • The description column defines a description of the template.

The following example shows a custom template resource file that points to a custom Content Management page (multicheckin_doc_man.htm) and a custom search results page (MultiCheckin_search_results.htm).

<?hda version="5.1.1 (build011203)" jcharset=Cp1252 encoding=iso-8859-1?>
@Properties LocalData
blDateFormat=M/d{/yy} {h:mm[:ss] {aa}[zzz]}!tAmerica/Chicago!mAM,PM
blFieldTypes=
@end
@ResultSet MultiCheckinTemplates
5
name
class
formtype
filename
description
DOC_MANAGEMENT_LINKS
DocManagement
DocManagementLinks
multicheckin_doc_man.htm
Page containing links to various document management functions
@end
@ResultSet MultiCheckin_2
6
name
formtype
filename
outfilename
flexdata
description
StandardResults
SearchResultsPage
MultiCheckin_search_results.htm
null
Text2 <$dDocTitle$> <$dInDate$>%       Text1 <$dDocName$>%
apStandardResultsDesc
@end

3.5.7.1 Template and Report Pages

Template pages and report pages are also called "presentation" pages, because the Content Server uses them to assemble, format, and present the results of a web page request.

The standard template pages are located in the IdcHomeDir/resources/core/templates directory. The standard report pages are located in the IdcHomeDir/resource/core/reports directory.

3.5.7.1.1 Template Page Example

The following example shows the template file for the standard Content Management page (doc_man.htm).

Figure 3-6 Template Page Example

Description of "Figure 3-6 Template Page Example"

3.5.7.1.2 Report Page Example

The following example shows the template file for the standard Document Types report page (doc_types.htm).

Figure 3-7 Report Page Example

Description of "Figure 3-7 Report Page Example"

3.5.8 Environment

An environment resource defines configuration variables, either by creating new variable values or replacing existing values. Because custom resources are loaded after the standard config.cfg file is loaded, the variable values defined in the custom environment resource replace the original variable values.

An environment resource is defined in a CFG file using a name/value pair format:

variable_name=value

After defining a variable value, you can reference the variable in templates and other resource files with the following Idoc Script tag:

<$variable_name$>

Environment resource files can include comment lines, which are designated with a # symbol:

#Set this variable to true to enable the function.

# Use this to turn on or off alternate row coloring
nsUseColoredRows=0

# These are the nested search field definitions.

nsFld1Caption=Document Text
nsFld1Name=
nsFld1Type=FullText
nsFld1OptionKey=
#
nsFld2Caption=Text
nsFld2Name=xtext
nsFld2Type=Text
nsFld2OptionKey=
#
nsFld3Caption=Date
nsFld3Name=xdate
nsFld3Type=Date
nsFld3OptionKey=
#
nsFld4Caption=Integer
nsFld4Name=xinteger
nsFld4Type=Int
nsFld4OptionKey=
#
nsFld5Caption=Option List
nsFld5Name=xoptionlist
nsFld5Type=OptionList
nsFld5OptionKey=optionlistList
#
nsFld6Caption=Info Topic
nsFld6Name=xwfsInfoTopic
nsFld6Type=OptionList
nsFld6OptionKey=wfsInfoTopicList

<$if isTrue(#active.nsUseColoredRows)$>
    <$useColoredRows=1, bkgHighlight=1$>
<$endif$>