Surf Platform - Freemarker Template and JavaScript API

From AlfrescoWiki

Jump to: navigation, search

Contents

[edit] Overview

When building new presentation templates or web components, developers may choose to use Alfresco's Freemarker and JavaScript API technologies. These are the default and preferred way to build high performance and lightweight web parts. They are easy to build and require no server restarts.

The availability of these APIs speeds the time to develop new functionality. Most Surf platform features are available as lightweight, JavaScript objects. Developers are able to work with the full range of the Surf platform object model, the request context, users, remote connections, and credential management.

The Freemarker Template API and the JavaScript API use a common object model. This means that the objects available to the JavaScript API are very similar (in most places, identical) to those used by the Freemarker API. There are some minor differences that are noted in their respective sections below.

[edit] Surf Platform Root-Scoped API

The Surf Platform Freemarker Template Processor extends the capabilities that are already provided by Alfresco's Freemarker Engine. These are covered in the Template Guide.

Similarly, the Surf Platform Web Scripts Runtime extends the capabilities that are already provided by Alfresco's Web Scripts Runtime. These are covered in great depth in the Web Scripts page and the Web Script Runtimes page. There, you will find links to examples of how to build your own web scripts from scratch.

In either case, the Surf platform bundles the existing Alfresco capabilities and then provisions a few additional, root-scoped objects into them.

[edit] Root-scoped Objects

The Surf platform root-scoped objects are:

context
The request context of the current page.
remote
The Web Script Framework remote helper object.
user
The current user.
content
The current content instance (available if the dispatcher is rendering a page for a given content instance id).
instance
The currently rendering model object (along with rendering context).
sitedata
Utility for working with the Surf platform object model.


[edit] context

The context variable provides the following properties:

id
The internally managed id for the current request.
pageId
The id of the page being rendered.
page
The page object being rendered.
templateId
The id of the template being rendered.
template
The template object being rendered.
user
The current user
themeId
The current theme id.
theme
The current theme object.
formatId
The format id for the current request.
properties
Associative array of all context values.

If the dispatcher is rendering a page for a given content instance id, the following variables will additionally be available:

contentId
The id of the content being rendered
content
The content being rendered.

For example: 

var pageTitle = context.page.title;
var userFullName = context.user.fullName;
var contentTitle = context.content.properties["title"];
var customValue = context.properties["customValue"];

[edit] user

The user variable provides the following properties:

properties
An associative array of user properties.
id
The user identifier.
name
The Principal name (most commonly, this will be the same as the user id).
fullName
The user's full name (for example, Joe Dwight Smith).
firstName
The user's first name (Joe).
middleName
The user's middle name (Dwight).
lastName
The user's last name (Smith).
email
The user's email.
organization
The user's organization.
jobTitle
The user's job title.
location
The user's location.
biography
The user's biography.
telephone
The user's telephone entry.
mobilePhone
The user's mobile phone entry.
skype
The user's skype id.
instantMsg
The user's instant message id.
companyPostcode
The user's company post code.
companyTelephone
The user's company telephone.
companyFax
The user's company fax entry.
companyEmail
The user's company email.
companyAddress1
The user's company address entry 1.
companyAddress2
The user's company address entry 2.
companyAddress3
The user's company address entry 3.

For example: 

<#if user.location == "Boston">
   <p>Welcome to the Red Sox appreciation page, ${user.firstName}!</p>
</#if>

[edit] content

The content variable provides the following properties:

id
The id of the content object.
typeId
The type id of the content object.
properties
An associative array of properties about the object.

The following properties are metadata fields about the object:

timestamp
The time (long) when the object was loaded.
endpointId
The id of the endpoint from which the object was loaded.
isLoaded
Whether the object successfully loaded.
statusCode
Status code from the attempt to load the object.
statusMessage
Status message from the attempt to load the object.

For example: 

var id = content.id;
var typeId = content.typeId;
var endpointId = content.endpointId;
var timestamp = content.timestamp;
var isLoaded = content.isLoaded;
var statusCode = content.statusCode;
var statusMessage = content.statusMessage;
var customData = content.properties["cm:customData"];

[edit] instance

The instance variable provides the following properties:

object
The currently executing object.
id
The id of the currently executing object.
htmlId
The HTML id of the currently executing object.
properties
An associative array of properties about the currently rendering object.

[edit] sitedata

The sitedata variable provides the following framework properties:

rootPage
Root page object for the web site/application.
siteConfiguration
Configuration object for the web site/application.

The following properties provide arrays of all objects of a given type:

chrome
Array of all Chrome objects.
components
Array of all Component objects.
componentTypes
Array of all ComponentType objects.
configurations
Array of all Configuration objects.
contentAssociations
Array of all ContentAssociation objects.
pages
Array of all Page objects.
pageTypes
Array of all PageType objects.
pageAssociations
Array of all PageAssociation objects.
templates
Array of all Template objects.
templateTypes
Array of all TemplateType objects.
themes
Array of all Theme objects.

The following properties provide associative arrays (or maps) of all instances for a given object type. These maps are keyed by object id:

chromeMap
Associative array of all Chrome objects.
componentsMap
Associative array of all Component objects.
componentTypesMap
Associative array of all ComponentType objects.
configurationsMap
Associative array of all Configuration objects.
contentAssociationsMap
Associative array of all ContentAssociation objects.
pagesMap
Associative array of all Page objects.
pageTypesMap
Associative array of all PageType objects.
pageAssociationsMap
Associative array of all PageAssociation objects.
templatesMap
Associative array of all Template objects.
templateTypesMap
Associative array of all TemplateType objects.
themesMap
Associative array of all Theme objects.

The following generic lookup methods are also available:

getObjects(objectTypeId)
Array of all objects of the given type
getObjectsMap(objectTypeId)
Associative array of all objects of the given type

The following methods allow you to create new objects:

newChrome()
Instantiates a new Chrome.
newComponent()
Instantiates a new Component.
newComponent(componentTypeId)
Instantiates a new Component with the given ComponentType id.
newComponent(componentTypeId, title, description)
Instantiates a new Component with the given ComponentType id, title and description.
newComponentType()
Instantiates a new ComponentType.
newConfiguration()
Instantiates a new Configuration.
newConfiguration(sourceId)
Instantiates a new Configuration bound to the given source id.
newContentAssociation()
Instantiates a new Content Association.
newPage()
Instantiates a new Page.
newPage(title, description)
Instantiates a new Page with the given title and description.
newPageAssociation()
Instantiates a new Page Association.
newPageType(pageTypeId)
Instantiates a new Page Type.
newTemplate()
Instantiates a new Template.
newTemplate(templateType)
Instantiates a new Template instance of the given template type.
newTemplate(templateTypeId, title, description)
Instantiates a new Template instance of the given template type, title and description.
newTemplateType(templateTypeId)
Instantiates a new Template Type with the given id.

The following generic object creation method is also available:

newObject(objectId, objectTypeId)
Instantiates a new object of the given type


The following methods look up objects and return arrays of results. An AND operator is applied across all supplied parameters. If a parameter is null, it is not included in the lookup.

findComponents(scopeId, sourceId, regionId, componentTypeId)
Finds all Component instances whose bindings match the given scope, source object, region and component type.
findChildPageAssociations(sourceId, destId)
Finds all PageAssociation instances of type child between the given source and destination pages.
findPageAssociations(sourceId, destId, assocType)
Finds all PageAssociation instances between the given source and destination pages of the given association type (that is, child).
findChildPages(sourceId)
Finds all child page objects for the given top level page id.
findContentAssociations(sourceId, destId, assocType, formatId)
Finds all ContentAssociation instances whose bindings match the given source id, dest id, association type and format.

The following methods look up objects and return maps of results. An AND operator is applied across all supplied parameters. If a parameter is null, it is not included in the lookup.

findComponentsMap(scopeId, sourceId, regionId, componentTypeId)
Finds all Component instances whose bindings match the given scope, source object, region, and component type.
findPageAssociationsMap(sourceId, destId, assocType)
Finds all PageAssociation instances between the given source and destination pages of the given association type (that is, child).
findContentAssociationsMap(sourceId, destId, assocType, formatId)
Finds all ContentAssociation instances whose bindings match the given source id, dest id, association type and format.
findTemplatesMap(pageId)
Finds all templates that are bound to the given page.

The following methods return a single object. An AND operator is applied across all supplied parameters. If a parameter is null, it is not included in the lookup. If multiple objects result from the lookup, the first one is returned:

findConfiguration(sourceId)
Returns a Configuration instance bound to the given sourceId.
findTemplate(pageId)
Returns the default Template instance bound to a given page.
findTemplate(pageId, formatId)
Returns the Template instance bound to a given page for a specific format.

The following methods are used to bind objects together. These are used to create association objects and to stamp binding parameters onto objects:

associateComponent(componentId, scopeId, sourceId, regionId)
Binds a given component to specified scope, source object, and region.
associateTemplate(templateId, pageId)
Binds the default template to a page.
associateTemplate(templateId, pageId, formatId)
Binds a template to a page for a given format id.
associatePage(sourceId, destId)
Associates a source page to a child page.
associateContent(contentId, pageId, formatId)
Associates a content id to a page for a given format id.
associateContentType(contentTypeId, pageId, formatId)
Associates a content type id to a page for a given format id.

The following methods are used to unbind objects from one another. They are used to remove association objects and to clear binding parameters on objects:

unassociateComponent(componentId)
Unbinds a given component so that it is uncoupled from a scope, source object, and region.
unassociateTemplate(pageId)
Unbinds the default template from a page.
unassociateTemplate(pageId, formatId)
Unbinds a template from a page for a given format id.
unassociatePage(sourceId, destId)
Unassociates a source page from a child page.
unassociateContent(contentId, pageId, formatId)
Unassociates a content id from a page for a given format id.
unassociateContentType(contentTypeId, pageId, formatId)
Unassociates a content type id from a page for a given format id.

The following methods can be used to look up individual objects:

getObject(objectTypeId, objectId)
Returns a single object with the given object type id and object id
getChrome(objectId)
Returns a Chrome instance with the given object id
getComponent(objectId)
Returns a Component instance with the given object id
getComponent(scope, regionId, sourceId)
Returns a Component instance bound to the given scope, region id and source id
getComponentType(objectId)
Returns a ComponentType instance with the given object id
getConfiguration(objectId)
Returns a Configuration instance with the given object id
getContentAssociation(objectId)
Returns a ContentAssociation instance with the given object id
getPage(objectId)
Returns a Page instance with the given object id
getPageType(objectId)
Returns a PageType instance with the given object id
getPageAssociation(objectId)
Returns a PageAssociation instance with the given object id
getTemplate(objectId)
Returns a Template instance with the given object id
getTemplateType(objectId)
Returns a TemplateType instance with the given object id
getTheme(objectId)
Returns a Theme instance with the given object id

For example: 

// create two pages
var page1 = sitedata.newPage("My First Product Page", "First Description");
var page2 = sitedata.newPage("My Second Product Page", "Second Description");

// associate both pages to the site's root page
sitedata.associatePage(sitedata.rootPage.id, page1.id);
sitedata.associatePage(sitedata.rootPage.id, page2.id);

// create a new template instance of type "product_display_template"
var template1 = sitedata.getObject("product_display_template");

// bind both pages to this template for their "default" format
sitedata.associateTemplate(template1.id, page1.id);
sitedata.associateTemplate(template1.id, page2.id, "default");

// create a component instance
var component1 = sitedata.newComponent("pdfViewer", "PDF Viewer", "Description");

// bind component into both pages at once by setting to template scope
sitedata.associateComponent(component1.id, "template", template1.id, "viewer");

[edit] Return types

[edit] Model objects

Model objects are returned from most of the query functions on sitedata. They are also bound to rendering contexts. A model object could be a component, a template, or any other object type.

[edit] Properties

By default, the following properties are available:

id
The id of the object.
title
The title of the object.
description
The description of the object.
properties
An associative array (map) of all properties on the object.

[edit] Metadata properties

The following metadata properties are available:

timestamp
The modification time of the object(long).
persisterId
The id of the persister to which the object belongs.
storagePath
The path to the file within the persister.

[edit] Persistence methods

The following persistence methods are available:

save()
Persists the model object to the store.
reload()
Reloads the model object from the store.
remove()
Removes the model object from the store.

[edit] Methods

The following methods are also available:

toXML()
Generates a user-friendly XML serialization of the object.
touch()
Touches the model file (updating its modification timestamp).
getProperty(key)
Returns the property directly from the model object.
setProperty(key, value)
Sets a property directly onto the model object.
removeProperty(key)
Removes a property from the model object.

[edit] Files

Individual files are exposed via methods on the file system.

The following properties are available:

name
The name of the file.
parent
The parent of this file.
path
The path of the file relative to the root of the file system.
length
The length of the file content (in bytes).
timestamp
The modification time of the file (long).
isFile
Whether this is a file.
isDirectory
Whether this is a directory.
properties
An associative array (map) of all properties.

The following methods are available:

readContents()
Returns a String of the file contents.
writeContents(contents)
Writes the given String contents to the file.
getChildren()
Returns the children of this directory. If the current object is not a directory, then null will be returned.
getChild(name)
Returns a given child of this directory. If the current object is not a directory, then null will be returned.
createFile(name)
Returns a new file as a child of this directory. If the current object is not a directory, then null will be returned.
delete()
Returns true/false on deletion of the file.

[edit] Rendering Engines

Although the API descriptions provided above are useful, it is also nice to have a quick list that you can look at to see what variables are available to each type of rendering engine. There are two rendering engines that are interesting: template renderers and component renderers.

[edit] Templates

The following root-scoped variables are available during the rendition of a Template:

  • sitedata - always available
  • context - always available
  • instance - always available
  • user - always available (guest if unauthenticated)
  • content - available if content is being dispatched
  • page - page mapping object (fields: id, title, description, theme, url)
  • theme - the current theme id
  • htmlid - the html id
  • url - URLHelper object
  • head - String of all component headers (<script> and <link> dependencies)

The following variables are presently in place but should be removed:

  • ${description} - should be replaced with ${page.description}
  • ${title} - should be replaced with ${page.title}

Custom properties of the Template can be accessed like this: 

${context.template.properties["customProperty"]}

Custom properties of the Page can be accessed like this: 

${context.page.properties["customProperty"]}

The following directives are available to Freemarker Templates: 

<@region id="regionName" scope="(global, template or page)" protected=true/false/>
<@component componentId="(id of component)" chrome="(id of chrome)" chromeless=true/false/>

[edit] Components

The following root-scoped variables are available during the rendition of a Page:

  • sitedata - always available
  • context - always available
  • instance - always available
  • user - always available (guest if unauthenticated)
  • content - available if content is being dispatched
  • page - page mapping object (fields: id, title, description, theme, url)
  • theme - the current theme id
  • htmlid - the html id

The following variables are presently in place but should be removed:

  • ${description} - should be replaced with ${page.description}
  • ${title} - should be replaced with ${page.title}

Custom properties of the Template can be accessed like this: 

${context.template.properties["customProperty"]}

Custom properties of the Page can be accessed like this: 

${context.page.properties["customProperty"]}
Retrieved from "http://wiki.alfresco.com/wiki/Surf_Platform_-_Freemarker_Template_and_JavaScript_API"