Aikau 1.0.66 - Angular 2 Integration

[ddraper]

Introduction

One of the greatest misconceptions about Aikau is that it is somehow aiming to compete with other UI frameworks and libraries such as Angular and React. This really isn’t the case - Aikau is designed to address specific use cases that no other UI framework meets.

This isn’t trying to say that Aikau is in any way better - it’s just that it can do things that other frameworks can’t. We have integrated other frameworks such as Dojo, JQuery and YUI2 into Aikau - but Angular has been somewhat conspicuous by its absence.

There are a couple of key reasons for this:
 

1. Angular 1 doesn’t really “play nicely” with other frameworks, although Angular 2 does a much better job of this
2. Quite honestly there has never been a truly compelling reason to integrate it.

It’s worth remembering the granularity of Aikau widgets and how they are fully decoupled from both each other and the data that they use. Whilst this approach has been key to supporting the dynamic customization use cases, it has not lent itself particularly well to making use of the capabilities that Angular provides.

As you may have heard from recent announcements at BeeCon, Alfresco is looking to start making greater use of Angular 2 for the development of new applications but that it intends to continue to develop Aikau for use in Share.

Recent Announcements

That doesn’t mean that Share is not capable of making use of Angular 2 (or indeed any of the other modern UI frameworks such as React, Ember, etc). In my previous post I showed how modern web development practices could be integrated into Share and in this post I’m going to demonstrate how to make use of some new capabilities available in the 1.0.66 release of Aikau that will allow you to seamlessly insert Angular 2 code into an Aikau page in Share.

One important thing to be aware of… the widget that will be demonstrated resides under a new “alfresco/experimental” package in the Aikau library - anything under this package does not fall into the usual backwards compatibility rules of Aikau and as such maybe changed or removed at any time. If this widget appears useful then you should let us know and we’ll look to make it a fully fledged Aikau widget so that it gets all the backwards compatibility guarantees that this brings.

In this example we’re going to be integrating an example from the Angular 2 tutorial into the faceted search page in Share. Doing so holds no value other than to demonstrate that it can be done.

Step 1. Get Aikau release

First of all, you need to make sure you have downloaded the 1.0.66 release of Aikau and have placed it in the 'share/WEB-INF/lib' folder.

Step 2. Create extension

Now you need to create an extension module for the faceted search page. The quickest way to do this is to follow the steps in this blog post to download an extension JAR file for the faceted search page.

Step 3. Create a package definition

Unpack the JAR file somewhere and edit the the “alfresco/site-data/extensions/extension.xml” file to add in a new AMD package declaration for the Angular 2 tutorial code (background information on defining new AMD packages via extensions can be found in the Alfresco Documentation here.

<extension>
  <modules>
    <module>
      <id>Angular 2 Tutorial Extension</id>
      <auto-deploy>false</auto-deploy>
      <evaluator type='default.extensibility.evaluator'/>
      <configurations>
        <config evaluator='string-compare' condition='WebFramework' replace='false'>
          <web-framework>
            <dojo-pages> 
              <packages> 
                <package name='blog' location='js/blog'/> 
              </packages>
            </dojo-pages>
          </web-framework>
        </config>
      </configurations>
      <customizations>
        <customization>
          <targetPackageRoot>org.alfresco.share.pages.faceted-search</targetPackageRoot>
          <sourcePackageRoot>org.alfresco.share.pages.faceted-search.customization</sourcePackageRoot>
        </customization>
      </customizations>
    </module>
  </modules>
</extension>‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Next you want to copy the “main.ts” and “app.component.ts” (these can be copied from here) into the “META-INF/js/blog” folder.

Step 4. Edit the controller extension

Now you want to update the generated JavaScript controller extension ('alfresco/site-webscripts/org/alfresco/share/pages/faceted-search/customization/faceted-search.get.js') to make a dynamic request to add the new Angular 2 widget into the page.

Add the following code into the file:

var verticalStack = widgetUtils.findObject(model.jsonModel.widgets, 'id', 'FCTSRCH_MAIN_VERTICAL_STACK');
if (verticalStack && verticalStack.config && verticalStack.config.widgets)
{
  verticalStack.config.widgets.unshift({
    name: 'alfresco/experimental/ng2/Bootstrap',
    config: {
      main: 'blog/main.ts',
      templateString: '<my-app>Loading...</my-app>'
    }
  });
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

The Bootstrap Widget

The widget being added is the “alfresco/experimental/ng2/Bootstrap” widget. The purpose of this widget is to bootstrap the example from the Angular 2 tutorial. Here we are choosing to insert the example above the main search controls.

There are two configuration attributes:
 

• “main” is the root Angular 2 component to load that should include the call to bootstrap Angular 2 

• “templateString” is the DOM fragment that contains the custom elements that the Angular 2 component will be looking to parse during bootstrapping.

Once you’ve made these changes you can re-pack the JAR file and copy it to the 'share/WEB-INF/lib' folder.

Restart Share and perform a search. Initially you won’t see anything different - this is because the module has not been applied. More importantly, a second extension module provided by the Aikau JAR is also required.

Step 5. Deploy the modules

Navigate to the Module Deployment page ('/share/page/modules/deploy') and add the “Angular 2 Tutorial Extension” and the “Angular 2 Support (version 1.0.66)” module and click the “Apply Changes” button.

The “Angular 2 Support” module adds all of the required Angular 2 JavaScript dependencies that are required - most importantly it loads System.js that is used to transpile the TypeScript and handle the ES6 import calls.

Once you have applied these modules you can reload the search page and you’ll see the tutorial example displayed like so:

Summary

Obviously this example has no practical purpose whatsoever. However the technique could be used to for much more sensible use cases.

It’s worth noting that, from the moment you bootstrap into an Angular 2 component, you are completely leaving Aikau behind and all future imports should be done via the ES6 import approach as shown in the Angular 2 tutorials.

It’s also important to recognize that this is not suitable for production purposes, because in reality you would want to transpile and compress the Angular 2 code before using it.

If you think the “alfresco/experimental/ng2/Bootstrap” widget would be useful to be made a first class Aikau widget then please let us know - if enough people are interested then we’ll move it to an appropriate package and make it product ready.

Download the Source

You can download the extension module source from this folder in a new GitHub repository that I've setup.