Introduction
This is the first in a series of blogs that is going to describe some of the new extensibility features that are now available in the latest Alfresco Community source code and will later appear in Alfresco Enterprise 4.0.
A complaint that we sometimes hear about Alfresco Share is that it is not particularly easy to customize. So for Alfresco Enterprise 4.0 we’re going to provide a number of different ways in which to make customization easier. One of the ways that it will be possible to do this is by taking advantage of new extensibility features that have been added into the Spring Surf framework upon which Alfresco Share is built.
The primary goal of these features was to ensure that it wasn’t necessary to completely re-write Alfresco Share. Although we wanted to introduce new concepts, we didn’t want to force developers to completely re-learn how Alfresco Share is put together.
In later blogs I’m going to explore the new framework in detail and describe all the features and exactly what’s changed, but as an introduction I’d like to demonstrate how to add some new content to an existing Alfresco Share page.
Tutorial
The quickest way to add content to an Alfresco Share page is to create the content as a Web Script and then add a new Sub-Component an existing Component on the page.
The content is going to be provided by an Extension Module deployed into Alfresco Share as a JAR file. The JAR file needs to contain the following packages:
- alfresco.site-data.extensions
- alfresco.site-webscripts
First of all, let’s create some content as a Web Script, the actual content isn’t important so we’ll keep it simple. A Web Script needs a minimum of 2 files; a descriptor and a template (this isn’t a blog on Web Scripts so I’m going to assume you know about them, but if you don’t – there’s lots of information available here.
Create a new file called “new-content.get.desc.xml” containing the following:
<webscript>
<shortname>New Content</shortname>
<url>/blog/demo/new-content</url>
<family>Blog Demo</family>
</webscript>
Create a new file called “new-content.get.html.ftl” containing the following:
<div>
Hello World!
</div>
Build your JAR file so that files are in the “alfresco.site-webscripts” package. Copy the JAR file into the “webapps/share/WEB-INF/lib” folder in Tomcat (or the equivalent location in whatever web server you’re using) and start (or restart) the server. It should be noted that placing a JAR in this folder means that the it won’t survive an upgrade or WAR re-deploy – but placing it there is sufficient for the purposes of this tutorial.
Open a browser at the URL http://localhost:8080/share/service/index (assuming you’re running the server on your local machine and you haven’t tinkered with the port and application context settings ) and you will be taken to the Web Scripts Home page. Check that you can see a link for “Browse ‘Blog Demo’ Web Scripts” (this indicates that your new Web Script has been successfully registered).
We now want to select a location to add our new content – to help with this we’re going to use a new tool called “SurfBug” (which I’ll cover in greater detail in a later blog). Log onto Alfresco Share (http://localhost:8080/share) in a separate browser window or tab, then switch back to the “Web Scripts Home” page and scroll to the bottom and click the button labelled “Enable SurfBug” (the page should refresh and the button should have changed to say “Disable SurfBug”.
Switch back to the Alfresco Share window and refresh the page. You should now see that the user dashboard now has some red boxes shown on it indicating the Sub-Components that are present on the page. Click in any of the boxes and a pop-up will be displayed providing information about that Sub-Component and its parent Component.
Click on the title bar and make a note of the “Component Details”, in particular the “region-id”, “source-id” and “scope” values which (if you’ve logged in as “Admin”) will be:
- title
- user/admin/dashboard
- page
This is the information that you’ll need to add a new Sub-Component to that existing Component. Create a new file called “blog-demo.xml” containing the following:
<extension>
<modules>
<module>
<id>Blog Module (New Content)</id>
<components>
<component>
<region-id>title</region-id>
<source-id>user/admin/dashboard</source-id>
<scope>page</scope>
<sub-components>
<sub-component id="New_Content" index="25">
<url>/blog/demo/new-content</url>
</sub-component>
</sub-components>
</component>
</components>
</module>
</modules>
</extension>
Note how the target Component is specified using the data taken from SurfBug and how the Sub-Component specifies the URL of the new Web Script created.
Re-build the JAR so that file is placed in the “alfresco.site-data.extensions” package, copy the new JAR over the old one in the “webapps/share/WEB-INF/lib” folder and restart the web server.
In order for the new content to be displayed the module needs to be deployed. Module deployment is a new feature in Alfresco 4.0 that is done through a Web Script found at: http://localhost:8081/share/service/modules/deploy. Navigate to this page and you should see a list of “Available Modules” and a list of “Deployed Modules”. Initially you should see the following 2 modules available:
- Alfresco Portlet Extension
- Blog Module (New Content)
Select “Blog Module (New Content)” and click the “Add” button to move it into the “Deployed Modules” list, then click the “Apply Changes” button (you should notice that the “Last update” time stamp changes). This action only needs to be done once as Module Deployment data is saved into the Alfresco Repository.
Now log back into Alfresco Share and you should see that the content from the new Web Script is displayed above the title bar:
Hi,
That looks really exciting.
But I just noticed a typo: three lines under the first image “Show-Blog-Demo-Web-Script-Family-screenshot-1-with-highlight.png”
Thanks for spotting that Romain, that should be fixed now.
It looks interesting.
But my concern is that there are a lot of steps involved in just getting a small update.
Alfresco 4 server seems to be a lot slower to start than 3.4.x and it looks like a re-jar followed by a web restart is required for every iteration during development. The time between development iterations looks to be very long.
Is there some way to do more rapid development?
Also — is it necessary to do a manual deploy? Can something be configured in the server files to avoid having to manually bring up the ‘Module Deployment’ screen and add it?
Thanks for the comments…
There is a configuration option for switching between manual and automatic deployment mode. You can place the following configuration in your share-custom-config.xml file to change to auto mode:
<config evaluator="string-compare" condition="WebFramework">
<web-framework>
<module-deployment>
<mode>auto</mode>
</module-deployment>
</web-framework>
</config>
All modules found in your Surf configuration locations will be be deployed automatically, however – you will have no control of deployment ordering and it will not be possible to override module evaluators and properties.
You will only need a restart for Java and Surf configuration changes – if you have just changed the associated WebScript then you simply need to refresh the WebScripts. You don’t have to use JARs during development (the files can just live in the exploded application WAR on the server) and I’ve found that using the Eclipse IDE you can produce a new version of the JAR in a couple of mouse clicks – I personally haven’t found development iterations overly long (although I do develop with the Alfresco Repository and Alfresco Share running on different Tomcat instances and the startup time for Share alone is much shorter).
You’re right that this is a lot of steps to achieve the blogged example – but it is just a trivial example to demonstrate the basic concepts. Your extension can be as complex and broad as you like.
Pingback: Erik Winlöf's blog » Blog Archive » Create pages in Alfresco Share using new “out of the box” templates
Pingback: Använda Alfresco som portal för webbapplikationer | Loftux AB
Pingback: Use Alfresco as a portal for web applications | Loftux AB
Thanks David for your blog!
I’ve been reading a interesting post that talks about calculated columns datalist and how to implement in 3.3 and 3.4b using AbstractFilter class and implementing four functions….
I wonder if you know a better way to achieve this in Alfresco Share, since I need this, from a list with properties a, b, c. And c= a + b.
Regards
The link of the post I mention is
http://www.boulderhopkins.com/2010/10/creating-calculated-datalist-columns-in.html
If you just want to implement calculated columns as the blog post shows then I actually think that using the previously available extension mechanisms as described are perfectly acceptable.
Regards,
Dave
Hi Dave,
your blog is explosive
congratulations, will be a tutorial on how to develop a new action on Alfresco 4? (With java becked webscript?).
In this tutorial it shows how to expose content for the user/admin/dashboard which shows the content
on the admin page only. How do i get this to show on the sites as well? I see ${site-id} as some example but how does this get populated
with the name of the site. I try to deploy my jar with user/${site-id}/dashboard but it did not work.
Any help would be great!!!!
Thanks
Got it working please disregard my comments above for April 3 2012
user/{userid}/dashboard
Hi David,
it’s very useful blog, thanks.
What I want to do is to place an action to the document library toolbar, that is displayed according to:
- folder type
- user membership in the special group
So it means this action should be displayed for some users in special folders.
But if I try to use an evaluator as described here: http://docs.alfresco.com/4.0/topic/com.alfresco.enterprise.doc/tasks/tu-v4-subcomponent-evals.html
I see a lot of limitations such us:
- as parameters I receive only a request context, that has info about used site but not about expanded folder
- the evaluator is called only once, if the document library has been opened and not by browsing of folders
May be you can add some details to this blog for more extended use-cases?
Thanks in advance
Vitali
Hi Vitali,
Thanks for the feedback. The approaches defined in this blog are for coarse-grained additions of content (i.e. at the component level, rather than within the content rendered by a component). For specific Document Library customizations we added some specific functionality (which Mike Hatfield describes here: http://blogs.alfresco.com/wp/mikeh/2011/09/26/share-document-library-extensions-in-v4-0/) and we’re also making improvements for the next major release that will make it easier to extend the JavaScript objects without copying and pasting code (which I’ve described in blogs starting here: http://blogs.alfresco.com/wp/ddraper/2012/05/22/customizing-share-javascript-widget-instantiation-part-1/).
We’re working hard to make customizing Share easier, and whenever you are unable to achieve a customization via the new features there is always the option of falling back to overriding via the “alfresco/web-extension” path (which unfortunately will require copying, pasting and then modifying the original code)
Regards,
Dave
Thank you very much for your great tutorial.
I have followed the guide but I face some problem:
1. I cannot name the package with site-webscripts or site-data in Java so I cannot build the jar file.
2. I put directly the files in the corresponding directories, and everything still seems to work. But After deploy the module, there is nothing on dashboard.
Did I miss some thing?
P/S. I’m a student studying about Alfresco. Maybe I have very little knowledge so please help me. Thank you very much again.
Dave:
Java packages don’t have dash in them? alfresco.site-webscripts can’t create this package? what is the work around?
thanks
Spider
@Spider: Can you provide some more context to this question please? The obvious answer from what you’ve stated in your question is simply not to use that package. The “alfresco/site-webscripts” location is configured as a Store for Surf and as such it shouldn’t be necessary to explicitly set that as a package anywhere. Can you please clarify where and why you’re trying to use that package please?
Regards,
Dave
Pingback: How To Hide Content On An Existing Alfresco Share Page | Alfresco Developer Blog