Update, 4th May 2011: The Backup action is now part of Share Extras and documentation and downloads are now available on the Custom Backup Action page.
Since the ability to package Share extensions was added in the HEAD codeline some weeks ago, both Kev and myself have demonstrated how you can package up dashlets in a JAR file for deployment into Share.
The example we both used was my Site Tags dashlet that we showed at the Alfresco Meetups last year, but at the Madrid meetup we also showed an example of how Share’s Document Library can be extended with a custom ‘backup’ action.
Document Library actions have no web-tier webscripts, but hook into the client-side actions framework using a bit of custom JavaScript. Each action has a small 16×16 icon and a bit of CSS code to apply this image, one or more text labels (which should of course be externalised for i18n goodness) and a bit of config to hook them into the app. Lastly, since most actions by their nature do something, it’s likely that they will make a RESTful call back to the repository to perform their work, which may require a custom webscript there.
That’s quite a few files, but fortunately we can use the JAR extension mechanism to package everything up nicely.
Just like the Site Tags dashlet, I set this up in Eclipse using a standard project layout and my share extensions build script (with a couple of minor changes) to build the JAR file.
To make it easy to copy this structure, I’ve uploaded a ZIP of the project directory, containing the following files
- build.xml – the extensions build script
- config/alfresco/messages/slingshot-custom-backup-action.properties – contains the strings used for the action label and confirmation/failure messages
- config/alfresco/templates/webscripts – contains the repository-tier webscript used to create a back-up copy of the file
- config/org/springframework/extensions/surf/slingshot-custom-backup-action-context.xml – Spring config used to initialise the i18n messages
- config/spring-surf-config-custom.xml – not used at present, but could define additional Surf endpoints for calling third-party RESTful services
- web – contains all client-side resources used by the action
It should be relatively easy to copy this structure to define your own custom action, following the custom action wiki document to understand what each file does. This will help you to build other actions that call back to the repository via a web script, but actions aren’t limited to calling Alfresco services only. For some examples, take a look at my own list of Share action ideas.
Once you have your structure you can build the JAR file using Ant, e.g.
ant -Djar.name=share-backup-action.jar
The JAR file can then be dropped into Tomcat’s shared/lib directory, and all that remains is to configure the document actions web scripts to pull in the action definition. This is the slightly fiddly bit.
Firstly, copy the web script configuration file WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/documentlibrary/documentlist.get.config.xml from the Share webapp into the directory alfresco/web-extension/site-webscripts/org/alfresco/components/documentlibrary in Tomcat’s shared/classes to override it. You should see a section <actionSet id="document"> which defines all the actions shown for a normal document in the document list view.
To add the backup action to this list, add the following line just before the </actionset> element for that block.
<action type="action-link" id="onActionBackup" permission="" label="actions.document.backup" />
If you also want the action to show up in the document details view, you need to copy the file WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/document-details/document-actions.get.config.xml into alfresco/web-extension/site-webscripts/org/alfresco/components/document-details in shared/classes in the same way.
Lastly, we need to ensure that the client-side JS and CSS assets get pulled into the UI as unfortunately the config files do not allow us to specify these dependencies.
To do this, we must override the file WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/documentlibrary/actions-common.get.head.ftl. Again, copy this into the corresponding directory in shared/classes/alfresco/web-extension and add the following lines at the bottom of the file.
<@link rel="stylesheet" type="text/css" href="${page.url.context}/res/components/documentlibrary/backup-action.css" />
<@script type="text/javascript" src="${page.url.context}/res/components/documentlibrary/backup-action.js"></@script>
That’s it. Now you can restart Tomcat and you should see the ‘Backup’ action – complete with UI labels and icon – in the Document Library.
Downloads
Just a small note here. This stuff
<@script type=”text/javascript” src=”${page.url.context}/res/components/documentlibrary/backup-action.js”/@script>
will probably not work. As far as I know, DEBUG is on by default so the @link and @script macros will look for the .min versions of the script. So you should probably go with this for safety:
Yeah… Tags got stripped out:
\
\\
You get the picture
Cosmin, you’re right that the @script macro will insert a reference to the compressed JavaScript files by default (since debug mode is turned OFF). If you look inside the JAR file or the source ZIP that I’ve included in this post, you should see the compressed versions included too.
Compressing your JavaScript is easy to do with YUI Compressor, given the increase in performance this gives you should always do it in your custom projects.
Yes, I meant Debug OFF, not ON. True, there is a min for JS, but not one for CSS.
Thanks for replying.
However, I am still wondering if a decent solution can be found to editing documentlist.get.config.xml and document-actions.get.config.xml. All I can think of is scripting this within Ant/Maven, inside the bigger build process (project-level).
What I would like to know if Alfresco has a way of storing multiple such files in separate locations/jars that can be “merged” together. It would be nice to have something like documentlist-custom.get.config.xml containing only my action which could be appended to the global actions list. But maybe I am pushing for too much right now 🙂
Hi all,
I’m relatively new to Alfreasco, overall on the 3.4d version.
I read the README.txt file provided with the distribution of the example.
Which are the changes that must be made to the actions framework for working with the example?
Thanks in advance
Hi Marco, the latest version of the action can now be found on Share Extras here – http://code.google.com/p/share-extras/wiki/BackupAction
If you check that wiki page, you should find full instructions there. No other steps should be required.
Hi
I have successfully used this project to create custom action for ver3.4d. I would now like to start experimenting with 4.0a but the same steps that applied to 3.4d does not work in 4.0a. The custom action is not displayed in the document library. What should I do to get it working in 4.0a.
I would also like to use this approach to add custom action to datalists. What do I need to change to make this work. I tried to follow the same steps except add the custom action to the datagrid view, I see the icon but it does not do anything if I select it
Any help would be appreciated
Thanks
“If you also want the action to show up in the document details view, you need to copy the file WEB-INF/classes/alfresco/site-webscripts/org/alfresco/components/document-details/document-actions.get.config.xml into alfresco/web-extension/site-webscripts/org/alfresco/components/document-details in shared/classes in the same way.”
What do we have to modify in the document-actions.get.head.ftl ?
Because I tried by modifying the following files document-actions.get.config.xml and the .get.head.ftl like the documentlist.get.config.xml and .get.head.ftl.
The new action displays so good in the Share UI but there is nothing when I click above (in the document-details part).
Could you help me please ?
Regards
Hi Eugene, I suggest you have a look at this file – http://code.google.com/p/share-extras/source/browse/trunk/SDK/Datalist%20Sample%20Action/README.txt – which has some details on adding datalist actions. The procedure is basically the same but there’s some tricky manual steps at the end to make the custom action display.
And yes, you’re right that the framework has changed complete for the doclib actions (not for datalists) in 4.0. There’s some pointers at the bottom of this page – http://docs.alfresco.com/4.0/topic/com.alfresco.enterprise.doc/concepts/doclib-client-side-template-and-action-extensions.html – or check the Share config for the detail of how the out-of-the-box actions are configured.
Hi Will
I have read your readme file and tried to make the changes that seems to be the obvious ones to make.
1) I used your Sample document library action source code as a starting point since the source code for the datalist back-up action does not point to a custom javascript
2) I then changed the the dir config/alfresco/templates/webscripts/org/shareextras/slingshot/documentlibrary/action/
to
config/alfresco/templates/webscripts/org/shareextras/slingshot/data-lists/action/
3) I then changed the the dir source/web/extras/components/documentlibrary
to
source/web/extras/components/data-lists
4) In then attempted to change the files as I could figure out but I did not see any real changes from the document library action files
5) I left the .js file as is but with my custom javascript action variable set
6) The slingshot-compile-email-action.properties file I only changed the line “actions.document.sample-script=Compile email”
to
“actions.datalist.compile-email=Compile email”
7) I then added “actions-common.get.head.ftl” and “datagrid.get.config.xml” to “\tomcat\shared\classes\alfresco\web-extension\site-webscripts\org\alfresco\components\data-lists\”
8) I added to “actions-common.get.head.ftl”
”
”
9) I added to “datagrid.get.config.xml”
“”
10) I did the mods to datagrid.js as you described in the readme and minified it
I can see the icon but it does not do anything when I click on it and it does not show my custom icon picture. So it appears it is not picking up my “actions-common.get.head.ftl” file.
I tried to describe what I did here in more detail
https://forums.alfresco.com/en/viewtopic.php?f=9&t=40986&p=127259#p127259
Hi Will
I’m trying to get this custom action for a datalist (that you assisted me with in the forum) to work on 4.0d. When I used lucene to run it it worked fine but now that I converted to Solr its not working. i do not see anything in the log files but it shows on the screen in share ” Failed to execute script”
It now works. The trick was not to change the dir.root variable. Solr has a few files that points to it on the C:/Alfresco/Alf_data location and I cannot find all the files that point here so its better not to change it then my custom action works again. Any way this is for me and only for my datalist action. Still need to figure out the doc lib action