05 Sep

Alfresco Development Framework in action

AngularIt was the end of june when the new Alfresco NG2 Components were announced as a new Alfresco Development Framework for developers. Today the framework is on its version 0.3, not mature for production enviroments yet, but very interesting for developers because it introduces an Angular 2 solution, for the development of your Alfresco customized front end.

In this post I would like to share some personal experiences using ADF in practice. I was wondering how the A.D.F. works and how to debug the source code… waiting to understand how to add a custom Angular 2 component. The approach is the same of several posts in the past: a step by step approach to make it work.

Prerequisites and tasks

Starting from a vanilla installation of Ubuntu 16.04.01 LTS, let’s install Java 8 following the tutorial at this link. Once Java 8 is successfully installed, we are going to cover the tasks described below.

  1. Alfresco setup
  2. Editor setup (using Sublime text 3)
  3. Angular 2 and Alfresco NG2 Components setup
  4. Creating your first A.D.F. application
  5. Debugging setup (using Augury)
  6. Running (and debugging) the application

Alfresco setup

alfrescoThe very first task is having an Alfresco repository available for your incoming custom application. Alfresco is extending its REST API to manage the Alfresco Javascript API (available from the Alfresco 201606-EA Community ahead). As unique customization you need to instruct Alfresco to enable CORS. Let’s see how to do it below.

To setup the Alfresco repository simply install it, using the provided wizard. You can download the installation executable called alfresco-community-installer-201606-EA-linux-x64.bin here, but please remember not to start Alfresco when the last window will ask you. To install Alfresco open a terminal and execute the commands below.

cd ~

wget https://sourceforge.net/projects/alfresco/files/Alfresco%20201606-EA%20Community/alfresco-community-installer-201606-EA-linux-x64.bin

chmod 777 alfresco-community-installer-201606-EA-linux-x64.bin 

./alfresco-community-installer-201606-EA-linux-x64.bin

At the last task of the installation, please uncheck the flags as described below.

alfresco wizard

Once Alfresco is installed (but not running), it’s time to install the Enabling CORS module.

cd ~/alfresco-community/modules/platform

wget https://artifacts.alfresco.com/nexus/service/local/repositories/releases/content/org/alfresco/enablecors/1.0/enablecors-1.0.jar

As an optional task you can install the REST API explorer. I personally find it useful but feel free to jump this task.

cd ../../tomcat/webapps

wget https://artifacts.alfresco.com/nexus/service/local/repositories/releases/content/org/alfresco/api-explorer/1.1/api-explorer-1.1.war

Now that Alfresco is correctly setup, you can start it with the commands described below.

cd ~/alfresco-community

./alfresco.sh start

tailf tomcat/logs/catalina.out

To check is working properly, open a browser and access to the URLs below.

  • http://localhost:8080/alfresco to see Alfresco repository available.
  • http://localhost:8080/api-explorer-1.1 to discover the Alfresco REST API (if installed).

Editor setup (using Sublime text 3)

Sublime_Text_LogoNow that Alfresco is up and running, it’s time to setup an editor to customize the source code. I personally like Sublime Text 3, so below the installation tasks with everything is requested to work with Angular 2. To install the Editor, open a terminal and execute the commands below.

sudo add-apt-repository ppa:webupd8team/sublime-text-3

sudo apt-get update

sudo apt-get install sublime-text-installer

subl &

The last command will open the editor and finally setup all the requested folders and settings in a default installation. Now that Sublime Text 3 is successfully installed, let’s install everything is useful to develop with Angular 2 executing the commands listed below.

cd ~/.config/sublime-text-3/Packages/ 

sudo apt-get install git 

git clone --depth 1 https://github.com/Microsoft/TypeScript-Sublime-Plugin.git TypeScript 

git clone https://github.com/pjlamb12/st3-ng2-snippets 

git clone https://github.com/sindresorhus/editorconfig-sublime

Angular 2 and Alfresco NG2 Components setup

Now it’s time to setup Angular 2, Yeoman and the Alfresco NG2 generator.

sudo apt-get install nodejs npm

sudo ln -s /usr/bin/nodejs /usr/bin/node

// Will require some minutes... please be patient.
sudo npm install -g yo

// Will require some minutes... please be patient.
sudo npm install -g generator-ng2-alfresco-app

Creating your first A.D.F. application

Ready to create your first custom application over Alfresco? If yes, open a terminal and execute the command below.

cd ~

// Will require some minutes... please be patient.
yo ng2-alfresco-app

Below a screenshot showing the parameters requested from the creation wizard in Yeoman. Please note the name of the application as my-first-alfresco-app (but you could choose your preferred name).

ng2-alfresco-app

Congrats! Your Alfresco application is available into the my-first-alfresco-app folder.

Now let’s setup the project into the Sublime Text 3 editor. First of all, execute the subl command into a terminal and then the tasks described below.

  • Click on the menu item ‘Project’, then on ‘Add Folder to Project’ and finally select the my-first-alfresco-app folder. A file selector will appear on the left.
  • Click on the menu item ‘Project’, then on ‘Save Project as…’ and write my-first-alfresco-app.sublime-text.

Debugging setup (using Augury)

auguryThe task below is optional (for example if your goal is to see the A.D.F. in action) but it could be relevant if you want to customize (and debug) your Alfresco application. I personally use Chromium browser + Augury extension. To setup the environment, open a terminal and execute the commands below.

sudo apt-get install chromium-browser

chromium-browser &

Please make Chromium as the default browser and visit https://augury.angular.io/ to install the browser extension (the installation is very straightforward).

Running (and debugging) the application

Now that everything is properly installed and configured, it’s time to run your custom Alfresco application.

Please, close Sublime Text during the application startup otherwise the compiling task will fail.

cd ~/my-first-alfresco-app

npm start

Your chromium browser will be opened with your custom Alfresco application running at  the URL http://0.0.0.0:3000/.

Interested in debugging your Alfresco application? Right click on the web page and select inspect. On the top right menu of the browser you will find augury item. Select it and something similar the screenshot below will be shown for your discovery.

adf_debug

I hope you will enjoy your brand new Angular 2 application over Alfresco.

Conclusion

In this post I share some personal experiences using the new Alfresco Development Framework for developers. Today the framework is on its version 0.3, not mature for production enviroments yet, but very interesting for developers because it introduces an Angular 2 solution, for the development of your Alfresco customized front end.

4 thoughts on “Alfresco Development Framework in action

  1. Thanks for the write-up, Francesco. Your are quite right we are not production-ready yet but we are interested in working with developers to ensure the solution works for them so thanks for contributing to that.

    I’d be interested in the source map error in your screenshot, which should not be there, and also why you need to close Sublime before building (we use IntelliJ within the team, but there is no problem having it open during compilation).

    We love to see people join the Gitter chat (https://gitter.im/Alfresco/alfresco-ng2-components) or if you think you have a real issue then feel free to log that direct on the GitHub project.

    • Francesco Corti

      Ciao Will,

      Thank you for your note, especially because you’re not the first one who underlines the “not-production-ready” sentence of this post.
      ADF is changing very rapidly and it’s only at its version 0.3 (we tested ADF since the very first draft because we would like to use it for an incoming project over Alfresco, planned in 2017).
      Regarding this need, there a lot of things to understand from our perspective:
      – how to develop a custom component over Alfresco,
      – how to integrate the available components with our custom components (for example: how to add a custom link/button into the document list?),
      – how to customize the available components,
      – etc…
      In one sentence: how to customize and integrate the avaialable components and the incoming new components?
      IMHO this is definitely regular, if we consider that ADF was born few months ago and the final goal is to have a complete (and powerful) set of components over Alfresco and Activiti, isn’t it?

      Regarding the error message in the image, my goal was not to underline an issue (or a bug).
      On the contrary, the goal of this post is to share my experience in setting up a development environment to use ADF in practice.
      Again: at this stage is definitely acceptable some minor bugs, if we consider that ADF was born few months ago.
      Thank you for your invitation to partecipate to the improvement of the development experience: I’ll do it for sure!
      And I hope that a lots of developers will push on it, considering that ADF will make the life easier for us in complex (and customized) projects over Alfresco.

  2. Hi Francesco,
    Thanks for your write-up on ADF. As you noted, ADF is very promising but there are not much online resources for a developer to start creating custom components on top of Alfresco. Do you have any resources that can help with this?

    Thanks
    Jerry

Leave a Reply

Your email address will not be published. Required fields are marked *

Time limit is exhausted. Please reload CAPTCHA.