Getting started with customizations

[jaspervlb]

Hi

I would like to customize alfresco share for my organisation. I've already been able to do some "standard" customizations by reading topics on several forums and blogs. Many thanks to the authors of those.

Now I'am arriving to the more specific customizations for my needs and I was trying to get along by myself but it proves to be very hard.
I was wondering if I could get a clear explanation of how share is built. What happens where and what is the function of each specific file. I've found bits and pieces everywhere. Outdated stuff and so on… Could someone give me a clear explanation? Pointers to the links I have missed. Or give an explanation that pastes the bits and pieces I have together.

For instance you have ".get.html.ftl" files, ".get.js" files, ".js" files, xml and so on…
I've read things about Freemarker, Surf, serverside javascript, clientside javascript, javabeans…how do these all connect together. Which files use which files? What connects them?
What makes a component different from a module?

Another practical question: I was trying to customize sites.get.js (of the header module). To understand what the script was doing I tried to include "window.alert" statements. However this did not work. Share told me he could not load the template module. I figured the javascript was executed server-side. How can I debug these scripts in a handy way? (and the other files used?)

I tried to keep my questions quite general. I will post my specific questions in seperate threads. I hope this thread can be like a general starting point for other people.

Thank you for your responses!

PS: I have a background in software engineering. I know javascript from making websites in php and html 10 years ago. Freemarker, json, surf, rest however are all new to me.

[ddraper]

Hi,

I'll try and give you some pointers to get you started…

First of all, when you post a question it's always helpful to say which version of Alfresco that you're working on - especially when it comes to customizing Share because this is an area that has seen a lot of development over the last few releases.

The reality is that like any application Share has evolved over many years of development (and is continuing to do so) which means giving a single clear-cut answer is not quite so straightforward.

The files you refer to ".get.html.ftl", ".get.js", etc are all WebScript files (http://wiki.alfresco.com/wiki/Web_Scripts). WebScripts follow an MVC pattern where the controller (either a Java class or a JavaScript file) define a model that is passed to a FreeMarker template. Each WebScript requires a descriptor (the .desc.xml file) that defines the URL(s) to access the WebScript along with lots of options including user access requirements, etc - it's worth reading that Wiki page thoroughly to get a good understanding of WebScripts as they are fundamental to Alfresco.

Share is built on the Spring Surf framework that has seen a radical overhaul over the last few years. The reality is that although it provided many powerful features it lacked documentation and the complexity of the pages that were created were built up from a lot of files and were difficult to understand and customize. We introduced the SurfBug tool (http://blogs.alfresco.com/wp/developer/2011/08/31/surfbug/) to help developers understand the makeup of a page and track down the correct files that they needed to work with.

Essentially a Surf Page maps to a Surf Template Instsnace that is associated with a view renderer (typically a FreeMarker template). This FreeMarker template would declare multiple regions and these would be bound to scoped Components when the page was rendered. Typically each Component was rendered by a WebScript that would define a DOM fragment and instantiate a JavaScript widget that was bound to it. The original set of widgets were almost exclusively built around the YUI2 clientside JavaScript library.

The original pattern for customizing Share was to copy/paste the WebScripts that backed the Components into the "web-extension" path (which Surf would search first) and make updates to the copied files. Unfortunately this would immediately introduce a maintenance issue to keep the custom WebScripts in-sync with changes to the originals.

For version 4.0 we updated Surf so that it was possible to dynamically add/remove/modify region definitions to make it easier to customise the page template to access different WebScripts. We also made updates to break Components down into Sub-Components to allow you to easily add/remove/change content at the Component level. However, this still left the problem of customizing the JavaScript loaded onto the page.

For 4.2 Community we refactored all of the WebScripts in Share to follow a pattern that moved all of the logic out of the FreeMarker WebScript file and into the JavaScript controller. This meant that it is now possible to easily override the JavaScript widgets loaded into the page to make much finer customizations.

At present we are working on making it even simpler to build and customize pages in Share with futher updates to Share that allows us to utilize the AMD pattern and define pages as simple JSON models in a WebScript controller where each page is built of smaller, decoupled Widgets that communicate over a pub/sub layer. This should ultimately provide more consistency across the application, and allow us to make pervasive changes to a smaller set of files and allow much greater flexibility with customizations. At the moment the only place this has currently been used is in the header bar that is in the latest committed source to the main SVN branch. Although we'll probably release the initial set of widgets into the Community source when 4.2 Enterprise is released, it is unlikely that they will be used in the main product until a later release.

So, now to answer your specific question on the sites.get.js file…  that file will be exceuted on the server side so adding an alert() statement won't have an impact. What you should do is work with one of the client-side resources.

With regards to the difference between components and modules … that was all in place before I joined the company, but I suspect that the JS file under "components" are there because they are specifically used by a Surf Component, whereas those under "modules" will cross-cut multiple Surf Components.

In terms of debugging… SurfBug will help you identify the files that make up a page and you can also enable the JavaScript debugger in the WebScripts console (goto /share/service/index  and click "Alfresco JavaScript Debugger" from under the "Maintenance" section). You should also set "client-debug" to true in "share-config.xml" to ensure that the uncompressed client-side resources are loaded to ensure that you can inspect/debug them with Firebug, etc

I hope this is useful,

Regards,
Dave

[zladuric]

Also, more bits and stuff here. It may sound like bragging, but it is not, it is just how I used to explain some of this stuff to myself and others. I think it might help a little bit.

So maybe start here, how to create a dashlet:
http://zlayer.net/blog/?p=255

So, lets say you can create a dashlet, or component, so now how to put a few of them together?
Also, how is a page assembled?
http://stackoverflow.com/questions/14499151/alfresco-share-using-dashlet-into-a-custom-page-programm...

And last, a little bit about client-side JS:
http://stackoverflow.com/questions/1221100/how-does-alfrescos-javascript-not-webscript-mechanism/998...

[mitpatoliya]

Dave & Zlatko,

Great explanation It certainly summarize the alfresco share anatomy.It is really difficult to first understand the existing architecture and also to keep updated about the changes done in the architecture in latest version as It is changing very rapidly. But I agree with Dave ongoing changes will certainly make it lot more easier to customize and extend the Share.

[jaspervlb]

Thanks for the responses. They where certainly helpful. Especially in understanding what file does what.

I did not include what alfresco version I was using, because it is a separate field you can fill in when you create a topic. Weird that is nowhere to be seen afterwards, that is a bit confusing.

I have some more specific questions now that I will ask in a separate thread.