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

[ADF-2451] Reviewed component docs (#3072)

Browse Source
This commit is contained in:
Andy Stark
2018-03-13 15:47:59 +00:00
committed by Eugenio Romano
parent d563dbbd77
commit 6c56d164ec
9 changed files with 185 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
docs/authentication.service.md
View File

@@ -1,14 +1,78 @@
---
Added: v2.0.0
Status: Active
Last reviewed: 2018-03-13
---
# Authentication Service
Provides authentication for use with the Login component.
Provides authentication to ACS and APS.
## Basic Usage
## Methods
**app.component.ts**
- `isLoggedIn(): boolean`
Checks if the user logged in.
- `login(username: string, password: string, rememberMe: boolean = false): Observable<{ type: string; ticket: any; }>`
Logs the user in.
- `username` - Username for the login
- `password` - Password for the login
- `rememberMe` - Stores the user's login details if true
- `isRememberMeSet(): boolean`
Checks whether the "remember me" cookie was set or not.
- `logout(): any`
Logs the user out.
- `removeTicket()`
Removes the login ticket from Storage.
- `getTicketEcm(): string`
Gets the ECM ticket stored in the Storage.
- `getTicketBpm(): string`
Gets the BPM ticket stored in the Storage.
- `getTicketEcmBase64(): string`
Gets the BPM ticket from the Storage in Base 64 format.
- `saveTickets()`
Saves the ECM and BPM ticket in the Storage.
- `saveTicketEcm()`
Saves the ECM ticket in the Storage.
- `saveTicketBpm()`
Saves the BPM ticket in the Storage.
- `saveTicketAuth()`
Saves the AUTH ticket in the Storage.
- `isEcmLoggedIn(): boolean`
Checks if the user is logged in on an ECM provider.
- `isBpmLoggedIn(): boolean`
Checks if the user is logged in on a BPM provider.
- `getEcmUsername(): string`
Gets the ECM username.
- `getBpmUsername(): string`
Gets the BPM username
- `setRedirectUrl(url: RedirectionModel)`
Sets the URL to redirect to after login.
- `url` - URL to redirect to
- `getRedirectUrl(provider: string): string`
Gets the URL to redirect to after login.
- `provider` - Service provider. Can be "ECM", "BPM" or "ALL".
- `handleError(error: any): Observable<any>`
Prints an error message in the console browser
- `error` - Error message
## Details
### Usage example
```ts
import { AuthenticationService } from '@alfresco/adf-core';
@@ -28,13 +92,6 @@ export class AppComponent {
}
```
### Events
## See also
| Name | Description |
| ---- | ----------- |
| onLogin | Raised when user logs in |
| onLogout | Raised when user logs out |
## Details
The authentication service is used inside the [login component](login.component.md) and is possible to find there an example of how to use it.
- [Login component](login.component.md)

2
docs/content-node-dialog.service.md
View File

@@ -1,7 +1,9 @@
---
Added: v2.1.0
Status: Active
Last reviewed: 2018-03-13
---
# Content Node Dialog service
Displays and manages dialogs for selecting content to open, copy or upload.

16
docs/search-control.component.md
View File

@@ -1,6 +1,7 @@
---
Added: v2.0.0
Status: Active
Last reviewed: 2018-03-13
---
# Search control component
@@ -28,7 +29,7 @@ Displays a input text which shows find-as-you-type suggestions.
| autocomplete | `boolean` | `false` | Toggles auto-completion of the search input field. |
| liveSearchEnabled | `boolean` | `true` | Toggles "find-as-you-type" suggestions for possible matches. |
| liveSearchMaxResults | `number` | `5` | Maximum number of results to show in the live search. |
| customQueryBody | `QueryBody` | | |
| customQueryBody | `QueryBody` | | Deprecated in v2.1.0. |
### Events
@@ -40,6 +41,8 @@ Displays a input text which shows find-as-you-type suggestions.
## Details
Below is an example of a component that uses the search control. In this example the search term is simply logged to the console. However, the component could instead emit an event to be consumed upstream,or it could trigger a change inside a search results component embedded inside the same component.
```html
<adf-search-control
[highlight]="true"
@@ -48,12 +51,9 @@ Displays a input text which shows find-as-you-type suggestions.
</adf-search-control>
```
Example of a component that uses the search control. In this example the search term is simply logged to the console
but instead the component could emit an event to be consumed upstream, or it could trigger a change inside a search
results component embedded inside the same component.
### Customizable template for no result
## Customizable template for no result
It is possible to customize with your own template what to show when no result are found for the search.
You can show your own custom template when no results are found for the search:
```html
<adf-search-control [highlight]="true"
@@ -65,4 +65,6 @@ It is possible to customize with your own template what to show when no result a
</adf-empty-search-result>
</adf-search-control>
```
All you need to add is the `adf-empty-search-result` tag in the `adf-search-control` and then put inside the template you want to render when no results are found.
Place the `adf-empty-search-result` tag inside the `adf-search-control` and then within it, put
whatever content you want to show for an "empty" result.

8
docs/sites-dropdown.component.md
View File

@@ -1,7 +1,9 @@
---
Added: v2.0.0
Status: Active
Last reviewed: 2018-03-13
---
# Sites Dropdown component
Displays a dropdown menu to show and interact with the sites of the current user.
@@ -23,11 +25,11 @@ Displays a dropdown menu to show and interact with the sites of the current user
| hideMyFiles | boolean | false | Hide the "My Files" option added to the list by default |
| siteList | [SitePaging](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/SitePaging.md) | null | A custom list of sites to be displayed by the dropdown. If no value is given, the sites of the current user are displayed by default. A list of objects only with properties 'title' and 'guid' is enough to be able to display the dropdown. |
| placeholder | string | 'DROPDOWN.PLACEHOLDER_LABEL' | The placeholder text/the key from translation files for the placeholder text to be shown by default |
| value | string | null | Id of the select site |
| relations | string | null | This parameter will allow to perform sites query filtering the results.It could have two possible values: **members** and **containers**. When **members** is used the site list will be filtered with only the sites where the user is a member of. |
| value | string | null | Id of the select site |
| relations | string | null | A custom list of sites to be displayed by the dropdown. If no value is given, the sites of the current user are displayed by default. A list of objects only with properties 'title' and 'guid' is enough to be able to display the dropdown. |
### Events
| Name | Returned Type | Description |
| ---- | ------------- | ----------- |
| change | [SiteModel](site.model.md) | emitted when user selects a site. When default option is selected an empty model is emitted |
| change | [SiteModel](site.model.md) | Emitted when user selects a site. When default option is selected an empty model is emitted |

26
docs/start-process.component.md
View File

@@ -1,7 +1,9 @@
---
Added: v2.0.0
Status: Active
Last reviewed: 2018-03-13
---
# Start Process component
Starts a process.
@@ -35,7 +37,9 @@ Starts a process.
| cancel | `EventEmitter<ProcessInstance>` | Emitted when the process is canceled |
| error | `EventEmitter<ProcessInstance>` | Emitted when the start process operation fails |
### Start a process with a default name and pre-selected process definition name
## Details
### Starting a process with a default name and pre-selected process definition name
```html
<adf-start-process
@@ -45,9 +49,11 @@ Starts a process.
</adf-start-process>
```
If your app has more than one process definition, with the property processDefinitionName you can select as dropdown default value your PROCESS_DEFINITION_NAME. The name will be the PROCESS_NAME.
You can use the `processDefinitionName` property to select which process will be selected by
default on the dropdown (when there is more than one process to choose from). Use the `name`
property to set the name shown on the dropdown item.
### Start a process not included in an app
### Starting a process not included in an app
```html
<adf-start-process
@@ -55,12 +61,12 @@ If your app has more than one process definition, with the property processDefin
</adf-start-process>
```
With the property processDefinitionName you can select as dropdown default value your PROCESS_DEFINITION_NAME.
Use `processDefinitionName` to set the dropdown item as in the example above.
### Custom data example
Here is an example of how to pass in form field values to initialize the start form that has been
defined for the process:
The following example shows how to pass in form field values to initialize the
start form for the process:
```ts
const formValues: FormValues = {
@@ -82,9 +88,11 @@ const formValues: FormValues = {
### Attaching a File to the start form of the process
After the repository is created in APS, you can it in the Alfresco Repositories list.
If the ID is set to 1 then all default values are fine.
However, if it is set to something else, for example, _1002_ and the name is _alfresco_, you must set the property `alfrescoRepositoryName` in your `app.config.json` file to _alfresco-1002_:
You can see a repository in the Alfresco Repositories list once it is created in APS.
If the repository is set up with an ID value of anything other than 1 then you will need
to declare it in `app.config.json`. For example, if the repository's ID is 1002 and its
name is _alfresco_ then you would set the `alfrescoRepositoryName` property in`app.config.json`
to _alfresco-1002_ as follows:
```json
{

44
docs/task-attachment-list.component.md
View File

@@ -1,6 +1,7 @@
---
Added: v2.0.0
Status: Active
Last reviewed: 2018-03-13
---
# Task Attachment List Component
@@ -17,13 +18,33 @@ Displays attached documents on a specified task.
</adf-task-attachment-list>
```
If the List is empty, a default no content template is displayed.
### Properties
| Name | Type | Default value | Description |
| ---- | ---- | ------------- | ----------- |
| taskId | `string` | | (**required**) The ID of the task to display. |
| disabled | `boolean` | `false` | Disable/Enable read only mode for attachement list. |
### Events
| Name | Type | Description |
| ---- | ---- | ----------- |
| attachmentClick | `EventEmitter<{}>` | Emitted when the attachment is double-clicked or a view option is selected from the context menu by the user from within the component. Returns a Blob representing the clicked object. |
| success | `EventEmitter<{}>` | Emitted when the attachment list has fetched all the attachments. Returns a list of attachments. |
| error | `EventEmitter<any>` | Emitted when an error occurs while fetching the attachments. |
## Details
If the List is empty, a default "no content" template is displayed.
![default-no-content-template-sample](docassets/images/default-no-content-template.png)
### How to Add Drag and Drop Functionality
If we want user to be able to upload attachments for empty lists, We can wrap our component with upload drag area component. In that case, We should also pass a custom _no content template_ as shown below with our component urging the user to drag files to upload whenever the list is empty.
You can wrap the component with an [Upload Drag Area component](upload-drag-area.component.md)
to enable the user to upload attachments for empty lists. When you do this, you can also pass
a custom _no content template_ as shown below. The component invites the user to drag files to
upload whenever the list is empty.
```html
<adf-upload-drag-area
@@ -42,10 +63,12 @@ If we want user to be able to upload attachments for empty lists, We can wrap ou
</adf-upload-drag-area>
```
```ts
import { UploadService } from '@alfresco/adf-core';
import { TaskUploadService } from '@alfresco/adf-process-services';
```
Make sure to override the UploadService with the TaskUploadService
Make sure you override the `UploadService` with the `TaskUploadService`
```ts
@Component({
@@ -64,18 +87,3 @@ export class MyCustomTaskAttachmentComponent {
If the List is empty, the custom no-content template we passed is displayed.
![custom-no-content-drag-drop-template-sample](docassets/images/custom-no-content-drag-drop-template.png)
### Properties
| Name | Type | Default value | Description |
| ---- | ---- | ------------- | ----------- |
| taskId | `string` | | (**required**) The ID of the task to display. |
| disabled | `boolean` | `false` | Disable/Enable read only mode for attachement list. |
### Events
| Name | Type | Description |
| ---- | ---- | ----------- |
| attachmentClick | `EventEmitter<{}>` | Emitted when the attachment is double-clicked or a view option is selected from the context menu by the user from within the component. Returns a Blob representing the clicked object. |
| success | `EventEmitter<{}>` | Emitted when the attachment list has fetched all the attachments. Returns a list of attachments. |
| error | `EventEmitter<any>` | Emitted when an error occurs while fetching the attachments. |

38
docs/task-details.component.md
View File

@@ -1,10 +1,12 @@
---
Added: v2.0.0
Status: Active
Last reviewed: 2018-03-13
---
# Task Details component
Shows the details of the task id passed in input
Shows the details of the task ID passed in as input.
## Basic Usage
@@ -37,29 +39,25 @@ Shows the details of the task id passed in input
| Name | Type | Description |
| ---- | ---- | ----------- |
| formSaved | `EventEmitter<any>` | Emitted when the form is submitted with the `Save` or custom outcomes. |
| formCompleted | `EventEmitter<any>` | Emitted when the form is submitted with the `Complete` outcome. |
| formContentClicked | `EventEmitter<any>` | Emitted when the form field content is clicked. |
| formLoaded | `EventEmitter<any>` | Emitted when the form is loaded or reloaded. |
| taskCreated | `EventEmitter<TaskDetailsModel>` | Emitted when a checklist task is created. |
| taskDeleted | `EventEmitter<string>` | Emitted when a checklist task is deleted. |
| error | `EventEmitter<any>` | Emitted when an error occurs. |
| formSaved | `EventEmitter<any>` | Emitted when the form is submitted with the `Save` or custom outcomes. |
| formCompleted | `EventEmitter<any>` | Emitted when the form is submitted with the `Complete` outcome. |
| formContentClicked | `EventEmitter<any>` | Emitted when the form field content is clicked. |
| formLoaded | `EventEmitter<any>` | Emitted when the form is loaded or reloaded. |
| taskCreated | `EventEmitter<TaskDetailsModel>` | Emitted when a checklist task is created. |
| taskDeleted | `EventEmitter<string>` | Emitted when a checklist task is deleted. |
| error | `EventEmitter<any>` | Emitted when an error occurs. |
| executeOutcome | `EventEmitter<any>` | Emitted when any outcome is executed. Default behaviour can be prevented via `event.preventDefault()`. |
| assignTask | `EventEmitter<void>` | Emitted when a task is assigned. |
| claimedTask | `EventEmitter<string>` | Emitted when a task is claimed. |
| unClaimedTask | `EventEmitter<string>` | Emitted when a task is unclaimed. |
| assignTask | `EventEmitter<void>` | Emitted when a task is assigned. |
| claimedTask | `EventEmitter<string>` | Emitted when a task is claimed. |
| unClaimedTask | `EventEmitter<string>` | Emitted when a task is unclaimed. |
## Details
### Custom 'empty Activiti Task Details' template
### Custom 'empty Task Details' template
By default the Activiti Task Details provides the following message for the empty task details:
```html
No Tasks
```
This can be changed by adding the following custom html template:
By default the Task Details component shows a simple "No Tasks" message when there are
no details. You can change this by adding the a custom HTML template as in the following
example:
```html
<adf-task-details [taskId]="taskId">
@@ -72,4 +70,4 @@ This can be changed by adding the following custom html template:
</adf-task-details>
```
Note that can put any HTML content as part of the template, including other Angular components.
Note that you can use any HTML content in the template, including other Angular components.

10
lib/content-services/site-dropdown/sites-dropdown.component.ts
View File

@@ -45,14 +45,20 @@ export class DropdownSitesComponent implements OnInit {
@Input()
siteList: SitePaging = null;
/** Id of the select site */
/** Id of the selected site */
@Input()
value: string = null;
/** Text or a translation key to act as a placeholder. */
/** Text or a translation key to act as a placeholder. Default value is the
* key "DROPDOWN.PLACEHOLDER_LABEL".
*/
@Input()
placeholder: string = 'DROPDOWN.PLACEHOLDER_LABEL';
/** Filter for the results of the sites query. Possible values are
* "members" and "containers". When "members" is used, the site list
* will be restricted to the sites that the user is a member of.
*/
@Input()
relations: string;

58
lib/core/services/authentication.service.ts
View File

@@ -47,16 +47,17 @@ export class AuthenticationService {
}
/**
* The method return true if the user is logged in
* Checks if the user logged in.
*/
isLoggedIn(): boolean {
return !!this.alfrescoApi.getInstance().isLoggedIn();
}
/**
* Method to delegate to POST login
* @param username
* @param password
* Logs the user in.
* @param username Username for the login
* @param password Password for the login
* @param rememberMe Stores the user's login details if true
*/
login(username: string, password: string, rememberMe: boolean = false): Observable<{ type: string, ticket: any }> {
this.removeTicket();
@@ -74,8 +75,8 @@ export class AuthenticationService {
}
/**
* The method save the "remember me" cookie as a long life cookie or a session cookie
* depending on the given paramter
* Saves the "remember me" cookie as either a long-life cookie or a session cookie.
* @param rememberMe Enables a long-life cookie
*/
private saveRememberMeCookie(rememberMe: boolean): void {
let expiration = null;
@@ -90,8 +91,7 @@ export class AuthenticationService {
}
/**
* The method retrieve whether the "remember me" cookie was set or not
*
* Checks whether the "remember me" cookie was set or not.
*/
isRememberMeSet(): boolean {
return (this.cookie.getItem(REMEMBER_ME_COOKIE_KEY) === null) ? false : true;
@@ -107,8 +107,7 @@ export class AuthenticationService {
}
/**
* The method remove the ticket from the Storage
*
* Logs the user out.
*/
logout() {
return Observable.fromPromise(this.callApiLogout())
@@ -130,7 +129,7 @@ export class AuthenticationService {
}
/**
* Remove the login ticket from Storage
* Removes the login ticket from Storage.
*/
removeTicket(): void {
this.storage.removeItem('ticket-ECM');
@@ -139,19 +138,20 @@ export class AuthenticationService {
}
/**
* The method return the ECM ticket stored in the Storage
* Gets the ECM ticket stored in the Storage.
*/
getTicketEcm(): string | null {
return this.storage.getItem('ticket-ECM');
}
/**
* The method return the BPM ticket stored in the Storage
* Gets the BPM ticket stored in the Storage.
*/
getTicketBpm(): string | null {
return this.storage.getItem('ticket-BPM');
}
/** Gets the BPM ticket from the Storage in Base 64 format. */
getTicketEcmBase64(): string | null {
let ticket = this.storage.getItem('ticket-ECM');
if (ticket) {
@@ -161,7 +161,7 @@ export class AuthenticationService {
}
/**
* The method save the ECM and BPM ticket in the Storage
* Saves the ECM and BPM ticket in the Storage.
*/
saveTickets(): void {
this.saveTicketEcm();
@@ -170,7 +170,7 @@ export class AuthenticationService {
}
/**
* The method save the ECM ticket in the Storage
* Saves the ECM ticket in the Storage.
*/
saveTicketEcm(): void {
if (this.alfrescoApi.getInstance() && this.alfrescoApi.getInstance().getTicketEcm()) {
@@ -179,7 +179,7 @@ export class AuthenticationService {
}
/**
* The method save the BPM ticket in the Storage
* Saves the BPM ticket in the Storage.
*/
saveTicketBpm(): void {
if (this.alfrescoApi.getInstance() && this.alfrescoApi.getInstance().getTicketBpm()) {
@@ -188,7 +188,7 @@ export class AuthenticationService {
}
/**
* The method save the AUTH ticket in the Storage
* Saves the AUTH ticket in the Storage.
*/
saveTicketAuth(): void {
if (this.alfrescoApi.getInstance() && (<any> this.alfrescoApi.getInstance()).getTicketAuth()) {
@@ -197,8 +197,7 @@ export class AuthenticationService {
}
/**
* The method return true if user is logged in on ecm provider
*
* Checks if the user is logged in on an ECM provider.
*/
isEcmLoggedIn(): boolean {
if (this.cookie.isEnabled() && !this.isRememberMeSet()) {
@@ -208,8 +207,7 @@ export class AuthenticationService {
}
/**
* The method return true if user is logged in on bpm provider
*
* Checks if the user is logged in on a BPM provider.
*/
isBpmLoggedIn(): boolean {
if (this.cookie.isEnabled() && !this.isRememberMeSet()) {
@@ -219,9 +217,7 @@ export class AuthenticationService {
}
/**
* Get the ECM username
*
*
* Gets the ECM username.
* @memberof AuthenticationService
*/
getEcmUsername(): string {
@@ -229,19 +225,23 @@ export class AuthenticationService {
}
/**
* Get the BPM username
*
*
* Gets the BPM username
* @memberof AuthenticationService
*/
getBpmUsername(): string {
return this.alfrescoApi.getInstance().bpmAuth.username;
}
/** Sets the URL to redirect to after login.
* @param url URL to redirect to
*/
setRedirectUrl(url: RedirectionModel) {
this.redirectUrl = url;
}
/** Gets the URL to redirect to after login.
* @param provider Service provider. Can be "ECM", "BPM" or "ALL".
*/
getRedirectUrl(provider: string): string {
return this.hasValidRedirection(provider) ? this.redirectUrl.url : null;
}
@@ -255,8 +255,8 @@ export class AuthenticationService {
}
/**
* The method write the error in the console browser
* @param error
* Prints an error message in the console browser
* @param error Error message
*/
handleError(error: any): Observable<any> {
this.logService.error('Error when logging in', error);