Improving Aikau Education

Showing results for 
Search instead for 
Did you mean: 

Improving Aikau Education

Intermediate II
0 16 4,082


In my last blog post I talked about the perspective I’d gained by working in another team at Alfresco that has been using Aikau. For the last 18 months the Aikau team has been so head down in development trying to provide features and fixes for internal teams, customers and the community that we’ve not had much opportunity to focus on reviewing and improving the educational material that is available for Aikau.

Interestingly with the advent of the new Angular based UI framework and the conclusion of a number of major Alfresco projects that use Aikau the heat is now off us and I’ve had some time to start looking at what resources are available and how we can improve the situation.

At this point I think it’s important to state that as far as I’m aware Aikau development is going to continue and that if you want to develop a user interface for Alfresco - particularly if you want to customize or add new pages to Share - then Aikau is still the recommended framework.

Alfresco is still actively using Aikau (most notably for Records Management in Share) which is hugely important for its business. The use of Aikau is never going to be the headline feature in an Alfresco release, but it’s usually there in the background getting the job done.

Eating Our Own Dog Food

I decided to have a go at reproducing some existing YUI2 based features of Share using Aikau to try and showcase how rapid development can be - but more importantly to try to understand where the gaps might be in available education.

I’ve started with the “People” page and you can watch me creating this page from scratch in a brand new client in this video. It’s a bit rough around the edges, for which I make no apologies - but hopefully it will be informative.

Feedback Wanted !

The full disclosure is that the first time I went through the process I found that some of the JSDoc could be better, we could provide some additional widgets and that the UserService needed updating - and I took care of these issues before recording the demo.

However, I would urge that anyone attempting to do any development that has similar problems to report them as a GitHub issue so that they can be addressed.

I’d also love your feedback on whether or not this medium is effective or not, whether I should record more demos and what they should be focused on. I’ve already got an idea for a follow up in developing some custom widgets to go on the page - but it might be better to work through an entirely different use case - Data Lists perhaps?

I'd also welcome any suggestions on other approaches we could take to help people get up to speed with Alfresco development using Aikau.

Accessing the Code

I've created a GitHub repository containing the application that I built in the video. I've tagged the commit with the code (and will continue to tag each commit if I do more examples) so that it's easy to try out the code and experiment with it yourself.

Active Member
Thank you Dave for all your work on Aikau. When I create issues on Github and see how quick you solve them, I really feel myself as a user with enterprise support (actually better).

Aikau is great for custom pages, but the most pain why we cannot use it for generic purposes is because it does not work with forms engine. Therefore we cannot use it for pages with custom content models, data lists and workflows.
Intermediate II
Thanks for the feedback Oksana - it's greatly appreciated!

You're absolutely right about the forms engine issue. It's something I've been trying to get us to focus on for a long time (but without success). I might try to find some time to see if I can address this within the Aikau libraries myself. The main issue is that the REST calls to the forms engine return HTML fragments (rather than something useful like JSON) so it's not quite such a simple fix - I will see what I can do though.
Active Member
I guess I could tell/ask a ton. Lets get me started with something basic. Smiley Happy

I may be doing it wrong, but I am having a hard time navigating around (Alfresco projects) JavaScript code in general (Rhino and or browser based - YUI and AMD). Specifically, I also tried out the  'Needs more Dojo' Intellij plugin but removed it due to troubles it introduced (which where caused by Alfresco code IIRC). Do you guys get to enjoy Dojo aware navigation, JSDoc support or  'advanced' autocompletion in your editor?
Intermediate II
Yes, I would agree that navigating around Alfresco product JS code in general can be tricky at first, although generally I don't find that I have too many problems with it these days but this is probably due to familiarity. I guess it all depends if you're taking about live debugging of code or just generally browsing of source code.

I'm not an Intellij user so am not familiar with that plugin. I'm also surprised that you feel that you need 'Dojo aware navigation' - I guess it depends on what you're attempting to do, but there are very few occasions when I ever need to dig into the Dojo source code. I find that the Dojo API doc ( and general documentation ( is sufficient for my day-to-day needs. But in all honesty I don't need to use it that much... aside from the basic Dojo widget hierarchy and some commonly used util modules like array and lang I don't use that much Dojo.

Debugging  a live Share instance for Aikau code is fairly straightforward in Chrome (because it has the best developer tools in my opinion) as all the Aikau code ends up in a single file (use CTRL-P to open the finder, type 'surf' and it's the first result, you can then easily find modules/function by searching for them by name (the function names are fully name spaced).

My editor of choice is Sublime and I have a few plugins (the most useful being the 'JSHint Gutter'). The find across all files is used quite frequently, but I have nothing Dojo or JSDoc specific.

I don't know much debugging of YUI code these days, but the trick I find with the Rhino debugger for WebScripts is to refresh all WebScripts from the service console after opening it... refresh the page you're interested in and then find the WebScript you're interested in. It can be clunky, but I find it has some quite powerful features - particularly the ability to execute code when stopped on a break point.

I'm not sure if that is any help to you at all?
Active Member
Hi Dave,

Given the recent announcements from Alfresco on Angular being the future of Alfresco's drive for applications built on the Alfresco platform, and Aikau remaining as the primary, recommended framework for adding custom pages within the Share application, it would be great if your posts actually showed your examples working within a Share context, rather than as standalone Surf apps.

It might end up as a very minor change, with no real material differences in most cases to what you're showing in the demo, but I think it would still be quite useful - even if it's just that it might lead to tips & tricks around the best ways to accomplish common things like how to naturally link the new custom page into Share navigation, the admin console or as a Site Page (as appropriate).

I think the video angle is nice - don't know if it ends up taking you twice as long as a plain blog post Smiley Happy but it's nice to see things come together in real time and see things that are a lot more difficult to get across in text, like debugging etc.  It's also good to see how fast things can come together with Aikau (when you know what you're doing)


Intermediate II
Thanks for the feedback Steven.  I think you're right that I could do more to show Aikau running in a Share context. The reason why I've taken the approach I have for the current video is because it keeps things 'cleaner' in the sense that I don't have to build and deploy AMPs to get the latest version of Aikau applied (of course you can just drop the JAR file into share/WEB-INF/lib - but that's not an endorsed approach). It also means that I'm not linking the demo to any specific version of Share.

What you've said is quite right though - there is no difference to the page created in the standalone client than if it was created in Share - you could just copy the files into Share and they'd work just the same. If I can get to the point of completing a new People page then I promise to come back full circle and show how you could use it in Share.

The other issue is the chicken-and-egg situation of not enough of Aikau being used in Share, which does restrict the customization use case options.

As much as possible I want to focus on just how to use the widgets and not get bogged down in setting up Share - or going through the SDK setup - although the SDK is a very powerful way of building Aikau pages and customizations.  Finally I wanted to demonstrate that Aikau is still a viable option for building new clients, even if it's not the approach that Alfresco is pushing.

As for the video side of things... the 'one take' approach was quite tricky (and actually required about 3 takes!) but I really wanted to demonstrate that there were no 'smoke and mirrors' at play... I was quite pleased I actually made a couple of minor mistakes and was able to correct them from the debug output.  It is time consuming, but I think the benefits so will try to do a few more at least.
Active Member
Despite the fact that the plugin is called 'Needs more Dojo', its about AMD awareness and hence, navigating around AMD based sources. I manage to get around without it - it's just not very convenient. The situation is pretty similar with server side code in *.lib.js or *.lib.ftl.

Regarding debugging, I'm pretty much doing the same things you do.
Active Member
My concerns are currently related to all the mix of technologies in Share.

At the moment I try to bring in 2 new people into Alfresco development and I realized again that this is really hard at the beginning.

Why it is hard? Too many ways to do something, too many files to navigate, adapt and copy, no clear development reference (mostly in form of development posts) and no real ide support, but apparently needed to have full customisation and be a little bit upgrade safe. Don´t get me wrong- you have done a lot to make Share upgrade safe, but maybe there is a level reached that only a small group of people understand all that stuff really...

And if Alfresco now does not commit to rework all parts of Alfresco Share with Aikau, Aikau has no future at all. Do you really want to leave parts of Share untouched with good old YUI2 which is not supported ? I am little bit shocked at the moment about this state...

What do you think how can the community helps to address that in management or somewhere else?

Or I am completely overseeing something?


Active Member
The title suggests you are focusing on Aikau, while the post ends mentioning you’d also welcome any suggestions to help people get up to speed with Alfresco development.

I think it is important to be clear about the scope of potential efforts if you want help with this.

For example: I follow some dirty but practical idioms to implement  Share Surf/YUI extensions. They may helpful in general, but are most likely out of scope if educational efforts focus on Aikau only.

Other than that, it would be helpful to understand if you are aiming at pure education, or whether there is a chance to introduce code changes - say in WebScripts / Surf.

It is really great to have Aikau along with a more open process on github. My personal trouble is that most of my issues cannot be addressed by looking at Aikau only.
Intermediate II
Thanks Andreas - I've updated the blog to be more specific about helping people with 'Alfresco development using Aikau'. As you say, that is really the only thing that I have much control over - and as you say, your requirements for Surf/YUI are out of scope for what I'm trying to achieve with the limited time and resources that I have.

Again, I'm not able to push code changes to Surf / WebScripts very easily, and even if I could - it would be quite difficult to access those changes due to the nature and frequencies of how those libraries are released. I would like to see Surf / WebScripts move to more of the Aikau development model (i.e. on GitHub with regular, backwards compatible releases).
Intermediate II
Thanks Jens - I completely agree. When I started working on Aikau, I had hoped that it would start the process of getting rid of much of the old YUI2 code and greatly simplifying the Share implementation - both making it easier to customize and to understand. However, for various reasons that hasn't happened - whether or not it ever will I can't say - but I still firmly believe that Aikau is the correct framework to do it with because it would continue to support the customization use cases in a more future proof way. 

I would be very happy to eliminate all of YUI2 from Share - although this is something I have been recommending for some time, I'm not responsible for defining what the engineering team work on.  It might be possible for the Community to influence Alfresco - but I just don't know.

However, the Community could start to work on porting Share across to Aikau itself - this could be done in the form of providing re-usable page libraries (like doclib.lib.js) via Aikau, creating the required widgets and services along the way. Customizations of Share (or even Order of the Bee releases) could then leverage those pages. If they were to prove popular then that would make it an easier task for Alfresco to integrate them into Share.
Active Member
The situation starts to remind of how Oracle is silently killing Java (EE) .

Is there something that can be done about Surf / WebScripts?

I understand it is all Open Source and people are pretty much free to do whatever they want with it. However, I think changing Surf / WebScripts only makes sense as long as this code ships with Share.

I think it is not too much to ask for an official statement about where Alfresco wants Surf / WebScripts to go or whether they simply want things to stay as they are.
Active Member
Thanks for the video!

It would be interesting to see how all of it would be done in share. How to start an extension. How to configure share to actually show the page somewhere. How does the development cycle look like in share? Just a reload as in standalone?
Active Member
[…] Improving Aikau Education […]
Intermediate II
Thanks for the feedback Torsten. You make a similar point to the one that Steven made in his comment above - I definitely do need to do more to show this in the context of Share.

I would do the development using the SDK - and you'd be able to do the same kind of hot-reloading. Only when finished would I deploy the finished AMP onto Share.
Active Member
[…] of the comments I had on my last blog post point out that one of the main problems with using Aikau is that it […]