Aloha Editor

These guides help you to make your content editable and to develop Aloha Editor.

Guides Index ▸

The Repository API

This guide describes

  • configuring the repository manager
  • implement the repository API
  • resource item data layout

1 Concept

A repository is a service or data source, which provides resource items and is registered with the repositoryManager. The repositoryManager manages all available repositories and routes queries to all registered repositories. Any plugin may make requests to the repositoryManager for resource items, and specify one or more kinds of items it wishes to have returned, such as “website” or “localanchor” (where “localanchor” could be a headline provided by a document repository implementation) Usually a cms backend would provide data such as links to sites, images, videos, files that should be available during the editing process. The respository data are resource items that contain JSON data with at least the following attributes: id, name, url, type. All other attributes are optional and depend on the item’s resourceObjectType. A repository may provide resource items of a freely definable resourceObjectType. We suggest the types to be mimetypes eg.: “image/png”, “text/html”, “video/H264”.

2 Configuring the repositoryManager

You may define a timeout when the repository manger should stop waiting for repository implementation response.


var Aloha = {
	settings : {
		repositories: {
			timeout: 10000 // default 5000 (5 sec)
		}
	}
};

If you want to figure out the optimal value for your timeout, you should test the server-sided script for your repository to find it’s typical response times under heavy load. After determining the maximum time it takes to load a result you might want to add a buffer (eg. 2-5 seconds) to allow for adapting to even higher server load.

3 Repository API

3.1 query

http://docs.oasis-open.org/cmis/CMIS/v1.0/cd04/cmis-spec-v1.0.html#_Toc234072402

Does a fulltext search in all attributes and properties which have ’’’fulltextIndexed == true’’’. This differes to the CMIS spec because we do not support a query language and do always a fulltext search.

3.1.1 Input attributes
  • queryString [String]
  • filter [array] OPTIONAL Attributes that will be returned.
  • orderBy [array] OPTIONAL ex. [{lastModificationDate:’DESC’, name:’ASC’}]
  • maxItems [Integer] OPTIONAL
  • in FolderId [ResourceItem] OPTIONAL his is a predicate function that tests whether or not a candidate object is a child-object of the folder object identified by the given inFolderId.
  • inTreeId [ResourceItem] OPTIONAL This is a predicate function that tests whether or not a candidate object is a descendant-object of the folder object identified by the given inTreeId.
  • skipCount [Integer] OPTIONAL This is tricky in a merged multi repository scenario
  • renditionFilter [array] OPTIONAL
    • Instead of termlist an array of ’’’kind’’’ or ’’’mimetype’’’ is expected. If ’’’null’’’ or ’’’array.length == 0’’’ all renditions are returned. See http://docs.oasis-open.org/cmis/CMIS/v1.0/cd04/cmis-spec-v1.0.html#_Ref237323310 for renditionFilter
3.1.2 Output attributes
  • [array] Objects Aloha objects as result of a fulltext search
  • Boolean hasMoreItems
  • Integer numItems OPTIONAL

3.2 getChildren

3.2.1 Input attributes
  • folderId [ResourceItem] OPTIONAL If null the root folderId should be used
  • maxItems [Integer] OPTIONAL
  • skipCount [Integer] OPTIONAL This is tricky in a merged multi repository scenario
  • filter [array] OPTIONAL Attributes that will be returned
  • renditionFilter [array] OPTIONAL
    • Instead of termlist an array of ’’’kind’’’ or ’’’mimetype’’’ is expected. If ’’’null’’’ or ’’’array.length == 0’’’ all renditions are returned. See http://docs.oasis-open.org/cmis/CMIS/v1.0/cd04/cmis-spec-v1.0.html#_Ref237323310
3.2.2 Output attributes
  • [array] Objects Aloha objects as result of a fulltext search
  • Boolean hasMoreItems
  • Integer numItems OPTIONAL

3.3 getObjectById

3.4 markObject

3.5 makeClean

3.6 example


/**
 * Create the Aloha Repositories object.
 */
define(
[ 'aloha', 'jquery' ],
function ( Aloha, jQuery ) {
	'use strict';
	
	new ( Aloha.AbstractRepository.extend( {
		
		_constructor: function () {
			this._super( 'myRepository' );
		},
				
		/**
		 * initalize the repository
		 */
		init: function () {	},
		
		
		/** 
		 * Searches a repository for object items matching queryString if none found returns null.
		 * The returned object items must be an array of Aloha.Repository.Object
		 * 
		 * @param {object} params object with properties
		 * @property {String} queryString 
		 * @property {array} objectTypeFilter OPTIONAL Object types that will be returned.
		 * @property {array} filter OPTIONAL Attributes that will be returned.
		 * @property {string} inFolderId OPTIONAL his is a predicate function that tests whether or not a candidate object is a child-object of the folder object identified by the given inFolderId (objectId).
		 * @property {string} inTreeId OPTIONAL This is a predicate function that tests whether or not a candidate object is a descendant-object of the folder object identified by the given inTreeId (objectId).
		 * @property {array} orderBy OPTIONAL ex. [{lastModificationDate:’DESC’}, {name:’ASC’}]
		 * @property {Integer} maxItems OPTIONAL number items to return as result
		 * @property {Integer} skipCount OPTIONAL This is tricky in a merged multi repository scenario
		 * @property {array} renditionFilter OPTIONAL Instead of termlist an array of kind or mimetype is expected. If null or array.length == 0 all renditions are returned. See http://docs.oasis-open.org/cmis/CMIS/v1.0/cd04/cmis-spec-v1.0.html#_Ref237323310 for renditionFilter
		 * @param {function} callback this method must be called with all result items
		 */
		query: function ( p, callback ) {
			callback.call( this, [
			     {
			    	 id: 1,
			    	 name: 'My item',
			    	 url: 'http://mydomain.com/myItem.html',
			    	 type: 'text/html'
			     }
			]);
		},
		
		/**
		 * Returns all children of a given motherId.
		 * 
		 * @param {object} params object with properties
		 * @property {array} objectTypeFilter OPTIONAL Object types that will be returned.
		 * @property {array} filter OPTIONAL Attributes that will be returned.
		 * @property {string} inFolderId OPTIONAL his is a predicate function that tests whether or not a candidate object is a child-object of the folder object identified by the given inFolderId (objectId).
		 * @property {array} orderBy OPTIONAL ex. [{lastModificationDate:’DESC’}, {name:’ASC’}]
		 * @property {Integer} maxItems OPTIONAL number items to return as result
		 * @property {Integer} skipCount OPTIONAL This is tricky in a merged multi repository scenario
		 * @property {array} renditionFilter OPTIONAL Instead of termlist an array of kind or mimetype is expected. If null or array.length == 0 all renditions are returned. See http://docs.oasis-open.org/cmis/CMIS/v1.0/cd04/cmis-spec-v1.0.html#_Ref237323310 for renditionFilter
		 * @param {function} callback this method must be called with all result items
		 */
		getChildren: function ( p, callback ) {
			callback.call( this, [
 			     {
 			    	 id: 1,
 			    	 name: 'My item',
 			    	 url: 'http://mydomain.com/myItem.html',
 			    	 type: 'text/html'
 			     }
 			]);
		},
				
		/**
		 * Get the repositoryItem with given id
		 * Callback: {Aloha.Repository.Object} item with given id
		 * @param itemId {String} id of the repository item to fetch
		 * @param callback {function} callback function
		 */
		getObjectById: function ( itemId, callback ) {
			callback.call( this, [
  			     {
  			    	 id: 1,
  			    	 name: 'My item',
  			    	 url: 'http://mydomain.com/myItem.html',
  			    	 type: 'text/html'
  			     }
  			]);
		},
		
		/**
		 * Mark or modify an object as needed by that repository for handling, processing or identification.
		 * Objects can be any DOM object as A, SPAN, ABBR, etc..
		 * (see http://dev.w3.org/html5/spec/elements.html#embedding-custom-non-visible-data)
		 * @param obj jQuery object to make clean
		 * @return void
		 */
		markObject: function (obj, repositoryItem) {
			obj.attr('data-myRepository-temporary-data').text( resourceItem.name );
		},

		/**
		 * Make the given jQuery object (representing an object marked as object of this type)
		 * clean. All attributes needed for handling should be removed. 
		 * @param {jQuery} obj jQuery object to make clean
		 * @return void
		 */
		makeClean: function ( obj ) {
			obj.removeAttr('data-myRepository-temporary-data');
		};

	}))(); 

});

4 Reccomandation of repository item attributes

The API and data layout is inspired by CMIS.

4.1 ObjectTypes

The object concept from CMIS is inconsistent and to complicated for Aloha Editors needs. So we changed to a much simpler model, which allows to implement CMIS, but is easier to use for developers. CMIS objects

There are 2 BaseTypes: document and folder. All other objectTypes may extend either document or folder. Extended Objects may not be extended any more.

4.2 Document

  • id MUST
  • repositoryId MUST
  • name MUST
  • baseType MUST (document|folder)
  • type MUST
  • parentId OPTIONAL
  • renditions OPTIONAL
  • localName OPTIONAL
  • createdBy OPTIONAL
  • creationDate OPTIONAL
  • lastModifiedBy OPTIONAL
  • lastModificationDate OPTIONAL
  • length OPTIONAL
  • mimeType OPTIONAL
  • fileName OPTIONAL
  • url OPTIONAL

4.3 Folder

  • id MUST
  • repositoryId MUST
  • name MUST
  • baseType MUST (document|folder)
  • type MUST
  • parentId MUST
  • localName OPTIONAL
  • createdBy OPTIONAL
  • creationDate OPTIONAL
  • lastModifiedBy OPTIONAL
  • lastModificationDate OPTIONAL

4.4 Rendition

  • documentId ID identfies the rendition document (baseObjectType == document)
  • url URL identifies the rendition stream.
  • mimeType String The MIME type of the rendition stream.
  • filename String The filename of the rendition stream
  • length Integer (optional)The length of the rendition stream in bytes.
  • name String (optional) Human readable information about the rendition.
  • kind String A categorization String associated with the rendition.
    • square – an image square 75×75
    • thumbnail – a thumbnail version of the object
    • small - 240 on longest side
    • medium- 500 on longest side
    • large – 1024 on longest side (only exists for very large original images)
    • docx – Microsoft docx Version of the content
    • lang_de – same content in german language
    • lang_fr – same content in frensh language
    • pdf – pdf version of the content
  • height Integer (optional) Typically used for ‘image’ renditions (expressed as pixels). SHOULD be present if kind = cmis:thumbnail.
  • width Integer (optional) Typically used for ‘image’ renditions (expressed as pixels). SHOULD be present if kind = cmis:thumbnail.
4.4.1 What are renditions, and why are they so useful?

A repository may implement renditions for any object that has “document” as its baseObjectType. A rendition is simply an alternative representation (rendering) of a given object. Any document may have any number of renditions. For example: A page document in a repositroy may be rendered in 3 different languages. Each of these 3 variations of that page can be served by the repository as a rendition of any of the other 2 translations that correspond with it. Each of these pages may be a stand-alone document in the repository as well. In fact, different renditions for a single document type will likely be different files which the repository will server back in response to a request for a specific rendition of a given object.

4.5 Example Flickr Image Object (Document Object)

  • id – gailenejane/5008283282
  • name – Quiet moment
  • baseType – document
  • type – image
  • url http://www.flickr.com/photos/gailenejane/5008283282/

The JSON response could look like:


{
id: 'gailenejane/5008283282’,
repositoryId: 'flickr',
name: 'Quiet moment’,
type: ‘image/jpeg’,
url: 'http://www.flickr.com/photos/gailenejane/5008283282/‘,
renditions: [{
  url: 'http://farm5.static.flickr.com/4128/5008283282_f3162bc6b7_s.jpg’,
  mimeType: ‘image/jpeg’,
  filename: '4128/5008283282_f3162bc6b7_s.jpg’,
  kind: ’thumbnail’,
  height: 75,
  width: 75
  }]
}