inteligr8/alfresco-ng2-components
1
0
Fork 0
mirror of https://github.com/Alfresco/alfresco-ng2-components.git synced 2025-07-24 17:32:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated the existing tutorials and added another about Using components. (#3191)

Browse Source
This commit is contained in:
Francesco Corti
2018-04-16 13:23:46 +02:00
committed by Eugenio Romano
parent eff3ea83b0
commit 68df6138c4
6 changed files with 142 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/tutorials/README.md
View File

@@ -17,3 +17,4 @@ The tutorials are graded as follows:
| [**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. | | [**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 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. | | [**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. |

12
docs/tutorials/new-component.md
View File

@@ -1,13 +1,8 @@
---
Level: Beginner
---
# Adding a new component # 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. 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 ## Creating a component
Starting from the root of your project, run the following command into a terminal. Starting from the root of your project, run the following command into a terminal.
ng generate component my-first-component ng generate component my-first-component
@@ -15,13 +10,11 @@ Starting from the root of your project, run the following command into a termina
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. 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 ## 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. 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. 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 ## 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: 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.scss` containing the CSS used by the component. This file is created as empty.
@@ -31,15 +24,12 @@ By default the new component is created into the `src/app` path and everything i
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. 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'; import { MyFirstComponentComponent } from './my-first-component/my-first-component.component';
@NgModule({ @NgModule({
declarations: [ declarations: [
... ...
MyFirstComponentComponent 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. 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.

76
docs/tutorials/new-view.md
View File

@@ -1,68 +1,38 @@
--- ---
Level: Beginner Level: Beginner
--- ---
# Adding a new component
# Adding a new view 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.
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 component
Starting from the root of your project, run the following command into a terminal.
## Creating a view ng generate component my-first-component
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. 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.
To create a view, run the following command into a terminal, starting from the root of your project. ## 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.
ng generate component my-first-view 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.
See the [Adding a new component](new-component.md) tutorial for further details. ## 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:
## Routing the view - `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.
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 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.
following source code.
import { MyFirstComponentComponent } from './my-first-component/my-first-component.component';
```ts
const appRoutes: Routes = [
{ path: 'path-in-the-app', component: ExistingComponent },
{ path: '**', component: PageNotFoundComponent }
];
@NgModule({ @NgModule({
imports: [ declarations: [
RouterModule.forRoot( ...
appRoutes, MyFirstComponentComponent
{ enableTracing: true } // <-- debugging purposes only. ],
)
// other imports here
],
...
})
```
To add the new view to the routing, change the `appRoutes` constant as follows: 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.
```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!

21
docs/tutorials/preparing-environment.md
View File

@@ -1,9 +1,7 @@
--- ---
Level: Beginner Level: Beginner
--- ---
## Preparing the development environment
# 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. 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
@@ -13,7 +11,7 @@ In this content is shared all the prerequisites valid for all the tutorials and
You need the latest `node.js` of either the `8.x` or `9.x` branch. 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. To check the version, run the following command in a terminal.
node -v node -v
## Angular CLI ## Angular CLI
@@ -23,11 +21,11 @@ Earlier and later versions have issues around `@angular/devkit-core`. 1.6.6 seem
If you already have `Angular CLI` installed check the version by running: If you already have `Angular CLI` installed check the version by running:
ng --version ng --version
To globally install `Angular CLI` version globally 1.6.6 run: To globally install `Angular CLI` version globally 1.6.6 run:
sudo npm install -g @angular/cli@1.6.6 sudo npm install -g @angular/cli@1.6.6
## Code Editor ## Code Editor
@@ -37,17 +35,16 @@ We recommend [Visual Studio Code](http://code.visualstudio.com) - it's a free, l
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: 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 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. 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: Uninstall previous versions with:
sudo npm uninstall generator-alfresco-adf-app sudo npm uninstall generator-alfresco-adf-app
sudo npm uninstall generator-ng2-alfresco-app sudo npm uninstall generator-ng2-alfresco-app
Install the latest version of the `generator-alfresco-adf-app` using the following command. Install the latest version of the `generator-alfresco-adf-app` using the following command.
sudo npm install -g generator-alfresco-adf-app sudo npm install -g generator-alfresco-adf-app

106
docs/tutorials/using-conponents.md Normal file
View File

@@ -0,0 +1,106 @@
---
Level: Beginner
---
# Using components
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 and 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.
<adf-login
copyrightText="&#169; 2017 - 2018 Alfresco Software, Inc. All rights reserved."
providers="ECM"
...
>
</adf-login>
When reviewing the documentation you can see that the `<adf-login/>` 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, suing 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).
<adf-login
copyrightText="&#169; 2017 - 2018 Alfresco Software, Inc. All rights reserved."
providers="ECM"
[showRememberMe]="..."
[showLoginActions]="..."
...
>
</adf-login>
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 `<adf-login/>` 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 `<adf-login/>` component (the position is not relevant).
<adf-login
...
(executeSubmit)="myExecuteSubmitMethod($event)"
>
</adf-login>
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:
<div>
<p>
<b>Here we have some bold text</b>
</p>
</div>
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 `<adf-login/>` 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 `<adf-login/>` tag.
<adf-login
...
>
<login-footer>
<ng-template>
Hello World!
</ng-template>
</login-footer>
</adf-login>
Watch carefully that you place the `<login-footer/>` tag *inside* the `<adf-login/>` tag. Inside the `<login-footer/>` or `<login-header/>` tags you can put anything you want, as long as you wrap it inside an `<ng-template/>` 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.

3
docs/user-guide/summary.json
View File

@@ -9,7 +9,8 @@
"children": [ "children": [
{ "title": "Preparing the development environment", "file": "preparing-environment.md"}, { "title": "Preparing the development environment", "file": "preparing-environment.md"},
{ "title": "Adding a new component", "file": "new-component.md"}, { "title": "Adding a new component", "file": "new-component.md"},
{ "title": "Adding a new view", "file": "new-view.md"} { "title": "Adding a new view", "file": "new-view.md"},
{ "title": "Using components", "file": "using-components.md"}
] ]
} }
] ]