Adding two tutorials on extension creation and installation. (#1959)

docs/abn-tree.yml

@@ -40,4 +40,6 @@
     children:
       - custom-route-with-parameters.md: Custom route with parameters
       - dialog-actions.md: Dialog actions
+      - how-to-create-your-first-extension.md: How to create your first extension
+      - how-to-install-an-existing-extension.md: How to install an existing extension
 - help.md: 'Get help'

docs/tutorials/README.md

@@ -11,3 +11,5 @@ Learn more about developing with the Alfresco Content Application.
 
 - [Custom route with parameters](/tutorials/custom-route-with-parameters)
 - [Dialog actions](/tutorials/dialog-actions)
+- [How to create your first extension](/tutorials/how-to-create-your-first-extension)
+- [How to install an existing extension](/tutorials/how-to-install-an-existing-extension)

docs/tutorials/how-to-create-your-first-extension.md.yaml

@@ -0,0 +1,149 @@
+---
+Title: How to create your first extension
+---
+
+The purpose of this tutorial is to describe how to develop a “hello word” extension for the [Alfresco Content Application (aka ACA)](https://github.com/Alfresco/alfresco-content-app "https://github.com/Alfresco/alfresco-content-app"). The [ACA extension mechanism](https://alfresco-content-app.netlify.app/#/extending/ "https://alfresco-content-app.netlify.app/#/extending/") is the suggested way to customise the supported front-end application, and this tutorial is supposed to be the foundation for a content to share with customers and partners.
+
+# Prerequisites
+
+The starting point for this tutorial is the availability of the full repository of the [Alfresco Content Application (aka ACA)](https://github.com/Alfresco/alfresco-content-app "https://github.com/Alfresco/alfresco-content-app") on your development environment (your laptop as an example). This tutorial has been written with the following versions of the software:
+-   ACA version 2.2.0,
+-   ACS 7.0.0-M3,
+-   NodeJs version 14.15.2,
+-   Chrome Version 87.0.4280.88.
+
+# Creating the ACA extension
+
+As described [here](https://github.com/Alfresco/alfresco-digital-workspace-app/blob/develop/docs/extending.md "https://github.com/Alfresco/alfresco-digital-workspace-app/blob/develop/docs/extending.md"), the creation of an ADW extension is straightforward following the [Nx Workspace](https://nx.dev/angular "https://nx.dev/angular") dev tools for monorepos.
+
+From the root folder of the ACA project, launch the command below from a terminal. As you can see, with the command below you are going to create a new extension named `my-extension`.
+
+    ng generate library my-extension
+
+In case of errors, add the following line to the `tsconfig.json` file.  
+
+    "compilerOptions": { "baseUrl": ".", "rootDir": "." }
+
+Once done, in the `projects/my-extension` path you will find the following structure:
+
+-   `src` folder containing all the typescript source code. Very important is the `public-api.ts` file defining all the inclusions of the extension and the `lib/my-extension.module.ts` file defining the module class for the extension.
+    
+-   README.md file for documentation purposes as well as other files used for testing and configuration.
+
+To complete the creation, build the extension launching the following command.
+
+    ng build my-extension
+
+# Developing the basics of the ACA extension
+
+Now that the `my-extension` is created, let's add the proper configuration to the extension module. For this purpose, edit the `projects/my-extension/src/lib/my-extension.module.ts` file changing what is described below.
+
+    // Add the import as described below.
+    import { ExtensionService } from '@alfresco/adf-extensions';
+    
+    // Add the constructor as described below.
+    NgModule({...})
+    export class MyExtensionModule {
+      constructor(extensions: ExtensionService) {
+        extensions.setComponents({
+          'my-extension.main.component': MyExtensionComponent,
+      }); 
+    }
+  }`
+
+It's now time for the configuration of the brand new extension. For this purpose, you are going instruct the extension to add a link that you can see on the left menu of the landing page of ACA.
+
+To create the proper configuration, create the folder below in the described path.
+
+    projects/my-extension/assets
+
+Once done, create the file `projects/my-extension/assets/my-extension.json` file with the following content.
+
+    {
+      "$schema": "../../../extension.schema.json",
+      "$id": "my-extension",
+      "$version": "1.0.0",
+      "$vendor": "Your name or company name",
+      "$name": "plugin1",
+      "$description": "demo plugin",
+      "$license": "MIT",
+      
+      "routes": [ 
+      {
+        "id": "my.extension.route",
+        "path": "ext/my/route",
+        "component": "my-extension.main.component"
+      }
+    ],
+      
+      "features": { 
+        "navbar": [
+          {
+            "id": "my.extension.nav",
+            "items": [
+              {
+                "id": "my.extension.main",
+                "icon": "extension",
+                "title": "My Extension",
+                "route": "my.extension.route"
+            } 
+          ]
+        }
+      ]
+    }
+    }
+
+This is a very basic example, adding a “My Extension” item to the existing left menu, implementing a blank page containing “my-extension works!“ text appearing in the ACA landing page. From here, you can enrich the capabilities of your extension following the documentation at [https://alfresco-content-app.netlify.app/#/extending/](https://alfresco-content-app.netlify.app/#/extending/ "https://alfresco-content-app.netlify.app/#/extending/").
+
+# Making the extension as part of the ACA application
+
+Now that the ACA extension is developed in its initial version, let's add the extension module to the list of the ones used by the application. To complete the task, edit the `src/app/extensions.module.ts` file as described below.
+
+    // Add the following import to the page.
+    import { MyExtensionModule } from 'my-extension';
+    
+    @NgModule({
+      imports: [
+        ...,
+        MyExtensionModule
+    ],
+  })
+  export class AppExtensionsModule {}
+
+In addition, edit the `src/assets/app.extensions.json` file on the `$references` array. Below how it should look like.
+
+    "$references": ["my-extension.json"],
+
+Let's instruct the configuration file for the extension to be visible from the ACA app through a public URL. To complete the task, edit the angular.json file as described below.
+
+    // Add to 'src/app.config.json' array.
+    ...
+    {
+      "glob": "my-extension.json",
+      "input": "projects/my-extension/assets",
+      "output": "./assets/plugins"
+    },
+    ...
+
+Last but not least, edit the package.json file to allow the build of the extension, adding the following line to the scripts section.
+
+    { ...
+      "scripts": {
+        ...,
+        "build:my-extension": "ng build my-extension && cpr projects/my-extension/assets dist/my-extension/assets --deleteFirst"
+    }, ...
+  }
+
+Once done, create the build of the extension running the following command.
+
+    npm install my-extension
+
+# Running ACA with the extension included
+
+Now that everything is properly developed, it’s time to launch ADW and see the result. To launch ADW, run the following command from a terminal.
+
+    npm start
+
+What you should see is a new item in left menu of the landing page for ACA, implementing the route to a new page with the following content. Below the screenshot describing what it should look like.
+
+![extension](../images/extension-01.png)

docs/tutorials/how-to-install-an-existing-extension.md.yaml

@@ -0,0 +1,51 @@
+---
+Title: How to install an existing extension
+---
+
+The purpose of this tutorial is to describe how to install an existing extension for the [Alfresco Content Application (aka ACA)](https://github.com/Alfresco/alfresco-content-app "https://github.com/Alfresco/alfresco-content-app"). The [ACA extension mechanism](https://alfresco-content-app.netlify.app/#/extending/ "https://alfresco-content-app.netlify.app/#/extending/") is the suggested way to customise the ADF-based front-end applications and this tutorial should help in this relevant task to manage extensions.
+
+# Prerequisites
+
+The starting point for this tutorial is the availability of a tested and working ACA extension as well as the full repository of the [Alfresco Content Application (aka ACA)](https://github.com/Alfresco/alfresco-content-app "https://github.com/Alfresco/alfresco-content-app"). This tutorial has been written with the following versions of the software:
+-   ACA version 2.2.0,
+-   ACS 7.0.0-M3,
+-   NodeJs version 14.15.2,
+-   Chrome Version 87.0.4280.88.
+
+In this tutorial it is assumed that the existing ACA extension is named `my-extension` and its structure is compliant with the content and structure of the `projects/my-extension` path described in the tutorial [here](how-to-create-your-first-extension.md "how-to-create-your-first-extension.md").
+
+# Installing the ACA extension
+
+The idea behind this task is to create a brand new ACA extension with the same name of the existing one, and replace its content to reach the described goal.
+
+From the root folder of the ACA project, launch the command below from a terminal. Please be sure that you are going to use the same name as the existing extension (in this case my-extension).
+
+    ng generate library my-extension
+
+In case of errors, add the following line to the `tsconfig.json` file.  
+
+    "compilerOptions": { "baseUrl": ".", "rootDir": "." }
+
+Once done, delete the full content of the `projects/my-extension` folder and replace it with the source code of the existing ACA extension.
+
+To complete the creation, build the extension launching the following command.
+
+    ng build my-extension
+
+In case of errors, add the following configuration to the `tsconfig.json` file.  
+
+    "compilerOptions": { ..., "allowSyntheticDefaultImports":true }
+
+# Making the extension as part of the ACA application
+
+Now that the ACA extension is developed in its initial version, let's add the extension module to the list of the ones used by the application. To complete the task you can follow the same task described for the tutorial named [How to create your first extension for the Alfresco Content Application (aka ACA)](how-to-create-your-first-extension.md) (paragraph “Making the extension as part of the ACA application“). Once the extension is installed with success (`npm install my-extension`), the task can be considered as completed.
+
+# Running ACA with the extension included
+
+Now that everything is properly developed, it’s time to launch ACA and see the result. To launch ADW, run the following command from a terminal.
+
+    npm start
+
+What you should see is a new item in left menu of the landing page for ACA, implementing the route to a new page with the following content. Below the screenshot describing what it should look like.
+
+![extension](../images/extension-02.png)