cascade-api.md

Classes

Cascade

Class to wrap REST calls to the Cascade Server API. This class operates in two modes, path or identifier. If on path mode, any path listed in the wrapper functions or APICall function will use a path, with the site specified either in the constructor or utility function. Otherwise it will use a Cascade asset ID. You can swap modes using the useId or usePath methods.

CascadeAsset

Class to represent assets to submit into Cascade Server. These are generally used when creating a new asset, as it makes it easier than creating the required properties from scratch.

Typically used to create new objects when using the createPage, createFile, and createFolder functions.

These are returned by the createBlankPage, createBlankFile, and createBlankFolder methods.

Cascade

Class to wrap REST calls to the Cascade Server API. This class operates in two modes, path or identifier. If on path mode, any path listed in the wrapper functions or APICall function will use a path, with the site specified either in the constructor or utility function. Otherwise it will use a Cascade asset ID. You can swap modes using the useId or usePath methods.

Kind: global class

• Cascade
  • new Cascade(apiRoot, authentication, [site])
  • .usePath(siteName)
  • .useId()
  • .createBlankPage() ⇒ CascadeAsset
  • .createBlankFile() ⇒ CascadeAsset
  • .createBlankBlockDataDef() ⇒ CascadeAsset
  • .createBlankFolder() ⇒ CascadeAsset
  • .APICall(operation, [type], [assetIDPath], [assetObject], [ajaxParameters]) ⇒ Object
  • .readPage(path) ⇒ Object
  • .readFile(path) ⇒ Object
  • .readBlock(path) ⇒ Object
  • .readFolder(path) ⇒ Object
  • .deletePage(path) ⇒ Object
  • .deleteFile(path) ⇒ Object
  • .deleteBlock(path) ⇒ Object
  • .deleteFolder(path) ⇒ Object
  • .editPage(assetObject) ⇒ Object
  • .editFile(assetObject) ⇒ Object
  • .editBlock(assetObject, [blockType]) ⇒ Object
  • .editFolder(assetObject) ⇒ Object
  • .publishPage(path) ⇒ Object
  • .publishFile(path) ⇒ Object
  • .publishFolder(path) ⇒ Object
  • .createPage(assetObject) ⇒ Object
  • .createFile(assetObject) ⇒ Object
  • .createBlock(assetObject, [blockType]) ⇒ Object
  • .createFolder(assetObject) ⇒ Object
  • .movePage(path, newName, folderPath) ⇒ Object
  • .moveFile(path, newName, folderPath) ⇒ Object
  • .moveBlock(path, newName, folderPath) ⇒ Object
  • .moveFolder(path, newName, folderPath) ⇒ Object
  • .doMove(path, newName, folderPath, type) ⇒ Object
  • .copyPage(path, newName, folderPath) ⇒ Object
  • .copyFile(path, newName, folderPath) ⇒ Object
  • .copyBlock(path, newName, folderPath) ⇒ Object
  • .copyFolder(path, newName, folderPath) ⇒ Object
  • .makeCopy(path, newName, folderPath, type) ⇒ Object
  • .checkRelationshipsPage(path) ⇒ Object
  • .checkRelationshipsFile(path) ⇒ Object
  • .checkRelationshipsBlock(path) ⇒ Object
  • .checkRelationshipsFolder(path) ⇒ Object

new Cascade(apiRoot, authentication, [site])

Create a new Cascade API object. This will build a REST query to the Cascade instance provided in the constructor. The class relies on one of two modes to operate in when making calls, paths, or identifiers, if a site is listed in the constructor, it will use path, otherwise it will use identifier.

Param	Type	Description
apiRoot	string	Root URL of your Cascade instance
authentication	Object	Authentication object, should either have username and password properties or apiKey property
authentication.apiKey	string	API key to make the call with. Either this OR username/password must be included.
authentication.username	string	Username to make the call with. Either username & password OR apiKey must be included.
authentication.password	string	Password to make the call with. Either username & password OR apiKey must be included.
[site]	string	Site to use if using paths to identify assets.

cascade.usePath(siteName)

Change the mode of the Cascade object to use paths.

Kind: instance method of Cascade

Param	Type	Description
siteName	string	Name of the site to add to calls.

cascade.useId()

Change the mode of the Casade object to use ids.

Kind: instance method of Cascade

cascade.createBlankPage() ⇒ CascadeAsset

Return a blank page, this is helpful when creating new assets.

Kind: instance method of Cascade
Returns: CascadeAsset - Blank page

cascade.createBlankFile() ⇒ CascadeAsset

Return a blank file, this is helpful when creating new assets. This should either have information in the data attribute, or text in the text attribute.

Kind: instance method of Cascade
Returns: CascadeAsset - Blank file

cascade.createBlankBlockDataDef() ⇒ CascadeAsset

Return a blank XHTML/Data Definition block, this is helpful when creating new assets. This should either have properly escaped XHTML in the xhtml attribute, or a structured data object in the structuredData attribute.

Kind: instance method of Cascade
Returns: CascadeAsset - Blank block

cascade.createBlankFolder() ⇒ CascadeAsset

Return a blank folder, this is helpful when creating new assets.

Kind: instance method of Cascade
Returns: CascadeAsset - Blank folder

cascade.APICall(operation, [type], [assetIDPath], [assetObject], [ajaxParameters]) ⇒ Object

Make an API call. Using the pre-defined functions is generally preferred, but if not all APIs have wrapper functions, this can be called directly. While most parameters are optional, most calls will need some number of them to be included.

This function is asynchronous, and will either return an object, or throw an error if the call did not succeed. The error should be caught on the front end.

Kind: instance method of Cascade
Returns: Object - Cascade response object. It could be either a system response for an operation like create or edit, or an object for an operation like read.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Default	Description
operation	string		Name of the operation as defined in the Cascade API.
[type]	string	false	Optional. Required for calls where an identifier is needed (read, publish, etc). If not needed use default.
[assetIDPath]	string	false	Optional. Either the path or id of the asset, needed where an identifier is needed, like type. If not needed use default.
[assetObject]	Object	false	Optional. Asset to be acted upon, needed for some calls (create, edit). Must have an attribute for the asset type that's being acted upon (page, block, etc)
[ajaxParameters]	Object	false	Optional. Parameters to be added to the body, examples being copyParameters or moveParameters which are required for those operations.

cascade.readPage(path) ⇒ Object

Read a page, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response. Page that was found will be in the .asset.page attribute
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of page to read

cascade.readFile(path) ⇒ Object

Read a file, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response. Page that was found will be in the .asset.page attribute
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of file to read

cascade.readBlock(path) ⇒ Object

Read a block, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response. Block that was found will depend on what type of block it was
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of block to read

cascade.readFolder(path) ⇒ Object

Read a folder, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response. Page that was found will be in the .asset.page attribute
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of folder to read

cascade.deletePage(path) ⇒ Object

Delete a page, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of page to delete

cascade.deleteFile(path) ⇒ Object

Delete a file, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of file to delete

cascade.deleteBlock(path) ⇒ Object

Delete a block, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of block to delete

cascade.deleteFolder(path) ⇒ Object

Delete a folder, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of folder to delete

cascade.editPage(assetObject) ⇒ Object

Edit a page, given a Cascade page object. Typically the page to edit is read in via readPage, but it can be manually created as well.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
assetObject	Object	Cascade object representing the page.

cascade.editFile(assetObject) ⇒ Object

Edit a file, given a Cascade file object. Typically the file to edit is read in via readFile, but it can be manually created as well.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
assetObject	Object	Cascade object representing the file.

cascade.editBlock(assetObject, [blockType]) ⇒ Object

Edit a block, given a Cascade block object. Typically the block to edit is read in via readBlock, but it can be manually created as well.

Unlike other assets, blocks need to specify

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Default	Description
assetObject	Object		Cascade object representing the block.
[blockType]	string	"xhtmlDataDefinitionBlock"	Type of the block to interact with, this defaults to an XHTML/Data Defintion Block

cascade.editFolder(assetObject) ⇒ Object

Edit a folder, given a Cascade folder object. Typically the folder to edit is read in via readFolder, but it can be manually created as well.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
assetObject	Object	Cascade object representing the folder.

cascade.publishPage(path) ⇒ Object

Publish a page, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of page to publish.

cascade.publishFile(path) ⇒ Object

Publish a file, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of file to publish.

cascade.publishFolder(path) ⇒ Object

Publish a folder, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of folder to publish.

cascade.createPage(assetObject) ⇒ Object

Create a page, given a Cascade page object. Typically this is created using createBlankPage, but it can be created manually as well.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
assetObject	Object	Cascade object representing the page.

cascade.createFile(assetObject) ⇒ Object

Create a file, given a Cascade file object. Typically this is created using createBlankFile, but it can be created manually as well.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
assetObject	Object	Cascade object representing the file.

cascade.createBlock(assetObject, [blockType]) ⇒ Object

Create a block, given a Cascade block object. Typically this is created using createBlankBlockDataDef, but it can be created manually as well.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Default	Description
assetObject	Object		Cascade object representing the block.
[blockType]	string	"xhtmlDataDefinitionBlock"	Type of the block to interact with, this defaults to an XHTML/Data Defintion Block

cascade.createFolder(assetObject) ⇒ Object

Create a folder, given a Cascade folder object. Typically this is created using createBlankFolder, but it can be created manually as well.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
assetObject	Object	Cascade object representing the folder.

cascade.movePage(path, newName, folderPath) ⇒ Object

Do a move operation on a page, given a path, name, and folder. Unlike the Move and Rename operations in Cascade, which have separate functionality, this combines them into a single operation.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of the page to move.
newName	string	New name of the page. If the asset is being moved to a different folder, this can be the same as the current name.
folderPath	string	Path or ID of the folder to move to. If the asset is not being moved to a different folder, this can be the same as the current folder.

cascade.moveFile(path, newName, folderPath) ⇒ Object

Do a move operation on a file, given a path, name, and folder. Unlike the Move and Rename operations in Cascade, which have separate functionality, this combines them into a single operation.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of the file to move.
newName	string	New name of the file. If the asset is being moved to a different folder, this can be the same as the current name.
folderPath	string	Path or ID of the folder to move to. If the asset is not being moved to a different folder, this can be the same as the current folder.

cascade.moveBlock(path, newName, folderPath) ⇒ Object

Do a move operation on a block, given a path, name, and folder. Unlike the Move and Rename operations in Cascade, which have separate functionality, this combines them into a single operation.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of the block to move.
newName	string	New name of the block. If the asset is being moved to a different folder, this can be the same as the current name.
folderPath	string	Path or ID of the block to move to. If the asset is not being moved to a different folder, this can be the same as the current folder.

cascade.moveFolder(path, newName, folderPath) ⇒ Object

Do a move operation on a folder, given a path, name, and folder. Unlike the Move and Rename operations in Cascade, which have separate functionality, this combines them into a single operation.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of the folder to move.
newName	string	New name of the folder. If the asset is being moved to a different folder, this can be the same as the current name.
folderPath	string	Path or ID of the folder to move to. If the asset is not being moved to a different folder, this can be the same as the current folder.

cascade.doMove(path, newName, folderPath, type) ⇒ Object

Do a move operation on an asset, given a path, name, folder, and type. Unlike the Move and Rename operations in Cascade, which have separate functionality, this combines them into a single operation.

This should generally not be called directly, and instead a wrapper function like movePage or moveFile should be used instead. But if you need to move or rename an asset that doesn't have a type this can be used.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of the asset to move.
newName	string	New name of the asset. If the asset is being moved to a different folder, this can be the same as the current name.
folderPath	string	Path or ID of the folder to move to. If the asset is not being moved to a different folder, this can be the same as the current folder.
type	string	Type of the asset being moved.

cascade.copyPage(path, newName, folderPath) ⇒ Object

Make a copy of a a page, given a path, type, new name, and folder.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of page to copy.
newName	string	New name of the page. If the asset is being copied to a different folder, this can be the same as the current name.
folderPath	string	Path or ID of the folder to copy to. If the asset is not being copied to a different folder, this can be the same as the current folder.

cascade.copyFile(path, newName, folderPath) ⇒ Object

Make a copy of a a file, given a path, type, new name, and folder.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of file to copy.
newName	string	New name of the file. If the asset is being copied to a different folder, this can be the same as the current name.
folderPath	string	Path or ID of the folder to copy to. If the asset is not being copied to a different folder, this can be the same as the current folder.

cascade.copyBlock(path, newName, folderPath) ⇒ Object

Make a copy of a a block, given a path, type, new name, and folder.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of block to copy.
newName	string	New name of the block. If the asset is being copied to a different folder, this can be the same as the current name.
folderPath	string	Path or ID of the folder to copy to. If the asset is not being copied to a different folder, this can be the same as the current folder.

cascade.copyFolder(path, newName, folderPath) ⇒ Object

Make a copy of a a folder, given a path, type, new name, and folder.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of folder to copy.
newName	string	New name of the folder. If the asset is being copied to a different folder, this can be the same as the current name.
folderPath	string	Path or ID of the folder to copy to. If the asset is not being copied to a different folder, this can be the same as the current folder.

cascade.makeCopy(path, newName, folderPath, type) ⇒ Object

Make a copy of an asset, given a path, type, new name, and folder. This should generally not be called directly, and instead a wrapper method like copyPage or copyFile should be used. If the type doesn't have a wrapper function, this can be used instead.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of asset to copy.
newName	string	New name of the item to use. If the asset is being copied to a different folder, this can be the same as the current name.
folderPath	string	Path or ID of the folder to copy to. If the asset is not being copied to a different folder, this can be the same as the current folder.
type	string	Type of the asset being copied.

cascade.checkRelationshipsPage(path) ⇒ Object

Check relationships for a page, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of page to check.

cascade.checkRelationshipsFile(path) ⇒ Object

Check relationships for a file, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of file to check.

cascade.checkRelationshipsBlock(path) ⇒ Object

Check relationships for a file, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of file to check.

cascade.checkRelationshipsFolder(path) ⇒ Object

Check relationships for a folder, given a path or ID (depending on the mode of the Cascade object) and return a Cascade response.

Kind: instance method of Cascade
Returns: Object - Object representing the Cascade response.
Throws:

• Will throw an error if the Cascade API operation was not successful.

Param	Type	Description
path	string	Path or ID of folder to check.

CascadeAsset

Class to represent assets to submit into Cascade Server. These are generally used when creating a new asset, as it makes it easier than creating the required properties from scratch.

Typically used to create new objects when using the createPage, createFile, and createFolder functions.

These are returned by the createBlankPage, createBlankFile, and createBlankFolder methods.

Kind: global class

new CascadeAsset([type])

Create a new CascadeAsset object.

Param	Type	Default	Description
[type]	string	"page"	Either page, file, or folder. Defaults to page.