Getting Started with Alfresco Application Development Framework

[alfresco]

An updated vesion of the tutorial can be found hereADF 101 - Getting Started with Alfresco Application Development Framework 

• What’s the Application Development Framework?
• What you need to install to get going
• Installing Alfresco
• Enable CORS in Alfresco
• Installing Node.js
• Installing Activiti (Optional)
• Your first application
• Installing Yeoman
• Installing/Updating the Alfresco Application Generator
• Generating the Application
• Startingand accessing the Application
• Customizing the Application
• Source code for the Application Development Framework

What’s the Application Development Framework?

The Alfresco application development framework is based on the Angular 2 JavaScript library. The framework is provided by Alfresco to make it easy to build custom web applications that should manage and view content in the Alfresco Platform Repository in a custom way and business processes through Activiti Workflow Engine.

As you probably know, there is a general user interface called Alfresco Share available out-of-the-box. Share is usually used as a quick way of getting started with content management with Alfresco. It gives you access to pretty much all the features provided by the Alfresco ECM system. And a lot of customers customize it for their specific domain.

However, there are use-cases that Share does not fit very well, such as:

• Feature-based clients, exposing functionality to perform a specific task(s)
• Role-based clients, exposing functionality based on role
• Clients where the UI layout and style differs significantly from the Share layout and styling
• Workflow clients, the new application development framework will also support BPM
• Line of business applications
• Mashup clients

This is where this application development framework can be very helpful as you build a solution on the Alfresco platform; it can be used to create exactly the user interface (i.e. web client) that the requirements demand.

The framework consists of a number of components that can be combined together to form a customized content management application. Here is a list of some of the available web components:

• Core library
• DataTable
• DocumentList
• Viewer
• Login
• Upload

You can browse all the components on this page.

An architecture overview looks like this:

Here we can also see that there is an Alfresco JavaScript framework in use that wraps the Alfresco REST API and the Activiti REST API. The Alfresco Angular2 components and the JavaScript API is all there to make life easier for the client developer.

What you need to install to get going

The web application that we build will need an Alfresco Platform (Repository) to talk to. It will expect the lastest REST API that comes with Alfresco Platform 5.2.a-EA. This means that you cannot build a web application with this framework and expect to use an earlier version of the platform, such as 5.1.

The application development framework is JavaScript based and makes use of the Node.js JavaScript runtime and the the Node Package Manager (npm). If you are familiar with Maven, then you can think of npm as mvn, Maven’s local repository as /usr/lib/node_modules, and Maven’s remote repository as https://www.npmjs.com/. Maven’s pom.xml is comparable to npm’s package.json.

The following need to be installed:

• An Alfresco Platform Repository (version 5.2.a-EA or newer) to talk to, which has CORS enabled.
• Node.js JavaScript runtime. Version 5 or greater.
• npm package manager for JavaScript.

Installing Alfresco

Alfresco comes with installers that will install all the servers, webapps, and tools needed to run Alfresco.

• Download Alfresco Community from this page. Make sure to navigate to the Early Access (EA) page to grab the latest 5.2 EA release.

• Install Alfresco following these instructions.

This will install the following Alfresco web applications:

• Alfresco Platform with the Content Repository, which we need so we can access content from our custom web client (alfresco.war)
• Alfresco Solr, which we need so we can search for content from our custom web client (solr4.war)
• Alfresco Share, not technically needed, but can be useful for creating users and groups, and to access and upload content to the repository while we are developing the custom web client (share.war)

Enable CORS in Alfresco

The web client that we are building with the application development framework will be loaded from a different web server than the Alfresco Platform is running on. So we need to tell the Alfresco server that any request that comes in from this custom web client should be allowed access to the Content Repository. This is done by enabling CORS.

To enable CORS in the Alfresco Platform do the following:

Download the enablecors platform module JAR and add it to the $ALF_INSTALL_DIR/modules/platform directory and restart the server.

Note. by default the CORS filter that is enabled will allow any origin.      

Installing Node.js

If you don't have Node.js installed then access this page and use the appropriate installer for your OS.

Make sure the Node.js version is greater than 5:

$ node -v

v5.12.0

Note. node.js comes with npm package manager so no need to install separately.

Installing Activiti (Optional)

If the solution includes a workflow that should be interacted with from the custom web application, then you need to also install the Activiti BPM Engine. Download and installation instructions are here.

Your first application

The easiest way to get going is to use the application generator. It will generate all the stuff you need to get going with a web application based on this framework. The generator is built with the Yeoman generator building tool, which is a JavaScript based tool (everything is JavaScript these days!).  So we need to install Yeoman first.

Installing Yeoman

To install Yeoman you need to install the yo JavaScript package with npm as follows (it will be downloaded fromhttps://www.npmjs.com/😞

$ npm install -g yo

(Sometimes you might need to use sudo.)

The -g switch tells npm to install this package globally on your computer (i.e. /usr/lib/node_modules) so you don’t have to download it every time you need it. Without this switch the package will be installed in the local node_modules folder. So using the -g switch is similar to how maven downloads to ~/.m2/repository.

Installing/Updating the Alfresco Application Generator

To install the Alfresco application generator, which is built with Yeoman, we use the following command:

$ npm install -g generator-ng2-alfresco-app

You can check what version of the application generator you have as follows:

$ npm list -g|grep generator-ng2-alfresco-app

├─┬ generator-ng2-alfresco-app@0.0.21

If you have used an earlier version of the application generator, then you might want to upgrade to the latest version. You can update as follows:

$ sudo npm update -g generator-ng2-alfresco-app

Generating the Application

It is now a simple task to generate the web application, use the Yeoman generator as follows:

$ yo ng2-alfresco-app

              ,****.          

         ,.**. `*****  <-_    

        ******** ***** ####  

       $********::**** ####;  

       _.-._`***::*** ######  

     ,*******, *::* .;##### @

     **********,' -=#####',@@@

     ***' .,---, ,.-==@@@@@@@@

      * /@@@@@',@ @\ '@@@@@@@

       '@@@@/ @@@ @@@\ ':#'  

       !@@@@ @@@@ @@@@@@@@@^  

        @@@@ @@@@@ @@@@@@@'  

         `"$ '@@@@@. '##'    

              '@@@@;'        

      Welcome to the awesome

      Angular 2 app generator

           for Alfresco!

? What's the name of your App? my-app

Your generator must be inside a folder named my-app

I'll automatically create this folder.

? How would you describe the app? My Alfresco Web Component App

? Author's Name Martin Bergljung

? Author's Email xxxxxxxx@gmail.com

? Author's Homepage

? Package keywords (comma to split) alfresco,webcomponents,angular2

? Which is your Alfresco platform server URL? http://127.0.0.1:8080

? GitHub username or organization

? Do you want include a navigation bar? Yes

? Do you want include a drawer bar? Yes

? Do you want include a search bar? Yes

? Do you want include a Document List? Yes

? Do you want include a Tasks List? Yes

? Do you want include a sample dashboard? Yes

? Which license do you want to use? (Use arrow keys)

❯ Apache 2.0

  MIT

  Unlicense

  FreeBSD

  NewBSD

  Internet Systems Consortium (ISC)

  No License (Copyrighted)

This will generate all the application files as follows:

   create app/main.ts

   create app/app.component.ts

   create app/app.component.html

   create app/components/login/login-demo.component.ts

   create app/components/login/login-demo.component.html

   create assets/material.orange-blue.min.css

   create app/css/muli-font.css

   create app/css/app.css

   create app/fonts/Muli-Regular.ttf

   create i18n/en.json

   create i18n/it.json

   create app/components/search/search.component.html

   create app/components/search/search.component.ts

   create app/components/search/search-bar.component.ts

   create app/components/search/search-bar.component.html

   create app/components/files/files.component.html

   create app/components/files/files.component.css

   create app/components/files/files.component.ts

   create app/components/tasks/tasks-demo.component.ts

   create app/components/tasks/activiti.service.ts

   create app/components/chart/chart.component.ts

   create app/components/chart/chart.component.html

   create browser-sync-config.js

   create typings.json

   create tslint.json

   create tsconfig.json

   create systemjs.config.js

   create README.md

   create PREREQUISITES.md

   create index.html

   create .gitignore

   create .editorconfig

   create package.json

   create LICENSE

Starting and accessing the Application

The new application can be started immediately via a supplied script (for script source see package.json and the scripts property).

Step into the directory and then execute the start script:

$ cd my-app/

.../my-app$ npm start

This will actually kick off a local web server that is run inside node.js, and the browser will be loaded with the web application:

Login with the usual admin/admin Alfresco user. You will then see the folders in Document library for the site that comes with the Alfresco installation.

Click around and familiar yourself with what features that are available to you when building Alfresco content based web applications.

Customizing the Application

Next thing you want to do is most likely changing stuff in the application to your liking. Let’s change the columns that are visible in the document list. The best way to see how to change stuff is to look up the documentation for the Alfresco Web Components, it can be found at this URL:https://devproducts.alfresco.com/browse:

  

Click on the Document List link in the left navigation bar to see specifics for that component:

You can directly see what you would need to do to install this component package on a host that did not have it. We just generated a complete application with all components so we have this component source already.

Scroll down on the doc page until you see the basic usage section:

This tells you what you would need to do in an Angular 2 component template to include this Alfresco web component. This is already done for us in our auto-generated application. See my-app/app/components/files/files.component.html source:

<alfresco-upload-drag-area

 [showUploadDialog]="true"

 [currentFolderPath]="currentPath"

 [uploaddirectory]=""

 (onSuccess)="documentList.reload()">

 <alfresco-document-list-breadcrumb

   [currentFolderPath]="currentPath"

   [target]="documentList">

 </alfresco-document-list-breadcrumb>

 <alfresco-document-list

   #documentList

   [currentFolderPath]="currentPath"

   (preview)="showFile($event)"

   (folderChange)="onFolderChanged($event)">

   <content-columns>

     <content-column source="$thumbnail" type="image"></content-column>

     <content-column

       title="{{'DOCUMENT_LIST.COLUMNS.DISPLAY_NAME' | translate}}"

       source="name"

       class="full-width ellipsis-cell">

     </content-column>

. . .

To get an idea of how to go about customizing the document list scroll further down the doc page until you hit the Custom columns section:

So customizing this document list is now quite simple, just add, remove, or update the content-column elements. For example, to add a mime type column we would do this:

<alfresco-upload-drag-area

 [showUploadDialog]="true"

 [currentFolderPath]="currentPath"

 [uploaddirectory]=""

 (onSuccess)="documentList.reload()">

 <alfresco-document-list-breadcrumb

   [currentFolderPath]="currentPath"

   [target]="documentList">

 </alfresco-document-list-breadcrumb>

 <alfresco-document-list

   #documentList

   [currentFolderPath]="currentPath"

   (preview)="showFile($event)"

   (folderChange)="onFolderChanged($event)">

   <content-columns>

     <content-column source="$thumbnail" type="image"></content-column>

     <content-column

       title="{{'DOCUMENT_LIST.COLUMNS.DISPLAY_NAME' | translate}}"

       source="name"

       class="full-width ellipsis-cell">

     </content-column>

     <content-column

             title="Type"

             source="content.mimeType">

     </content-column>

     <content-column

       title="{{'DOCUMENT_LIST.COLUMNS.CREATED_BY' | translate}}"

       source="createdByUser.displayName"

       class="desktop-only">

     </content-column>

     <content-column

       title="{{'DOCUMENT_LIST.COLUMNS.CREATED_ON' | translate}}"

       source="createdAt"

       type="date"

       format="medium"

       class="desktop-only">

     </content-column>

   </content-columns>

. . .

This requires no compiling or building, this developer environment is instant hot reload, switch to the browser and you should see:

Pretty cool!

Source code for the Application Development Framework

The source code for all the stuff can be found here:

Alfresco Application Development Framework: https://github.com/Alfresco/alfresco-ng2-components 

Alfresco JavaScript API: https://github.com/Alfresco/alfresco-js-api 

Alfresco App Generator: https://github.com/Alfresco/generator-ng2-alfresco-app 

Alfresco Component Generator: https://github.com/Alfresco/generator-ng2-alfresco-component 

• What’s the Application Development Framework? What you need to install to get going Installing Alfre...
• What’s the Application Development Framework?
• What you need to install to get going
  • Installing Alfresco
  • Enable CORS in Alfresco
  • Installing Node.js
  • Installing Activiti (Optional)
• Your first application
  • Installing Yeoman
  • Installing/Updating the Alfresco Application Generator
  • Generating the Application
  • Starting and accessing the Application
  • Customizing the Application
• Source code for the Application Development Framework