Prompted by Jeff’s post the other day on developing custom actions for Share, I’ve spent a small amount of time this week revisiting the custom Document Library actions hosted on Share Extras, and making a few 4.0-compatibility updates.
There are now two add-ons within the project that provide custom doclib actions for 4.0

• The Execute Script action provides a small JavaScript action with a dialogue for selecting a JavaScript file to run against a document or folder. Although duplicated by the new onActionFormDialog-powered document-execute-script action (configured out-of-the-box but not included in the default action groups) in 4.0, it provides a useful example of a simple client-side custom action.
• The Document Geographic Details add-on provides a Geotag action for adding or modifying geo data on repository items, plus two other actions which complement the out-of-the-box View in Google Maps action by adding support for OpenStreetMap, as well as other mapping providers via the Geohack service used by Wikipedia articles.

Since the second add-on provides a few more varied examples of custom actions (which may not be obvious from the project name!) I thought it was worth stepping through each of these in turn.

Geotag Action

This JavaScript action was present in the original 3.x version, and allows geographic information – basically latitude and longitude values – to be added to items, or modified on items which already have it. If your camera doesn’t have a GPS receiver to capture this information, or if you need to make minor corrections to it, then this might be useful.
To make the action compatible with 4.0 there weren’t too many changes needed. Actions are now declared via Bubbling rather than as additional prototype methods of Alfresco.doclib.Actions, so a small refactoring of the code is necessary, but should not affect the main logic of your JavaScript action.
I’ll try to post an update in the near future on converting your existing actions to 4.0.

The action works by calling a separate web script – included within the add-on – to display a modal dialogue with a Google Map view. You can use the cursor to position the marker indicating the item’s location as you need, then the position of the marker is saved back to the repository when the OK button is clicked.

View in OpenStreetMap Action

One of the new features in Alfresco 4.0 is an additional page that allows you to view the geographic location of an item using an embedded Google Map. But sometimes Google Maps just doesn’t have the detail that other mapping providers have – particularly for rural areas – and OpenStreetMap is a great example of a collaboratively-built map available on open terms.
The OpenStreetMap view looks similar to the Google Maps view. In fact, although it declares a new site page, it borrows everything but the map view itself from existing Share page components on the Google Maps page.

The map view is provided by a single additional web script, which delegates the work of setting up the map to a client-side component, as per the regular Share pattern.
When I first added the map view last year, I implemented the view using the popular OpenLayers viewer, but I had problems getting a marker and an associated pop-up that looked as good as Google’s. So I switched the other day to the upstart Leaflet,  which provides a much easier-to-implement and cleaner-looking alternative.
From their site,

Leaflet is a modern, lightweight BSD-licensed JavaScript library for making tile-based interactive maps for both desktop and mobile web browsers, developed by CloudMade to form the core of its next generation JavaScript API.
It is built from the ground up to work efficiently and smoothly on both platforms, utilizing cutting-edge technologies included in HTML5. Its top priorities are usability, performance, small size, A-grade browser support, flexibility and easy to use API. The OOP-based code of the library is designed to be modular, extensible and very easy to understand. Find out more on the features page.

This is the first time I’ve tried Leaflet, but it works well here. I’d be interested in any feedback on this, as I may consider replacing the Google Maps view currently provided in the Document Geographic Details page component with it in the future.
There’s no doubt a few enhancements possible here, such as displaying the location of nearby repository items on the map view in addition to the currently-selected item. Again I’d be interested in any feedback.
Back to the action definition. Now since the action itself just needs to link to the new page, it can be easily handled by the pagelink action type, much easier than implementing a custom client-side action handler. An action evaluator ensures that the action is only shown for geotagged items, and is borrowed from the configuration of the View in Google Maps action.
Lastly, if you look closely at the screenshot you’ll see that as well as displaying the map itself, it also indicates the location of the marker, e.g.

This is looked up via a separate AJAX call to OpenStreetMap’s Nominatim reverse geocoding service, which takes a latitude and longitude, and returns some text indicating the name of the area that it resides in. Nominatim is accessed via a custom Surf endpoint, declared in the add-on’s configuration.

View Location on Geohack Action

The Geohack service allows a referring web site to specify a latitude and longitude as URL parameters and then returns links to that location on a wide range of mapping providers. If you want to view a location on other mapping services besides Google Maps and OpenStreetMap then you can use this action to do that.
Like the Geotag action this is implemented as a client-side JavaScript action, but since it only needs to open a new window with the Geohack service there is no additional dialogue or page definition needed.
With 4.0, it is possible to implement such actions much more easily using the link action type, which takes a target URL in its configuration, and which can include parameters that are substituted in at runtime, based on the node’s properties. But implementing it in a client-side handler as I’ve done here can give you more control.

Developing your own actions

Hopefully the three examples I’ve walked through will provide examples of what is possible to achieve in Alfresco using custom actions. You can find the code linked to from the Document Geographic Details add-on page, and further docs in Client-side template and action extensions on docs.alfresco.com and in Mike Hatfield’s DevCon 2012 presentation.