This section covers the following topics:
The site assets in Site Studio allow for a very modular, customizable method of easily maintaining the content separate from the presentation. The relationship between the templates and the definitions, such as how they are connected across many different pages, may be necessary to know when you want to make specific changes to individual assets in the site.
Site assets are used to directly control the visual presentation of the site, and the actual content on the web pages (the "information"). In this way, the content and the presentation are separate, and can be maintained and modified without affecting each other.
The files that maintain the structure and presentation of the web site are the templates: page templates, subtemplates, and region templates. Cascading style sheets can also be used to control structure and presentation and managed with Site Studio. The files that maintain the content are the definitions: placeholder definitions, region definitions, and element definitions. With these definitions, you control how the content is maintained.
The content itself is stored in content files: contributor data files, native documents, images, and any other related media (such as Flash) which you may use on your site. Contributor data files are XML formatted files that are generated by Site Studio. Contributor data files are edited using the Site Studio Contributor application. Native documents are files created using familiar third-party applications such as Microsoft Word. Native documents are converted to HTML format using Dynamic Converter, and they are edited using their associated application. Contributors are expected to be in charge of the content, and thus contributor data files are edited through Contributor. Native documents and other files can be edited through the associated third-party software (for instance, Microsoft Word or Adobe Photoshop) and then added to the site by the contributor. The files that the contributor may add can be easily controlled by the designer or administrator.
In addition, there are several control and configuration files used to ensure that the site works as it should. These control files are described in other chapters of this guide.
Templates are used to arrange available site assets. They are all sections of HTML (or in the case of page templates, complete HTML pages) where the tags describing the related content are stored.
The three types of templates used are:
Templates allow the data to be placed in a certain manner. The definitions define which site assets are available to place on a template, as well as how the assets can display.
Page templates are the only templates that are complete HTML pages. Generally, the best use of Site Studio is to maximize reuse of assets, the page template should be looked at as a framework for the other templates; the subtemplates and region templates used to specifically align the content. Page templates and subtemplates additionally define the placement of the contribution regions.
Each section in the hierarchy can have - and typically will have - a page template assigned as the primary page for that node. The root section of the site hierarchy is where the home page of the web site is located. Just as with the other sections in the hierarchy, the Primary Page and Secondary Page entries in section properties display the page templates used for the primary and secondary pages of the each second, including the root.
The data associating a page template with a primary or secondary page in a section is stored in the project page. Assigning a primary and secondary page is done in the properties pane.
Placeholders on a page template are ultimately placed using the wcmPlaceholder script extension. Placeholders themselves are not a site asset, placeholders are simply a defined area on a page template or subtemplate where you can use a placeholder definition to determine how content is reused in the specific placeholder.
Subtemplates are, simply, page templates that do not have a <HEAD> section. They can contain a contribution region, and are most commonly used to break one contribution region on a page template into multiple parts.
Tags can be inserted on a subtemplate the same way they would be on a page template. However, any instance of reference to the <HEAD> tag on a subtemplate will generate unanticipated results. This is most common when using fragments on a subtemplate that have multiple snippets where one refers to the head.
Region templates help define where the elements and the associated content display. The region template is selected based on the region definition used.
Region templates are used to arrange the elements as they will display on the consumer page. The elements available to use are defined by the region definition. Not all elements available must be used, which allows for creating region templates that can have multiple layouts for the same named element definitions. Using the same element definitions by name, but a different data file, allows for the easy reuse of the site assets.
Definitions are used to define which assets are available to use and how they can be used.
This section contains the following topics:
The placeholder definition controls the allowed actions within the contribution region, including if contributors can modify data, if the metadata can be modified, if the associated data file can be switched or removed, and other actions.
The placeholder definition is associated to a placeholder in code (a tag), in a section property, the global mapping property, or as the default placeholder. When there is more than one listed association of a placeholder definition to a placeholder, then they are determined in that priority; that is, association in code takes precedence over the section property, which takes precedence over the global mapping property, which takes precedence over the default placeholder.
The <complexProperty name="flags"> is the collection of allowed (and disallowed) actions when the placeholder definition is used.
The <mappings> tag lists the allowed region definitions (using the <regionDefinition> tag) and their associated region templates (using the <regionTemplate> tag). Additionally, the default region template for a given region definition is coded within the <regionTemplate> tag. Similarly, the available subtemplates (if any) are listed under the <subTemplates> tag.
These are handled in the Designer UI through the Placeholder Definition dialog. The source code for definitions can be viewed in Designer by selecting the Source tab.
<?xml version="1.0" encoding="UTF-8"?>
<placeholderDefinition
xmlns="http://www.oracle.com/sitestudio/PlaceholderDefinition/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.oracle.com/sitestudio/PlaceholderDefinition/
http://www.oracle.com/sitestudio/ss_placeholder_definition.xsd">
<property name="description" value="Default placeholder definition" />
<complexProperty name="flags">
<property name="update" value="true" />
<property name="preview" value="true" />
<property name="reset" value="true" />
<property name="modifyMetadata" value="true" />
<property name="approve" value="true" />
<property name="reject" value="true" />
<property name="docInfo" value="true" />
<property name="switchDataFile" value="true" />
<property name="viewUsageReport" value="true" />
<property name="viewTrackerReport" value="true" />
<property name="docInfoUpdate" value="true" />
<property name="switchRegionTemplate" value="true" />
<property name="removeAssociation" value="false" />
</complexProperty>
<mappings>
<regionDefinition location="regiondefinition_recipe">
<regionTemplate location="regiontemplate_recipe" default="true" />
</regionDefinition>
<regionDefinition location="regiondef_nativedoc">
<regionTemplate location="regiontemplate_nativedocument" default="true" />
<regionTemplate location="regiontemplate_recipe" />
</regionDefinition>
<regionDefinition location="regiondefinition_basic">
<regionTemplate location="regiontemplate_default" default="true" />
</regionDefinition>
</mappings>
<subTemplates>
<subTemplate location="subtemplate_right_left" />
<subTemplate location="subtemplate_new_basic" />
</subTemplates>
</placeholderDefinition>
You can see in the section of XML that each placeholder definition associates region templates with a region definition, and additionally marks which region template is the default template for that region definition within the scope of the placeholder definition. It follows that if you use a different placeholder definition, a different association could be in place.
The region definition is used to map the content (any content, including contributor data files, native documents, and so forth) through the placeholder definition to get to the appropriate region template.
The region definition used in an instance can be defined in one of two ways. First, the region definition can be explicitly called in the wcmPlaceholder tag when written in a page template or a subtemplate.
More commonly, the region definition is loaded based on the value of the metadata field xRegionDefinition for the data file used in the placeholder.
This particular example is a region definition with five element definitions referenced. Each <elementReference> tag has additional <property> tags defining the value for the label, which will also display in Contributor when the region is opened for editing, and the value for the description, which is the tooltip text displayed when the contributor hovers the mouse over the label. For more information about Contributor, see the Oracle WebCenter Content User's Guide for Site Studio Contributor.
The <dataProperty name="metadata"> tag is the location for any exceptions to enabling metadata modification. This is done in the Designer UI through the Enable Metadata Modification dialog (see the Oracle WebCenter Content User's Guide for Site Studio Designer).
The <complexproperty name="switchregioncontent"> tag is the location for the content the contributor is allowed to access via the Switch Region Content dialog. This is done in the Designer UI through the Region Content Options dialog (see the Oracle WebCenter Content User's Guide for Site Studio Designer).
<?xml version="1.0" encoding="UTF-8"?>
<regionDefinition xmlns="http://www.oracle.com/sitestudio/Element/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.oracle.com/sitestudio/Element/
http://www.oracle.com/sitestudio/ss_element_definition.xsd">
<elements>
<elementReference name="Title_textonly" location="element_plaintext_full">
<property name="label" value="Title_textonly" />
<property name="description" value="Title of recipe, using text only
element" />
</elementReference>
<elementReference name="Image" location="element_image_min">
<property name="label" value="Recipe_image" />
<property name="description" value="Image associated with the recipe" />
</elementReference>
<elementReference name="Ingredients" location="element_wysiwyg_full">
<property name="label" value="Ingredients" />
<property name="description" value="" />
</elementReference>
<elementReference name="Directions" location="element_plaintext_full">
<property name="label" value="Directions" />
<property name="description" value="" />
</elementReference>
<elementReference name="DynamicList" location="element_dynlist_full">
<property name="label" value="Dynamic List" />
<property name="description" value="Dynamic List for toolbar purposes" />
</elementReference>
<elementReference name="StatList" location="element_staticlist_full">
<property name="label" value="Statlist" />
<property name="description" value="Static List for the toolbar" />
</elementReference>
</elements>
<property name="description" value="Recipe Region" />
<dataProperty name="metadata">
<![CDATA[]]>
</dataProperty>
<complexProperty name="switchregioncontent"> <property name="createnewxml" value="true" /> <property name="createnewnative" value="true" /> <property name="choosemanaged" value="true" /> <property name="chooselocal" value="true" /> <property name="choosenone" value="false" /> <valueList name="createnewnativedoctypes"> <value>.pptx</value> <value>.psd</value> </valueList>
<complexProperty name="choosemanagedquerytext">
<property name="corecontentonly" value="false" />
<dataProperty name="querytext">
<![CDATA[xWebsiteObjectType <Matches> `Data File` <OR>
xWebsiteObjectType <Matches> `Native Document`]]>
</dataProperty>
</complexProperty>
<dataProperty name="defaultmetadata">
<![CDATA[]]>
</dataProperty>
</complexProperty>
</regionDefinition>
Each element definition, just as with other site assets, is a simple XML file.
The static list element definition files will have more code in the XML because it must list each element definition used within the static list.
Custom elements will not be any more complex than other element definitions, because custom elements simply load a separate form in HTML.
The code for an element definition can vary widely depending on the type of element. All elements will contain a <complexProperty name="flags"> section to describe the flags and their state. The flags used by an element through the element definition depend on the element.
Because of the variations in code for the element definitions, none are represented here. To see the differences in the code, open the element definitions in Designer.
The idea is to make this section a technical description of the interactions between the template and the definition to control page layout and reusability.
All data must be tagged with a region definition. That is how it is placed with the appropriate definition and template combination.
Since each asset is stored individually, the page is combined on the server before it is served to the client. The assets used to construct are selected based on the references in each other asset, as previously described.
The general process of events in creating the page happens in this manner after the request is made:
The page template is loaded based on the requested URL.
A specific page request will load the page template associated with that page, and a request for a folder or the root will load the page template named in the project file. That template's name is editable through the properties pane in Designer.
All assets not listed in a placeholder are loaded.
As the assets outside of the placeholder are loaded, the Idoc script is executed and the placeholder is filled, starting with the evaluation of the placeholder definition. The specific placeholder definition for the page is loaded in this order:
The placeholder definition explicitly named in the wcmPlaceholder tag.
If no placeholder definition is specifically listed in the tag, the definition listed in the section properties based on the URL is used.
If the section properties lists no placeholder definition, then the definition used in the global definition mappings is used.
If there is no placeholder definition listed in the global definition mappings, then the placeholder listed in the web site properties in the properties pane is used.
The data file used is based on the value listed in the Primary (or Secondary) Page Params in the section properties. The exception is when the data file to use is listed explicitly in the wcmPlaceholder tag.
The xRegionDefinition metadata field for the data file lists which region definition to use. Again, this is when a region definition is not explicitly listed in the wcmPlaceholder tag.
The region template and element definitions used are determined from the settings in the region definition, unless a different region template is stated in the wcmPlaceholder tag.
Once all elements are collected, the page is asembled and served.
For more information on using wcmPlaceholder, see Section 9.2, "wcmPlaceholder."
The conversions definitions, like the templates and definitions, are simple XML files used to reference the conversion rules.
Here is an example of the XML used in a conversions definition with a rule that is the default:
<?xml version="1.0" encoding="UTF-8"?> <conversionsDefinition xmlns="http://www.oracle.com/sitestudio/ConversionsDefinition/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.oracle.com/sitestudio/ConversionsDefinition/ http://www.oracle.com/sitestudio/ss_conversions_definition.xsd"> <conversion name="default" type="simple" key="s~"/> </conversionsDefinition>
Contribution mode is the state a page is in when the contributor has it open for editing. The rest of the time, the page is considered to be in consumption mode.
This section covers the following topics:
The key command is the keystroke combination used to enter and exit contributor mode. This is set in the JavaScript file wcm.toggle.js. For more information, see Section 5.3, "wcm.toggle.js."
Setting wcm.contributor.mode within the query string will enable contributor mode or consumption mode, depending on the setting. This is most commonly done in the URL, as in this example:
http://www.example.com?wcm.contributor.mode=true
Setting it to true will enable contributor mode; setting it to false will enable consumption mode.
A session cookie is set to persist the contributor mode setting when navigating within the same domain. The cookie is set and removed based upon the key command action or query string value.
When a contributor opens a page for editing, the page passes through these states:
The user presses the key command (as set in wcm.toggle.js; default is Ctrl + Shift + F5).
The contribution mode session cookie is set.
The contribution mode query string value is removed from the URL (if present).
The browser requests the same page from the server using the newly calculated URL.
Server authentication; the contributor mode cookie is removed in the event of an authentication failure.
The browser loads the requested page.
During page load, an OnKeyDown event handler is applied to the HTML document object to detect the next contributor mode keyboard command.
During page load, the JavaScript code detects the contributor mode cookie. (Assuming that the contributor mode cookie was not removed by the server.)
The contribution mode is drawn in the browser at the HTML window OnLoad event.