Getting Started with Alfresco Application Development Framework

cancel
Showing results for 
Search instead for 
Did you mean: 

Getting Started with Alfresco Application Development Framework

alfresco
Alfresco Employee
6 16 22.4K

An updated vesion of the tutorial can be found hereADF 101 - Getting Started with Alfresco 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:

 

You can browse all the components on this page.

 

An architecture overview looks like this:

Alfresco App Dev Framework - Architecture (1).png

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.

 

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 

16 Comments
mitpatoliya
Moderator
Moderator

Getting this error on windows 10

<code>

> my-pulse@0.1.0 tslint G:\Laision\Synapture\AngularAlf\my-pulse

> tslint -c tslint.json *.ts && tslint -c tslint.json 'app/{,**/}**.ts'

'tslint' is not recognized as an internal or external command,

operable program or batch file.

npm ERR! Windows_NT 10.0.14393

npm ERR! argv "C:\\Program Files\\nodejs\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "run

" "tslint"

npm ERR! node v6.8.1

npm ERR! npm  v3.10.8

npm ERR! code ELIFECYCLE

npm ERR! my-pulse@0.1.0 tslint: `tslint -c tslint.json *.ts && tslint -c tslint.json 'app/{,**/}**.ts'`

npm ERR! Exit status 1

npm ERR!

npm ERR! Failed at the my-pulse@0.1.0 tslint script 'tslint -c tslint.json *.ts && tslint -c tslint.json 'app/{,**/}**.t

s''.

npm ERR! Make sure you have the latest version of node.js and npm installed.

npm ERR! If you do, this is most likely a problem with the my-pulse package,

npm ERR! not with npm itself.

npm ERR! Tell the author that this fails on your system:

npm ERR!     tslint -c tslint.json *.ts && tslint -c tslint.json 'app/{,**/}**.ts'

npm ERR! You can get information on how to open an issue for this project with:

npm ERR!     npm bugs my-pulse

npm ERR! Or if that isn't available, you can get their info via:

npm ERR!     npm owner ls my-pulse

npm ERR! There is likely additional logging output above.

npm WARN Local package.json exists, but node_modules missing, did you mean to install?

npm ERR! Please include the following file with any support request:

npm ERR!     G:\Laision\Synapture\AngularAlf\my-pulse\npm-debug.log

npm ERR! Windows_NT 10.0.14393

npm ERR! argv "C:\\Program Files\\nodejs\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "run

" "build"

npm ERR! node v6.8.1

npm ERR! npm  v3.10.8

npm ERR! code ELIFECYCLE

npm ERR! my-pulse@0.1.0 build: `npm run tslint && npm run tsc && npm run license-check`

npm ERR! Exit status 1

npm ERR!

npm ERR! Failed at the my-pulse@0.1.0 build script 'npm run tslint && npm run tsc && npm run license-check'.

npm ERR! Make sure you have the latest version of node.js and npm installed.

npm ERR! If you do, this is most likely a problem with the my-pulse package,

npm ERR! not with npm itself.

npm ERR! Tell the author that this fails on your system:

npm ERR!     npm run tslint && npm run tsc && npm run license-check

npm ERR! You can get information on how to open an issue for this project with:

npm ERR!     npm bugs my-pulse

npm ERR! Or if that isn't available, you can get their info via:

npm ERR!     npm owner ls my-pulse

npm ERR! There is likely additional logging output above.

npm WARN Local package.json exists, but node_modules missing, did you mean to install?

npm ERR! Please include the following file with any support request:

npm ERR!     G:\Laision\Synapture\AngularAlf\my-pulse\npm-debug.log

npm ERR! Windows_NT 10.0.14393

npm ERR! argv "C:\\Program Files\\nodejs\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "sta

rt"

npm ERR! node v6.8.1

npm ERR! npm  v3.10.8

npm ERR! code ELIFECYCLE

npm ERR! my-pulse@0.1.0 start: `npm run build && concurrently "npm run tsc:w" "npm run serve" `

npm ERR! Exit status 1

npm ERR!

npm ERR! Failed at the my-pulse@0.1.0 start script 'npm run build && concurrently "npm run tsc:w" "npm run serve" '.

npm ERR! Make sure you have the latest version of node.js and npm installed.

npm ERR! If you do, this is most likely a problem with the my-pulse package,

npm ERR! not with npm itself.

npm ERR! Tell the author that this fails on your system:

npm ERR!     npm run build && concurrently "npm run tsc:w" "npm run serve"

npm ERR! You can get information on how to open an issue for this project with:

npm ERR!     npm bugs my-pulse

npm ERR! Or if that isn't available, you can get their info via:

npm ERR!     npm owner ls my-pulse

npm ERR! There is likely additional logging output above.

npm WARN Local package.json exists, but node_modules missing, did you mean to install?

npm ERR! Please include the following file with any support request:

npm ERR!     G:\Laision\Synapture\AngularAlf\my-pulse\npm-debug.log

PS G:\Laision\Synapture\AngularAlf\my-pulse>

</code>

mitpatoliya
Moderator
Moderator

I was able to resolve above error after upgrading npm and node to latest version.

Then run following command under new application directory.

npm install

then you can start application using "npm start"

luharry
Active Member

hi,everybody , i can run by npm start,but the loading page does not work normal . i input account and password ,click loading button , no respond.  

         the error is 'licence check is disabled'.  how can i do ,please help me.

luharry
Active Member

the problem is i do not have enablecors jar ;the download page is not open;so i feel despair  

luharry
Active Member

thank you very much .

tonalamona
Member II

Hi, 

I am having the same issue, 'license check is disabled' and once I try to log in I get the following error: LOGIN.MESSAGES.LOGIN-ERROR-CREDENTIALS

Could you help?

Thank you in advanced

fcorti
Alfresco Employee

Hi Marta Dern‌,

I suppose it is a side effect, not the real issue.
Unfortunately you did not share enough information to give you support.
Please ask in Alfresco/alfresco-ng2-components - Gitter or open a separate question/discussion, providing more details about your environment, installation and issue.

Thanks.

ymuwakki
Partner

Hi Alfresco team.

I cannot get CORS to work for ADF to access Activiti in a Windows environment.  I tried everything.  So Alfresco 5.2 EA is running on port 8080 and Activiti 1.5.2 is running on port 8090 all on my windows 10 pro laptop.    I even installed nginx-1.11.8 for windows with the correct nginx.conf but still does not work.  And I even updated activiti's web.xml to add the CORS filter but that also did not work.  I am getting the following error from the ADF app in Chrome browser:  

XMLHttpRequest cannot load http://localhost:8090/activiti-app/app/authentication. Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:3000' is therefore not allowed access.

Can we copy the enablecors-1.0.jar into the Activiti app to get it to work? Or what is the correct filter to be added? Is it a different filter-mapping config then Alfresco One?

<filter-mapping>       <filter-name>CORS</filter-name>       <url-pattern>/api/*</url-pattern>       <url-pattern>/service/*</url-pattern>       <url-pattern>/s/*</url-pattern>       <url-pattern>/cmisbrowser/*</url-pattern> </filter-mapping>
ohej
Established Member II

Hi 

Looking at your error, it seems that ADF is pinging Activiti directly on port 8090 and not the nginx? 

Anyways, as I mentioned in the other thread https://community.alfresco.com/community/application-development-framework/blog/2016/06/30/announcin...  if you grab 1.5.2.1 or 1.5.3 it is be easy to configure CORS without the proxy. Once you have it installed you find tomcat\lib\activiti-app.properties and add the following:

cors.enabled=true
cors.allowed.origins=*
cors.allowed.methods=GET,POST,HEAD,OPTIONS,PUT,DELETE
cors.allowed.headers=Authorization,Content-Type,Cache-Control,X-Requested-With,accept,Origin,Access-Control-Request-Method,Access-Control-Request-Headers,X-CSRF-Token
cors.exposed.headers=Access-Control-Allow-Origin,Access-Control-Allow-Credentials
cors.support.credentials=true
cors.preflight.maxage=10
security.csrf.disabled=true
ymuwakki
Partner

Hi Ole,

Thank you very much for your quick response.  Yes, I tried this time without the nginx to test the CORS filter in the web.xml.

In any case your suggestion ot update the new CORS properties in the tomcat\lib\activiti-app.properties worked on Activiti 1.5.3.

I do have Activiti 1.5.3 installed but there was no documentation that I found related to those CORS properties. 

douglascrp
Advanced II

This document is obsolete.

The right one to follow is this one GitHub - Alfresco/generator-ng2-alfresco-app: Yeoman Generator Angular 2 Alfresco Application 

ohej
Established Member II

We have a new updated Getting Started Guide ready, we will be updating this document over the next days, stay tuned. 

fcorti
Alfresco Employee

Please check below for an updated version.

 

douglascrp
Advanced II

Nice. Thank you.

douglascrp
Advanced II

I am going to read it right now.

Thank you.