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:
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
