Why is the admin tools not working in Alfresco Share with the SDK?

I get asked this question a lot. When running Share from the Alfresco SDK, the admin console is broken out of the box – it simple displays an empty page as shown below.

Blank admin tools page

The fix?

To fix this issue you simply turn off development mode. You can do this by editing this file:

src/test/resources/alfresco/web-extension/share-config-custom.xml

Change

<mode>development</mode>

with

<mode>production</mode>

Restart share to have the changes picked up.

Why is this happening?

To support hot reloading of server side Javascript files in Share, we have to turn on development mode. This setting will tell the Rhinoscript Processor not to compile and cache the JS files. Cool, we can now change server side JS files and have the changes picked up, without having to restart or refresh web scripts.

But… Due to a known bug in the Surf framework (ALF-9970) this will break the admin consoles in Share.

Alfresco has, for some reason, decided not to fix this bug, so either we can have hot reloading of server side JS or a working admin console.

The permanent fix?

Development mode is an older trick. It solves some of the old -min.js things, most which are not even used any longer. The only thing we want from the “old” development mode is to tell Rhino no to cache the compiled JS files. This could easily be done by extracting this into a config option in XML instead of having it happen via the development mode tag. This change needs to be made in the Surf framework so I expect hope this change makes it into the product in a later release, as it should be a small change.

My thoughts on the future of Alfresco Share

After reading Dave, Kevin, Erik and David’s blog post about the alternate realities of Share development, I treid to make up a good reply but it ended up a bit too long for a comment so I decided to dedicate a blog post about it.

TL;DR: I can only agree with all the points in the UI teams blog post. I want to see Alfresco invest heavily in Share and Aikau. It’s a PITA right now because it breaks existing addons, but it will provide a much better foundation for the future of Share. Documentation needs to be addressed internally at Alfresco.

Backwards compatibility

Share was not meant to be extended from the beginning. It was supposed to be a reference on how a new web frontend for Alfresco could work.

However, Share was much better than Alfresco Explorer. It started to gain traction and now developers wanted to customize and extend it, but it just wasn’t geared for this. Over the years Share evolved quite a bit and the extension model got a bit better, but let’s face it: If you have done heavy customizations on Share in Alfresco 4.x you will have to agree that it’s a lot of work, and keeping your changes across version upgrades is a whole different chapter for it self.

If you’re doing a small extension it’s easier, but have you ever upgraded to a new version of Share and thought to yourself “Wow, that was so easy!” .. No? I certainly haven’t.

Over the last four years I’ve been working on too many Alfresco projects to remember, but one of the biggest ones involved a heavily customized Share. Maintaining this across version is a big pain. A year ago we upgraded from 4.0.d to 4.2.c. This was a huge task, we had modified some of the core javascript files, because sometimes there is just no way around it. To make it even more fun, we had to continue to 4.2.e because of some serious CIFS issues, and guess what broke again?

The point is, right now, it’s already a pain to keep your customizations working on different versions of Share.

Of course there is a difference in having to modify your customizations and a complete rewrite of your addon, which is the bigger issue right now.

As Share migrates more and more features to Aikau, your customizations will need to be redone with Aikau. There is no way around this, and let’s be honest: Do you really enjoy working with YUI2?
It sucks that your customizations won’t work and you have to do a lot of extra work to port your customizations to Aikau, but what’s the alternative?

Write a completely new client

Sure, why not? I mean it’s not like it’s a TON of work to do. It will be quick and easy…. On a serious note, I don’t think many people realise just how much work it would require for Alfresco to whip up a complete new web frontend with the same features that Share has today. Heck, Share doesn’t even have feature parity with Alfresco Explorer yet.

This would not solve the backwards compatibility issue, at all, if anything it will only make it worse.

But Share is so complex and hard to extend, if Alfresco would just start over from scratch it would be much easier

I’ve heard this been thrown in the ring a few times. Think about all the features we expect Share to contain. Think about the fact that developers demands that we can extend and bend it to our will in every possible way. Now, do you seriously think a fresh start will make it any less complex?

Oh god, why? Why did you create a new javascript framework?

Why didn’t you use Angular?! jQuery! No web components! No, ember.js! GWT! Backbone! Dart! React!

Aikau is *NOT* a new javascript framework to compete with the new cool kid on the block. It’s a framework to support extensions in a proper way, handle pages and dependencies. Wrap it all up with AMD and it enables you to work with your favorite framework and still be able to extend Share.

The very core of Aikau is to make Share more extendible without locking you to a specific framework. The only thing you are tied to is AMD.

Alfresco chose to go with Dojo for the core widgets, but that does not mean you have to.

Summing it all up

Overall I think Alfresco is on the right track with Aikau. It’s a great framework that gives more freedom to the developers and makes it much easier to extend and customize various parts of Alfresco without having to overwrite huge 3000 line javascript files. It is painful to introduce changes like these, but it’s for the greater good, but there are a few things Alfresco needs to pay attention to:

  • Make a clear and open roadmap for Aikau. Developers needs to know what’s happening and when it’s happening. There is already a pretty good Aikau document library. When will it be switched to default? Is the underlying code going to change much in the next release?
  • Make concrete examples on using other frameworks than Dojo. For people to truely understand Aikau, we need to show that it works with other frameworks
  • Improve documentation and examples. Dave has done a great job over the last months by writing blog posts on various examples, but we need all this information in an easier form for developers to consume. If you are new to Aikau, it’s hard to understand the examples. I think the documentation team needs to send a guy over to Dave a day every week to learn and talk, then go produce some great, official documentation

There is a ton of great resources around. My tutorial, Dave’s blog and there is a bit on the official docs, but it could be much better. Documentation is a key area that needs attention, if Aikau is to gain traction and adaptation this.

Tutorial about the Aikau framework in Alfresco Share

A while ago I finally managed to finish my tutorial on the Aikau framework for Alfresco Share. 

If you have no idea what Aikau is all about, be sure to check out Tech Talk Live – Episode 78 where Dave Draper talks about the framework, once you’re hooked read my tutorial to get started!

This is my first tutorial. I’ve learned a lot writing it and I’ve gotten some great feedback already.

Aikau is the future of Share, so be sure to check it out:
http://ohej.github.io/alfresco-tutorials/tutorial/aikau/tutorial.html