[ADF-2679] Added first tutorials (#3186)

* [ADF-2679] Updated tutorial index script and added the first few tutorials

* [ADF-2679] Minor fixes to README and index script

docs/README.md

@@ -16,6 +16,9 @@ that the component is complete and suitable for normal use. The other status lev
 -   **Experimental** ![](docassets/images/ExperimentalIcon.png) - The component is available for
     experimentation but not fully complete and tested for production code.
 
+There is also a set of ADF tutorials that describe how to accomplish tasks step-by-step.
+See the [Tutorials index](tutorials/README.md) for the full list.
+
 ## Contents
 
 -   [User Guide](#user-guide)

docs/tutorials/README.md

@@ -0,0 +1,19 @@
+# ADF Tutorials
+
+Learn about ADF step-by-step with the tutorials listed below.
+You may find it helpful to follow them in sequence because some of the
+later tutorials build on knowledge introduced in the earlier ones.
+
+The tutorials are graded as follows:
+
+-   **Beginner:** Suitable for users with no previous knowledge of ADF.
+-   **Intermediate:** For users who want to add to their knowledge of the basics.
+-   **Advanced:** For experienced users who want to learn about features in depth.
+
+## Tutorials
+
+| Name | Level | Abstract |
+| -- | -- | -- |
+| [**Preparing the development environment**](preparing-environment.md) | Beginner | In this content is shared all the prerequisites valid for all the tutorials and descriptions of the entire documentation. This content contains the development environment description, along with the details of the suggested versions for each tools, library or module. |
+| [**Adding a new component**](new-component.md) | Beginner | By definition a _component_ controls a patch of screen called a view. As an example, individual components define and control menus, tabs, forms, buttons and every simple or complex portion of layout of an application. In this tutorial you will learn how to create a component using [Angular CLI](https://cli.angular.io/). After the creation you will learn how to add it to an existing application. |
+| [**Adding a new view**](new-view.md) | Beginner | Every application developed in Angular is a single page application where the concepts of _view_ and _routing_ play a key role in the user experience. Being a single page application, the navigation between the different layouts (called _views_) is enabled through the _routing_. In this tutorial you will learn how to create a new view into your application and how to have access to it using a defined endpoint. |

docs/tutorials/new-component.md

@@ -0,0 +1,45 @@
+---
+Level: Beginner
+---
+
+# Adding a new component
+
+By definition a *component* controls a patch of screen called a view. As an example, individual components define and control menus, tabs, forms, buttons and every simple or complex portion of layout of an application. In this tutorial you will learn how to create a component using [Angular CLI](https://cli.angular.io/). After the creation you will learn how to add it to an existing application.
+
+## Creating a component
+
+Starting from the root of your project, run the following command into a terminal.
+
+    ng generate component my-first-component
+
+If you are adding the component to an application with more than one module, you might want to specify it using the `--module` parameter. For example use `--module app` to add the new component to the root app of your application.
+
+## Using the component
+
+Once done, wherever you will use `<app-my-first-component></app-my-first-component>` into the HTML file of another component, you will see the content of the new component rendered exactly in that place.
+
+As an example, add `<app-my-first-component></app-my-first-component>` on top of the `app.component.html` file stored into the `src` folder, and run the application again. Directly in the browser you will see `my-first-component works!`, that shows exactly the place where the component is rendered in the layout.
+
+## Anatomy of the component
+
+By default the new component is created into the `src/app` path and everything is stored in a folder named like the component itself. In this example a folder named with `my-first-component` is added to `src/app`, with inside the following content:
+
+ - `my-first-component.component.scss` containing the CSS used by the component. This file is created as empty.
+ - `my-first-component.component.html` containing the HTML used to render the component. This file is created with a very basic message rendering the name of the component included in a `p` tag.
+ - `my-first-component.component.spec.ts` containing the unit tests for the component.
+ - `my-first-component.component.ts` containing the `MyFirstComponentComponent` class implementing the business logic in typescript.
+
+To make the component usable, one or more modules should declare it (or import it). In this example the `app.module.ts` file stored into the `src/app` folder contains the following code.
+
+```ts
+    import { MyFirstComponentComponent } from './my-first-component/my-first-component.component';
+
+    @NgModule({
+        declarations: [
+            ...
+            MyFirstComponentComponent
+        ],
+```
+
+These are the very basic information you should be know about your brand new component. All you have read here is standard Angular, not customised or valid for ADF applications only.
+

docs/tutorials/new-view.md

@@ -0,0 +1,68 @@
+---
+Level: Beginner
+---
+
+# Adding a new view
+
+Every application developed in Angular is a single page application where the concepts of *view* and *routing* play a key role in the user experience. Being a single page application, the navigation between the different layouts (called *views*) is enabled through the *routing*. In this tutorial you will learn how to create a new view into your application and how to have access to it using a defined endpoint.
+
+## Creating a view
+
+Into an Angular application, a view is implemented by a regular component. A view can use other views (so other components), but a view can be used to implement the full layout of your application. This is the reason why creating a view is the task than creating a component.
+
+To create a view, run the following command into a terminal, starting from the root of your project.
+
+    ng generate component my-first-view
+
+See the [Adding a new component](new-component.md) tutorial for further details.
+
+## Routing the view
+
+An Angular application has one singleton instance of the `Router` service that is used to match the browser's URL with the corresponding component to display. The `Router` service must be configured in a typescript file (usually in the `imports` , in with a syntax similar to the
+following source code.
+
+```ts
+    const appRoutes: Routes = [
+      { path: 'path-in-the-app', component: ExistingComponent },
+      { path: '**', component: PageNotFoundComponent }
+    ];
+    
+    @NgModule({
+      imports: [
+        RouterModule.forRoot(
+          appRoutes,
+          { enableTracing: true } // <-- debugging purposes only.
+        )
+        // other imports here
+      ],
+      ...
+    })
+```
+
+To add the new view to the routing, change the `appRoutes` constant as follows:
+
+```ts
+    const appRoutes: Routes = [
+      { path: 'path-in-the-app', component: ExistingComponent },
+      { path: 'my-first-view', component: MyFirstViewComponent }, // <-- Add this!
+      { path: '**', component: PageNotFoundComponent }
+    ];
+```
+
+And remember to import the component in the same file with the following syntax:
+
+```ts
+    import { MyFirstViewComponent } from './my-first-view/my-first-view.component';
+```
+
+Be aware that the `Router` service can be declared in a file that can be stored in different places in the application's structure. Usually the place where the `Router`  service is declared is closed to the file containing the root module.
+
+## Testing the view
+
+To render the new view through the application and check the user experience, restart the application and open a browser to the following URL.
+
+    http://<ip_address>:<port>/my-first-view
+
+The result should be a very simple page with the following content.
+
+    my-first-view works!

docs/tutorials/preparing-environment.md

@@ -0,0 +1,53 @@
+---
+Level: Beginner
+---
+
+# Preparing the development environment
+
+In this content is shared all the prerequisites valid for all the tutorials and descriptions of the entire documentation. This content contains the development environment description, along with the details of the suggested versions for each tools, library or module.
+
+## Node.js
+
+[Node.js](https://nodejs.org) is a JavaScript runtime built using an event-driven, non-blocking I/O model that makes it lightweight and efficient. Node.js uses [npm](https://www.npmjs.com/) as public registry and a package system.
+
+You need the latest `node.js` of either the `8.x` or `9.x` branch.
+To check the version, run the following command in a terminal. 
+
+    node -v
+
+## Angular CLI
+
+The [Angular CLI](https://cli.angular.io/) is a tool to initialise, develop, scaffold and maintain [Angular](https://angular.io/) applications
+
+Earlier and later versions have issues around `@angular/devkit-core`. 1.6.6 seem to be the stable choice currently.
+
+If you already have `Angular CLI` installed check the version by running:
+
+    ng --version
+
+To globally install `Angular CLI` version globally 1.6.6 run:
+
+    sudo npm install -g @angular/cli@1.6.6
+
+## Code Editor
+
+We recommend [Visual Studio Code](http://code.visualstudio.com) - it's a free, lightweight and *very* powerful tool from Microsoft that works great with Angular development.
+
+## ADF Yeoman generator (optional)
+
+You might want to ensure that you have `Yeoman` installed by running `yo --version`. If this is not in your system make sure you run:
+
+    sudo npm install -g yo
+
+If you have installed it previously, you might want to make sure you uninstall them before. In ADF 2.0 we renamed the generator packages and the update is highly suggested.
+
+Uninstall previous versions with:
+
+    sudo npm uninstall generator-alfresco-adf-app
+    sudo npm uninstall generator-ng2-alfresco-app
+    
+Install the latest version of the `generator-alfresco-adf-app` using the following command.
+
+    sudo npm install -g generator-alfresco-adf-app
+
+

docs/user-guide/summary.json

@@ -4,5 +4,12 @@
     { "title": "Internationalization in ADF", "file": "internationalization.md" },
     { "title": "Theming", "file": "theming.md" },
     { "title": "Typography", "file": "typography.md" },
-    { "title": "Walkthrough - adding indicators to highlight information about a node", "file": "metadata-indicators.md" }
+    { "title": "Walkthrough - adding indicators to highlight information about a node", "file": "metadata-indicators.md" },
+    { "title": "Tutorials", "file": "tutorialIndex.md",
+        "children": [
+            { "title": "Preparing the development environment", "file": "preparing-environment.md"},
+            { "title": "Adding a new component", "file": "new-component.md"},
+            { "title": "Adding a new view", "file": "new-view.md"}
+        ]
+    }
 ]

lib/config/DocProcessor/doctool.config.json

@@ -1,6 +1,7 @@
 {
     "enabledTools": [
         "index",
-        "versionIndex"
+        "versionIndex",
+        "tutorialIndex"
     ]
 }

lib/config/DocProcessor/templates/tutIndex.combyne

@@ -1,3 +1,5 @@
+| Name | Level | Abstract |
+| -- | -- | -- |
 {% each tuts as tut %}
-1. [**{{tut.title}}**]({{tut.link}}) ({{tut.level}}): {{tut.briefDesc}}
+| [**{{tut.title}}**]({{tut.link}}) | {{tut.level}} | {{tut.briefDesc}} |
 {% endeach %}

lib/config/DocProcessor/tools/index.js

@@ -391,9 +391,11 @@ function buildGuideSection(guideJsonFilename, forSubFolder) {
             filePath = guideFolderName + "/" + filePath;
         }
 
+        if (summary[i].title !== "Tutorials") {
             var link = unist.makeLink(unist.makeText(summary[i].title), filePath);
             listItems.push(unist.makeListItem(link));
         }
+    }
 
     return unist.makeListUnordered(listItems);
 }

lib/config/DocProcessor/tools/tutorialIndex.js

@@ -10,6 +10,7 @@ var combyne = require("combyne");
 var unist = require("../unistHelpers");
 var tutFolder = path.resolve("..", "docs", "tutorials");
 var templateFolder = path.resolve(".", "config", "DocProcessor", "templates");
+var userGuideFolder = path.resolve("..", "docs", "user-guide");
 function initPhase(aggData) { }
 exports.initPhase = initPhase;
 function readPhase(tree, pathname, aggData) { }
@@ -38,14 +39,20 @@ function updatePhase(tree, pathname, aggData) {
 }
 exports.updatePhase = updatePhase;
 function getIndexDocData() {
-    var indexFile = path.resolve(tutFolder, "index.json");
-    var indexArray = JSON.parse(fs.readFileSync(indexFile, "utf8"));
+    var indexFile = path.resolve(userGuideFolder, "summary.json");
+    var summaryArray = JSON.parse(fs.readFileSync(indexFile, "utf8"));
+    var indexArray = [];
+    summaryArray.forEach(function (element) {
+        if (element["title"] === "Tutorials") {
+            indexArray = element["children"];
+        }
+    });
     var result = {
         tuts: []
     };
     indexArray.forEach(function (element) {
-        var tutData = { link: element };
-        var tutFile = path.resolve(tutFolder, element);
+        var tutData = { link: element["file"] };
+        var tutFile = path.resolve(tutFolder, element["file"]);
         var tutFileText = fs.readFileSync(tutFile, "utf8");
         var tutMD = remark().use(frontMatter, ["yaml"]).parse(tutFileText);
         var metadata = getDocMetadata(tutMD);

lib/config/DocProcessor/tools/tutorialIndex.ts

@@ -12,6 +12,7 @@ import * as unist from "../unistHelpers";
 
 const tutFolder = path.resolve("..", "docs", "tutorials");
 const templateFolder = path.resolve(".", "config", "DocProcessor", "templates");
+const userGuideFolder = path.resolve("..", "docs", "user-guide");
 
 
 export function initPhase(aggData) {}
@@ -51,17 +52,24 @@ export function updatePhase(tree, pathname, aggData) {
 
 
 function getIndexDocData() {
-    let indexFile = path.resolve(tutFolder, "index.json");
-    let indexArray = JSON.parse(fs.readFileSync(indexFile, "utf8"));
+    let indexFile = path.resolve(userGuideFolder, "summary.json");
+    let summaryArray = JSON.parse(fs.readFileSync(indexFile, "utf8"));
+    let indexArray = [];
+
+    summaryArray.forEach(element => {
+        if (element["title"] === "Tutorials") {
+            indexArray = element["children"];
+        }
+    });
 
     let result = {
         tuts: []
     };
 
     indexArray.forEach(element => {
-        let tutData = { link: element };
+        let tutData = { link: element["file"] };
 
-        let tutFile = path.resolve(tutFolder, element);
+        let tutFile = path.resolve(tutFolder, element["file"]);
         let tutFileText = fs.readFileSync(tutFile, "utf8");
         let tutMD = remark().use(frontMatter, ["yaml"]).parse(tutFileText);