Tutorial on creating ADF based applications. (#6600)

docs/abn-tree.yml

@@ -13,7 +13,24 @@
         - working-with-nodes-api-service.md: 'Working with the Nodes API Service'
         - working-with-nodes-js-api.md: 'Working with nodes using the JS-API'
         - content-metadata-component.md: 'Content metadata component'
-- user-guide: 'User guide'
+- user-guide: 
+    title: 'User guide'
+    children:
+        - adf-introduction.md: 'Introduction to ADF'
+        - angular-material-design.md: 'Angular Material Design'
+        - theming.md: 'Theming'
+        - typography.md: 'Typography'
+        - internationalization.md: 'Internationalization'
+        - localization.md: 'Localization'
+        - transclusion.md: 'Transclusion'
+        - rtl-support.md: 'Right-to-left languages'
+        - debug-test-build-and-promote.md: 'Debug, test, build and promote'
+        - app-extensions.md: 'App extensions'
+        - apa-extensions.md: 'Form Extensibility for APA Form Widget'
+        - aps-extensions.md: 'Form Extensibility for APS Stencil'
+        - extensibility.md: 'Form Extensibility and Customization'
+        - metadata-indicators.md: 'Adding indicators'
+        - kerberos.md: 'Kerberos'
 - core:
     title: 'Core API'
     children:

docs/tutorials/creating-your-first-adf-application.md

@@ -3,120 +3,102 @@ Title: Creating your first ADF app
 Level: Basic
 ---
 
-# Creating your first ADF application
+In this tutorial you are going to learn how to create a very basic (and almost “empty”) ADF-based application that you can start enriching with features, behaviors and customizations. The creation of this basic ADF-based application is possible through a scaffolding tool called [Yeoman](https://yeoman.io/ "https://yeoman.io/"), which makes this task very straightforward.
 
-This tutorial shows you how to set up your development environment and create an ADF application.
+# Prerequisites and the requirements
 
-To get up and running with ADF development, you will need to install a few prerequisites: `node.js`, `Yeoman`, and a code editor.
+The first thing to do is to check the prerequisites and the requirements to run the front-end application directly into a development environment.
-Once you have the prerequisites installed, you need to create the application using the ADF Yeoman generator, then configure your ADF application to point to your Alfresco Content Services repository.
 
-## Prerequisites
+More in particular check that you have:
+-   Alfresco Content Services (alias ACS) Enterprise edition up and running (identify the URL that will be required as configuration).
+-   The latest lts version of [NodeJs](https://nodejs.org/en/ "https://nodejs.org/en/").
+-   A recent (and supported) version of a browser (see [here](https://github.com/Alfresco/alfresco-ng2-components#browser-support "https://github.com/Alfresco/alfresco-ng2-components#browser-support") for further details).
 
-### Install node.js
+All the Angular development is done using the [Typescript](https://www.typescriptlang.org/ "https://www.typescriptlang.org/") language. With this in mind, it is highly suggested to adopt a good text editor to help you in this task. We recommend [Visual Studio Code](http://code.visualstudio.com/ "http://code.visualstudio.com/") a free, lightweight, and _very_ powerful tool from Microsoft that works well with Angular development and has a [big ecosystem of plugins](https://marketplace.visualstudio.com/VSCode "https://marketplace.visualstudio.com/VSCode") to make the developer experience even better.
 
-You need the latest `node.js` release, which you can download from [https://nodejs.org/en/](https://nodejs.org/en/). Choose the installer for your OS and follow the install instructions. Once completed, open a terminal and verify the installation with the following command:
+# Installing the ADF Yeoman Generator
 
-	node -v
+**Note:** If you're on Linux or MacOS, you might need to run the following commands using sudo.
-	
-*Note: Both version `14.x` and `12.x` should work just fine.*
 
-**TIP**: If you are planning to do extensive development with ADF, `node.js`, and `Angular`, you might consider installing a version manager for `node.js` such as [n](https://github.com/tj/n) or [nvm](https://github.com/creationix/nvm/). This tool will allow you to have multiple `node.js` versions installed simultaneously and quickly switch between versions.
+You need to ensure you have [Yeoman](https://yeoman.io/ "https://yeoman.io/") installed by running `yo --version`. If this is not already installed, run the following command.
 
-### Install ADF Yeoman generator
+    npm install -g yo
 
-![yeoman_creation](../docassets/images/yeoman-alfresco-adf-app.jpg)
+Now install the latest version of the [generator-alfresco-adf-app](https://github.com/Alfresco/generator-alfresco-adf-app "https://github.com/Alfresco/generator-alfresco-adf-app").
 
-**Note:** If you're on Linux or macOS, you might need to run these commands with `sudo`.
+    npm install -g generator-alfresco-adf-app@latest
 
-You need to ensure you have `Yeoman` installed by running `yo --version`. If this is not in your system, you should run:
+Feel free to check the [generator-alfresco-adf-app](https://github.com/Alfresco/generator-alfresco-adf-app "https://github.com/Alfresco/generator-alfresco-adf-app") repository for further details. The project is Open Source and free.
 
-	npm install -g yo
+# Installing the Angular CLI
-	
-Now install the latest version of the `generator-alfresco-adf-app`:
 
-	npm install -g generator-alfresco-adf-app@latest
+To take full advantage of Angular, we suggest you install the latest version of [Angular CLI](https://cli.angular.io/ "https://cli.angular.io/").
-
-### Install Angular CLI
-
-To take full advantage of Angular, we suggest you install the latest version of [Angular CLI](https://cli.angular.io)
 
     npm install -g @angular/cli
 
-This will make it easy to create components, libraries, and much more. 
+This will make it easy to create components, libraries, and much more.
 
-### Installing a code editor
+To test the installed version [Angular CLI](https://cli.angular.io/ "https://cli.angular.io/"), launch the ng v command directly in the terminal.
 
-All Angular development is using [Typescript](https://www.typescriptlang.org). With this in mind, it a great thing to have tools that make development a little easier, but any text editor will do just fine.
+# Create your first ADF application
 
-We recommend [Visual Studio Code](http://code.visualstudio.com) - it's a free, lightweight, and *very* powerful tool from Microsoft that works well with Angular development and has a [big ecosystem of plugins](https://marketplace.visualstudio.com/VSCode) to make the developer experience even better.
+Now that the system is properly configured, it's time to generate the application running the following command.
 
-Other recommendations include IntelliJ IDEA or WebStorm from [JetBrains](https://www.jetbrains.com) *but note that the community edition does not support [Typescript](https://www.typescriptlang.org).*
+    yo alfresco-adf-app
 
-## Create your first ADF application
+Enter a name and choose Content Services as the application blueprint, then enter `Y` to install the dependencies (the following questions are optional and easy to understand).
 
-Now that we have all the prerequisites in order, it's time to generate an application:
+The Yeoman generator will create a new project and install all dependencies required for your application.
 
-	yo alfresco-adf-app
+**Note:** The Yeoman generator creates a new directory for your project. Make sure you change into this new directory.
-	
-Enter a name and choose `Content Services` as the application blueprint, then enter `Y` to install the dependencies.
 
-The `Yeoman` generator will create a new project and install all dependencies required for your application. 
+# Configure the application to work with Alfresco Content Services
 
-*Note: The `Yeoman` generator creates a new directory for your project. Make sure you change into this new directory.*
+The next step is to open up the newly-created project in your code editor and open the file `proxy.conf.js`. Change the target property in this file, so it points to your Alfresco Content Services URL and port. Please refer to your installation guide to find this URL, or if you're running an online trial, you will find the information in the email.
 
-## Configure ADF to work with Alfresco Content Services
+Modify `"target": "http://localhost:8080"`, so that it matches your URL and save the file.
 
-The next step is to open up the newly-created project in your code editor, and open the file `proxy.conf.js`. Change the `target` property in this file, so it points to your Alfresco Content Services URL and port. Please refer to your installation guide to find this URL, or if you're running an online trial, you will find the information in the email.
+Please note that you do not need `/alfresco` at the end of the target URL. Let's say you've launched Alfresco Content Services 6.1 using Docker Compose. Your Alfresco Content Services repository might be available at `http://localhost:8080/alfresco`. In this case, you will want the `proxy.conf.json` file to look like this:
 
-Modify `"target": "http://localhost:8080",` so that it matches your URL and save the file.
+    module.exports = {
+        "/alfresco": {
+            "target": "http://localhost:8080",
+            "secure": false,
+            "changeOrigin": true
+        }
+    };
 
-Please note that you do not need `/alfresco` at the end of the target URL. Let's say you've launched Alfresco Content Services 6.1 using [Docker Compose](https://docs.alfresco.com/6.0/tasks/deploy-docker-compose.html). Your Alfresco Content Services repository might be available at `http://localhost:8080/alfresco`. In this case, you will want the `proxy.conf.json` file to look like this:
+If you're running an online trial, consult your emails for the correct URL. The `proxy.conf.json` should look like this:
 
-```json
+    module.exports = {
+        "/alfresco": {
+            "target": "https://xyz.trials.alfresco.com",
+            "secure": false, "changeOrigin": true
+        }
+    };
 
-module.exports = {
+# Start the application
-    "/alfresco": {
-        "target": "http://localhost:8080",
-        "secure": false,
-        "changeOrigin": true
-    }
-};
-```
 
-If you're running an [online trial](https://www.alfresco.com/platform/content-services-ecm/trial/online), consult your emails for the correct URL. The `proxy.conf.json` should look like this:
+To run the project, open a terminal and run:
 
-```json
+    npm start
 
-module.exports = {
+A browser will automatically open up at http://localhost:4200.
-    "/alfresco": {
-        "target": "https://xyz.trials.alfresco.com",
-        "secure": false,
-        "changeOrigin": true
-    }
-};
-```
-
-## Start the application
-
-To run the project, open a terminal and run 
-
-	npm start
-	
-A browser will automatically open up at `http://localhost:4200`. 
 
 ![yeoman_creation](../docassets/images/app-started.jpg)
 
 Click the key icon in the side navigation, and you can now log in!
 
-*Note:* If you're running an online trial, you can find your login credentials in the welcome email.
+**Note:** If you're running an online trial, you can find your login credentials in the welcome email.
 
 Take a few minutes to explore your application. You have the essential features: Browsing the repository, uploading, and previewing documents.
 
+# Troubleshooting and support
 
-# Next step
+If you have any issue, don’t worry! There is an entire community available to help you.
 
-Congratulations! You're now ready to start developing your first ADF application! 
+In case of problems raise a question into the [Alfresco Forum](https://hub.alfresco.com/ "https://hub.alfresco.com/") (Application Development Framework section) or connect with the developers into the [Alfresco Gitter channel](https://alfresco.atlassian.net/wiki/spaces/PM/overview "https://alfresco.atlassian.net/wiki/spaces/PM/overview"). Being an Alfresco customer or partner you can also raise a request for support into the Alfresco Support Portal.
 
-In the next tutorial, you will explore how you can extend, use, and configure ADF Components by customizing the login screen.
+# Other types of ADF based applications
 
-* [Extend, use and configure ADF Components](using-components.md)
+In this tutorial you learned how to create an ADF based application from scratch, running against an existing instance of Alfresco Content Services. Using the [ADF Yeoman Generator](https://github.com/Alfresco/generator-alfresco-adf-app "https://github.com/Alfresco/generator-alfresco-adf-app"), more in particular during the creation of the ADF based application, you can decide to use a different application blueprint (content only, content and process and process only). The tasks described above don’t really change except for the fact that you have to update the URLs of the backend services accordingly.

docs/user-guide/debug-test-build-and-promote.md

@@ -0,0 +1,92 @@
+---
+Title: Debug, test, build and promote
+Level: Basic
+---
+
+In this tutorial you are going to learn how to debug, test, build and promote the Alfresco Digital Workspace (aka ADW). Being an application built using the Alfresco Development Framework (aka ADF), what is described here for ADW is mostly valid also for any other ADF-based application. Differences and common commands will be described as part of this tutorial.
+
+Being a standard Angular application, the lifecycle and the tasks described for ADW are following the same principles, tooling and best practices of any other standard Angular application. We are not going to detail here what is widely described for Angular based applications (for example for what concern the debugging) but we are going to point on third party content and best practices.
+
+# Installing
+
+The command to be used is the same of any Angular application
+
+    npm nstall
+
+## Applications and distributions
+
+As part of the ADW distribution there are three different distributions to be run:
+-   content-ce (Open Source Alfresco Content Application)
+-   content-ee (Alfresco Digital Workspace with Alfresco Process Services extension)
+-   content-ee-cloud (Alfresco Digital Workspace with Alfresco Process Automation extension)
+
+The default distribution for ADW is set to be content-ee.
+
+For the Alfresco Content Application (aka ACA) or any other ADF-based application, the is always one distribution and no need to specify it at build level.
+
+## Starting
+
+The following command is valid for ADW.
+
+    npm start <content-ce|content-ee|content-ee-cloud> [prod]
+
+For ACA or any other ADF-based application the command is simply npm start.
+
+## Testing
+
+The following command is valid for ADW.
+
+    npm run build <content-ce|content-ee|content-ee-cloud> [prod]
+
+For ACA or any other ADF-based application the command is simply `npm run build`.
+
+Unit tests on ACA and ADW are developed and executed using [Karma](https://karma-runner.github.io/ "https://karma-runner.github.io/"). If you want to learn more about the available unit tests and maybe develop one (or some), you can check directly in the source code as an example.
+
+Unit tests are developed in files with extension `specs.ts`. Almost every component has a relatedspecs.ts file stored directly in the same folder where the component lives. A unit test lloks like the following piece of source code.
+
+    it('...descrioption...', () => { // Source code. });
+
+You can refer to the [Karma](https://karma-runner.github.io/ "https://karma-runner.github.io/") documentation and tutorials for further details on how to develop your own tests.
+
+## Debugging
+
+The debugging strategy for ADW, ACA or any other ADF-based application does not differ from what is recommended for any standard Angular application. Please refer to the dedicated content or documentation for further details.
+
+## Building
+
+The following command is valid for ADW.
+
+    npm run build <content-ce|content-ee|content-ee-cloud> [prod]
+
+For ACA or any other ADF-based application the command is simply npm run build.
+
+Once the build succeeds, a new folder named `dist` is created inside the project root. Inside of it, you will find a collection of files representing the distribution of your application.
+
+## Building without one or more extensions
+
+To exclude any of the bundled extensions from the distribution, you simply need to remove the imported module representing the extension, from the imports.
+
+In case of ADW, update the `apps/content-ee/src/app/extensions.module.ts` file and remove one or more modules from the imports, as shown below.
+
+    @NgModule({
+	    imports: [
+		    AosExtensionModule,
+		    AcaAboutModule,
+		    AcaSettingsModule,
+		    AiViewModule,
+		    RecordModule,
+		    ProcessServicesExtensionModule,
+		    ContentServicesExtensionModule,
+		    ExtensionsOrderExtensionModule,
+		 ],
+	}) export class AppExtensionsModule {}
+
+## Promoting in a different environment
+
+Once built, the compiled ADF-based application is available as a collection of files directly in the `dist` folder. The promotion of the distribution of the application in a different environment can be done simply by copying the files in the target server.
+
+Also in this case, nothing differs from a standard Angular application and the same tips and best practices can be followed.
+
+# Conclusions
+
+In this content you learned the most common and basic tasks for ADW and any ADF-based application.