Preparing for ADF 2.0

[ohej]

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.