Hyland Community
Help
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

Anatomy of an ADF application

alfresco
Elite Collaborator
Elite Collaborator
‎02-09-2017 08:47 PM

After the ADF 101 about creating your first Alfresco Application Development Framework application, in this set of tutorials we are going to see how to customise it in layout, behaviours and basic elements (buttons, text, etc.). We would like here to remember that Alfresco Application Development Framework (from now on ADF) is provided by Alfresco as Open Source, to build custom applications on top of the Activiti BPM Engine and Alfresco ECM Repository. We won’t introduce here the basis of the Alfresco ADF, because we would like to focus the content on customising an existing ADF application. To better describe the tasks, we are going to use “a step by step“ approach, more practical and easy to follow for our goal.

For further details about the Alfresco ADF, please refer to the alfresco-ng2-components GitHub Project and take a look to the Alfresco Catalog, with a friendly (and technical) overview of all the available components. For requests of support, questions and feedback, don’t forget to participate to the Community of Developers dedicated to the ADF or to the Gitter space dedicated to the Alfresco Angular 4 components.

Before diving deep in the customisations, let’s understand some technical basis about the ADF applications in general.

An ADF application as a standard Angular 4 application

As clearly described since the very beginning, an ADF application is a standard Angular 4 application. If you are not familiar with the Angular 4 development, we suggest to go through the Tour of Heroes tutorial and the Architecture Overview. It is not an easy read the very first time, but as every new technology, it will appear understandable after some training.

As a standard Angular 4 application, an ADF application can be described as following.

  • An ADF application created with the Yeoman Generator, uses Angular 4 Webpack as module bundler to incorporate assets that belong together and should be served to the client in a response to a single file request.

The structure of an ADF application

Now that we know how an ADF application is related to a standard Angular 4 application, let’s share more details about the application’s structure. Looking at the ADF application into the file system, we can recognise all the modules and components introduced above. In the following picture is showed an example of ADF application, called my-adf. The my-adf application has been created with the Yeoman Generator, exactly in the same way it is described in the Getting started with Application Development Framework tutorial.

Structure of the my-adf application into the file system.

The structure of the application is quite straightforward, if you know how an Angular 4 application works. Below some highlights on the most important files and folders, for the correct execution of the my-adf application.

  • index.html This is the starting point for each session. The file is a regular HTML file, except for the <alfresco-app> tag that links the root module, where all the magic happens. This file contains the <html>, <head> and <body> content, common to all the pages of our application.

  • app folder. This folder contains the core content of the Angular 4 application, defined by the root module and the components. In the following picture is showed the corresponding app folder of our my-adf application.

Structure of the app folder into the file system.

Below some highlights on the most important content in the app folder.

  • main.ts This is the TypeScript file used for bootstrapping. This file indicates where to start bootstrapping, using the AppModule class (the Angular 4 root module) declared into the app.module.ts file.

  • app.module.ts This is the TypeScript file containing the AppModule class (the Angular 4 root module). This class defines:
    • The list of Angular 4 components, used in the application. In this specific application they are hosted into the components folder.
    • The Angular 4 routing to enable the navigation from one view to the next. The routing rules are declared into the app.routes.ts file.
    • The bootstrapping component, in our case named AppComponent, stored into the app.component.* files.

  • app.component.css, html and ts Those files define a standard Angular 4 component, controlling a patch of screen called a view. In particular:
    • app.component.css defines the specific stylesheet of the component.
    • app.component.html defines the HTML generated by the component (in this case, exactly where the tag <alfresco-app> appears into the index.html file).
    • app.component.ts is the TypeScript file declaring the AppComponent class implementing the real business logic (and behavior) of the component.

  • components folder. This folder contains all the Angular 4 components used in the application. In the following picture is showed the corresponding components folder of the my-adf application.

Structure of the components folder into the file system.

In the components folder you can find: one folder for each Angular 4 component (each folder contains the component source code), an index.ts file containing the links between the alias of each component and the folder with the source code.

The implementation of each Angular 4 component, really depends on the component’s role and goal in each specific application. We won’t detail here the listed components, because some of them are extremely specific for this sample application. Instead of this, we would like to submit to your attention the online Alfresco Catalog, containing a friendly (and technical) overview of all the available components, with practical examples and human readable source code.

Google Material Design in ADF applications

Before facing the customization, there is another topic to discuss about the ADF applications: the stylesheet. ADF applications are designed and developed to work with the Google Material Design, in particular with Material Design Lite. We won’t discuss here the basis of that design language. If you want to learn more about it, you can start from the Official Documentation and go through the library and styles, for a better understanding.

From a technical point of view, the relevant thing we are interested to share, is that every ADF application is designed according to Material Design Lite. And this means:

<!-- Google Material Design Lite -->
<link href="css/material.orange-blue.min.css" rel="stylesheet">
<script src="js/material.min.js"></script>
<link href="css/iconfont/material-icons.css" rel="stylesheet">

  • Each ADF component generates the HTML portion, according to the Material Design components. You can find the HTML template in the *.component.html file of each folder containing an ADF component.

  • Each ADF component can have a customised stylesheet declared into the *.component.css file. If you check into the my-adf application, in particular into each folder containing an ADF component, you can find a *.component.css file (for example in activiti, files, home, login, setting) or you cannot find it, if the default Material Design Lite stylesheet is enough (for example in about, search). Those *.component.css files are exactly the place where we are going to act to customise the colors and stylesheet in general.

Next task >>

Copyright © 2024 Khoros, LLC