7 Site Studio Tag Library and Helper Methods

This section provides information on the Site Studio tag library and the Site Studio helper methods. It covers the following topics:

Note:

Site Studio tags and helper methods are subject to change with each release of Site Studio. For information on tag library service caching see Section 1.9, "Understanding Service Caching with the Site Studio Tag Library."

7.1 Site Studio Tag Library

This topic provides information on the Site Studio tag library and provides descriptions and details for each tag.

7.1.1 Site Studio Tag Descriptions

This section lists each Site Studio tag and provides a brief description. See the specific tag for additional details.

Tag Description
wcm:context The Context tag creates a new SiteContext object and sets it on the current HttpServletRequest. This overrides any existing SiteContext already present. Subsequent calls to any Site Studio API or tag will use this context.
wcm:dataFile The Data File tag loads content from the content server and parses it into a DataFile object. The object is then exposed as a variable to be used by the Expression Language (EL) to access the individual components of the data file.
wcm:dynamicConversion The Dynamic Conversion tag is used to specify the conversion rule to use when creating a dynamic conversion of a native document.
wcm:dynamicList The Dynamic List tag executes the query from the dynamic list element specified that is in the region definition, and makes the results available in the variable var.
wcm:idcParameter The Idc Parameter tag is used in combination with the Idc Service tag to execute a IDC service call on the content server. Takes a name/value pair.
wcm:idcService The Idc Service tag is used in combination with the Idc Parameter tag to execute a IDC service call on the content server.
wcm:metadata The Metadata tag performs a DOC_INFO service call for the content item, and makes the resulting DataBinder available containing the document information about the given content item.
wcm:placeholder The Placeholder tag is used to specify where an item will be inserted in a template. This will typically be content, but it can also be navigation, code, subtemplates, etc.
wcm:staticPlaceholder The Static Placeholder tag can be used to add a placeholder with a fixed data file. This is useful for content that does not change, such as headers and footers.
wcm:url The URL tag renders either hierarchical links into the site structure or links to content server content.

7.1.2 Site Studio <wcm:context> Tag

The Context tag creates a new SiteContext object and sets it on the current HttpServletRequest. This overrides any existing SiteContext already present. Subsequent calls to any Site Studio API or tag will use this context.

If the context is not initialized from the current path (initFromPath is false or not specified), then the new SiteContext will have the same site ID and same URL (unless specified) as the existing SiteContext, if available.

Parameters

  • siteID: The site identifier. Required.

  • url: The site path. This is a portion of path minus the site ID (for example, /about/index.html. Required.

  • initFromPath: Set to true to initialize the context from the current HttpServletRequest path (the url parameter is then ignored).

Example

Initialize a new context to the primary page of the about section for site ID "mysite":

<wcm:context siteID="mysite" url="/about/index.html" />

Reset the current SiteContext to a new URL, without specifying the site ID:

<wcm:context url="/index.html" />

7.1.3 Site Studio <wcm:dataFile> Tag

The Data File tag loads content from the content server and parses it into a DataFile object. The object is then exposed as a variable to be used by the Expression Language (EL) to access the individual components of the data file. Typically the wcm:dataFile tag is used on a region template, to load the assigned DataFile for display.

The DataFile object implements the Map interface, allowing access to all members by the element name. There are two types of elements that can be retrieved:

  • TextElement: The text content.

  • ListElement: The static list content. The ListElement implements the List interface, which each member of the list a map of TextElements.

Parameters

  • var: The variable name of the resulting DataFile object. Required.

  • dataFile: The content ID of the data file. If not specified, it uses the currently assigned ID for the current placeholder if called from within a wcm:placeholder tag. Optional.

Example

Assume the data file, with a content ID of AWARDS has the following shape:

<?xml version="1.0" encoding="UTF-8"?>
<root xmlns="http://www.stellent.com/wcm-data/ns/8.0.0" version="8.0.0.0">
  <element name="title">Awards</wcm:element>
  <list name="list">
    <row>
      <element name="name">2007 Outstanding Organization Award</element>
    </row>
    <row>
      <element name="name">2006 Top 50 Company</element>
    </row>
  </list>
</root

From a region template, load the assigned data file:

<wcm:dataFile var="dataFile" />

Alternatively, load the data file by specifying the content ID:

<wcm:dataFile var="dataFile" contentID="" />

Model the data into some HTML:

<h2>${title}</h2>
<ul>
<c:forEach var="row" items="${dataFile.list}">
  <li>${row.name}</li>
</c:forEach>
</ul>

7.1.4 Site Studio <wcm:dynamicConversion> Tag

The Dynamic Conversion tag is used to specify the conversion rule to use when creating a dynamic conversion of a native document.

Parameter

  • rule: The name of the dynamic conversion rule as defined in the ConversionsDefinition file. Required.

    From View > Property Inspector > Rule > Edit you can select a rule for the dynamic conversion tag. If a rule is not selected, the default rule is used.

  • page: The page number to display. Optional.

  • var: Variable to assign the output of the dynamic conversion. If not specified, the output of the conversion will be written to the page directly. Optional.

  • dataFile: The dDocName (content ID) of the item to convert. If not specified, the data file assigned to the current placeholder will be used. Optional.

Example

Convert the current data file using the rule ruleName:

<wcm:dynamicConversion rule="ruleName" />

Convert the data file MY_WORD_DOC using the rule ruleName:

<wcm:dynamiConversion dataFile="MY_WORD_DOC" rule="ruleName" />

7.1.5 Site Studio <wcm:dynamicList> Tag

The Dynamic List tag executes the query from the dynamic list element specified that is in the region definition, and makes the results available in the variable var.

Parameters

  • element: Name of the element within the list used to construct the list element. Required.

  • var: A dynamic list variable. Required.

  • dataFile: The data file assigned to the placeholder rendering this dynamic list. Optional.

  • placeholder: The name of the placeholder rendering this dynamic list. Optional.

Example

Query using the assigned data file in a region template:

<wcm:dynamicList element="example" var="example"/>

Model the results:

<ul>
<c:forEach var="row" items="${example.resultSets.SearchResults.rows}">
  <li>${row.dDocName} - ${row.dDocTitle}</li>
</c:forEach>
</ul>

7.1.6 Site Studio <wcm:idcParameter> Tag

The Idc Parameter tag is used in combination with the Idc Service tag to execute a IDC Service call on the content server. Takes a name/value pair.

Important: Parameters will vary depending on the service called. Refer to the Oracle WebCenter Content Services Reference Guide for the list of service calls and parameters.

Parameters

  • name: The IDC Parameter. Enter the parameter for the IDC Service call made on the content server. Use the Site Studio IdcService Tag to define the IDC Service call to be executed on the content server. Required.

  • value: An Idc Parameter variable. Enter a valid value for this parameter. Required.

  • file: If true, the value parameter specifies a path (either a local file path or a relative file path in this web application) and will be added to the DataBinder as a file object. Optional.

Example

This example used both the Idc Service tag and Idc Parameter tag. In this example, the CHECKIN_UNIVERSAL service is called and the parameters for the service are defined using name/value pairs.

  • The doFileCopy parameter is set to TRUE (1), so the file will not be deleted from hard drive after successful check in.

  • The dDocName parameter defines the Content ID.

  • The dDocTitle parameter defines the Title.

  • The dDocType parameter defines the Type.

  • The dSecurityGroup parameter defines the Security Group.

  • The dDocAuthor parameter defines the Author.

  • The primaryFile parameter defines original name for the file and the absolute path to the location of the file as seen from the server.

<wcm:idcservice service="CHECKIN_UNIVERSAL" var="callStatus"
  <wcm:idcparameter name="doFileCopy" value="1"/>
  <wcm:idcparameter name="dDocName" value="RemoteTestCheckin23"/>
  <wcm:idcparameter name="dDocTitle" value="Test1"/>
  <wcm:idcparameter name="dDocType" value="ADACCT"/>
  <wcm:idcparameter name="dSecurityGroup" value="Public"/>
  <wcm:idcparameter name="dDocAuthor" value="sysadmin"/>
  <wcm:idcparameter name="primaryFile" value="C:/inetpub/Scripts/query2.asp"/>
/>

This example shows how to get data back from the service call:

<wcm:idcService service="DOC_INFO_BY_NAME" var="docinfo">
  <wcm:idcParameter name="dDocName" value="DATAFILE1234" />
  <wcm:idcParameter name="RevisionSelectionMethod" value="LatestReleased" />
</wcm:idcService>
<c:forEach var="row" items="${docinfo.resultSets.DOC_INFO.rows}">
  <p>The content item <em>${row.dDocName}</em> is a
  <u>${row.xWebsiteObjectType}</u></p>
</c:forEach>

7.1.7 Site Studio <wcm:idcService> Tag

The Idc Service tag is used in combination with the Idc Parameter tag to execute a IDC service call on the content server.

Important: Parameters will vary depending on the service called. Refer to the Oracle WebCenter Content Services Reference Guide for the list of service calls and parameters.

Parameters

  • service: The Idc Service. Enter the IDC Service call to be executed on the content server. The service call returns a data binder. Use the Site Studio IdcParameter tag to set parameters for the service call. Required.

  • var: An Idc Service variable. Enter a name for the variable that will hold the results of the returned response from the content server. Required.

  • type: If set to stream, the response from the content server is an InputStream object. By default, the response is a oracle.stellent.ridc.model.DataBinder. Optional.

Example

This example used both the Idc Service tag and Idc Parameter tag. In this example, the CHECKIN_UNIVERSAL service is called and the parameters for the service are defined using field/value pairs

  • The doFileCopy parameter is set to TRUE (1), so the file will not be deleted from hard drive after successful check in.

  • The dDocName parameter defines the Content ID.

  • The dDocTitle parameter defines the Title.

  • The dDocType parameter defines the Type.

  • The dSecurityGroup parameter defines the Security Group.

  • The dDocAuthor parameter defines the Author.

  • The primaryFile parameter defines original name for the file and the absolute path to the location of the file as seen from the server.

<wcm:idcservice service="CHECKIN_UNIVERSAL" var="callStatus"
  <wcm:idcparameter name="doFileCopy" value="1"/>
  <wcm:idcparameter name="dDocName" value="RemoteTestCheckin23"/>
  <wcm:idcparameter name="dDocTitle" value="Test1"/>
  <wcm:idcparameter name="dDocType" value="ADACCT"/>
  <wcm:idcparameter name="dSecurityGroup" value="Public"/>
  <wcm:idcparameter name="dDocAuthor" value="sysadmin"/>
  <wcm:idcparameter name="primaryFile" value="C:/inetpub/Scripts/query2.asp"/>
/>

This example shows how to get data back from the service call:

<wcm:idcService service="DOC_INFO_BY_NAME" var="docinfo">
  <wcm:idcParameter name="dDocName" value="DATAFILE1234" />
  <wcm:idcParameter name="RevisionSelectionMethod" value="LatestReleased" />
</wcm:idcService>
<c:forEach var="row" items="${docinfo.resultSets.DOC_INFO.rows}">
  <p>The content item <em>${row.dDocName}</em> is a
  <u>${row.xWebsiteObjectType}</u></p>
</c:forEach>

7.1.8 Site Studio <wcm:metadata> Tag

The Metadata tag performs a DOC_INFO service call for the content item, and makes the resulting DataBinder available containing the document information about the given content item.

Parameters

  • contentID: The content ID. Required.

  • var: The metadata variable. Required.

Example

<wcm:metadata contentID="DATAFILE1234" var="metadata"/>
<c:forEach var="metadatarow" items="${metadata.resultSets.DOC_INFO.rows}">
  <p>The content item <em>${metadatarow.dDocName}</em> is a
  <u>${metadatarow.xWebsiteObjectType}</u></p>
</c:forEach>

You can also use the data file on a region template rather than a fixed ID, for example:

<wcm:metadata contentID="${wcmContext.placeholder.dataFile}" var="meta"/>

7.1.9 Site Studio <wcm:placeholder> Tag

The Placeholder tag is used to specify where an item will be inserted in a template. This will typically be content, but it can also be navigation, code, subtemplates, etc.

Parameters

  • name: The name of the placeholder. Required.

  • location: The location on the template. Optional.

  • definition: Specifies the mapping to a placeholder definition, which overrides any mappings specified in other ways. Optional.

  • template: The region template to use to render the Data File. Optional.

  • dataFile: The dDocName of the data file to assign to this placeholder. Optional.

  • regionDefinition: The dDocName region definition to use, instead of the xRegionDefinition on the data file. Optional.

  • actions: The allowed actions of the placeholder definition. Any number of actions can be set. If you use parameters that do not work together (for example, specifying a subtemplate as well as a region definition), then the tag will execute based on the order of parameters listed above. Optional.

    • Update [E]: Allows contributor update.

    • Approve [A]: Allows workflow approval.

    • Reject [R]: Allows workflow rejection.

    • Document Information [I]: Allows viewing document information.

    • Switch Data File [S]: Allows switching the data file.

    • View Usage Report [U]: Allows viewing the web usage report.

    • View tracker Report [T]: Allows viewing the web tracker report.

    • Update Document Information [M]: Allows updating the content information.

    • Switch Region Template [V]: Allows switching the region template.

    • Remove Content [N]: Allows content removal by the contributor.

Example

<wcm:placeholder name="yourplaceholdername" actions="E"/>
<wcm:placeholder name="yourplaceholdername" actions="EPRISUTMVN"/>

7.1.10 Site Studio <wcm:staticPlaceholder> Tag

The Static Placeholder tag can be used to add a placeholder with a fixed data file. This is useful for content that does not change, such as headers and footers.

Parameters

  • dataFile: The dDocName (content ID) of the data file to assign to this static placeholder. Required.

  • name: The name of the static placeholder. Optional.

  • template: The region template to use to render the data file. Optional.

  • actions: The allowed actions of the placeholder definition. Any number of actions can be set. If you use parameters that do not work together (for example, specifying a subtemplate as well as a region definition), then the tag will execute based on the order of parameters listed above. Optional.

    • Update [E]: Allows contributor update.

    • Approve [A]: Allows workflow approval.

    • Reject [R]: Allows workflow rejection.

    • Document Information [I]: Allows viewing document information.

    • View Usage Report [U]: Allows viewing the web usage report.

    • View tracker Report [T]: Allows viewing the web tracker report.

    • Update Document Information [M]: Allows updating the content information.

    • Switch Region Template [V]: Allows switching the region template.

Example

<wcm:staticPlaceholder datafile="yourdatafile" actions="E"/>
<wcm:staticPlaceholder datafile="yourdatafile" actions="EPRIUTMV"/>

7.1.11 Site Studio <wcm:url> Tag

The URL tag renders either hierarchical links into the site structure or links to content server content.

Parameters

  • var: The variable name to store the link result.

  • type: The type of link. Required.

    • node: Defines a URL for a node.

    • dcresource: Defines a URL for a dynamic conversion resource. Only valid inside a placeholder tag.

    • dcpage: Defines a URL for a dynamic conversion page. Only valid inside a placeholder tag.

    • rendition: Defines a URL for a rendition.

    • resource: Defines a URL for a resource. Used to link to weblayout static resources, such as images.

    • Link: Used to create links to content.

  • url: The link parameter (format dependent on the type). Required.

    • node: Format of nodeId|nodePath.

    • dcresource: Format of dcResourcePath.

    • dcpage: Format of dcPageNum.

    • rendition: Format of dDocName/renditionName.

    • resource: Format of dDocName or webLayoutPath.

    • Link: Format of dDocName or (nodeId|nodePath)/dDocName.

  • siteID: The site identifier for the link target. This consists of the section ID and the content ID for a site content item. For example, a section ID of 56 and content ID of TEST_ITEM.

Example

Create a link to the /About section (which has a section ID of 20):

<wcm:url var="url" type="node" url="/About" />
<wcm:url var="url" type="node" url="20" />

Create a link to a piece of content in the content server:

<wcm:url var="url" type="resource" 
  url="/groups/public/documents/document/news_article.doc" />

Url to a rendition of a content item::

<!--$wcmUrl("resource","dDocName")-->
<!--$wcmUrl("resource","groups/public/documents/adacct/mydocname.jpg")-->

Create a link to a piece of content to display inside a node (optionally specifying the section):

<wcm:url var="url" type="link" url="NEWS_ARTICLE" />
<wcm:url var="url" type="link" url="20/NEWS_ARTICLE" />

7.2 Site Studio Helper Methods

These Site Studio Helper Methods are available for scripting templates:

7.2.1 Site Studio <filterSections> Method

Filter a section list to remove inactive sections and contributor-only sections if not in contribution mode.

public static List<SectionNode> filterSections (SiteContext siteContext, List sections) { } 

Parameters

  • siteContext: The site context.

  • sections: A list of {@link SectionNode} objects.

  • stopLevel: The level to stop (inclusive).

  • includeHome: True to include the home section

Returns

  • sectionList: Return a list rows (represented as a list of sections).

Code

public static List<SectionNode> filterSections (SiteContext siteContext, List sections) { 
    if (sections == null) { 
      return null; 
  } 
 
    List<SectionNode> sectionList = new ArrayList<SectionNode> (sections.size ()); 
    for (Object sectionObj : sections) { 
   SectionNode section = (SectionNode)sectionObj; 
   if (!Boolean.parseBoolean (section.getModel ().getActive ())) { 
  continue; 
        } 
   if (Boolean.parseBoolean (section.getModel ().getContributorOnly ()) 
          && !siteContext.isContributorMode ()) { 
          continue; 
       } 
  
        //add the section to the list 
        sectionList.add (section); 
    } 
  
    return sectionList; 
} 

7.2.2 Site Studio <listSectionsForRows> Method

Create a list of sections matching the given parameters. Each row in the list will contain all sections at that level.

public static List listSectionsForRows (SiteContext siteContext, int startLevel, int stopLevel, boolean includeHome) { } 

Parameters

  • siteContext: The site context.

  • startLevel: The level to start (inclusive).

  • stopLevel: The level to stop (inclusive).

  • includeHome: True to include the home section.

Returns

  • rows: Return a list rows (represented as a list of sections).

Code

   public static List listSectionsForRows (SiteContext siteContext, int startLevel, int stopLevel, boolean includeHome) { 
        List<List<SectionNode>> rows = new ArrayList<List<SectionNode>> (); 
         //get the first level 
         if (startLevel < 1) { 
             startLevel = 1; 
         } 
         if (stopLevel < 1) { 
             stopLevel = 1; 
         } 
       Project project = siteContext.getProject (); 
        for (int i = startLevel; i <= stopLevel; i++) { 
             List<SectionNode> sections = project.getStructure ().getSectionsAtLevel (i); 
             if (sections.isEmpty ()) { 
                 //no more sections so we can end here 
                 break; 
             } 
             rows.add (sections); 
         } 
       if (startLevel == 1 && includeHome) { 
            List<SectionNode> nodes = null; 
             if (rows.size () >= 1) { 
                 nodes = rows.get (0); 
             } else { 
                 nodes = new ArrayList<SectionNode> (); 
                 rows.add (nodes); 
             } 
             nodes.add (0, project.getStructure ().getRootSection ()); 
        } 
         return rows; 
    } 

7.2.3 Site Studio <isNodeInNavigationPath> Method

Look to see if the current node is in the navigation path.

public static boolean isNodeInNavigationPath
(SiteContext siteContext, String nodeID, boolean includeHome) { } 

Parameters

  • siteContext: The site context.

  • nodeID: The node ID.

  • includeHome: True to include the home section in this check, false to exclude

Returns

  • isInNavPath: Returns true if the node ID is part of the current navigation path.

Code

    public static boolean isNodeInNavigationPath (SiteContext siteContext, String nodeID, boolean includeHome) {         if (nodeID == null) {             return false;         }          boolean isInNavPath = false;         SectionNode section = siteContext.getSection ();         if (section != null) {             isInNavPath = (section.getID ().equals (nodeID));              if (!isInNavPath) {                 for (SectionNode parent : section.getAncestors ()) {                     if (parent.getParent () == null && !includeHome) {                         continue;                     }                     isInNavPath = (parent.getID ().equals (nodeID));                     if (isInNavPath) {                         break;                    }                }             }          }            return isInNavPath;      } 

7.2.4 Site Studio <lookupSection> Method

Look up a section by path or ID.

public static SectionNode lookupSection (SiteContext siteContext, String id) { } 

Parameters

  • siteContext: The site context.

  • id: The section path or ID.

Returns

  • section: Return the section or null if not found.

Code

public static SectionNode lookupSection (SiteContext siteContext, String id) { 
         //see if this is a number 
         SectionNode section = null; 
         boolean isNumber = false; 
         try { 
           Integer.parseInt (id); 
           isNumber = true; 
        } catch (NumberFormatException exp) { 
             //ignored 
         } 
  
         if (isNumber) { 
             section = siteContext.getProject ().getStructure ().getSectionByID (id); 
         } else { 
             //fix up path 
           id = PathHelper.ensureForwardSlashes (id); 
            //handle relative 
             if (!id.startsWith ("/")) { 
                 //get the current section 
                 SectionNode current = siteContext.getSection (); 
                 if (current != null) { 
                     id = current.getUrlPath () + "/" + id; 
                 } 
             } 
           section = siteContext.getProject ().getStructure ().getSectionByPath (id); 
        } 
  
         return section; 
     }