6 Fragments

This section covers the following topics:

6.1 About Fragments

A fragment is a self-contained snippet of HTML or script (including client-side JavaScript and server-side Idoc) that may have value in being reused in more than one template on a web site.

A fragment may contain references to other files, too, with tags like <IMG SRC=xxx>, <SCRIPT SRC=xxx>, and <$ docLoadResource(xxx) $>. Externally referenced files or resources serve as a fragment asset and therefore need to be made available whenever the fragment is used.

Simple fragments may contain atomic content that can be inserted anywhere in a template. More complex fragments require some content to be placed in the <head> of the page and other content to be placed in the <body>. In the <body>, content may be placed at the top of the page, the bottom of the page, or at the cursor's current position. A fragment, therefore, may contain multiple fragment snippets.

While it is possible to include multiple <body> snippets with a <head> snippet, this is discouraged. Primarily because fragments that use the <head> of a page cannot be placed in a region template or a subtemplate. This is because neither region templates nor subtemplates are full HTML pages, and do not contain a <head>. Fragments should be created using just the <body> to best fit with the flexible nature of Site Studio architecture. Using just a <body> would allow the fragment to be used on page templates, subtemplates, and region templates.

A page template does contain a <head>, and fragments can have both a <head> and <body> when used in a fragment. However, these fragments will create an <ssinfo> XML data island. For more information, see Section 6.8, "Fragment Instance Structure in the <ssinfo> XML Data Island."

The designer may want a fragment to take on a different look and feel or behavior depending on where it is used on the web site. This functionality is made available by the use of fragment parameters. With fragment parameters, the creator of a fragment can specify certain variable parameters, and the site designer can choose from these parameters when the fragment is actually added to a template.

From a high level, fragments contain:

  • Zero or more fragment parameter definitions (name, type, default value) that are referenced in the fragment snippets but declared uniquely on each page that includes the fragment instance.

  • One or more fragment snippets, which are pieces of HTML or script along with an identifier to indicate where that content should be placed when the fragment is added to a template.

  • Zero or more fragment assets, which are the local files referenced by a fragment that will be made available to the fragment when it is used on a web page.

It is common for a fragment to consist of two snippets. The first, usually found in the <head> of the page, may reference a CSS file, which will format the page, or a JavaScript file, which will provide some or all of the fragment's implementation. The second, usually found in the <body> of the page at the drop-point, contains the presentation for the fragment. It may be as simple as a JavaScript call of a method provided by the included .js file, or it may contain a collection of HTML, JavaScript, and Idoc Script.

6.2 Fragment Libraries

Site Studio stores individual fragments in fragment libraries. You can store each fragment in its own library or store related fragments together in the same library. Fragment libraries are stored as managed objects in the content server in the following way:

  • Primary file: a zip file containing all of the assets required by each fragment in the fragment library.

  • Alternate file: a fragment definition file that defines the entire structure of each fragment in the fragment library.

Oracle Content Server manages content items as either primary or alternate files, or both (see Oracle Content Server Help). These files are unrelated to, and should not be confused with, primary and secondary pages in Site Studio.

Note:

The fragment asset zip file that is checked in as the Primary file above should not be confused with a fragment library zip file that contains both the fragment assets and the fragment definition file. The fragment library zip file is what is used with the Designer's Upload and Download fragment library utilities and provides a simpler way to manage fragment libraries. You will only need to manage fragment asset zip files if you are accessing the managed fragment libraries directly in the content server instead of using the Designer's fragment management utilities.

The fragment definition file contains the root element <fragments>, which includes one or more <fragment> elements to define each fragment in the library. The exact syntax of the fragment definition file is described in the Fragment Definition File. For more information, see Section 6.7, "The Fragment Definition File."

To add a fragment library to the content server, you won't use the standard content server check-in page. Instead, you use the "Upload Fragment Library feature in Designer. This feature checks in the managed content items and ensures that a copy of the fragment asset zip file is extracted to the appropriate runtime weblayout directory (where CS_name is the name of your content server):

CS_name\weblayout\fragments

This path can then be referenced by server-side Idoc Script in a fragment by using one of two Idoc variables:

  • HttpFragmentsRoot: the full HTTP path to the fragments folder.

  • HttpRelativeFragmentsRoot: the relative HTTP path to the fragments folder.

6.3 Read-Only Fragment Libraries

The root <fragments> element within the fragment definition files (sample fragments) that ship with the product are given a read-only attribute to prevent them from being edited or erased within the Designer application. There is no GUI exposed to set or clear this attribute: it is simply intended to avoid changes being made to the out-of-the-box fragments because they will be overridden when upgrading to future versions of Site Studio.

Designers, of course, can copy and edit these fragments and make modifications to their own copy.

6.4 Fragment Inclusion Using wcmFragment

While the Toolbox allows for quick and simple drag-and-drop placement of fragments on a template, some prefer to use the scripting method to place a fragment directly in the source.

The wcmFragment script is used on templates to add a fragment. If the tag is used on a region template or subtemplate, only the first drop-point snippet will be used.

If the tag is used on a page template, then a legacy <ssinfo> XML data island is inserted by Site Studio. For more information, see Section 6.8, "Fragment Instance Structure in the <ssinfo> XML Data Island."

Parameters

  • fragmentInstanceId: ID of the fragment instance on the page. Used to differentiate fragments that have multiple pages of returns, such as dynamic lists. The ID allows the dynamic lists to display different 'pages' of query results. For instance, one fragment can be on page 1 of its query results, while the other can display page 3 of its own results. If the same ID is used for both fragments, then clicking to a particular page of results for one query will cause the other fragment to display the same page number of its own results.

  • fragmentDocName: dDocName of the fragment library.

  • fragmentId: ID of fragment within the named library.

  • snippetId: ID of snippet within the named fragment.

  • tagProperties: The named value pairs of properties of the fragment.

Code Example

<!--$wcmFragment("fragmentInstanceID", "fragmentDocName", "fragmentID", "snippetID", "ssTheme=default", "ssHoverColor=", "ssTextColor=", "ssFocusColor=", "ssShowHome=true", "ssShowNext=false", "ssClassName=IDocNavTabsTop")-->

6.5 Fragment Snippets and the ssIncludeXml()

Each fragment contains a snippet defined by the fragment definition file for the fragment library. A fragment snippet can be included in a fragment in one of three ways:

  • simple: the fragment snippet is added directly to the layout page with no additional markup and is no longer recognized or managed as a fragment.

  • inline: the fragment snippet is added directly to the layout page but with special markup surrounding it so that it can be recognized and managed as a fragment.

  • reference: the fragment snippet is not actually added to the layout page; rather, a reference to the snippet is added (much like an include file) along with surrounding markup so that it can be recognized and managed as a fragment.

It is highly recommended that you use reference as the include mechanism for all but the most trivial of snippets. This way you can manage the snippet content in a single place even if the fragment is used many times across the site.

The exact syntax for the special markup surrounding inline and reference snippets can be found in Section 9.14, "ssIncludeXml." For snippets included by reference, the snippet is added to the layout page using a script extension called ssIncludeXml().

This script extension provides an Idoc mechanism for including elements from a managed XML file and placing them in a layout page. The parameters for the ssIncludeXml() include the dDocName of the fragment definition file of the fragment library and an XPath expression for the XML node to be extracted. (More parameters are explained in Section 9.14, "ssIncludeXml"). The content of the XML node extracted is further evaluated in the scope of the current template and therefore can include additional server-side Idoc Script, if necessary.

6.6 Fragments That Use Custom Section Properties

Custom section properties can be defined by the Designer and unique values can be assigned to each property for each section of the web site (see the Oracle Fusion Middleware User's Guide for Site Studio Designer). The definitions and the values are stored in the web site project file.

By themselves, custom section properties are useless. Only when a custom property is referenced by client-side or server-side script within a layout page (or more typically, within a fragment snippet), does it become useful. There are two primary ways to access custom section property values: client-side JavaScript and server-side Idoc Script.

6.6.1 Client-Side JavaScript

The client-side runtime generated file sitenavigation.js contains an array of NavNode objects containing a definition for the current web site hierarchy (See Section 5.2.1, "sitenavigation.js"). Each custom section property that has a value for the current section will be contained within the NavNode object for that section in a member variable whose name begins with cp_.

The most typical use of these client-side representations of the custom section properties is within navigation fragments. When a navigation fragment is iterating through the NavNode objects, it can detect the existence of the cp_XXX member variables and use them to customize the navigation scheme being displayed. Since the cp_XXX member variable may or may not exist, accessing the parameter is made easier through the use of two JavaScript methods provided by Site Studio:

  • customSectionPropertyExists (prop): returns true or false to indicate whether the custom section property exists; if this method returns true, you can use the custom section property directly.

  • getCustomSectionProperty (prop): returns the value for the custom section property, if it exists; returns an empty string otherwise.

You can see these two methods in action in the CSP Sample Navigation (client) fragment that ships with Site Studio (for more information, see the Oracle Fusion Middleware User's Guide for Site Studio Designer).

6.6.2 Server-Side Idoc Script

There are a number of ways to access custom section properties using server-side Idoc Script:

  • ssGetNodeProperty(name): this script extension retrieves the value for the named property for the current web site section.

  • ssGetNodeProperty (nodeId, name): this script extension retrieves the value for the named property for the specified web site section.

  • SS_GET_ALL_NODE_PROPERTIES service: this service retrieves a list of all custom section properties for the specified web site section.

You can see these in action in the CSP Sample Navigation (server), CSP Sample Dynamic List, and Sample CSP Page Title fragments, which ship with Site Studio (see "Sample fragments" in the Oracle Fusion Middleware User's Guide for Site Studio Designer).

The custom section properties are also stored in the XML rendition of the site hierarchy in the sitenavigation.xml file (see Section 5.2.3, "sitenavigation.xml"). So if you are building a navigation fragment that uses server-side script to parse this XML file, you will also have access to the custom section properties for each section.

The name of the property MUST be in quotes. Thus, if you wanted to get the label property of a specific node, you would write:

<!--$label = ssGetNodeProperty(nodeId, "label")-->

6.7 The Fragment Definition File

A fragment definition file is a pure XML file containing content that inherits its structure from the contribution region that the file is assigned to. From a coding view, a fragment definition file for a fragment library looks like this:

<fragments>
  <fragment>

    <parameters>
     <parameter> param definition goes here </parameter>
     <parameter> another param def goes here </parameter>
    </parameters>

    <snippets>
     <snippet> HTML snippet goes here </snippet>
     <snippet> another HTML snippet goes here </snippet>
    </snippets>

    <elements>
     <element> element definition goes here </element>
     <element> another element def goes here </element>
    </elements>

    </fragment>
</fragments>

The fragment definition file typically contains the following tags:

6.7.1 <fragments>

The <fragments> tag represents a fragment library.

Parameters

  • id: a unique name or identifier for the fragment library.

  • name: the display name for the fragment library.

  • readonly: can be set to True to prevent the fragments in the library from being edited in Designer.

The <fragments> tag contains a collection of one or more <fragment> child tags.

6.7.2 <fragment>

The <fragment> tag represents a single fragment definition.

Parameters

  • id: a unique name or identifier for the fragment. It is used in XPath expressions when including snippets by reference.

  • name: the displayed name for the fragment.

  • language: the server-side language for the fragment implementation. The languages available are idoc, asp or jsp.

  • type: the type for this fragment. It is used to determine which category in the Designer Toolbox the fragment should display in. It also determines whether the fragment is a static list or dynamic list. The available types are navigation, staticlist, dynamiclist, or other.

  • icon: the name of the icon to use in the Designer Toolbox for this fragment. There is a predefined list of fragment icons to choose from:

    Icon name Image
    region region
    wysiwyg wysiwyg
    plaintext plaintext
    image1 image1
    image2 image2
    list1 list1
    list2 list2
    list3 list3
    list4 list4
    list5 list5
    list6 list6
    tree tree
    horizontalrule horizontalrule
    nonbreakingspace nonbreakingspace
    linebreak linebreak
    span span
    div div
    heading1 heading1
    heading2 heading2
    heading3 heading3
    heading4 heading4
    heading5 heading5
    heading6 heading6
    copyright copyright
    flash flash
    companylogo companylogo
    documents documents

Child Tags

The <fragment> tag contains the following child tags:

6.7.3 <parameter>

The <parameter> tag represents a single parameter of a fragment. Its attributes are:

Parameters

  • name: the parameter name.

  • type: the parameter type, of which there are several:

    • text: a simple text parameter that may contain a predefined list of choices using one or more <option> child tags.

    • bigtext: a multi-line text parameter.

    • boolean: a simple True/False parameter.

    • integer: a simple integer parameter.

    • float: a simple floating point parameter.

    • size: a parameter representing an HTML size (10px, 50%, 3pt, and so forth).

    • color: a color value, either in RGB or an HTML color name.

    • url: a URL.

    • manageddoc: the dDocName of a managed document in Oracle Content Server, selected through the Search Results page. The query parameters can be specified using the <querytext> child tag.

    • managedurl: the DocUrl of a managed document in Oracle Content Server, selected through the Search Results page. The query parameters can be specified using the <querytext> child tag.

    • managedquery: a query text string, selected through the CAPTURE_QUERY page.

    • cssstyle: a text parameter that represents a CSS style attribute. This type behaves like the "text" type. (It is intended for future use.)

    • siteid: a siteId value for one of the web sites on the same instance of the content server, selected through the Select Site dialog.

    • nodeid: a nodeId value for one of the sections in the web site, selected through a site hierarchy in the Select Section dialog.

    • custom: a parameter that provides its own custom GUI for entering values using the <customgui> child tag.

  • description: the description of the parameter to appear in the Fragment Parameter Values dialog.

  • required: a true or false value that determines if the parameters for a fragment are required before that fragment can be added to a layout page.

  • optionsonly: a True or False value that applies only if one or more <option> child tags is supplied with possible predefined options.

The <parameter> tag may contain text representing the default value (if any) for the parameter. It may also contain the following optional child tags:

  • <option>: use one or more option tags to specify a list of predefined choices for parameters of type text. For more information, see Section 6.7.3.1, "<option>."

  • <querytext>: contains the QueryText value for parameters of type manageddoc and managedurl. For more information, see Section 6.7.3.2, "<querytext>."

  • <validate>: contains a customized script function for validating the parameter. For more information, see Section 6.7.3.3, "<validate>."

  • <convert>: contains a customized script function for converting the parameter before inserting it. For more information, see Section 6.7.3.4, "<convert>."

  • <customgui>: contains a customized HTML snippet to provide its own GUI for entering parameter values. For more information, see Section 6.7.3.5, "<customgui>."

6.7.3.1 <option>

The <option> tag represents a single option in a choice list and applies only to parameters of the type text. The <option> tag should contain text that will display in the choice list. Its single attribute is:

  • value: the value to be inserted if this option is chosen. This attribute is optional if the value displayed in the option is the same as the value to be inserted.

For example:

<option>Option 1</option>
<option>Option 2</option>
<option>Option 3</option>
<option>Option 4</option>

or

<option value="A">Option A</option>
<option value="B">Option B</option>
<option value="C">Option C</option>
<option value="D">Option D</option>

6.7.3.2 <querytext>

The <querytext> tag represents the query parameter to use when performing a search in the content server and applies only to parameters of the type manageddoc or managedurl. The tag contains the query text within a CDATA section. It has no attributes.

For example:

<querytext>
  <![CDATA[
     dExtension <matches> `gif` <or> dExtension <matches> `jpg`
  ]]>
</querytext>

6.7.3.3 <validate>

The <validate> tag is optional and represents a customized script routine that can be provided to validate a parameter before it is inserted into the fragment snippets. The script routine can be written in any WSH-compatible scripting language (VBScript or JScript) and must contain a single function named validate that takes a single string as input.

The return value for the function will be either:

  • boolean: True/False, to represent a valid or invalid parameter.

    or

  • string: returns an empty string if the parameter is valid, and an error message if the parameter is invalid.

The <validate> tag contains the script within a CDATA section. Its single attribute is:

  • language: the language used for this script is VBScript or JScript.

For example:

<validate language="VBScript">
  <![CDATA[
    Function validate(strInput)
     If InStr(strInput, "hello") > 0 Then
      validate = ""
     Else
      validate = "Error, ValidatedParam must contain " _
      "the text 'hello' somewhere in the string"
     End If
    End Function
  ]]>
</validate>

Note:

The <validate> tag is operational, but it is not exposed in the Fragment Editor user interface. It is, therefore, currently unsupported.

6.7.3.4 <convert>

The <convert> tag is optional and represents a customized script routine that can be provided to convert a parameter as it is inserted into the fragment snippet. The script routine can be written in any WSH-compatible scripting language (VBScript or JScript) and must contain a single function named convert that takes a single string as input and returns the converted string as output.

The <convert> tag contains the script within a CDATA section.

Parameters

  • language: the language used for this script is VBScript or JScript.

For example:

<convert language="VBScript">
  <![CDATA[
    Function convert(strInput)
     If StrComp(strInput, "") = 0 Then
      convert = "(empty)"
     Else
      convert = "Your Value Was [" & strInput & "]"
     End If
    End Function
  ]]>
</convert>

Note:

The <convert> tag is operational, but it is not exposed in the Fragment Editor user interface. It is, therefore, currently unsupported.

6.7.3.5 <customgui>

The <customgui> tag is used only for parameters of type custom. It allows fragment designers to provide their own (simple) GUI for entering a fragment parameter. It contains an HTML snippet in a CDATA section that can contain any standard HTML or JavaScript.

It interacts with Site Studio through four JavaScript methods.

  • window.external.GetValue(): the method used to obtain an initial value for the parameter. The custom parameter starts off the same, as a plain text parameter, but it has a button (Figure 6-1) in the edit field to bring up the custom GUI. This method gets the current value from the edit field.

Figure 6-1 Edit Field Custom GUI Button

Edit Field
  • window.external.SetValue(): the method used to set a new value in the edit field.

  • window.external.OnOK(): the method used to tell Site Studio it has finished and that it should accept the values passed to it by the SetValue() method.

  • window.external.OnCancel(): the method used to tell Site Studio it has finished but that it should ignore the values passed to it, if any, by the SetValue() method.

For example:

<customgui>
 <![CDATA[
  <HTML>
  <HEAD>
  <SCRIPT language="javascript">
   function initialize()
   {
    strResult = window.external.GetValue() + "00000";
    bold.checked = (strResult.charAt(0) == "1");
    italic.checked = (strResult.charAt(1) == "1");
    underlined.checked = (strResult.charAt(2) == "1");
    font.checked = (strResult.charAt(3) == "1");
   }
   function getvalue()
   {
    strResult = "";
    strResult = strResult + (bold.checked ? "1" : "0");
    strResult = strResult + (italic.checked ? "1" : "0");
    strResult = strResult + (underlined.checked ? "1" : "0");
    strResult = strResult + (font.checked ? "1" : "0");
    return strResult;
   }
  </SCRIPT>
  </HEAD>
  <BODY onload="initialize();">
    Welcome to my Customized Parameter Input Screen. This example
    could perhaps be used as a starting point for entering the
    contribution suppression flags.<BR>
    <TABLE>
     <TR>
      <TD>Allow BOLD</TD>
      <TD><INPUT type="checkbox" id="bold"></TD>
     </TR>
     <TR>
      <TD>Allow ITALIC</TD>
      <TD><INPUT type="checkbox" id="italic"></TD>
     </TR>
     <TR>
      <TD>Allow UNDERLINED</TD>
      <TD><INPUT type="checkbox" id="underlined"></TD>
     </TR>
     <TR>
      <TD>Allow Font Changes</TD>
      <TD><INPUT type="checkbox" id="font"></TD>
     </TR>
     <TR><TD COLSPAN="2">&nbsp;</TD></TR>
     <TR>
      <TD COLSPAN="2">
       <INPUT type="button" value="OK"
         onclick="window.external.SetValue(getvalue()); window.external.OnOK();"/>
       <INPUT type="button" value="Cancel"
         onclick="window.external.OnCancel();"/>

      </TD>
     </TR>
    </TABLE>
   </BODY>
 ]]>
</customgui>

Note:

The <customgui> tag is operational, but it is not exposed in the Fragment Editor user interface. It is, therefore, currently unsupported.

6.7.4 <snippet>

The <snippet> tag represents a single snippet of a fragment.

Parameters

  • id: the unique identifier for the snippet in the fragment definition.

  • location: the location in the layout page where the snippet should be placed. There are four locations: head, topofbody, drop-point, and bottomofbody

  • include: how the snippet should be included in a template:

    • simple: copy the contents of the snippet directly into the template (do not mark up the snippet with fragment instance details), and replace parameters directly inline by searching for %paramname% in the snippet content when it is first inserted.

    • inline: copy the contents of the snippet directly into the template and mark the content as a fragment instance snippet so that it can be treated atomically and moved, edited, and deleted as a fragment snippet.

    • reference: insert an ssIncludeXml() call into the template and mark it as a fragment instance snippet so that it can be treated atomically and moved, edited, and deleted as a fragment snippet.

The <snippet> tag contains a single complete snippet of HTML or script that makes up a single atomic piece of the fragment content. The snippet content is contained within a CDATA section. Additionally, the tag may contain the following optional child tags:

  • <designview>: a design-time representation of the snippet that will be shown in design view in Designer.

6.7.5 <designview>

The <designview> tag represents an optional design-time view of a fragment snippet that will be shown in the Design view in Designer (the default display will be the fragment name). The tag contains HTML within a CDATA section. It has no attributes.

For example:

<designview>
   <![CDATA[
     example copyright fragment goes here
   ]]>
</designview>

6.7.6 <element>

The <element> tag represents a simple element contained in a static list fragment definition. The syntax for the <element> tag in a <fragment> definition tag is identical to the syntax of the <element> tag used in a <region> definition tag in a layout page.

Only elements of type 1, 4, 5, and 6 (wysiwyg, custom, image, and plaintext) are allowed as elements within a static list fragment definition.

6.8 Fragment Instance Structure in the <ssinfo> XML Data Island

The structure that defines a fragment instance and its parameters is maintained in the <ssinfo> XML data island by the Designer application. The data island contains a single <fragmentinstance> tag for every instance of a fragment on a page template, and each tag contains some Idoc Script that declares the fragment instance parameters. The <ssinfo> data island will appear only when a fragment with a <head> snippet is added to a page template. Fragments added to region templates and subtemplates will not generate an <ssinfo> XML data island.

Advanced fragment types, such as static and dynamic lists, may have additional child tags in the <fragmentinstance> tag. For the exact syntax for these tags and their attributes, see the Technical Reference Guide for Site Studio 10gR3.