First of all why am I doing this?
Dojo is a popular javascript library which is used extensively and, of particular interest, is coming to more prominence within Alfresco.
dojo.store is based on HTML5/W3C’s IndexedDB object store API
and is useful because stores can be used to provide the data access methods for a wide range of dojo/dijit widgets and are especially useful to easily visualize data in any number of ways.
CMIS is standard used to access content stored in a repository, such as Alfresco and, particularly with the advent of the browser binding in CMIS 1.1, it makes it possible to manage information within that repository using a series of HTTP requests.
While the CMIS API is relatively straightforward there are some wrinkles, particularly with respect to cross-origin requests, so it seems to make sense, allied to the advantages of having the API available as a dojo store, to provide a wrapper for the simple actions at least.
So now I’ve explained my motivation on with a brief description and some basic examples: (This is available in example.html in the git repository)
The first thing to do is to create a store:
var targetRoot =
"https://localhost/alfresco/api/-default-/public/cmis/versions/1.1/browser";
this.cmisStore = new CmisStore({
base: targetRoot,
succinct: true
});
The first thing to notice is the value of base – note that there is no /root at the end – this will be automatically appended by the store (use the root option if you need to change this)
Next we need to attach it to something I’m going to use dijit.Tree here.
We’ll need to provide a mapping to the ObjectStoreModel – I’ll also wrap it in Observable so we can see any changes.(this doesn’t work brilliantly for dijit.Tree as it puts in a duplicate node at the root level as well as it the right place – I haven’t worked out why yet – probably something to do with not knowing the parent)
You’ll see the query parameter which is used to determine what to fetch – this could be a path to a folder
We also have to provide a function to determine whether it’s a leaf node – contrary to the documentation this function isn’t called if it’s in the CmisStore (neither does getLabel)
this.treeStore = new Observable(this.cmisStore);
// Create the model
var model = new ObjectStoreModel({
store: this.treeStore,
query: { path: this.path, cmisselector: 'object'},
labelAttr: "cmis:name",
mayHaveChildren : function(data) {
if (data['cmis:baseTypeId'] == 'cmis:folder') {
return true;
} else {
return false;
}
}
});
Now that we’ve done that we can create our Tree.
// Create the Tree.
this.tree = new Tree({
model: model
});
this.tree.placeAt("foldertree");
this.tree.startup();
That’s it – you’ll have a nice tree representation of your CMIS repository – it’s as easy to use other widgets like one of the data grids – plenty of scope to get creative! (e.g. https://github.com/speich/remoteFileExplorer)
Making changes
Here you can see some code to add a folder.
First you fetch the parent folder – this can be done either by path or objectId. If the parameter contains a / or the { usePath: true} is set as the second options parameter then it’s a path otherwise it’s a objectId.
This object is then set as parent in the options parameter of the store.add call as shown in the example.
Finally once the folder has been added the grid can be refreshed to show the new folder.
You’ll see that there’s a formatter function to take account whether the succinct version of the CMIS response is being used – note this only handles simple values.
lang.hitch is used so that the function called inside the “then” has access to the same context.
addFolder: function addFolder() {
//Get the test folder to be the parent of the new folder
this.cmisStore.get(this.testFolder).then(lang.hitch(this, function(result) {
this.cmisStore.add({
'cmis:objectTypeId': 'cmis:folder',
'cmis:name': this.tempFolder
}, {
parent: result
}).then(
lang.hitch(this,function( result) {
//Do something
}));
}), function (error) {
console.log(error);
}, function (progress) {
console.log(progress);
});
},
Updating
Making changes to your content is very easy – the store handles it – so all you’ve got to do is make sure your widget handles the data correctly.
One way you might like to edit your data is via dgrid – this makes it extremely straightforward to add an editor to a column e.g.
editor({
label : ("pub.title"),
field : "t.cm:title",
formatter : formatFunction,
editor : "text",
autoSave : true
})
One thing you will notice is that my field is called t.cm:title this is because the query on my OnDemandGrid is defined like this:
query : {
'statement' : 'SELECT * FROM cmis:folder
join cm:titled as t on cmis:objectId = t.cmis:objectId',
}
The code inside the store put method will strip off the leading alias i.e. upto and including the .
You need to be aware that not all the properties can be updated via CMIS – the store has a couple of ways of handling this working by either using a list of excluded properties or allowed properties. This is determined by the putExclude property which is set to true or false.
If you are working with custom properties then you may need to modify the list – this can be done by modifying the excludeProperties or allowedProperties members of the store e.g.
cmisStore.excludeProperties.push('cm:title');
Note this works on the absolute property name, not the namespace trimmed value.
The store will post back the entire object, not just the changed properties so you either need to make sure that the value is valid or exclude the property.
Error handling isn’t covered here and will depend on which widget you’re using.
Dates
For handling dates you need to convert to/from the CMIS date (secs since epoch) to a javascript Date object as part of the editor definition.
Use dijit/form/DateTextBox as your editor widget.
editor({
field : 'p.myns:myDate',
autoSave : true,
get: function(rowData) {
var d1 = rowData["p.myns:myDate"];
if (d1 == null) {
return null;
}
var date1 = new Date(d1[0]);
return(date1);
},
set: function (rowData) {
var d1 = rowData["p.myns:myDate"];
if (d1) {
return d1.getTime();
} else {
return null;
}
}
}, DateTextBox),
The CMIS server will error if it is sent an empty string as a datetime value so in order to avoid this the CmisStore will not attempt to send null values.
Select
For a simple select just use a dijit/form/Select widget as the basis for you editor and set the options using the editorArgs e.g.
editor({
label : ("pub.type"),
field : "p.cgghPub:type",
editorArgs : {
options : [
{ label : "one", value : "1"}
]
}
}, Select)
MultiSelect
MultiSelect doesn’t have the luxury of using options in the constructor – the easiest way I found is to create your own widget and use that e.g.
declare("CategoryMultiSelect", MultiSelect, {
size : 3,
postCreate : function() {
domConstruct.create('option', {
innerHTML : 'cat1',
value : 'cat1'
}, this.domNode);
domConstruct.create('option', {
innerHTML : 'cat2',
value : 'cat2'
}, this.domNode);
domConstruct.create('option', {
innerHTML : 'cat3',
value : 'cat3'
}, this.domNode);
this.inherited(arguments);
}
});
Other information:
The most useful settings for query are either a string, representing a path or object id, or an object containing either/both of the members path and statement where statement is a CMIS query e.g. SELECT * FROM cmis:document.
The store uses deferred functions to manipulate the query reponse so that either the succinctProperties or the properties object for each item are returned – if you’re not using succinct (the default) then make sure you get the value for your property
The response information is retrieved by making a second call to get the transaction information.
Add actual makes three calls to the server – add, retrieve the transaction and then fetch the new item – although it’s not documented it seems that Tree at least expects the response from add to be the created item.
The put method only allows you to update a limited number of properties (note cmis:description is not the same as cm:description) and returns the CMIS response rather than the modified object
Remove makes the second call despite the fact that’s it’s not in a transaction – this allows response handling to happen.
For documentation there is the Dojo standard – I did also consider using JSDoc but decided to stick with Dojo format
There are some tests written with Intern however they are fairly limited – not least because there’s a very simple pseudo CMIS server used.