|Oracle® Fusion Middleware Technical Reference Guide for Site Studio
11g Release 1 (11.1.1)
Part Number E10615-02
This section covers the following topics:
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.
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:
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):
This path can then be referenced by server-side Idoc Script in a fragment by using one of two Idoc variables:
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.
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."
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.
<!--$wcmFragment("fragmentInstanceID", "fragmentDocName", "fragmentID", "snippetID", "ssTheme=default", "ssHoverColor=", "ssTextColor=", "ssFocusColor=", "ssShowHome=true", "ssShowNext=false", "ssClassName=IDocNavTabsTop")-->
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.
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.
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_.
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).
There are a number of ways to access custom section properties using server-side Idoc Script:
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")-->
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:
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.
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:
<parameters>: a collection of zero or more parameters. For more information, see Section 6.7.3, "<parameter>."
<snippets>: a collection of zero or more snippets. For more information, see Section 6.7.4, "<snippet>."
<elements>: a collection of zero or more elements. For more information, see Section 6.7.6, "<element>."
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.
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.
<option>: use one or more option tags to specify a list of predefined choices for parameters of type text. For more information, see Section 22.214.171.124, "<option>."
<querytext>: contains the QueryText value for parameters of type manageddoc and managedurl. For more information, see Section 126.96.36.199, "<querytext>."
<validate>: contains a customized script function for validating the parameter. For more information, see Section 188.8.131.52, "<validate>."
<convert>: contains a customized script function for converting the parameter before inserting it. For more information, see Section 184.108.40.206, "<convert>."
<customgui>: contains a customized HTML snippet to provide its own GUI for entering parameter values. For more information, see Section 220.127.116.11, "<customgui>."
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.
<option>Option 1</option> <option>Option 2</option> <option>Option 3</option> <option>Option 4</option>
<option value="A">Option A</option> <option value="B">Option B</option> <option value="C">Option C</option> <option value="D">Option D</option>
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.
<querytext> <![CDATA[ dExtension <matches> `gif` <or> dExtension <matches> `jpg` ]]> </querytext>
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.
string: returns an empty string if the parameter is valid, and an error message if the parameter is invalid.
language: the language used for this script is VBScript or JScript.
<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.
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.
language: the language used for this script is VBScript or JScript.
<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.
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.
Note:The <customgui> tag is operational, but it is not exposed in the Fragment Editor user interface. It is, therefore, currently unsupported.
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
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.
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.
<designview> <![CDATA[ example copyright fragment goes here ]]> </designview>
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.
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.