mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2025-07-24 17:32:15 +00:00
[ADF-2451] Reviewed component docs (#3101)
* [ADF-2451] Reviewed Login component docs * [ADF-2451] Reviewed component docs
This commit is contained in:
Andy Stark
committed by
Eugenio Romano
Eugenio Romano
parent
347b2bb5e8
commit
436a911e0d
@@ -1,7 +1,9 @@
|
||||
---
|
||||
Added: v2.0.0
|
||||
Status: Active
|
||||
Last reviewed: 2018-03-20
|
||||
---
|
||||
|
||||
# Form Field model
|
||||
|
||||
Contains the value and metadata for a field of a Form component.
|
||||
|
||||
@@ -1,7 +1,9 @@
|
||||
---
|
||||
Added: v2.0.0
|
||||
Status: Active
|
||||
Last reviewed: 2018-03-19
|
||||
---
|
||||
|
||||
# Login component
|
||||
|
||||
Authenticates to Alfresco Content Services and Alfresco Process Services.
|
||||
@@ -18,13 +20,14 @@ Authenticates to Alfresco Content Services and Alfresco Process Services.
|
||||
- [Details](#details)
|
||||
|
||||
- [Handling events](#handling-events)
|
||||
- [Change footer content](#change-footer-content)
|
||||
- [Change header content](#change-header-content)
|
||||
- [Extra content](#extra-content)
|
||||
- [Changing content](#changing-content)
|
||||
- [Custom logo and background](#custom-logo-and-background)
|
||||
- [Customize Validation rules](#customize-validation-rules)
|
||||
- [Customizing validation rules](#customizing-validation-rules)
|
||||
- [Call an external identity provider to fetch the auth token](#call-an-external-identity-provider-to-fetch-the-auth-token)
|
||||
- [Controlling form submit execution behaviour](#controlling-form-submit-execution-behaviour)
|
||||
|
||||
- [See Also](#see-also)
|
||||
|
||||
## Basic usage
|
||||
|
||||
```html
|
||||
@@ -38,17 +41,17 @@ Authenticates to Alfresco Content Services and Alfresco Process Services.
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
| ---- | ---- | ------------- | ----------- |
|
||||
| showRememberMe | `boolean` | `true` | Should the `Remember me` checkbox be shown? |
|
||||
| showLoginActions | `boolean` | `true` | Should the extra actions (`Need Help`, `Register`, etc) be shown? |
|
||||
| needHelpLink | `string` | `''` | Sets the URL of the NEED HELP link in the footer. |
|
||||
| registerLink | `string` | `''` | Sets the URL of the REGISTER link in the footer. |
|
||||
| logoImageUrl | `string` | `'./assets/images/alfresco-logo.svg'` | Path to a custom logo image. |
|
||||
| backgroundImageUrl | `string` | `'./assets/images/background.svg'` | Path to a custom background image. |
|
||||
| copyrightText | `string` | `'\u00A9 2016 Alfresco Software, Inc. All Rights Reserved.'` | The copyright text below the login box. |
|
||||
| showRememberMe | `boolean` | `true` | Should the `Remember me` checkbox be shown? |
|
||||
| showLoginActions | `boolean` | `true` | Should the extra actions (`Need Help`, `Register`, etc) be shown? |
|
||||
| needHelpLink | `string` | `''` | Sets the URL of the NEED HELP link in the footer. |
|
||||
| registerLink | `string` | `''` | Sets the URL of the REGISTER link in the footer. |
|
||||
| logoImageUrl | `string` | `'./assets/images/alfresco-logo.svg'` | Path to a custom logo image. |
|
||||
| backgroundImageUrl | `string` | `'./assets/images/background.svg'` | Path to a custom background image. |
|
||||
| copyrightText | `string` | `'\u00A9 2016 Alfresco Software, Inc. All Rights Reserved.'` | The copyright text below the login box. |
|
||||
| providers | `string` | | Possible valid values are ECM, BPM or ALL. By default, this component will log in only to ECM. If you want to log in in both systems then use ALL. There is also a way to call your Auth token API using the string "OAUTH" (supported only for BPM) |
|
||||
| fieldsValidation | `any` | | Custom validation rules for the login form. |
|
||||
| disableCsrf | `boolean` | | Prevents the CSRF Token from being submitted. Only valid for Alfresco Process Services. |
|
||||
| successRoute | `string` | `null` | Route to redirect to on successful login. |
|
||||
| fieldsValidation | `any` | | Custom validation rules for the login form. |
|
||||
| disableCsrf | `boolean` | | Prevents the CSRF Token from being submitted. Only valid for Alfresco Process Services. |
|
||||
| successRoute | `string` | `null` | Route to redirect to on successful login. |
|
||||
|
||||
### Events
|
||||
|
||||
@@ -87,11 +90,10 @@ export class AppComponent {
|
||||
}
|
||||
```
|
||||
|
||||
### Change footer content
|
||||
### Changing content
|
||||
|
||||
|
||||
|
||||
You can replace the entire content in the footer of the login component with your custom content.
|
||||
You can replace the content of the header and footer of the Login component with
|
||||
your own custom content, as shown in the examples below:
|
||||
|
||||
```html
|
||||
<adf-login ...>
|
||||
@@ -99,11 +101,7 @@ You can replace the entire content in the footer of the login component with you
|
||||
</adf-login>`
|
||||
```
|
||||
|
||||
### Change header content
|
||||
|
||||
|
||||
|
||||
You can replace the entire content in the header of the login component with your custom content.
|
||||
|
||||
|
||||
```html
|
||||
<adf-login ...>
|
||||
@@ -111,10 +109,10 @@ You can replace the entire content in the header of the login component with you
|
||||
</adf-login>`
|
||||
```
|
||||
|
||||
### Extra content
|
||||
|
||||
|
||||
You can put additional html content between `alfresco-login` tags to get it rendered as part of the login dialog.
|
||||
This becomes handy in case you need to extend it with custom input fields handled by your application or parent component:
|
||||
Also, any content that you put inside the <adf-login> tags will be rendered as part
|
||||
of the Login dialog:
|
||||
|
||||
```html
|
||||
<adf-login ...>
|
||||
@@ -124,13 +122,15 @@ This becomes handy in case you need to extend it with custom input fields handle
|
||||
</adf-login>
|
||||
```
|
||||
|
||||
Here's an example of custom content:
|
||||
This is useful if you need to extend the functionality of the dialog
|
||||
with custom input fields handled by your application or parent component:
|
||||
|
||||
|
||||
|
||||
### Custom logo and background
|
||||
|
||||
It is possible changing logo and background images to custom values.
|
||||
You can change the logo and background images using the `backgroundImageUrl` and
|
||||
`logoImageUrl` properties:
|
||||
|
||||
```html
|
||||
<adf-login
|
||||
@@ -139,11 +139,9 @@ It is possible changing logo and background images to custom values.
|
||||
</adf-login>
|
||||
```
|
||||
|
||||
Should give you something like the following:
|
||||
|
||||
|
||||
|
||||
Alternatively you can bind to your component properties and provide values dynamically if needed:
|
||||
You can also bind to your component properties and provide values dynamically if you need to:
|
||||
|
||||
```html
|
||||
<adf-login
|
||||
@@ -152,10 +150,10 @@ Alternatively you can bind to your component properties and provide values dynam
|
||||
</adf-login>
|
||||
```
|
||||
|
||||
### Customize Validation rules
|
||||
### Customizing validation rules
|
||||
|
||||
If needed it is possible to customise the validation rules of the login
|
||||
form. You can add/modify the default rules of the login form.
|
||||
You can add to or modify the default validation rules of the login form if you
|
||||
need your own custom validation:
|
||||
|
||||
**MyCustomLogin.component.html**
|
||||
|
||||
@@ -192,7 +190,7 @@ export class MyCustomLogin {
|
||||
|
||||
### Call an external identity provider to fetch the auth token
|
||||
|
||||
If needed it is possible to call an external provider to identify the user.
|
||||
You can access an external provider to get an auth token for a user:
|
||||
|
||||
**app.config.json**
|
||||
|
||||
@@ -208,6 +206,7 @@ If needed it is possible to call an external provider to identify the user.
|
||||
```
|
||||
|
||||
**MyCustomLogin.component.html**
|
||||
|
||||
```html
|
||||
<adf-login
|
||||
[providers]="'OAUTH'"
|
||||
@@ -232,14 +231,15 @@ export class MyCustomLogin {
|
||||
|
||||
### Controlling form submit execution behaviour
|
||||
|
||||
If absolutely needed it is possible taking full control over form
|
||||
submit execution by means of `executeSubmit` event.
|
||||
This event is fired on form submit.
|
||||
The standard form submission system is suitable for most tasks but you can
|
||||
take full control of submission if you need to. Use the `executeSubmit` event
|
||||
to modify the submission process with your own code just after the form is
|
||||
submitted.
|
||||
|
||||
You can prevent default behaviour by calling `event.preventDefault()`.
|
||||
This allows for example having custom form validation scenarios and/or additional validation summary presentation.
|
||||
|
||||
Alternatively you may want just running additional code without suppressing default one.
|
||||
If you want to replace the submission process completely (rather than just extend
|
||||
it), you can use `event.preventDefault()` in the handler to avoid the default
|
||||
behavior. You could use this, for example, to customize the validation heavily or
|
||||
to present a summary of validation before submitting the form.
|
||||
|
||||
**MyCustomLogin.component.html**
|
||||
|
||||
@@ -269,8 +269,8 @@ export class MyCustomLogin {
|
||||
}
|
||||
```
|
||||
|
||||
**Please note that if `event.preventDefault()` is not called then default behaviour
|
||||
will also be executed after your custom code.**
|
||||
Note that if you do not call `event.preventDefault()` then the default behaviour
|
||||
will execute _after_ your custom code has completed.
|
||||
|
||||
## See Also
|
||||
|
||||
|
||||
@@ -1,7 +1,9 @@
|
||||
---
|
||||
Added: v2.0.0
|
||||
Status: Active
|
||||
Last reviewed: 2018-03-20
|
||||
---
|
||||
|
||||
# Pagination Component
|
||||
|
||||
Adds pagination to the component it is used with.
|
||||
@@ -22,15 +24,6 @@ Adds pagination to the component it is used with.
|
||||
</adf-pagination>
|
||||
```
|
||||
|
||||
## Integrating with Document List
|
||||
|
||||
```html
|
||||
<adf-document-list #documentList ...></adf-document-list>
|
||||
|
||||
<adf-pagination [target]="documentList" ...>
|
||||
</adf-pagination>
|
||||
```
|
||||
|
||||
### Properties
|
||||
|
||||
| Name | Type | Default value | Description |
|
||||
@@ -43,26 +36,42 @@ Adds pagination to the component it is used with.
|
||||
|
||||
| Name | Type | Description |
|
||||
| ---- | ---- | ----------- |
|
||||
| change | `EventEmitter<PaginationQueryParams>` | Emitted when paginaton changes in any way. |
|
||||
| changePageNumber | `EventEmitter<Pagination>` | Emitted when the page number changes. |
|
||||
| changePageSize | `EventEmitter<Pagination>` | Emitted when the page size changes. |
|
||||
| nextPage | `EventEmitter<Pagination>` | Emitted when the next page is requested. |
|
||||
| prevPage | `EventEmitter<Pagination>` | Emitted when the previous page is requested. |
|
||||
| change | `EventEmitter<PaginationQueryParams>` | Emitted when pagination changes in any way. |
|
||||
| changePageNumber | `EventEmitter<Pagination>` | Emitted when the page number changes. |
|
||||
| changePageSize | `EventEmitter<Pagination>` | Emitted when the page size changes. |
|
||||
| nextPage | `EventEmitter<Pagination>` | Emitted when the next page is requested. |
|
||||
| prevPage | `EventEmitter<Pagination>` | Emitted when the previous page is requested. |
|
||||
|
||||
## Details
|
||||
|
||||
The pagination object is a generic component to paginate component. The Alfresco API are paginated and return a Pagination object. You can use the pagination object to feed the pagination component and then listen to the event which returns the current pagination and query again the API with the options chosen by the user.
|
||||
You can use the Pagination component to add pagination features to other components. The Alfresco
|
||||
APIs make use of pagination to reduce the amount of data transferred in a single call. The start offset
|
||||
and number of items in the page are passed during the call. The items of interest will be
|
||||
returned along with a Pagination object. You can use this object to set up the pagination component
|
||||
and then subscribe to one of the page change events. This will return updated pagination data that you
|
||||
can pass to a subsequent API call.
|
||||
|
||||
Each event helps to detect the certain action that user have made using the component.
|
||||
Each event corresponds to a particular action from the user. For the `change` event, a
|
||||
[PaginationQueryParams](https://github.com/Alfresco/alfresco-ng2-components/blob/development/ng2-components/ng2-alfresco-core/src/components/pagination/pagination-query-params.interface.ts) object is returned. This contains the query
|
||||
parameters supported by the REST API, `skipCount` and `maxItems`.
|
||||
|
||||
For `change` event, a [PaginationQueryParams](https://github.com/Alfresco/alfresco-ng2-components/blob/development/ng2-components/ng2-alfresco-core/src/components/pagination/pagination-query-params.interface.ts) (including the query parameters supported by the REST API, `skipCount` and `maxItems`) is returned.
|
||||
For all events other than `change`, a new Pagination object is returned as in the following example. The
|
||||
new object contains updated properties that you can use to fetch the next page of information.
|
||||
|
||||
For all events other than `change`, a new Pagination object is returned as in the following example, with updated properties to be used to query further.
|
||||
### Integrating with the Document List component
|
||||
|
||||
```html
|
||||
<adf-document-list #documentList ...></adf-document-list>
|
||||
|
||||
<adf-pagination [target]="documentList" ...>
|
||||
</adf-pagination>
|
||||
```
|
||||
|
||||
### Custom pagination
|
||||
|
||||
The component also provides light integration with external implementations of the pagination.
|
||||
Any component can implement the `PaginatedComponent` and be used as a value for the `target` property.
|
||||
The component also makes it easy to integrate your own implementation of pagination.
|
||||
You can supply any component that implements the `PaginatedComponent` interface as the value of the
|
||||
`target` property.
|
||||
|
||||
```js
|
||||
export interface PaginatedComponent {
|
||||
@@ -73,8 +82,9 @@ export interface PaginatedComponent {
|
||||
}
|
||||
```
|
||||
|
||||
Your component needs to provide a `pagination` subject to allow Pagination component to reflect to changes.
|
||||
Every time user interacts with the Pagination, it will call the `updatePagination` method and pass the parameters.
|
||||
Your component must provide a `pagination` subject to allow the Pagination component to respond to changes.
|
||||
Every time user interacts with the Pagination component, it will call the `updatePagination` method
|
||||
and pass the updated parameters.
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -1,7 +1,9 @@
|
||||
---
|
||||
Added: v2.0.0
|
||||
Status: Active
|
||||
Last reviewed: 2018-03-20
|
||||
---
|
||||
|
||||
# Process Service
|
||||
|
||||
Manages Process Instances, Process Variables, and Process Audit Log.
|
||||
|
||||
@@ -68,7 +68,7 @@ export class PaginationComponent implements OnInit, OnDestroy {
|
||||
@Input()
|
||||
pagination: Pagination;
|
||||
|
||||
/** Emitted when paginaton changes in any way. */
|
||||
/** Emitted when pagination changes in any way. */
|
||||
@Output()
|
||||
change: EventEmitter<PaginationQueryParams> = new EventEmitter<PaginationQueryParams>();
|
||||
|
||||
|
||||
Reference in New Issue
Block a user