Back to Part I: How to create an Alfresco page that uses no authentication

This post is trying to explain in few short steps how to create an Alfresco dashlet. It was inspired by this question on StackOverflow.

Basically, a dashlet is consisting of a few files (usually 3-4 + internalization files), most of them placed in tomcat shared loader (the usual way I deploy Alfresco extensions). Here are  the typical files we would create:

<TOMCAT>/shared/classes/alfresco/web-extension/site-webscripts/my-dashlet/my-dashlet.get.desc.xml
<TOMCAT>/shared/classes/alfresco/web-extension/site-webscripts/my-dashlet/my-dashlet.get.html
<TOMCAT>/shared/classes/alfresco/web-extension/site-webscripts/my-dashlet/my-dashlet.get.js
<TOMCAT>/shared/classes/alfresco/web-extension/site-webscripts/my-dashlet/my-dashlet.get.properties
<TOMCAT>/shared/classes/alfresco/web-extension/site-webscripts/my-dashlet/my-dashlet.get_de.properties
<TOMCAT>/share/components/dashlets/my-dashlets.css
<TOMCAT>/share/components/dashlets/my-dashlet.js
<TOMCAT>/share/components/dashlets/my-dashlet-min.js

We could do with just the first two, so let’s try. (Alfresco used one more file in versions prior to 4, but the differences are minor. If you run into that, ask me or at the Alfresco forums.)

The first file is my-dashlet.get.desc.xml. When starting, Alfresco will pick up the *desc.xml files from site-webscripts folder and get its configuration. The GET part of the name says that this component will answer to a GET HTTP call. If you named it my-dashlet.post.desc.xml, you would not be able to access the component via GET method.

Anyway, the file:

<webscript>
  <shortname>My Dashlet</shortname>
  <description>Example dashlet</description>
  <family>user-dashlet</family>
  <url>/components/dashlets/my-dashlet</url>
</webscript>

The URL part is the most important thing here – if you remember, in our page template, we reserved a region for such a dashlet.

Now, the second file, my-dashlet.get.html.ftl is the actual HTML that we will use. We can simply say something like this:

<@markup id="html">
  <@uniqueIdDiv>
    <div class="dashlet my-class">
      <div class="title">My Dashlet</div>
        <div class="body">Hello world!</div>
      </div>
    </@>
 </@>

If you now copy the two files in their folders and refresh Share webscripts (http://localhost:8080/share/service/index, click on Refresh webscripts), you would see this dashlet when trying to customize user dashboard.

You can even access the component directly, by going to http://localhost:8080/share/components/dashlets/my-dashlet – you would only get the component (dashlet), not the whole page.

We could make things a bit more fun, you could replace the html content with this:

<@markup id="html">
  <@uniqueIdDiv>
    <div class="dashlet my-class">
      <div class="title">${msg("header.title")}</div>
        <div class="body">${msg("text.hello")}</div>
      </div>
    </@>
 </@>

And then add another file or two, my-dashlet.get.properties (with the default messages) and my-dashlet.get_de.properties (with German language messages).
The default, my-dashlet.get.properties, contains this:

header.title=My dashlet
text.hello=Hello world

The other file could look like this:

header.title=Meine dashlet

If you deploy the two files to their places and refresh the webscripts, you’d get the same result. However, if you change your language setting in the browser and place German above English, you’d get slightly different dashlet title. (That’s how you internationalize dashlets.)

To make things pretty, you would add a CSS call in the html.ftl file, and to make things useful, you could also include some client-side Javascript. Just add the links to them in the my-dashlet.html.ftl file:

<@markup id="css" >
 <#-- Link to your CSS file -->
 <@link rel="stylesheet" type="text/css" href="${url.context}/res/components/dashlets/my-dashlet.css" group="dashlets"/>
</@>
<@markup id="js">
 <#-- Your JavaScript file. You actually only need the my-dashlet-min.js file (unless in development mode), but we usually keep the original source in my-dashlet.js there so we can change it later.
-->
 <@script type="text/javascript" src="${url.context}/res/components/dashlets/my-dashlet.js" group="dashlets"/>
</@>

<@markup id="widgets">
<!-- Now let's initialize those two thingies - put them in the <head> of the page --> 
 <@createWidgets group="dashlets"/>
</@>
<@markup id="html">
 <@uniqueIdDiv>
   <div class="dashlet my-class">
     <div class="title">${msg("header.title")}</div>
       <div class="body">${msg("text.hello")}</div>
     </div>
  </@>
</@>

What you put in the CSS in JS files is…well, out of scope .

Now, to make things more dynamic, we could also use something dynamic: we can make a servers-side javascript file my-dashlet.get.js which will be able to show us something dynamic.

Let’s say we want to know what’s the time on the server. We can put this in the JS file:

model.currentTime = new Date();

You see, we placed a currentTime variable into the page model. Now we can use that variable in our HTML template. Put this under our Hello world line:

<p>Current time on the server is ${currentTime?string.medium}.</p>

That’s basically it. You can also call the repository backend unauthenticated, you just need to define the backend webscripts with <authentication>none</authentication> – and you could access some of the public data this way. But that’s another matter for another post and another poster.

Hopefully this made creating some dashlets easier to someone.