Skip navigation
All Places > Application Development Framework > Blog > Authors ohej
ohej

Taking ADF 2.0 out for a spin

Posted by ohej Employee Nov 29, 2017

Now that ADF 2.0 is finally released, we need to update all our Getting Started content. While we're doing this, we wanted to give you a quick guide to create an ADF based application.

 

ADF 2.0 works with Alfresco Content Services 5.2.x, Alfresco Community Edition 5.2.x and Alfresco Process Services (Powered by Activiti) 1.6.4+/1.7.x. You'll need to have at least one of these running before going ahead. No special configuration is required during development.

 

Please note that ADF does not currently support Activiti, only Alfresco Process Services. We plan to bring this support in the future. Stay tuned for more news on this topic.

 

Since we're embracing Angular CLI, there are a few things you need to have installed:

 

Start by installing node.js. Once this is installed install Angular CLI, then Yeoman and the ADF App Generator:

$ npm install -g @angular/cli
$ npm install -g yo
$ npm install -g generator-alfresco-adf-app

Depending on your system, you may have to run the commands above with sudo.

 

Next up, let's generate our application with Yeoman:

$ yo alfresco-adf-app

 

The generator will now ask a few questions, mainly the name of your app, and which blueprint you want to use:

 

You can select one of three blueprints. To describe them from the bottom up:

Process Services

This will generate an application for Alfresco Process Services. It contains the following components: Login, App List, Task List, Form and Start Process.

 

Content Services

This will generate an application for Alfresco Content Services (or Alfresco Community Edition). It contains the following components: Login, Document List, Viewer.

 

Process and Content Services

This will generate an application for both Alfresco Process and Content Services and will be a combination of the two blueprints above.

 

Select the one you want to use, and the generator will now ask if you want to install dependencies right away. Enter "Y" and hit enter.

 

This can take a minute or two depending on your internet connection. You might see a few warnings at the end like this:

npm notice created a lockfile as package-lock.json. You should commit this file.
npm WARN @angular/flex-layout@2.0.0-beta.10 requires a peer of @angular/core@0.0.0-NG but none is installed. You must install peer dependencies yourself.
npm WARN @angular/flex-layout@2.0.0-beta.10 requires a peer of @angular/common@0.0.0-NG but none is installed. You must install peer dependencies yourself.
npm WARN @angular/material-moment-adapter@5.0.0-rc0 requires a peer of moment@^2.18.1 but none is installed. You must install peer dependencies yourself.
npm WARN codelyzer@3.2.2 requires a peer of @angular/compiler@^2.3.1 || >=4.0.0-beta <5.0.0 but none is installed. You must install peer dependencies yourself.
npm WARN codelyzer@3.2.2 requires a peer of @angular/core@^2.3.1 || >=4.0.0-beta <5.0.0 but none is installed. You must install peer dependencies yourself.

 

These warnings are normal. Unfortunately they happen within the Angular Flex Layout package that ADF depends on. You can safely ignore them. 

 

Next you want to change into the directory of your app and inspect the proxy.conf.json file. This file will tell Webpack to create a proxy for your backend (Content or Process services). Change the URLs and ports to reflect where they are currently running. In my case I have ACS running on http://localhost:8080 and APS running on http://localhost:9999, so my proxy.conf.json file should look like this:

{
  "/alfresco": {
    "target": "http://localhost:8080",
    "secure": false,
    "changeOrigin": true
  },
  "/activiti-app": {
    "target": "http://localhost:9999",
    "secure": false,
    "changeOrigin": true
  }
}

 

You'll notice that this is an Angular CLI project, so you can now take advantage of all the CLI commands to generate new components, modules and much more. We encourage you to checkout the Angular CLI documentation.

 

Now you can simply run "npm start". This takes a couple of seconds, and will automatically open a browser to http://localhost:4200/. Once the page loads, you can navigate to http://localhost:4200/login which should look like this:

 

Enter a valid username and password and you have now successfully created your very first ADF 2.0 application!

 

Happy hacking!

ohej

Announcing ADF 2.0 GA

Posted by ohej Employee Nov 29, 2017

We're pleased to announce that the Application Development Framework 2.0 has now been released!

 

While this release had a high focus on stabilization and bug fixes, we have also introduced new and enhanced features. These include a completely revamped Viewer component, a new metadata component and file versioning. We have updated to Angular 5 and Angular Material. Also, ADF is now localized into 11 different languages. In total, we have closed around 242 issues in JIRA. 

 

Please see the ADF 2.0.0 Release Note for all the juicy details!

 

Since we follow SEMVER, we can only introduce breaking changes in major releases. We started ADF in April 2016 and we have learned a lot since then. We have taken this opportunity to restructure our packages, refactor components and keep up with the developments from the Angular community. Unfortunately, this means that we have done some breaking changes which we blogged about a few weeks ago in Preparing for ADF 2.0. You can also find more details in the release notes, and we will be providing guidance on how to upgrade existing projects to 2.0.

 

With ADF 2.0 we have embraced Angular CLI for developing ADF applications, which means you can now leverage this tool during development to help scaffold components, modules and much more. We have updated our Yeoman generators to reflect this, so it will now give you three choices, either create a Process + Content app, Process app or a Content app. The end result is a basic ADF based application that gives you a great starting point. 

 

We have continued to improve on the documentation and we can now officially share the new site for ADF's documentation: ADF Component Catalog

 

We are currently updating all our "Getting Started" material to reflect the latest and greatest, but here are some quick instructions to get the latest and greatest running: Taking ADF 2.0 out for a spin.

 

As part of the changes for 2.0, we will also be renaming the Github repositories for ADF, however, we couldn't get this done prior to the release so this will happen shortly. Luckily, Github will automatically set up redirects so we don't expect any issues regarding this. 

 

ADF 2.0 is the first General Available release of ADF. This means that Enterprise customers can now get support via the support portal, and customers with Developer Support will have you covered.

 

The Alfresco University team has been hard at work developing training content. We will be releasing two new courses, with the first of these available on the release date: 

Alfresco Application Development Framework Overview
This eLearning course is designed for those wishing to learn about the new Application Development Framework (ADF). Through a series of lectures, videos, and demonstrations, students will walk away with a thorough understanding of the ADF platform.

Shortly after ADF 2.0 is released the second course will be available:
Creating and Customizing an Application using Alfresco ADF
This eLearning course is designed for those wishing to learn more about the Application Development Framework (ADF). Using a scenario-based approach and through a series of lectures, videos, demonstrations, and lab exercises, students will learn how to create and customize an ADF application.

 

As always we welcome feedback! Join the Gitter channel where the entire team hangs out, raise an issue or pull request on Github, or leave a comment below.

ohej

Preparing for ADF 2.0

Posted by ohej Employee Nov 28, 2017

We've been busy in the last months preparing for the next major release of ADF. Since we follow SEMVER we can only introduce breaking changes in major versions, and we're currently at a point where we not only flip the version number to 2.0 but we also go into General Availability, meaning ADF will be fully supported by Alfresco.

 

We are introducing a set of new features, most notably the File Viewer component. The viewer was one of the first components to be created but in 2.0 we have given it a complete rework. It has a new design, along with a lot of ways to customize, including the info drawer, toolbar and thumbnails. We will provide a more in-depth write up of the new features in the release notes.

 

To support the new File Viewer, we have added a new component based on the Info Drawer to show metadata from Content Services. This component can be externally configured to include/exclude metadata and offers inline editing of properties as well.

 

The Yeoman Generators have been given a lot of love. We are embracing Angular CLI, and in 2.0 the Yeoman Generators will give you three options: Create a Process + Content app, a Content app or a Process app. These apps will have a very small footprint and have the basic setup you need to get up and running with ADF and Angular.

 

Last but not least, we have made big improvements to the documentation. Although we have added some completely new docs, we have mainly focused on gathering the information that was already there and making it easier to find and use. On GitHub, we now have one Markdown file per component and an index page that gives clearer detail about what is available in the docs. Internally, the Markdown files now have a more consistent structure that should make them easier to read, write and maintain. Also, we have added more links between the doc pages and to outside resources (community, other APIs, etc). This should help users form a better picture of how ADF fits together and of its relationship to the rest of the Node/Angular ecosystem.

 

This is just a small subset of the changes - we will be detailing everything in the release notes.

 

ADF has come a long way since its beginning. We have learned a lot and are adjusting based on feedback from our customers, partners and community. Some of these adjustments will include breaking changes, and we would like to take this opportunity to give some early insight on what to expect when upgrading to ADF 2.0.

 

Renaming and refactoring
When we started with ADF we used an early release of Angular2. Back then it was common practise to name components with a ng2-* prefix. Back in May we upgraded to Angular4 and last week we merged the pull request to upgrade to Angular5. Because of this we want to remove the ng2-* prefix and instead just be ADF.

 

We also used the old naming conventions from Alfresco, so all components were either ng2-alfresco-* or ng2-activiti-*.

As a result of this we are doing some house keeping in the Github repository and renaming all ADF components.

From ADF 2.0 we will split everything into three main packages:

@alfresco/adf-content-service
@alfresco/adf-process-services
@alfresco/adf-core
@alfresco/adf-insights


The Alfresco Javascript API remains the same and will be deployed as previously.
The structure of the Github repository will be re-arranged to reflect these changes.

The impact for developers using ADF is that the dependencies need to be adjusted (and simplified) in package.json, and all import statements in typescript files need to be changed.


A concrete example of this would be

import { FormRenderingService, FormService, ValidateFormFieldEvent, FormEvent, FormComponent } from 'ng2-activiti-form';

This would need to be changed to

import { FormService, FormEvent, FormComponent } from '@alfresco/adf-core';


Updating to the latest Angular Material Design
Recently we completed the transition from Material Design Lite to Angular Material Design which is more complete and has more features.


The Angular Material Design project recently introduced a number of breaking changes as they are moving towards a major release as well.

 

In the 2.0.0-beta11 release of Angular Material Design the team decided to rename all md-* prefixes to mat-*. The team have provided a tool to help migrating. To use this tool, please make sure you run it before upgrading to ADF 2.0. As of this writing we are currently on the 5.0.0-rc0 release of Angular Material Design.

 

This is mostly an exercise of search'n'replace in the source, along with some testing to ensure you have caught everything.

We highly recommend checking out the breaking changes for the last couple of releases here: https://github.com/angular/material2/releases

 

Renaming events
Following the guidance from the Angular project, we have renamed all our components' events so they no longer start with "on", which impacts all use of events from the ADF components. Examples of this would be "(onSuccess)" is now "(success)", "(onSave)" is just "(save)".

 

With these changes in mind, we strongly believe we have the right structure and naming to grow and scale ADF. We expect to release ADF 2.0 by the end of November.

By bringing together content & process, Alfresco is a unique platform for building solutions and business applications.

As a platform company, it is critical for us to ensure that our developer ecosystem is successful and our community, customers, and partners can deliver applications on top of Alfresco as quickly as possible.

Earlier this year, we embarked on a customer, partner, and community consultation exercise and analysing market data and industry trends. We got a lot of feedback from customers, partners and community that they are focusing more and more on Angular. John Newton wrote a nice blog post in May about our direction to move towards Angular and focus on Experience Design.

To support our strategy Alfresco invested in a new development organisation dedicated to frameworks, tools, and APIs to help reduce the time to develop and deliver applications across both ECM (Alfresco One) and BPM (Activiti). The organisation is headed by John Sotiropoulos our VP of Developer Products who works closely with me to deliver our strategy .

Our Application Development Framework is our overall offering that helps our developer ecosystem build applications on top of Alfresco and Activiti and provide a rapid, consistent, and unified developer experience. We have articulated our strategy in a set of slides, but like any vision it will evolve.

We also want to break the habit of doing development “in the dark” and be open and transparent about the process, revitalising our community. This is why we’re making the source of our work so far available - and we want your feedback!

Today we are announcing a brand new Javascript API, a set of NG2 components and a couple of Yeoman generators to help bootstrap your Angular2 project and components.

Alfresco Javascript API

One thing we keep hearing over and over again is that developers spend a significant portion of time doing boilerplate code. Bootstrapping a project from scratch takes time. Dealing with APIs, authentication and the lower levels are key. To help ease all of this we’ve developed a new API that wraps around our new v1 REST APIs.

The Javascript API is not tied into any specific framework. This means you can use this in all javascript based applications, whether it is a node.js backend application or a plain vanilla javascript page.

The goal with the Alfresco Javascript API is simple - we want to provide a great developer experience for developers consuming our APIs.

Be sure to check it out - https://github.com/Alfresco/alfresco-js-api

Alfresco NG2 Components

Building on top of the Alfresco Javascript API we have built a core set of components that are easy to use, configure and extend to fit your needs.

Initially we have focused on a set of high level components:

 

    • ng2-alfresco-core - Core services and utilities to help power components
       
    • ng2-alfresco-datatable - A simple file list

 

    • ng2-alfresco-documentlist - An advanced list of documents
       
    • ng2-alfresco-login - A login component
       
    • ng2-alfresco-search - A basic search component
       
    • ng2-alfresco-upload - Advanced upload capabilities that integrates with lists
       
    • ng2-alfresco-viewer - A PDF.js based viewer to preview content


Once you start using these components you will notice that they are all styled with our new design guidelines based on Google Material Design.

Be sure to check it out - https://github.com/Alfresco/alfresco-ng2-components

Alfresco NG2 App Generator

To help you get started as quickly as possible we have created a Yeoman generator to scaffold and generate your project. The generator will ask you a set of questions, but also offer to include and wire in the components listed above.

Be sure to check it out - https://github.com/Alfresco/generator-ng2-alfresco-app

Get started today!

We have a bunch of good material to help you get up and running. This page gives you a brief dive on how the components and the javascript api ties together.

The biggest requirement to get up and running is the 201606 Community Edition since we rely exclusively on the new v1 REST APIs. On top of this you need to have CORS enabled.

Since the NG2 components are purely client side components you need to have the Alfresco Platform allow requests from other domains, otherwise your browser will not allow the javascript api to make XHR requests.

First you need to download 201606 Community Edition, then download the “enablecors” module here. Put the JAR file in $ALF_HOME/modules/platform. The module contains a web fragment that configures CORS for the repository. You can find more detailed information here.

While you’re at it, why not include the REST API Explorer? Grab the war file here and put it in $ALF_HOME/tomcat/webapps.

Start up Alfresco and leave it running.

Next up is making sure you have Node.js installed. You will need to have a minimum version of 5 - we recommend you use the latest.

Once Node.js is installed you need to install the Yeoman generator:

npm install -g yo

npm install -g generator-ng2-alfresco-app

Run the generator, followed by “npm start” and you’re good to go!

Components documentation

Now that you have everything up and running, it’s time to have a look the component catalog and figure out how to configure and extend the components. Go to http://devproducts.alfresco.com to browse the components and view the documentation. We make a point of having both sample code and documentation as part of the definition of done. This way we ensure we have up to date documentation for our developers from day one.

We want your feedback

We recognise this is early days for our new “Application Development Framework”, but we want to have an open and transparent development process. We are continuing to develop more components and improve on the existing ones, but we would love to hear your thoughts and ideas. We will also welcome any pull requests with new features, bug fixes, enhancements to documentation, samples or anything else you would like to contribute.

If you want to contribute we are all set up on Github, please make sure to read the code contribution acceptance criteria, our Code Style, Commit format and Definition of Done.

Next steps

We are planning a Tech Talk Live next week, Wednesday 6th of July where we will present and demo what we have and we have a series of blog posts planned on how to use the individual components. Stay tuned!