Alfresco Development Framework in action

It 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.
- Alfresco setup
- Editor setup (using Sublime text 3)
- Angular 2 and Alfresco NG2 Components setup
- Creating your first A.D.F. application
- Debugging setup (using Augury)
- Running (and debugging) the application
Alfresco setup
The 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.
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)
Now 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).
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)
The 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.
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.
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.
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.
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.
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
Hi Jerry,
Did you know the links below?
https://community.alfresco.com/community/application-development-framework/pages/get-started
https://github.com/Alfresco/adf-examples
If yes, can you please share which are the gaps so I can plan to write more tutorials and guides for developers?
Cheers.