You are here

Building Your First Webscript

Webscripts are fast becoming the main development tool for those who are seeking to extend and enhance Alfresco. In this article I'm going to try and detail how to build a webscript. This is as much for my own documentation needs as it is for public consumption. So if you notice any errors, then please let me know!

Webscripts can sit in a variety of places, from directly in the Alfresco repository, to sitting within their own SpringSurf apps. However, no matter where you put them, they all have a similar structure.

  • XML descriptor file that tells describes important aspects of the webscript (Required)
  • Javascript file that does some processing etc (Optional)
  • Freemarker template file that returns some nicely presented information to the user. (Optional)

Although the second and third of the above elements are optional, you need to have one or the other, otherwise your webscript wont do anything.

Purpose of the Webscript

We're going to design a webscript that sits within the Webscript Extension area of the Data Dictionary. This could in theory be added to the classpath, but putting it in the data dictionary means you don't have to do a server restart everytime you change it. The webscript itself is fairly basic, and all it does is return back the structure of a given area within the repository. This kind of script can be used as the basis for site tree, or something similar.

The Descriptor File

This is perhaps one of the easiest parts of developing the webscript, and yet it can inself cause problems if you enter the wrong information. There are specific naming conventions that need to be observed for all webscript files. First comes the name of the webscript, then the type of HTTP call that is being made (GET, POST, etc), then the type of information that is being returned (HTML, JSON, etc), and finally the file extension. So for our webscript, we'll create a file called getsitetree.get.desc.xml. Here's the contents of the file.

1
2
3
4
5
6
7
8
<webscript>
  <shortname>Get Site Tree</shortname>
  <description>Retrieve the site tree from Alfresco</description>
  <url>/alfrescocms/getsitetree</url>
  <format default="html">extension</format>
  <authentication>user</authentication>
</webscript>
 

Let me take a little time to explain what this all means.

<webscript>

A container element that contains all the parameters of your webscript.

<shortname>

A brief shortname for your webscript that will be shown when browsing available webscripts. This can be anything you want.

<description>

What your webscript does.

<url>

This is a really important one. This is basically the url that your webscript will respond to. It is entirely up to you decide what you want to call it. You might want to group certain scripts under certain nodes (e.g. /node/script), or every script may just get a root name (/script). Give that for the most part you will be dealing with an evironment that has other scripts (Alfresco related) and not just your own, I find it is better to go for the first option for usabilitys sake.

<format>

This can include the default return type. One of the great things about webscripts is that one webscript can return multiple different types, all through the power of freemarker. So, for example, I might want a webscript to be able to return html, json and xml. But if no return type is specified, then whatever the default specified is, that is what is returned.

<authentication>

There are three different possible values for this.

  • admin
    Admin requires someone who has administrator priviledges for the Alfresco system (not just  for a specific area). Be aware that there can sometimes be a performance hit when using this one. As it has access to everything, there can be a lot more information to wade through than for just an ordinary user.
  • user
    Requires any user that can log in to Alfresco
  • guest
    No login required

Javascript File

Next comes the javascript file. This is the main engine of the webscript that will do the majority of the processing for you. The freemarker templates can do some processing, but that is more at the presentation level than the nuts and bolts stuff sometimes required. Following the naming conventions outlines above, our file will be called getsitetree.get.js (nothing being returned by this file, so no need for the html/json bit.)

1
2
var folder = companyhome.childByNamePath("WebStore/www"); 
model.www = folder.children;

This is very basic. What is does is declare a variable called folder that goes and gets all the children of the path specified. In this case it returns all the children of the folder "www", which is below "WebStore". Because we are using the companyhome root scoped object, this folder has to appear in the "Company Home" area of the repository.

Finally it declares a new variable in the model called www and loads it with the children of the variable we declared in the previous line.

Freemarker Template

Now that we have some information in our model, we can do some processing on it. We're going to pass this information back as html initially to make our lives a bit easier. So our freemarker template should have the filename getsitetree.get.html.ftl. Here's what it includes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<#if (www?size > 0)>
	<ul>
		<#list www as child>
			<li><a href="${url.context}/home/page=${child.nodeRef}">${child.name}</a>
				<#if (child.children?size > 0)>
					<ul>
					<#list child.children as grandchild>
						<li>${grandchild.name}</li>					
					</#list>
					</ul>
				</#if>
 
			</li>
		</#list>
	</ul>
<#else>
	<p>Nothing to Retrieve</p>
</#if>

This returns an unordered HTML list that gives the first two levels of our structure. What we might want to do in the future is change that so that it cycles through the entire tree, but this will suffice for the time being.

Line 1 checks to see whether there is anything in the www object. If there isn't, it simply skips to line 17 and tells the user there is nothing to retrieve.

Line 3 sets us up to access the child nodes of the object and output them, which is accomplished by line 4. Line 5 checks to see whether the current node has any children, if it does, the same thing happens again and those children are output.

Common problems arise from not closing your tags properly, so it is always the first thing I check when debugging a problem.

Getting Alfresco to recognise the webscript

Whilst I said above that Alfresco doesn't require a server restart, it does require an extra step so you can tell it to recognise the webscript. This is accomplished by going to "http://localhost:8080/alfresco/s/" and logging in with an administrator username and password. Click on the "Refresh Webscripts" link and all going well you should see your webscript count go up by 1.

Calling your Webscript

To test your webscript you can simply call it from the address bar in your browser. So for our example above, we would go to "http://localhost:8080/alfresco/s/alfrescocms/getsitetree".

Tags: