mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2025-07-24 17:32:15 +00:00
[ADF-3745] Updates for doc review (#3963)
* [ADF-3745] Updates for doc review * [ADF-3745] Updated tutorial index * [ADF-3745] Updated document list doc page
This commit is contained in:
Andy Stark
committed by
Eugenio Romano
Eugenio Romano
parent
aab19708a2
commit
89fcdec5ef
@@ -1,148 +1,174 @@
|
||||
---
|
||||
Level: Beginner
|
||||
Level: Basic
|
||||
---
|
||||
|
||||
# Using components
|
||||
# Using ADF Components
|
||||
|
||||
There are three different ways to use, extend and configure an ADF component: configuration properties, event listeners, and content projection / HTML extensions. In this tutorial you will see a practical example of each approach using the [Login component](../core/login.component.md).
|
||||
In this tutorial you will learn how to extend, use and configure ADF Components.
|
||||
|
||||
The ADF documentation is always a good starting point when you plan to use a component. 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.
|
||||
We will be customizing the [Login component](../core/login.component.md) as an example, where we will remove the `Remember me`, `Need Help?` and `Register` links in the footer and setup an event listener that displays an alert when the login form is submitted. We will finish off by setting up a custom footer.
|
||||
|
||||
## Configuration properties
|
||||
The final result will look like this:
|
||||
|
||||
Angular components can easily be configured via properties in the HTML template. In this example we will
|
||||
work with the "Remember me" checkbox and "Need Help?" and "Register" links in the footer of the [Login component](../core/login.component.md).
|
||||
|
||||
|
||||
To prepare for the task, make sure you have your ADF application up and running by executing `npm start`
|
||||
in a terminal from the root folder of the project. Access the login page using your browser and edit the [`login.component`](../core/login.component.md)`.html` file stored in the `src/app/.../login` folder. The content of the [`login.component`](../core/login.component.md)`.html` file should look like the following:
|
||||
We have carefully picked these three customizations because they cover the three fundamental ways you can ways to use, extend and configure ADF Components:
|
||||
|
||||
1. Configuration Properties
|
||||
2. Event Listeners
|
||||
3. HTML Extensions / _Content Projection_
|
||||
|
||||
You should always consult the documentation for the component you are looking to use. For this exercise it would be useful to open a browser window with the [Login Component](../core/login.component.md)
|
||||
documentation.
|
||||
|
||||
Let's do a practical example with each approach.
|
||||
|
||||
## Configuration Properties
|
||||
|
||||
Angular components can easily be configured via properties in the HTML template. In this example we will remove the `Remember me`, `Need Help?` and `Register` links in the footer.
|
||||
|
||||
Make sure you have the application running from the [previous tutorial](creating-your-first-adf-application.md).
|
||||
|
||||
Open the project in a code editor. It's best to open the entire folder so it will be easier to switch between files.
|
||||
|
||||
Open the `src/app/login/login.component.html` file. The contents will look like this:
|
||||
|
||||
```html
|
||||
<adf-login
|
||||
copyrightText="© 2017 - 2018 Alfresco Software, Inc. All rights reserved."
|
||||
providers="ECM"
|
||||
...
|
||||
>
|
||||
copyrightText="© 2017 Alfresco Software, Inc. All Rights Reserved."
|
||||
successRoute="/documentlist">
|
||||
</adf-login>
|
||||
```
|
||||
|
||||
Looking at 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 you haven't specified any values for these properties in the source code then set them both
|
||||
to `false` using the syntax shown in the example below. If you have specified values in the source code then
|
||||
set them to the opposite value in the HTML template (set them to `true` if they are `false` in the source
|
||||
and vice versa).
|
||||
Looking at the documentation, we can see that the `<adf-login/>` component has a lot of different properties. The ones we are interested in are `showRememberMe` and `showLoginActions`. These are set to `true` by default, but we can easily change them like this:
|
||||
|
||||
```html
|
||||
<adf-login
|
||||
copyrightText="© 2017 - 2018 Alfresco Software, Inc. All rights reserved."
|
||||
providers="ECM"
|
||||
[showRememberMe]="..."
|
||||
[showLoginActions]="..."
|
||||
...
|
||||
>
|
||||
[showRememberMe]="false"
|
||||
[showLoginActions]="false"
|
||||
copyrightText="© 2017 Alfresco Software, Inc. All Rights Reserved."
|
||||
successRoute="/documentlist">
|
||||
</adf-login>
|
||||
```
|
||||
|
||||
After saving the HTML template, you will see the login page updated with a different layout matching the
|
||||
new property values.
|
||||
Save the file. The browser will automatically reload once the file is saved. The result will look like this:
|
||||
|
||||
**Note:** The two new properties are specified with `[]` around them. There are three ways to configure a
|
||||
property:
|
||||
|
||||
|
||||
1. `[property]=""` This sets the property using an expression or another property from the Typescript
|
||||
controller. Use this syntax for boolean expressions or variables.
|
||||
2. `property=""` This value will be passed as raw text.
|
||||
3. `[(property)]` This is called _banana in a box_ and is used for two way binding.
|
||||
**Note:** The two new properties are specified with `[]` around them. There are three ways to configure a component property:
|
||||
|
||||
## Event listeners
|
||||
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
|
||||
|
||||
Now that you've successfully configured properties on the `<adf-login/>` component, it's time to look at events.
|
||||
## Event Listeners
|
||||
|
||||
Looking now at the events section of 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`.
|
||||
Now that we've successfully configured properties on the `<adf-login/>` component, it's time to look at events.
|
||||
|
||||
We can subscribe to these events and have our custom code executed when they are emitted. We will
|
||||
hook into the `executeSubmit` event and show a simple `alert()` when the form is submitted.
|
||||
Again, looking at the [Login Component](../core/login.component.md)
|
||||
docs, we can see that it emits three events: `success`, `error` and `executeSubmit`.
|
||||
|
||||
Back in the [`login.component`](../core/login.component.md)`.html` file, add `(success)="mySuccessMethod($event)"` to the `<adf-login/>` component (the position is not relevant).
|
||||
We can subscribe to these events and have our custom code executed when these events are emitted. Let's hook into the `executeSubmit` and do a simple `alert()` when the form is submitted.
|
||||
|
||||
Open `src/app/login/login.component.html` and add `(success)="mySuccessMethod($event)"` to the `<adf-login/>` component:
|
||||
|
||||
```html
|
||||
<adf-login
|
||||
...
|
||||
(executeSubmit)="myExecuteSubmitMethod($event)"
|
||||
>
|
||||
[showRememberMe]="false"
|
||||
[showLoginActions]="false"
|
||||
(success)="mySuccessMethod($event)"
|
||||
copyrightText="© 2017 Alfresco Software, Inc. All Rights Reserved."
|
||||
successRoute="/documentlist">
|
||||
</adf-login>
|
||||
```
|
||||
|
||||
Next, implement `myExecuteSubmitMethod` in the Typescript class that defines the component. Edit
|
||||
the [`login.component`](../core/login.component.md)`.ts` file stored in the same `src/app/.../login` folder and add the implementation
|
||||
of `myExecuteSubmitMethod` as follows:
|
||||
Next we need to implement `mySuccessMethod` in the typescript. Open `src/app/login/login.component.ts` and add a new method:
|
||||
|
||||
```ts
|
||||
// Add this!
|
||||
mySuccessMethod(event: any) {
|
||||
alert('Form was submitted!');
|
||||
console.log(event);
|
||||
}
|
||||
```
|
||||
|
||||
The complete file should now look like this:
|
||||
|
||||
```ts
|
||||
import { Component } from '@angular/core';
|
||||
|
||||
@Component({
|
||||
...
|
||||
selector: 'app-login',
|
||||
templateUrl: './login.component.html',
|
||||
styleUrls: ['./login.component.css']
|
||||
})
|
||||
export class LoginComponent {
|
||||
|
||||
...
|
||||
|
||||
// Add this!
|
||||
myExecuteSubmitMethod(event: any) {
|
||||
// Add this!
|
||||
mySuccessMethod(event: any) {
|
||||
alert('Form was submitted!');
|
||||
console.log(event);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
After saving both files, the [login component](../core/login.component.md) will be refreshed in your browser. Enter random values for
|
||||
the 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.
|
||||
Save the files, go to the [login component,](../core/login.component.md) enter a valid username and password and you should now see an alert. Looking in the console in the browser, you'll see the event data. Here we get all the details for the form.
|
||||
|
||||
**Bonus objective:** Add a custom logo and background to the login view using the relevant properties
|
||||
described in the documentation.
|
||||
## Content Projection / HTMl Extensions
|
||||
|
||||
## 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.
|
||||
|
||||
The final way to configure or extend a component is through an approach called _Content projection_. This
|
||||
involves adding placeholders to a component 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:
|
||||
In normal HTML, elements can be nested, for example:
|
||||
|
||||
```html
|
||||
<div>
|
||||
<p>
|
||||
<b>Here we have some bold text</b>
|
||||
</p>
|
||||
<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 another
|
||||
component. The documentation shows which targets are available. For example, 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`](../core/login.component.md)`.html` and add a new tag _inside_ the `<adf-login/>` tag:
|
||||
We can use the same approach with ADF Components to inject custom code or whole components into the ADF component.
|
||||
|
||||
The documentation gives information about which targets are in place. Components that support content
|
||||
project have a
|
||||
[Transclusions](../user-guide/transclusion.md)
|
||||
section in the doc page with all the relevant details.
|
||||
|
||||
The `<adf-login/>` component supports two targets: `login-header` and `login-footer`.
|
||||
|
||||
Let's add a simple Hello World message in the footer. Open the template `src/app/login/login.component.html` and add a new tag _inside_ the `<adf-login/>` HTML tag:
|
||||
|
||||
```html
|
||||
<adf-login
|
||||
...
|
||||
>
|
||||
<login-footer>
|
||||
<ng-template>
|
||||
Hello World!
|
||||
</ng-template>
|
||||
</login-footer>
|
||||
[showRememberMe]="false"
|
||||
[showLoginActions]="false"
|
||||
(executeSubmit)="myExecuteSubmitMethod($event)"
|
||||
copyrightText="© 2017 Alfresco Software, Inc. All Rights Reserved."
|
||||
successRoute="/documentlist">
|
||||
<login-footer>
|
||||
<ng-template>
|
||||
Hello World!
|
||||
</ng-template>
|
||||
</login-footer>
|
||||
</adf-login>
|
||||
```
|
||||
|
||||
Make sure 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 add custom or 3rd party components.
|
||||
Be careful that you place the `<login-footer/>` tag _inside_ the `<adf-login/>` tag.
|
||||
|
||||
When you are done, save the template and you should see a "Hello World!" message in the footer of your
|
||||
login page when the browser refreshes.
|
||||
Inside the `<login-footer/>` or `<login-header/>` tags we can put anything we want, as long as we wrap it inside an `<ng-template/>` tag. We can also source in custom or 3rd party components.
|
||||
|
||||
### Bonus objective: Add a custom logo and background to the login screen
|
||||
|
||||
Are you up for a challenge? Explore the [Login component](../core/login.component.md)
|
||||
docs to find out how you can change the logo and background image!
|
||||
|
||||
# Next steps
|
||||
|
||||
We have a number of tutorials for you to explore. Here are a few suggested ones to try next:
|
||||
|
||||
- [Basic theming](basic-theming.md)
|
||||
- [Create a new page](new-view.md)
|
||||
- [Adding a new component](new-component.md)
|
||||
|
||||
Reference in New Issue
Block a user