From AlfrescoWiki

DRAFT/WIP

This page describes the JavaScript Services API for Alfresco Labs 3. See also JavaScript API 3.0

Contents 1 Site service 1.1 Site service 1.1.1 Create a new site 1.1.2 List the available sites 1.1.3 Get a site 1.1.4 List the site roles 1.2 Site 1.2.1 Save sites 1.2.2 Delete sites 1.2.3 Get list of site members 1.2.4 Get site member's role 1.2.5 Indicate if user is site member 1.2.6 Set membership details for user 1.2.7 Remove user membership from site 1.2.8 Get container folder for component id 1.2.9 Get container folder for component id 1.2.10 Determine if the container folder exists 1.2.11 Reset all permissions 1.2.12 Allow all members to collaborate 1.2.13 Deny access 2 Activities service 2.1 Post activity 2.1.1 Post a custom activity type 2.1.2 Post a predefined activity type 2.1.3 Post a predefined activity type with optional name of node 2.1.4 Post a predefined activity for deleted nodeRef 2.2 Feed controls 2.2.1 Set feed control 2.2.2 Get feed controls 2.2.3 Unset feed control 3 Tagging services 3.1 Tagging service 3.1.1 Get tags 3.2 Tag scope 3.2.1 Get top tags 3.2.2 Get count of tag 3.2.3 Refresh the tag scope 3.3 TagDetails 3.4 Extensions To Existing Script Node 3.4.1 Clear the node's tags 3.4.2 Add tag to a node 3.4.3 Add all tags to a node 3.4.4 Remove tag from a node 3.4.5 Remove all tags from a node 3.4.6 Get all children of node 3.5 Extensions To Existing Search API 3.5.1 Search for node by tag 4 Thumbnail Services 4.1 Thumbnail Service 4.1.1 Indicate if thumbnail is registered 4.1.2 Get place holder resource path 4.2 Extensions To Existing Script Node 4.2.1 Create thumbnail 4.2.2 Get thumbnail 4.2.3 Get thumbnails 4.2.4 Get thumbnail defintions 4.3 Thumbnail

[edit] Site service

A site is a collaborative area for a unit of work or a project.

This section describes the methods available for the Site Service. The methods are grouped into the following object types:

• Site service
• Site

[edit] Site service

The following sections describe the available methods.

[edit] Create a new site

This method creates a new site.

createSite(sitePreset, shortName, title, description, isPublic)

Parameters:
sitePreset	The site preset.
shortName	The site short name. The site short name will be used to identify the site, so it must be unique.
title	A title for the site.
description	A description for the site.
isPublic	Determines whether the site is public or not.

Return values:
Site	The created site.

[edit] List the available sites

This method lists the sites that are available in the repository. The returned list can optionally be filtered by name and site.

listSites(nameFilter, sitePresetFilter)

Parameters:
nameFilter	The name of the filter.
sitePresetFilter	The site preset filter.

Return values:
List<Site>	A list of the site filtered, as appropriate. If no filters are specified then all the available sites are returned.

[edit] Get a site

This method gets a site for a provided short name.

getSite(shortName)

Parameters:
shortName	The short name of the site.

Return values:
Site	The site. This is null if the sire does not exist.

[edit] List the site roles

This method lists the roles for a site.

listSiteRoles()

[edit] Site

The following list shows the properties for site:

shortName

The unique short name identifying the site (read-only).

sitePreset

The name of the site preset used to create the site (read-only).

title

The displayable title of the site.

description

The displayable description of the site.

isPublic

Indicates whether the site is public or not.

node

The site node, null if none.

[edit] Save sites

This method saves any outstanding updates to the site details. If properties of the site are changed and the save method is not called, those changes will be lost.

save()

[edit] Delete sites

This method deletes the site.

deleteSite()

[edit] Get list of site members

This method gets a map of members of the site with their role within the site. This list can be filtered by name and/or role.

listMembers(nameFilter, roleFilter)

Parameters:
nameFilter	The user name filter.
roleFilter	The user role filter.

Return values:
Map<String, String>	The list of members of a site with their roles. If no name or role filter is specified, all members of the site are listed.

[edit] Get site member's role

This method gets a user's role on this site.

getMembersRole(userName)

Parameters:
userName	The user's name.

Return values:
String	The user's role. If the user is not a member of the site then null is returned.

[edit] Indicate if user is site member

This method indicates whether a user is a member of the site.

isMember(userName)

Parameters:
userName	The user's name.

Return values:
boolean value	This is a boolean value that is true if the user is a member of the site, or false if otherwise.

[edit] Set membership details for user

This method sets the membership details for a user. If the user is not already a member of the site, then they are added with the role given. If the user is already a member of the site, then their role is updated to the new role. Only a site manager can modify memberships and there must be at least one site manager at all times.

setMembership(userName, role)

Parameters:
userName	The user's name.
role	The role for the user.

Return values:
role	The site role.

[edit] Remove user membership from site

This method removes a user's membership of the site. Only a site manager can remove a user's membership and the last site manager can not be removed.

removeMembership(userName)

Parameters:
userName	The user's name.

[edit] Get container folder for component id

This method gets (or creates) the container folder for the specified component id. NOTE: The container is of type cm:folder.

ScriptNode getContainer(String componentId)

Parameters:
componentId	The component identifier.

Return values:
node	The container folder.

[edit] Get container folder for component id

This method gets (or creates) the container folder for the specified component id. NOTE: The type of container is either the one specified by the caller (which must be cm:folder or a sub-type of), or cm:folder, if a type is not specified at all.

public ScriptNode getContainer(String componentId, String folderType)

Parameters:
componentId	The component identifier.
folderType	The type of folder to create. If this is null, it creates a standard folder.

Return values:
node	The name of the container folder. This is null if the container cannot be created.

[edit] Determine if the container folder exists

This method determines if the container folder for the specified component exists.

hasContainer(String componentId)

Parameters:
componentId	The component identifier.

Return values:
boolean value	If this is true, the container folder exists.

[edit] Reset all permissions

This method resets any permissions that have been set on the node. All permissions will be deleted and the node set to inherit permissions.

resetAllPermissions(node)

[edit] Allow all members to collaborate

This method allows all members of the site collaboration rights on the node.

allowAllMembersCollaborate(node)

[edit] Deny access

This method denies access to all members of the site to the node. Note: site managers will still have appropriate permissions on the node.

denyAllAccess(node)

[edit] Activities service

Activities refer to the updates to content within a site, including the uploaded files, blogs, discussions, calendars, and the team wiki.

This section describes the methods available for the Activities Service. The methods are grouped into the following object types:

• Post activity
• Feed controls

[edit] Post activity

Note: siteId is currently required in order to get site members (and to apply feed controls).
Note: appToolId is optional, although recommended (to enable feed controls to applied to a specific type of appTool).

The following sections describe the overloaded methods for post activity.

[edit] Post a custom activity type

This method posts a custom activity type.

postActivity(String activityType, String siteId, String appTool, String jsonActivityData)

Parameters:
activityType	This is a required parameter.
siteId	This is a required parameter.
appToolId	This is an optional parameter. If it is set, then the feed controls can be applied.
jsonActivityData	This is a required parameter.

[edit] Post a predefined activity type

This method posts a predefined activity type. Activity data will be looked-up asynchronously, including:

• name
• displayPath
• typeQName
• firstName (of posting user)
• lastName (of posting user)

postActivity(String activityType, String siteId, String appTool, NodeRef nodeRef)

Parameters:
activityType	This is a required parameter.
siteId	This is a required parameter.
appToolId	This is an optional parameter. If it is set, then the feed controls can be applied.
nodeRef	This is a required parameter. Do not use this parameter for deleted (or about to be deleted) nodeRef.

[edit] Post a predefined activity type with optional name of node

This method posts a predefined activity type, for example, for checked-out nodeRef or renamed nodeRef.

postActivity(String activityType, String siteId, String appTool, NodeRef nodeRef, String beforeName)

Parameters:
activityType	This is a required parameter.
siteId	This is a required parameter.
appToolId	This is an optional parameter. If it is set, then the feed controls can be applied.
nodeRef	This is a required parameter. Do not use this parameter for a deleted (or about to be deleted) nodeRef.
beforeName	This is an optional parameter. The name of the node prior to the name change.

[edit] Post a predefined activity for deleted nodeRef

This method posts a predefined activity, for example, for the deleted nodeRef.

postActivity(String activityType, String siteId, String appTool, NodeRef nodeRef, String name, QName typeQName, 
NodeRef parentNodeRef)

Parameters:
activityType	This is a required parameter.
siteId	This is a required parameter.
appToolId	This is an optional parameter. If it is set, then the feed controls can be applied.
nodeRef	This is a required parameter. Do not use this parameter for deleted (or about to be deleted) nodeRef.
name	This is an optional parameter. The name of name.
typeQName	This is an optional parameter. The type of node.
parentNodeRef	This is a required parameter. This is used to lookup path/displayPath.

[edit] Feed controls

The following sections describe the methods for feed controls.

[edit] Set feed control

This method sets the feed control (opt-out) for a site, an appTool, or a site/appTool combination for the current user.

setFeedControl(String siteId, String appToolId)

Parameters:
siteId	This is a required parameter but is optional if the appToolId is supplied.
appToolId	This is a required parameter but is optional if the siteId is supplied.

[edit] Get feed controls

This method gets the feed control for the current user.

FeedControl[] getFeedControls()

FeedControl returns an array of user feed controls.

[edit] Unset feed control

This method unsets the feed control for the current user.

  
unsetFeedControl(String siteId, String appTool)

Parameters:
siteId	This is a required parameter but is optional if the appToolId is supplied.
appToolId	This is a required parameter but is optional if the siteId is supplied.

[edit] Tagging services

A tag is a non-hierarchical keyword or term assigned to a piece of information.

This section describes the methods available for the Tagging Service. The methods are grouped into the following object types:

• Tagging service
• Tag scope
• Tag details

The following are extensions to the existing JavaScript_API.

• Extensions to existing Script Node
• Extensions to existing search API

[edit] Tagging service

The following section describes the getTags method for the tagging service.

[edit] Get tags

function getTags();

[edit] Tag scope

The following properties are available for tag scope:

tags

Read only array containing the tag details in count order.

The following sections describe the methods for tag scope.

[edit] Get top tags

This method gets the top N tags ordered by count.

getTopTags(topN);

Parameters:
topN	The number of top tags to return.

Return values:
TagDetails[]	The top N tag details ordered by count.

[edit] Get count of tag

This method gets the count of a tag.

getCount(tag);

Parameters:
tag	The tag name.

Return values:
int	The tag count. This is zero if the tag is not present.

[edit] Refresh the tag scope

This method refreshes the tag scope.

refresh();

[edit] TagDetails

The following properties are available for TagDetails:

name

The name of the tag.

count

The tag count.

[edit] Extensions To Existing Script Node

The following properties are extensions to the existing Script Node:

isTagScope

Read/write boolean property indicating whether the node is a tag scope or not.

tagScope

Read property that provides the 'nearest' tag scope for the node, is null if no tag scope found.

tags

Read/write string array property of tags applied to this node. Setting the value of this property resets all the tags on that node.

The following sections describe the additional methods for Script Node.

[edit] Clear the node's tags

This method clears the node's tags.

clearTags()

[edit] Add tag to a node

This method adds a tag to the node.

addTag(tag)

Parameters:
tag	The tag name.

[edit] Add all tags to a node

This method adds all the tags to the node.

addTags(tags)

Parameters:
tags	An array of tag names.

[edit] Remove tag from a node

This method removes a tag from the node.

removeTag(tag)

Parameters:
tag	The tag name.

[edit] Remove all tags from a node

This method removes all the tags from the node.

removeTags(tags)

Parameters
tags	An array of tag names.

[edit] Get all children of node

This method gets all the (deep) children of this node that have the tag specified.

    
childrenByTag(tag)

Parameters:
tag	The tag name.

Return values:
ScriptNode	The nodes that are the deep children of the node with the tag.

[edit] Extensions To Existing Search API

The following sections describe the additional methods for the Search API.

[edit] Search for node by tag

This method searches the store for all nodes with the given tag applied.

tagSearch(store, tag)

Parameters:
store	The store reference string. The default is used if null is provided.	tag	The tag name.

Return values:
ScriptNode	The nodes with the tag applied.

[edit] Thumbnail Services

A thumbnail is a small image that provides a preview of the file without opening it. This section describes the methods available for the Thumbnail Service.

The methods are grouped into the following object types:

• Thumbnail service
• Thumbnail

The following are extensions to the existing JavaScript_API:

• Extensions To Existing Script Node

[edit] Thumbnail Service

The following methods describe the methods for the thumbnail service.

[edit] Indicate if thumbnail is registered

This method indicates whether a given thumbnail name has been registered.

isThumbnailNameRegistered(thumbnailName)

Parameters:
thumbnailName	The thumbnail name.

Return values:
boolean value	This is true if the thumbnail name is registered, otherwise it is false.

[edit] Get place holder resource path

This method gets the resource path for the place holder thumbnail for the given named thumbnail.

getPlaceHolderResourcePath(thumbnailName)

Parameters:
thumbnailName	The thumbnail name.

Return values:
String	The place holder thumbnail resource path. This is null if it is not set.

[edit] Extensions To Existing Script Node

The following sections describe the additional methods to the existing Script Node.

[edit] Create thumbnail

This method creates a thumbnail based on the definition registered for the thumbnail name provided.

createThumbnail(thumbnailName, async)

Parameters:
thumbnailName	The thumbnail name. If the thumbnail name has not been registered, there will be an error.
async	This is an optional parameter and is false by default. This parameter is true if the thumbnail was created asynchronously. Otherwise, it is false. When it is set to false, the method blocks until the thumbnail is created and the newly created thumbnail is returned. If it is set to true, the method queues the creation of the thumbnail asynchronously and immediately returns to the calling client with null.

The return value for createThumbnail is the thumbnail script node if the async is false. Otherwise it is null.

[edit] Get thumbnail

This method gets the given thumbnail for the content property.

getThumbnail(thumbnailName)

Parameters:
thumbnailName	The thumbnail name.

Return values:
ScriptThumbnail	The thumbnail.

[edit] Get thumbnails

This method gets all the thumbnails for a given node's content property.

getThumbnails()

Return values:
ScriptThumbnail	A list of thumbnails. This is empty if none are available.

[edit] Get thumbnail defintions

This method returns the names of the thumbnail definitions that can be applied to the content property of this node. Thumbnail definitions only appear in this list if they can produce a thumbnail for the content found in the content property. This will be determined by looking at the mimetype of the content and the destination mimetype of the thumbnail.

getThumbnailDefintions()

Return values:
String	An array of thumbnail names that are valid for the current content type.

[edit] Thumbnail

The thumbnail object extends the standard ScriptNode and represents a thumbnail object.

updateThumbnail()