diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index b3da0b1bc9..ad5f384341 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -15,7 +15,10 @@ The tutorials are graded as follows: | 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. | +| [**Creating your ADF application using Yeoman**](creating-the-app-using-yeoman.md) | Beginner | In this tutorial you are going to see how to create an ADF application from scratch, using the [Yeoman scaffolding tool](http://yeoman.io/). | | [**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. | | [**Using components**](using-components.md) | Beginner | There are three different ways to use, extend and configure an ADF component: configuration properties, event listeners, content projection / HTML extensions. In this tutorial you are going to see a practical example for each approach. As an example, the Login component will be used. | +| [**Customising the Login component**](customising-login.md) | Intermediate | In this tutorial you will learn how to customise the [`Login` component](https://alfresco.github.io/adf-component-catalog/components/LoginComponent.html) assuming that you read the [technical documentation](https://alfresco.github.io/adf-component-catalog/components/LoginComponent.html). | | [**Working with a DataTable**](working-with-data-table.md) | Intermediate | In this tutorial you will learn how to populate a DataTable component, with custom data coming from a generic back-end service or third party API. | + diff --git a/docs/tutorials/creating-the-app-using-yeoman.md b/docs/tutorials/creating-the-app-using-yeoman.md new file mode 100644 index 0000000000..3f52412b42 --- /dev/null +++ b/docs/tutorials/creating-the-app-using-yeoman.md @@ -0,0 +1,76 @@ +--- +Level: Basic +--- +# Creating your ADF application using Yeoman + +In this tutorial you are going to see how to create an ADF application from scratch, using the [Yeoman scaffolding tool](http://yeoman.io/). This is a "getting started" task that should enable you to start developing your own ADF application. + +## Prerequisites +Before any further task, be sure you executed the optional section described in [the preparation of the development environment](./preparing-the-development-environment.html), dedicated to the installation of the ADF Yeoman generator. This is a requested prerequisite to complete this tutorial with success. + +## Creating the ADF application +The creation of a brand new application is straightforward using the [Yeoman generator](http://yeoman.io/). Open a terminal and execute the following command. + + yo alfresco-adf-app + +After the execution, the generator asks few questions: mainly the name of your app (in this example we are going to use `myApp`) and which blueprint you want to use. below the picture showing how the wizard looks like. + +![yeoman_creation](../docassets/images/yeoman_creation.png) + +You can select one of the three following blueprints. + +**Process Services** + +This will generate an application for Alfresco Process Services. It mainly contains the following components: Login, App List, Task List, Form and Start Process. + +**Content Services** + +This will generate an application for Alfresco Content Services. It mainly contains the following components: Login, Document List, Viewer. + +**Process and Content Services** + +This will generate an application for both Alfresco Process and Content Services and will be a combination of the two blueprints above. + +Select your preferred one and the generator asks if you want to install dependencies right away. Enter "`Y`" and hit enter. This can take a minute or two depending on your internet connection. You might see a few warnings at the end like this: + + npm notice created a lockfile as package-lock.json. You should commit this file. + npm WARN @mat-datetimepicker/core@1.0.4 requires a peer of @angular/core@^5.2.3 but none is installed. You must install peer dependencies yourself. + npm WARN @mat-datetimepicker/core@1.0.4 requires a peer of @angular/material@^5.2.4 but none is installed. You must install peer dependencies yourself. + npm WARN @mat-datetimepicker/core@1.0.4 requires a peer of @angular/cdk@^5.2.4 but none is installed. You must install peer dependencies yourself. + npm WARN @mat-datetimepicker/moment@1.0.4 requires a peer of @angular/material@^5.2.4 but none is installed. You must install peer dependencies yourself. + npm WARN @mat-datetimepicker/moment@1.0.4 requires a peer of @angular/material-moment-adapter@^5.2.4 but none is installed. You must install peer dependencies yourself. + npm WARN @angular/compiler-cli@5.2.10 requires a peer of @angular/compiler@5.2.10 but none is installed. You must install peer dependencies yourself. + npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.1.3 (node_modules/fsevents): + npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@1.1.3: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"}) + +These warnings are normal. Unfortunately they happen within the Angular Flex Layout package that ADF depends on. You can safely ignore them. + +Once done, you will find a folder named `myApp` where you can find all the ADF application already created and completed. + +## Configuring the application + +To configure the ADF application, you only need to point on the correct Alfresco Content Services and Alfresco Process Services, accordingly with the blueprint you decided to use during the creation. + +To setup the correct back-end services, change into the directory of your app (`myApp` in our case) and inspect the `proxy.conf.json` file. This file will tell Angular Webpack to create a proxy for your backend (Content or Process services). Change the URLs and ports to reflect where they are currently running. Below an example of how the `proxy.conf.json` file should look like. + +{ + "/alfresco": { + "target": "http://localhost:8080", // <-- Change this! + "secure": false, + "changeOrigin": true + }, + "/activiti-app": { + "target": "http://localhost:9999", // <-- Change this! + "secure": false, + "changeOrigin": true + } +} + +## Using the application + +Now that you ADF application is correctly configured, start it running the `npm start` command from a terminal, double checking you are located into the project folder (in our case `myApp`). The execution of the command takes a couple of seconds and a browser will automatically open at `http://localhost:4200/`. + +As you can see from the user interface, the Alfresco ADF application is really straightforward and basic. This is a precise requirement for this example, because it focuses the attention on the comprehension of the basis, instead of containing complex features that will be part of an intermediate/expert learning path. Below a screenshot of how the home page looks like. + +![yeoman_start](../docassets/images/yeoman_start.png) + diff --git a/docs/tutorials/customising-login.md b/docs/tutorials/customising-login.md new file mode 100644 index 0000000000..079a86d869 --- /dev/null +++ b/docs/tutorials/customising-login.md @@ -0,0 +1,31 @@ +--- +Level: Intermediate +--- +# Customising the Login component + +In this tutorial you will learn how to customise the [`Login` component](https://alfresco.github.io/adf-component-catalog/components/LoginComponent.html) assuming that you read the [technical documentation](https://alfresco.github.io/adf-component-catalog/components/LoginComponent.html). In this tutorial we are going to describe a very simple task, considering that the technical documentation is complete and it is presented in form of examples and tutorial. + +## Locating the component into your application + +Starting from an existing ADF application, the `Login` component, like any other component, is stored in a subfolder of the `app` folder: in [Alfresco Content App](https://github.com/Alfresco/alfresco-content-app) it is stored into the `/src/app/components/login` path, in an ADF app created with [Yeoman](http://yeoman.io/) it is stored into the `/src/app/login` path. + +As an example, locate the `Login` component for your application and proceed to customise it as described below. + +## Changing the header + +As every regular [Angular Component](https://angular.io/guide/architecture-components), the `Login` component can be customised through the CSS, HTML and Typescript. In this simple example we are going to customise the header (as described also into the [technical documentation](https://alfresco.github.io/adf-component-catalog/components/LoginComponent.html)). + +To complete the task, edit the login.component.html file and change the content accordingly to the following source code. + + + My custom HTML for the header + + +After saving the file, the login form will look like the following picture. + +![login_header](../docassets/images/login_header.png) + +## More examples + +As introduced above in this tutorial, this is a very basic example and the `Login` component can be customised many more than this. For a complete and detailed description, full of examples, check the [technical documentation about the component](https://alfresco.github.io/adf-component-catalog/components/LoginComponent.html) that contains everything you might want to know about the customisation of the `Login` component + diff --git a/docs/tutorials/using-conponents.md b/docs/tutorials/using-conponents.md deleted file mode 100644 index f66dbe0722..0000000000 --- a/docs/tutorials/using-conponents.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -Level: Beginner ---- -# Using components -In this tutorial you will learn the common basics on using ADF components and Angular components in general. - -The best option you should consider when you plan to use an ADF component and want to learn the details of its usage, is always to check the documentation for the component you are looking to use. More in general, there are three different ways to use, extend and configure an ADF component: -1. Configuration properties. -2. Event listeners. -3. Content projection / HTML extensions. - -In this tutorial you are going to see a practical example for each approach. As an example, the [Login component](https://alfresco.github.io/adf-component-catalog/components/LoginComponent.html) will be used. - -## Configuration properties -Angular components can easily be configured via properties in the HTML template. In this example we will act on the "Remember me" check and "Need Help?" + "Register" links in the footer of the Login component. - -To prepare the task, be sure you have an ADF application up and running by executing `npm start` in a terminal, from the root folder of the project. Access to the login page using your browser and edit the `login.component.html` file stored into the `src/app/.../login` folder. The content of the `login.component.html` file should look like the following source code. - - - - -When reviewing the documentation you can see that the `` component has a lot of different properties. As an example we will toggle `showRememberMe` and `showLoginActions` (all set to `true` by default). If not already specified, add both the properties both with the false value, using the syntax described below in the example. If the properties are defined in the HTML template, toggle the value according to what you see in the source code (set them to `true` if they have the `false` value and viceversa). - - - - -Once saved the HTML template you will see the login page updated with a different layout accordingly with the property values. - -**Notice:** The two new properties are specified with `[]` around them. There are three ways to configure a component. - -1. `[property]=""` This will be an expression or property from the typescript controller. Use this for boolean expressions or variables. -2. `property=""` This will be passed in as raw text. -3. `[(property)]` This is called *banana in a box* and is used for two way binding. - -## Event listeners - -Now that you've successfully configured properties on the `` component, it's time to look at the events. - -As we did for the previous task, looking at the [Login component documentation](https://alfresco.github.io/adf-component-catalog/components/LoginComponent.html) we can see that it emits three events `success`, `error` and `executeSubmit`. - -We can subscribe to these events and have our custom code executed once these events are emitted. Let's hook into the `executeSubmit` and do a simple `alert()` once the form is submitted. - -Continue to edit the `login.component.html` file and add `(success)="mySuccessMethod($event)"` to the `` component (the position is not relevant). - - - - -Next you need to implement `myExecuteSubmitMethod` in the typescript class implementing the component. Edit the `login.component.ts` file stored in the same `src/app/.../login` folder and add the implementation of `myExecuteSubmitMethod` as follows. - - @Component({ - ... - }) - export class LoginComponent { - - ... - - // Add this! - myExecuteSubmitMethod(event: any) { - alert('Form was submitted!'); - console.log(event); - } - } - -Save both the files and the login component will be refreshed in your browser. Enter random values for username and password and you should see the alert after pressing the submit button. Looking in the console of the browser, you'll see the `event` data containing all the details of the form. - -**Bonus objective:** Add a custom logo and background to the login view. - -## Content projection / HTML extensions -The last way a component can be configured or extended is through an approach called *Content projection*. This allows components to put placeholders in their template, allowing developers to "project" their own code or components into pre-defined locations within the component. - -In regular HTML, elements can be nested, for example: - -
-

- Here we have some bold text -

-
- -We can use the same approach with ADF components to inject custom code or entire components into the ADF component. Going to the documentation you can find more details about which targets are in place. - -The `` component supports two targets: `login-header` and `login-footer`. Let's add a simple "Hello World" message in the footer. Edit the template `login.component.html` and add a new tag *inside* the `` tag. - - - - - Hello World! - - - - -Watch carefully that you place the `` tag *inside* the `` tag. Inside the `` or `` tags you can put anything you want, as long as you wrap it inside an `` tag. You can also source in custom or 3rd party components. - -Once done, save the template and you should see a "Hello World!" message in the footer of your login page through your browser. diff --git a/docs/user-guide/summary.json b/docs/user-guide/summary.json index 7612fa728b..1a0f9cb2c8 100644 --- a/docs/user-guide/summary.json +++ b/docs/user-guide/summary.json @@ -8,9 +8,11 @@ { "title": "Tutorials", "file": "tutorialIndex.md", "children": [ { "title": "Preparing the development environment", "file": "preparing-environment.md"}, + { "title": "Creating your ADF application using Yeoman", "file": "creating-the-app-using-yeoman.md"}, { "title": "Adding a new component", "file": "new-component.md"}, { "title": "Adding a new view", "file": "new-view.md"}, { "title": "Using components", "file": "using-components.md"}, + { "title": "Customising the Login component", "file": "customising-login.md"}, { "title": "Working with a DataTable", "file": "working-with-data-table.md"} ] }