How are you using Aikau?

[ddraper]

I'd like to get an idea of what people are using Aikau for and in particular to try to understand where any difficulties are in using it or understanding how it works. Even if you've just used it once for a very minor customization it would be useful to know about so just adding a comment that says "Yes, I've used it" would be fine, but the more detail you can provide the better - especially about the use cases you were trying to solve and the problems you encountered (both technically and conceptually).

I'm very happy for this to be used as a general discussion thread where I can answer any questions on how and why Aikau has been implemented the way it has, but obviously if you have any specific questions on a current customization or implementation then you may want to raise a separate discussion thread (and I'm happy to be tagged in questions on Aikau so that I get notified immediately about them!)

Ultimately my goal is to be able to improve both the documentation around Aikau and the general experience of developing with Aikau and I can only do this with input from the Community so any information you can provide would be greatly appreciated !!

[deas0815]

Hallo David,

I am asked to implement things fulfilling business requirements. Those business people want things cheap and fast, and do not care about technology. Personally, I often get requests for tweaks to existing components. Most of the time, I find these are still based on Surf/YUI. Hence, the easiest route is to hack on them instead of rebuilding things in Aikau. I understand this does not quite answer the question. Still, I wanted it mentioned because it leaves us with a chicken and egg situation.

Other than that, the difficulties I personally have are mostly related to the weak support offered by tooling. Take the IDE as an example.  IntelliJ is pretty smart in general, but has nearly no understanding of the JS controller code or the AMD modules. It ultimately ends up in more runtime errors and/or fulltext searching through the codebase. This is a general issue which extends beyond Aikau and I understand that there is little that can be done about it.

Another issue which bugs me from time to time is that it can be annoying to make third party libraries play with the AMD environment. E.g. you cannot simply add basic script tags for React or (recent) CodeMirror to the head.

Due to issues with the SDK, I stopped using it years ago and rolled my own alternative. Looks like with SDK 3.0, it may finally be time for me to move over.

regards

Andreas

[ddraper]

First of all, thanks for getting the ball rolling... I do recognize the problems that you're facing, unfortunately there is little I can do in the immediate time frame to address them.

1. As more of Share gets ported to Aikau (and yes, this stalled to a certain degree during 2016 but based on recent meetings with the Product Manager and Architect for Share I think that 2017 will see more of this happening) then needing to use Surf/YUI2 will reduce - obviously this won't happen overnight - and where possible I'm looking to provide options for getting ahead of Share releases with libraries available in Aikau (see these posts on tasks, data lists, people and document library)

2. On a road map for Aikau - sorting out tooling would be very far down the list unless I'm unexpectedly given a huge amount of resources (which I don't think is likely to happen). It would be nice to see improvements in the SDK where Aikau is concerned, but that is something that Ole Hejlskov​ would need to comment on.

3. I'd like to understand this further... there are examples of how to package 3rd party libraries into Aikau (even when they're non-AMD compliant) and it is equally possible to bypass Aikau and add them directly into Share. I've not tried integrating React into Aikau but have integrated Angular 2 and vue.js) ... CodeMirror is already integrated into Aikau out-of-the-box. If you can provide me a bit more specific information on what you're trying to do then I'll see if I can resolve the issue.

Have there been any specific instances where you have used Aikau that would have benefited from any additional documentation? If you have done customizations using it, have things went well or badly? What were the barriers to success?

[deas0815]

There are Android issues with CodeMirror which seem to require a recent version. IIRC Aikau bundles version 4.something. JavaScript Console (which uses version 5.0) still exposes the issue. Just try typing something meaningful with an Android device. We are pretty lucky the version coming with JavaScript Console plays as is. Just naively replacing the files with a recent version blows up unless you properly wrap it up for AMD. The situation is the same with React. It can be made working, but requires an extra bit AMD fiddling.

While we are at it, it seems recent Surf versions use the Google Closure compiler. I did not take the time to look closely, but will it be possible (supported?) to use module types other than AMD?

With regards to documentation, I am really the wrong person to ask because I hardly read it.

[ddraper]

If there is an issue with the version of CodeMirror that is bundled with Aikau (on Android devices) then obviously we'd want to update it to resolve that problem. Up until this point we've not known that there was an issue - I've raised it on the Aikau GitHub project and will investigate and resolve as soon as possible. There are often issues with the way that some 3rd party libraries have implemented AMD (often hi-jacking the "require" function) which can be problematic and can make them hard for Aikau to work with. Having said that, I don't see why the dependencies could not have been loaded via Surf (bypassing Aikau if you weren't using it).  What I don't understand is why you've not flagged this issue up sooner? We can't fix problems that we don't know about.

With regards to React ... again, are you trying to bundle this within an Aikau widget or separately within Share?

The Google Closure compiler alone will not support other module types. We'd need to do additional work within Surf to support ES6 class definitions and module importing/exporting if nothing else. However, at some stage in the future when there is support for browsers to natively support import/export of modules and HTTP2 is available many of these issues will go away. The question is how much of our (exceptionally limited) resource do we assign to this activity. Increasingly there are Node-in-Java solutions that might make the integration of Babel possible - but we have not had a huge amount of time to look into these.

Finally with regards to documentation - it's a great pity that you don't read them because it would be useful to get the feedback. Do you not read them just because they're documentation? because you've looked at them previously and didn't find them helpful? or because you find that you don't need them?

[deas0815]

I stopped reporting most issues a while ago due to experiences with JIRA. I understand Aikau is different, and today I would surely raise or fix issues with it.

Wrapping up React in AMD works. It is just a little more fiddling than just dropping  a script tag into the head of the document (which did not work for me), same story with recent CodeMirror versions.

The Closure compiler generally does support module types other than AMD (even node modules are just coming up). Sure, it would still require additional work in Surf if we want to leverage this capability. I was just asking, because I personally do not feel very comfortable with AMD.

I rarely read Alfresco documentation because this is how I got used to work. In the past, I too often felt mislead (because things seemed incomplete or outdated) or I just don't like the format. This is just my 2c.

I have more issues with Surf (e.g. various scalability issues with "large" quantities of extensions), but I guess this is out of scope here as we should be focused around Aikau?

[ddraper]

Yes... issues raised on Aikau are definitely handled differently to how they are handled on JIRA. There are many reasons for this, not least because it's a smaller code base and there are less issues that are reported - I also made a commitment to try and carry zero technical debt in the project anywhere. Some issues I've been blocked on (by things beyond my control) but on the whole I've tried to stay on top of them. It is worth still raising issues on Aikau (if and when you find them) as you might be pleasantly surprised by the response!

I'm glad you were able to resolve your React issues - it sounds like I don't have anything specific to do in that area immediately then.

With regards to the Closure compiler, it's about how we use it and what we generate from it... there is quite a bit of historical context to this. When I wrote the code to generate the aggregated JS resource in Surf there was really only AMD to work with and what is built is actually a cache file that the Dojo AMD loader understands. It is this area in Surf that we would need to do additional work to change how the resource is constructed from the compiled code.

In the same way that issues in Aikau are dealt with separately from issues in JIRA, documentation is entirely generated by me for Aikau - so the process and authoring is completely different, whilst my ability with wording is likely to be worse, my technical understanding should hopefully make it helpful. As with everything Aikau related though, I need to know where it can be improved, how it can be improved and what might be missing... and I can't do this without feedback.

Unfortunately, yes... Surf is really out of the scope of this discussion. There is much I'd dearly love to do with Surf but once again it comes down to resourcing and the inclination of the Project Management team to focus on it.

[billydekid]

Hi Dave,

Thanks for posting this interesting subject 🙂

I'm a newbie on Alfresco development and have some basic questions regarding Aikau dashlet development.

I just can create a simple webscript that deployed to Repository (not to classpath). It can be accessed through an URI "outside" of Alfresco UI / dashboard.

And now I need that my webscript page can be inserted into a custom dashlet, and will be used on site dashboard.

Following your tutorial "How to Create an Aikau Dashlet for Share", I stopped on an empty dashlet, even it can be installed and shown on site dashboard. I really need to know on how my webscript can be "treated" as a simple widget which then deployed on that new empty widget.

The basic understanding of "webscript description" between for my webscript and dashlet made me confused

And of course for others freemaker template for both also.

Could you explain steps on development for my problem?

Many thanks!

[bayu]

[ddraper]

Firstly... thanks for replying and providing this feedback, I'll try to help you however I can...

If you're new to Alfresco then I can imagine that things can be quite strange - especially in the area of UI development. This is because of the history of how Share (and the underlying Spring MVC extension called Surf that it is built on) was developed. Improving the getting started experience of getting up and running with Aikau is definitely something I'd like to focus on.  There is a tutorial on GitHub that we put together but to try and get people up and running - however, we very intentionally stayed away from getting to involved in other concepts like Share and WebScripts and tried to keep the focus purely on Aikau.

The reason for this was partly that there was a lot of information already available on WebScripts and Share and that as they'd been around for a long time they were well understood. Perhaps I need to provide a better path for people coming to Alfresco, Share and Aikau without any background knowledge at all? Do you think that this would be useful? If so, what would you like it to cover?

The dashboard use case is quite an unusual one because it is not ideally how Aikau should be used.... Aikau works best when the page is a single Surf Component bound to a single WebScript that renders Aikau content. The Share dashboard is a page that is made up of multiple Surf Components, each bound to a different WebScript (the majority of which will not be Aikau rendered).

You can find a relatively up-to-date set of Aikau references here... one of those references is to a recording of a presentation I did at Alfresco Summit 2013 where I cover the background of how Share pages are mostly comprised - this link takes you to the exact point where I describe it - I would definitely recommend watching at least that section to understand more about Share - this will hopefully also help you understand the relationship between Dashlet (Surf Component), WebScript and Aikau Dashlet widget.

Hopefully this information is useful - please ask follow up questions or start a new discussion thread with any specific implementation questions that you have, if you tag me in the question then I'll immediately be alerted to it!

[billydekid]

OK, thank you Dave. Very clear!