Book Image

Alfresco Developer Guide

Book Image

Alfresco Developer Guide

Overview of this book

Table of Contents (17 chapters)
Alfresco Developer Guide
Credits
About the Author
About the Reviewers
Preface
Index

JavaScript


As you learned in examples throughout the book, JavaScript is used in several different places across the Alfresco platform, particularly as one option for controller logic in web scripts. This section starts with a listing of the out of the box root JavaScript objects available to all scripts (except where noted), and then provides details for the rest of the JavaScript API.

Root Objects

The root objects available to your scripts are either utility objects or entry points into different areas of the JavaScript API. This section lists the root objects available and notes where further APIs exist. API details are provided in the next section, "JavaScript API".

Root Object

Description

actions

Entry point into the Actions API. Used to retrieve the list of actions configured in the repository or as a factory to retrieve an instance of an action.

args

Available when the script is run as a web script controller. Contains the arguments passed to the script.

avm

Entry point into the AVM API. Used to retrieve a list of all AVM stores, to search for a store based on ID, or to search for a specific node.

cache

Available when the script is run as a web script controller. The cache object is used to dynamically modify the cache settings for a web script.

classification

Entry point into the Classification API. Used to get and create root categories, or to get all category nodes for a classification.

companyhome

ScriptNode representing the Company Home folder.

crossRepoCopy

Utility object for copying nodes between the DM and AVM store (and vice-versa).

document

ScriptNode representing the document against which the script is running, if applicable. See space.

logger

Utility object for logging messages to the console.

model

Available when the script is run as a web script controller. The associative array used to pass data to the view.

people

Entry point into the People API, which is used to work with people and groups.

person

ScriptNode representing the current user executing the script.

script

ScriptNode representing the script being executed.

search

Entry point into the Search API, which can be used to execute Lucene searches, XPath searches, saved searches, and searches based on node reference.

session

Used to retrieve the ticket for the current user executing the script.

space

ScriptNode representing the space against which the script is running. See document. Note that space is available even when the script is running in the context of a document. In that case, the space returned is the enclosing folder.

status

Available when the script is run as a web script controller. Used to set the response code, error message, and redirect flag.

userhome

ScriptNode representing the home space of the current user executing the script.

utils

A generic utility object with commonly used functions.

workflow

Available in Labs only, this is the entry point into the Workflow API. It is used to get tasks, workflow definitions, and workflow instances. It can also be used to create workflow packages.

JavaScript API

The classes that implement the JavaScript root objects are in org.alfresco.repo.jscript. Much of the information in the tables within this section has been taken directly from the Alfresco Javadoc comments for the classes in that package.

Note

In this section, method names are listed as they appear in the underlying Java class. For getters and setters, this means the "get" or "set" is shown even though it is typically dropped in JavaScript. For example, document.tags and document.getTags() are equivalent.

General

This section lists general utility classes or classes that are used across multiple APIs, such as ScriptNode.

Association

Function

Description

Return value

getAssociationRef()

Gets the AssociationRef object for this association.

AssociationRef

getSource()

Gets the source ScriptNode of the association.

ScriptNode containing the source node.

getTarget()

Gets the target ScriptNode of the association.

ScriptNode containing the target node.

getType()

Gets the type of the association.

String containing the QName of the association type.

ChildAssociation

Function

Description

Return value

getChild()

Gets the child node on the target end of this association.

ScriptNode containing the child.

getChildAssociationRef()

Gets the AssociationRef object for this association.

AssociationRef

getName()

Gets the name of the association.

String containing the QName of the association.

getParent()

Gets the parent node.

ScriptNode containing the parent.

getType()

Gets the type of the association.

String containing the QName of the association type.

isPrimary()

Determines whether or not this is the primary association for this node.

True if this is the primary association, otherwise false.

ScriptNode

Function

Description

Return value

addAspect(String type)

addAspect(String type, ScriptableObject props)

Adds an aspect to the node.

True if the aspect was added successfully, false if an error occurred.

addNode (ScriptNode node)

Adds an existing node as a child of this node.

Void

addTag(String tag) (3.0 Labs)

Adds the specified tag to the node.

Void

getAspects()

Gets the aspects applied to the node.

ScriptableObject (an Array) of QNames.

getAspectsSet() (3.0 Labs)

Gets the aspects applied to the node.

Set of QNames.

getAssociations() (3.0 Labs)

Gets the target associations for a node.

Associative array of target associations.

getAssocs()

Gets the target associations for a node.

Associative array of target associations.

cancelCheckout()

Cancels the check-out of a working copy document.

ScriptNode representing the original object that was checked out.

checkin()

checkin(String history)

checkin(String history, boolean majorVersion)

Checks in a working copy document.

ScriptNode representing the original object that was checked out.

checkout()

checkout(ScriptNode destination)

Performs a check-out of this document into the current parent space or, alternatively, the specified destination folder.

ScriptNode representing the working copy Node for the checked out document.

getChildAssociations() (3.0 Labs)

Gets the child associations for a node.

Associative array of child associations.

getChildAssocs()

Gets the child associations for a node.

Associative array of child associations.

getChildByNamePath(String path) (2.2 Enterprise)

Returns the node at the specified cm:name-based path by walking the children of this node.

ScriptNode of the matching child.

getChildren()

Gets the child nodes for a node.

ScriptableObject of ScriptNodes representing each child.

getChildrenByXPath (String xpath)

Searches the children of this node with the supplied XPath expression.

Array of matching nodes.

getContent()

Gets the content property of this node as a string.

String containing the node content.

getCrossRepositoryCopyHelper()

Brings in use the cross repository copy object to copy nodes between the DM and AVM repositories.

CrossRepositoryCopy object.

copy(ScriptNode destination)

copy(ScriptNode destination, boolean deepCopy)

Copies this node to a new parent destination. Note that children of the source node are not copied unless the deepCopy flag is used.

ScriptNode representing the newly copied node, or null if the copy fails.

createAssociation (ScriptNode target, String assocType)

Creates an association between this node and the specified target node.

Void

createFile(String name)

Creates a new File (cm:content) node as a child of this node. Once created the file should have content set using the content property.

ScriptNode representing the new node, or null if the creation fails.

createFolder(String name)

Creates a new folder (cm:folder) node as a child of this node.

ScriptNode representing the new node, or null if the creation fails.

createNode(String QName, String QNameType)

createNode(String QName, String QNameType, ScriptableObject properties)

createNode(String QName, String QNameType, ScriptableObject properties, String QnameAssocName)

createNode(String name, String type, Object properties, String assocType, String assocName) (3.0 Labs)

createNode(String QName, String QNameType, String QNameAssocName)

Creates a new Node of the specified type as a child of this node.

ScriptNode representing the new node, or null if the creation fails.

createThumbnail(String thumbnailName) (3.0 Labs)

createThumbnail(String thumbnailName, boolean async) (3.0 Labs)

Creates a thumbnail for the content property of the node.

ScriptThumbnail representing the new thumbnail.

getDisplayPath()

Gets the human-readable path to the node.

String containing the path.

getDownloadUrl()

For a content document, this method returns the download URL to the content for the default content property.

String containing the URL.

hasAspect(String QNameAspect)

Checks for the presence of the specified aspect.

True if the aspect has been applied, otherwise returns false.

hasPermission(String permission)

Checks to see if the current user has the specified permission on this node.

True if the user has permission, otherwise returns false.

getIcon16()

getIcon32()

Returns the small or large icon for the node.

String containing the URL for the image.

getId()

Returns the UUID for the node.

String containing the ID.

inheritsPermissions()

Checks to see whether or not this node inherits its permissions from a parent.

True if the inherit permission flag is turned on, otherwise returns false.

getIsCategory()

Checks whether or not the node is a category.

True if the node is a category, otherwise it returns false.

getIsContainer()

Checks whether or not the node is a folder.

True if the node is a folder, otherwise it returns false.

getIsDocument()

Checks whether or not this node is of type cm:content.

True for cm:content or its children, otherwise it returns false.

getIsLinkToContainer()

Checks whether or not this node is a link to a folder.

True if the node is a folder link, otherwise returns false.

getIsLinkToDocument()

Checks whether or not this node is a link to a document.

True if the node is a document link, otherwise returns false.

getIsLocked()

Checks whether or not this node is locked.

True if the node is locked, otherwise returns false.

getIsTagScope()

Checks whether or not this node is a tag scope.

True if it is, false if it is not.

getMimetype()

Gets the mimetype for the node.

String containing the mimetype.

move(ScriptNode destination)

Moves this Node to a new parent destination.

True if the move succeeds, and false if it fails.

getName()

Gets the cm:name property of the node.

String containing the value of the cm:name property.

getNodeRef()

Gets the node reference for the node.

String containing the node's node reference.

getOwner()

Gets the owner of the node.

String containing the owner of the node.

getParent()

Gets the node reference for the node's parent.

ScriptNode containing the parent's node reference.

getPermissions()

Retrieves the permissions for the node.

Array of permissions applied to this Node. Strings returned are of the format [ALLOWED|DENIED];[USERNAME|GROUPNAME];PERMISSION for example: ALLOWED;kevinr;Consumer so can be easily tokenized on the ";" character.

getPrimaryParentAssoc()

Gets the primary parent association for this node.

ChildAssociationRef representing the parent association.

processTemplate(String template)

processTemplate (ScriptNode template)

processTemplate(String template, ScriptableObject args)

processTemplate (ScriptNode template, ScriptableObject args)

Processes the specified FreeMarker template against this node.

String containing the output of the FreeMarker template.

getProperties()

Gets all properties for the node.

An Associative Array of QNames and values.

getQnamePath()

Gets the QName-based path for this node.

A String representing the path.

getQnameType()

Gets the QName type for this node.

A String representing the QName type.

getSourceAssociations() (3.0 Labs)

Gets the source associations for this node.

Map of source associations.

getSourceAssocs() (3.0 Labs)

Gets the source associations for this node.

Map of source associations.

getStoreId() (3.0 Labs)

Gets the store ID for this node.

String representing the store ID.

getStoreType() (3.0 Labs)

Gets the store type for this node.

String representing the store type.

getTags() (3.0 Labs)

Gets the list of tags applied to this node.

String array containing the tags.

getThumbnail(String thumbnailName) (3.0 Labs)

Gets the thumbnail for this node given a thumbnail name.

ScriptThumbnail object containing the thumbnail.

getThumbnails()

Gets all thumbnails for this node.

Array of ScriptThumbnail objects.

remove()

Deletes the node.

Returns true if the deletion was successful, false if it wasn't.

removeAspect (String QNameType)

Removes the specified aspect from the node.

Returns true if the removal was successful, false if it wasn't.

removeAssociation(ScriptNode target, String QNameAssocType)

Removes an association between this node and the specified target node.

Void

removeNode(ScriptNode node)

Removes an existing child node of this node.

Void

removePermission(String permission)

removePermission(String permission, String authority)

Removes permission for ALL users from this node or from the specified authority.

Void

removeTag(String tag)

Removes the specified tag from this node.

Void

save()

Saves the property changes to this node.

Void

setContent(String content)

Sets the content of this node to the value of the provided String.

Void

setInheritsPermissions (boolean inherit)

Sets whether this node should inherit permissions from the parent node.

Void

setIsTagScope(boolean tagScope) (3.0 Labs)

Sets whether or not this node is a tag scope.

Void

setMimetype(String mimetype)

Sets the mimetype for the content attached to this node.

Void

setName(String name)

Sets the cm:name property of this node.

Void

setOwner (String userId)

Sets the owner of the node.

Void

setPermission(String permission)

setPermission (String permission, String authority)

Sets the permission for all users of this node or for the specified authority.

Void

specializeType(String type)

Specializes the type of the node.

True if successful, otherwise false.

getSize()

Gets the size of the content that is attached to the node.

The size, in bytes, of the content.

takeOwnership()

Takes ownership of the node.

Void

transformDocument (String mimetype)

transformDocument (String mimetype, ScriptNode destination)

Transforms a document to a new document mimetype format. A copy of the document is made and the extension changed to match the new mimetype, then the transformation is applied.

ScriptNode representing the newly transformed content.

transformImage(String mimetype)

transformImage(String mimetype, String options)

transformImage(String mimetype, String options, ScriptNode destination)

transformImage(String mimetype, ScriptNode destination)

Transforms an image to a new image format. A copy of the image document is made and the extension changed to match the new mimetype, then the transformation is applied.

ScriptNode representing the newly transformed image.

getType()

Gets the content type of this node.

String containing the content type.

getUrl()

Gets either the content stream URL or, for folders, the browse details URL for this node.

String containing the URL.

getWebdavUrl()

Gets the WebDAV URL for this node.

String containing the URL.

ScriptUtils

Function

Description

Return value

getNodeFromString (String nodeRefString)

Retrieves a ScriptNode based on the string representation of its node reference.

ScriptNode representing the desired node.

pad(String string, int length)

Pads a string with zeros ("0") to the desired length.

Padded String.

toBoolean(String booleanString) (3.0 Labs)

Converts a String to a boolean.

Boolean value.

Root object: cache

Function

Description

Return value

getIsPublic()

Determines if the web script can have its response placed in a public cache.

True if the content is public, false if it is not.

getMustRevalidate()

Determines whether or not the cache should re-validate to make sure it is picking up the latest version of the web script response.

True if cache should revalidate, false if it does not have to revalidate.

getNeverCache()

Determines if the web script response should never be cached.

True if the response should never be cached, false if it is OK to cache.

setIsPublic(boolean isPublic)

Sets the isPublic flag.

Void

setMustRevalidate(boolean mustRevalidate)

Sets the mustRevalidate flag.

Void

setNeverCache(boolean neverCache)

Sets the neverCache flag.

Void

Root object: crossRepoCopy

Function

Description

Return value

copy(ScriptNode src, ScriptNode dest, String name)

Performs a copy of a source node to the specified parent destination node. The name will be applied to the destination node copy. Inter-store copy operations between Workspace and AVM and visa-versa are supported.

ScriptNode of the copied node if successful, otherwise null.

Root object: logger

Function

Description

Return value

isLoggingEnabled()

Determines whether or not logging is enabled.

True if logging is enabled, false if it is not.

log(String message)

Writes a message to the log.

Void

Root object: status

Function

Description

Return value

getCode()

Gets the status code for the web script's response.

Code as an int.

setCode(int code)

setCode (int code, String message) (3.0 Labs)

Sets the status code for the web script's response.

Void

getCodeDescription()

Gets the description of the status code.

String representing the status code description.

getCodeName()

Gets the short name of the status code.

String representing the short name of the status code.

getException()

Gets the exception that's been set on this status object.

Throwable representing the exception.

getLocation()

Gets the location.

String representing the location.

setLocation(String location)

Sets the location.

Void

getMessage()

Gets the web script status message.

String representing the status message.

setMessage(String message)

Sets the web script status message.

Void

getRedirect()

Gets the redirect flag.

Boolean representing the redirect flag.

setRedirect(boolean redirect)

Sets the redirect flag.

Void

setException(Throwable exception)

Sets the exception.

Void

Actions API

Root object: actions

Function

Description

Return value

create(String actionName)

Creates a reference to an Action

ScriptAction object representing the action.

getRegistered()

Gets the registered list of actions.

An Array of registered actions.

ScriptAction

Function

Description

Return value

execute(ScriptNode nodeRef)

Executes the script.

Void

getName()

Gets the name of the action.

String representing the name of the action.

getParameters()

Gets the parameters for the action.

ScriptableObject (a Map) of the action parameters.

AVM API

The AVM API is used for working with objects in the AVM store, which is currently only used by Alfresco's WCM functionality:

Root object: avm

Function

Description

Return value

assetUrl(String avmPath)

assetUrl(String storeId, String assetPath)

Gets the preview URL for the given avmPath.

String containing the URL.

getModifiedItems(String storeId, String username, String webapp)

Gets the list of modified items for the specified user sandbox for a specific webapp as compared against the staging store in the store specified by the store ID.

List of AVMNodes.

lookupNode(String path)

Return an AVM Node for the fully qualified path.

AVMNode of the matching node.

lookupStore(String store)

Returns an AVM store object for the specified store name

AVMScriptStore of the matching store.

lookupStoreRoot(String store)

Returns an AVM Node representing the public store root folder.

AVMNode of the root folder.

stagingStore(String storeId)

Gets the staging store name for the given store ID.

String containing the name.

getStores()

Gets a list of AVM stores in the repository.

ScriptableObject containing the list of stores.

userSandboxStore (String storeId, String username)

Gets the Sandbox Store name for the given store ID and username.

String containing the name.

getWebappsFolderPath()

Gets the folder path to the webapps folder.

String containing the path.

websiteStagingUrl(String storeId)

Gets the preview URL for the web site managed in the store represented by the store ID.

String containing the URL.

websiteUserSandboxUrl (String storeId, Stri ng username)

Gets the preview URL for the user sandbox for the store and username specified.

String containing the URL.

AVMNode (extends ScriptNode)

Function

Description

Return value

copy (String destination)

copy (ScriptNode destination)

Copies this node into a new parent destination.

ScriptNode representing the copy of this node

getAspects() (2.2)

getAspectsSet() (3.0)

Gets the list of aspects applied to this node.

List of QNames.

getName()

Gets the name property of the node.

String representing the name.

hasLockAccess()

Determines whether or not the current user can make a change to the node either because the node is not locked or the node is locked and the user is the lock owner or a Content Manager.

True if the user can make a change, false if they cannot.

isDirectory()

Determines whether or not this node is a directory.

True if it is a directory, false if it is not.

isFile()

Determines whether or not this node is a file.

True if it is a file, false if it is not.

getIsLocked()

Determines whether or not this node is locked.

True if it is locked, false if it is not.

isLockOwner()

Determines if this node is locked and the current user is the lock owner.

True if the node is locked and the user is the lock owner, otherwise false.

isLockOwner()

Determines if this node is locked and the current user is the lock owner.

True if the node is locked and the user is the lock owner, otherwise false.

move(String destination)

move(ScriptNode destination)

Moves this node to the specified destination.

True if the move is successful, false if it is not.

getParentPath()

Gets the path to this node's parent.

String representing the path.

getPath() (3.0 Labs)

Gets the full AVM path to this node.

String representing the path.

rename(String name)

Renames this node to the new name specified.

True if the rename is successful, false if it is not.

getType()

Gets the Qname type of the node.

String representing the type.

getVersion()

Gets the version of the node.

Version number of the node as an integer.

AVMScriptStore

Function

Description

Return value

getCreatedDate()

Gets the store's creation date.

Date the store was created.

getCreator()

Gets the user who created the store.

String representing the store creator.

getId()

Gets the store's ID.

String representing the store ID.

lookupNode(String path)

Looks up a node in the store; the path is assumed to be related to the webapps folder root. Therefore a valid path would be |ROOT/WEB-INF|lib|web.xml.

AVMNode matching the path specified

getName()

Gets the store's name.

String representing the name of the store.

lookupRoot()

Gets the store's root node.

AVMNode representing the root node.

luceneSearch(String query)

Executes a Lucene query against this store and returns the results.

ScriptableObject containing the search results. See Chapter 8 for information concerning the limitations of search in the AVM store.

Classification API

The Classification API is used for working with categories.

Root node: classification

Function

Description

Return value

getAllClassificationAspects()

Gets all the aspects that define this classification.

String array containing a list of aspect names.

createRootCategory(String aspect, String name)

Creates a root category for this classification.

Void

getAllCategoryNodes(String aspect)

Gets all category nodes for this classification.

ScriptableObject containing a list of the category nodes.

getCategoryUsage(String aspect, int maxCount) (3.0 Labs)

Gets categories with the most number of objects. The number of categories returned is specified in maxCount.

ScriptableObject containing the top categories.

getRootCategories (String aspect)

Gets all root categories for this classification.

ScriptableObject containing the root categories.

CategoryNode (extends ScriptNode)

Function

Description

Return value

getCategoryMembers()

Gets all of the members of a category.

An array of ScriptNodes.

createSubcategory(String name)

Creates a new subcategory.

CategoryNode representing the new subcategory.

getImmediateCategoryMembers()

Gets the immediate members of a category.

Array of ScriptNodes.

getImmediateMembersAndSubCategories()

Gets the immediate members and subcategories.

Array of ScriptNodes.

getImmediateSubCategories()

Gets the immediate subcategories.

Array of CategoryNodes.

getMembersAndSubCategories()

Gets the members and subcategories for this category.

Array of ScriptNodes.

removeCategory()

Removes this category.

Void

getSubCategories()

Gets the subcategories for this category.

Array of CategoryNodes.

People API

The People API is for working with people and groups:

Root node: people

Function

Description

Return value

addAuthority(ScriptNode parentGroup, ScriptNode authority)

Adds an authority (a user or group) to a group container as a new child.

Void

createGroup (String groupName)

createGroup(ScriptNode parentGroup, String groupName)

Creates a new root-level group (or a subgroup if a parent is specified) with the specified unique name (do not use the "GROUP_" prefix).

ScriptNode representing the new group if it was successful, otherwise null.

createPerson(boolean createUserAccount, boolean setAccountEnabled) (3.0 Labs)

Creates a person with a generated username.

ScriptNode containing the person object if it was successfully created.

deleteGroup(ScriptNode group)

Deletes the specified group.

Void

deletePerson(String username) (3.0 Labs)

Deletes the specified person object.

Void

enablePerson(String username) (3.0 Labs)

Enables the specified user account.

Void

getContainedAuthorities(ScriptNode container, AuthorityType type, boolean recurse) (3.0 Labs)

Gets the authorities this authority contains, optionally recursing into subauthorities.

Array of Objects representing the contained authorities.

getContainerGroups(ScriptNode person)

Gets the groups that contain the specified authority.

ScriptableObject (a JavaScript Array) containing the list of groups.

getGroup (String groupName)

Gets the group specified.

ScriptNode representing the specified group.

getMembers(ScriptNode group)

getMembers(ScriptNode group, boolean recurse)

Gets the people that belong to the specified group and, optionally, any sub-groups of the specified group.

ScriptableObject (a JavaScript Array) containing the list of people.

getPeople(String filter) (3.0 Labs)

Gets all the people in the repository, optionally filtered by a query string.

ScriptableObject representing the collection of people.

getPerson(String username)

Gets the person given the specified username.

ScriptNode representing the specified user or null if the user does not exist.

removeAuthority(ScriptNode parentGroup, ScriptNode authority)

Removes a person or group from the specified group.

Void

Presence API (3.0 Labs)

The Presence API can be used to determine whether or not someone is online according to their preferred presence provider:

presence

Function

Description

Return value

getDetails(ScriptNode person)

Gets the presence provider and presence user name of the person specified.

String of the format [presence provider]|[presence username].

hasPresence(ScriptNode person)

Determines whether or not the person specified is configured with a presence provider.

True if the person is configured for presence, otherwise false.

Search API

The Search API is for executing queries, including saved searches:

search

Function

Description

Return value

findNode(String nodeRef)

findNode(ScriptNode nodeRef)

findNode(String referenceType, String[] reference)(3.0 Labs)

Finds a single Node by the Node reference. 3.0 version adds the ability to pass in a reference type and string as follows:

  • The "Node" reference type resolves to a node via its Node Reference: {store_type}|{store_id}|{node_id}

  • The "Path" reference type resolves to a node via its display path: {store_type}|{store_id}|{path}

  • The "AVM Path" reference type resolves to a node via its AVM display path: {store_id}/{path}

  • The QName reference type resolves to a node via its child qname path: {store_type}/{store_id}/{child_qname_path}

ScriptNode if found or null if failed to find.

luceneSearch (String searchString)

luceneSearch (String store, String search) (3.0 Labs)

luceneSearch (String search, String sortColumn, boolean asc) (3.0 Labs)

luceneSearch (String store, String search, String sortColumn, boolean asc) (3.0 Labs)

Executes a Lucene search.

JavaScript array of Node results from the search— can be empty, but not null.

savedSearch (String nodeRef)

savedSearch (ScriptNode nodeRef)

Executes a saved Lucene search.

JavaScript array of Node results from the search—can be empty, but not null.

xpathSearch (String search)

xpathSearch (String store, String search) (3.0 Labs)

Executes an XPath search.

JavaScript array of Node results from the search— can be empty, but not null.