How To Add Content To An Alfresco Share Page

cancel
Showing results for 
Search instead for 
Did you mean: 

How To Add Content To An Alfresco Share Page

ddraper
Intermediate II
0 24 10.2K

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).

Screenshot showing "Blog Demo" Web Script family highlighted

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'.

A screenshot of te Web Scripts Home page showing the enable surf bug buttonScreenshot showing the Surf Bug status page

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.

Screen shot of Share displaying Surf Bug information

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.

Module Deployment page with the blog module undeployed

Module deployment page with the blog module deployed

Now log back into Alfresco Share and you should see that the content from the new Web Script is displayed above the title bar:

Screenshot of Share user dashboard with new content

24 Comments
blog_commenter
Active Member
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'
ddraper
Intermediate II
Thanks for spotting that Romain, that should be fixed now.
blog_commenter
Active Member
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?
ddraper
Intermediate II
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.
blog_commenter
Active Member
[...] existerande komponentet med vår egen utan att ändra mallen. För detaljer kring detta läs, read David Drapers blogg (första inlägget i en [...]
blog_commenter
Active Member
[...] an existing component with our own, without changing the template. For details on this, read David Drapers blog (first post in a [...]
blog_commenter
Active Member
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
ddraper
Intermediate II
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
blog_commenter
Active Member
Hi Dave,

your blog is explosive Smiley Very Happy congratulations, will be a tutorial on how to develop a new action on Alfresco 4? (With java becked webscript?).
blog_commenter
Active Member
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
blog_commenter
Active Member
Got it working please disregard my comments above for April 3 2012

user/{userid}/dashboard
blog_commenter
Active Member
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
ddraper
Intermediate II
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: https://www.alfresco.com/blogs/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: https://www.alfresco.com/blogs/ddraper/2012/05/22/customizing-share-javascript-widget-instantiation-...).

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
blog_commenter
Active Member
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.
blog_commenter
Active Member
Dave:
Java packages don't have dash in them? alfresco.site-webscripts can't create this package? what is the work around?
thanks
Spider
ddraper
Intermediate II
@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
blog_commenter
Active Member
[...] my last blog I introduced some of the new extensibility features that are now available in the latest Alfresco [...]
blog_commenter
Active Member
Dave,



Did you even read your own blog?



'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'



Hence spiders question.
ddraper
Intermediate II
@Jon ... you're right, I neglected to bother to re-read a blog I wrote over two years ago and gave a snap answer without really appreciating the context of the question. However, given that I've now written numerous blogs on this subject (and provided downloadable source code) that contain the example packages that spider claims aren't working, I guess I missed the point. I suppose the answer is, 'Yes... actually you can use those packages, we do it all time.'
blog_commenter
Active Member
Thanks in advance, Dave Draper, for putting these examples together.  I'm an Alfresco newbie and I'm trying to hide a significant portion of the functionality used in the Share site from my users and leave mainly the Document Library.  To accomplish this, I started working with this example to figure out how to get webscripts going, then planned to move on to the next tutorial where you show how to hide things and I should be able to take it from there.  Please feel free to stop me here if there's a better (or newer) way to accomplish this task.



On to this example, I am having issues getting the very first part working and I too am afraid that my problem may be with how I've structured the 'packages' in my JAR file.  I created the following directories:



/alfresco_mods

/alfresco_mods/alfresco

/alfresco_mods/alfresco/site-data

/alfresco_mods/alfresco/site-data/extensions

/alfresco_mods/alfresco/site-webscripts



And placed the following files in '/alfresco_mods/alfresco/site-webscripts':



new-content.get.desc.xml

new-content.get.html.ftl



After JAR'ing up the directory, copying to my Tomcat's 'webapps/share/WEB-INF/lib', and restarting Tomcat, I'm not seeing the new entry in the Webscripts list.  Am I missing something obvious?  Did I fail to layout my JAR file correctly?  Do you perhaps have a sample JAR you could post here (or send me directly) so I can ensure my structure matches?  Thanks in advance for any assistance you can offer -Don
ddraper
Intermediate II
@Don - try the JAR without the 'alfresco_mods' root directory - it should work then.
blog_commenter
Active Member
Hi, Dave.

Thanks for a greate post and instruction.

Could you please tell me what should be used as source-id and scope values to add block to a title region on all Share pages?

Thanks in advance =)
ddraper
Intermediate II
@Ilya - Thanks for the feedback.  I'd recommend using SurfBug to find out that information as the blog post says, more info here: https://www.alfresco.com/blogs/developer/2011/08/31/surfbug/



However, you should bear in mind that this blog was written quite a while ago and the header has changed significantly since then... this technique will only be relevant for v4.0 and v4.1 - otherwise see these later posts for 4.2: https://www.alfresco.com/blogs/developer/2013/09/04/customizing-the-share-header-menu-part-1/