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-1549] Initial files for new doc format (#2342)

Browse Source
This commit is contained in:
Andy Stark
2017-09-18 10:47:16 +01:00
committed by Eugenio Romano
parent 43277148b2
commit 7157d60ed0
42 changed files with 2815 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
docs/breadcrumb.component.md Normal file
View File

@@ -0,0 +1,41 @@
# Breadcrumb Component
Indicates the current position within a navigation hierarchy.
![Breadcrumb](../docassets/images/breadcrumb.png)
<!-- markdown-toc start - Don't edit this section. npm run toc to generate it-->
<!-- toc -->
- [Basic Usage](#basic-usage)
* [Properties](#properties)
* [Events](#events)
<!-- tocstop -->
<!-- markdown-toc end -->
## Basic Usage
```html
<adf-breadcrumb
[target]="documentList"
[folderNode]="documentList.folderNode">
</adf-breadcrumb>
```
### Properties
| Name | Type | Description |
| --- | --- | --- |
| target | DocumentListComponent | (optional) DocumentList component to operate with. Upon clicks will instruct the given component to update. |
| folderNode | [MinimalNodeEntryEntity](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/NodeMinimalEntry.md) | Active node, builds UI based on `folderNode.path.elements` collection. |
| root | string | (optional) Name of the root element of the breadcrumb. You can use this property to rename "Company Home" to "Personal Files" for example. You can use i18n resource key for the property value. |
| rootId | string | (optional) The id of the root element. You can use this property to set a custom element the breadcrumb should start with. |
### Events
| Name | Returned Type | Description |
| --- | --- | --- |
| navigate | [PathElementEntity](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-core-rest-api/docs/PathElementEntity.md) | emitted when user clicks on a breadcrumb |

141
docs/data-column.component.md Normal file
View File

@@ -0,0 +1,141 @@
# DataColumn Component
Defines column properties for DataTable, Tasklist, Document List and other components.
<!-- markdown-toc start - Don't edit this section. npm run toc to generate it-->
<!-- toc -->
- [Basic Usage](#basic-usage)
* [Properties](#properties)
- [Details](#details)
* [Automatic column header translation](#automatic-column-header-translation)
* [Custom tooltips](#custom-tooltips)
* [Column Templates](#column-templates)
<!-- tocstop -->
<!-- markdown-toc end -->
## Basic Usage
```html
<adf-datatable [data]="data">
<data-columns>
<data-column key="icon" type="image" [sortable]="false"></data-column>
<data-column key="id" title="Id"></data-column>
<data-column key="createdOn" title="Created"></data-column>
<data-column key="name" title="Name" class="full-width name-column"></data-column>
<data-column key="createdBy.name" title="Created By"></data-column>
</data-columns>
</adf-datatable>
```
### Properties
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| key | string | | Data source key, can be either column/property key like `title` or property path like `createdBy.name` |
| type | string | text | Value type for the column. Possible settings are 'text', 'image', 'date', 'fileSize' and 'location'. |
| format | string | | Value format (if supported by components), for example format of the date |
| sortable | boolean | true | Toggles ability to sort by this column, for example by clicking the column header |
| title | string | | Display title of the column, typically used for column headers. You can use the i18n resouce key to get it translated automatically. |
| template | `TemplateRef` | | Custom column template |
| sr-title | string | | Screen reader title, used for accessibility purposes |
| class | string | | Additional CSS class to be applied to column (header and cells) |
| formatTooltip | Function | | Custom tooltip formatter function. |
## Details
### Automatic column header translation
You can use i18n resource keys with DataColumn `title` property.
The component will automatically check the corresponding i18n resources and fetch corresponding value.
```html
<data-column
key="name"
title="MY.RESOURCE.KEY">
</data-column>
```
This feature is optional. Regular text either plain or converted via the `translate` pipe will still be working as it was before.
### Custom tooltips
You can create custom tooltips for the table cells by providing a `formatTooltip` property with a tooltip formatter function when declaring a data column.
```html
<data-column
title="Name"
key="name"
[formatTooltip]="getNodeNameTooltip"
class="full-width ellipsis-cell">
</data-column>
```
And the code in this case will be similar to the following:
```ts
import { DataColumn, DataRow } from 'ng2-alfresco-datatable';
@Component({...})
export class MyComponent {
...
getNodeNameTooltip(row: DataRow, col: DataColumn): string {
if (row) {
return row.getValue('name');
}
return null;
}
}
```
To disable the tooltip your function can return `null` or an empty string.
### Column Templates
It is possible to assign a custom column template like the following:
```html
<adf-datatable ...>
<data-columns>
<data-column title="Version" key="properties.cm:versionLabel">
<template let-value="value">
<span>V. {{value}}</span>
</template>
</data-column>
</data-columns>
</adf-datatable>
```
Example above shows access to the underlying cell value by binding `value` property to the underlying context `value`:
```html
<template let-value="value">
```
Alternatively you can get access to the entire data context using the following syntax:
```html
<template let-entry="$implicit">
```
That means you are going to create local variable `entry` that is bound to the data context via Angular's special `$implicit` keyword.
```html
<template let-entry="$implicit">
<span>V. {{entry.data.getValue(entry.row, entry.col)}}</span>
</template>
```
In the second case `entry` variable is holding a reference to the following data context:
```ts
{
data: DataTableAdapter,
row: DataRow,
col: DataColumn
}
```

1308
docs/document-list.component.md Normal file
View File

File diff suppressed because it is too large Load Diff

255
docs/extensibility.md Normal file
View File

@@ -0,0 +1,255 @@
# Form Extensibility and Customisation
_Note: it is assumed you are familiar with Alfresco Activiti form definition structure._
- How components and widgets are rendered on a Form
- Replacing default form widgets with custom components
- Replacing custom stencils with custom components
## How components and widgets are rendered on a Form
All form field editors (aka widgets) on a Form are rendered by means of `FormFieldComponent`
that takes an instance of a `FormFieldModel`:
```html
<form-field [field]="field"></form-field>
```
This component depends on `FormRenderingService` service to map `FormFieldModel` to UI component
based on field type or metadata information.
### Component type resolvers
`FormRenderingService` maps field types to corresponding instances exposing `ComponentTypeResolver` interface:
```ts
export interface ComponentTypeResolver {
(field: FormFieldModel): Type<{}>;
}
```
Typically a `ComponentTypeResolver` is a function that takes `FormFieldModel` and returns corresponding component type.
It can be either a predefined component type or a dynamically evaluated based on field properties and metadata.
#### Static component mapping
You can (re)map fields like in the following:
```ts
let customResolver: ComponentTypeResolver = () => CustomWidgetComponent;
formRenderingService.setComponentTypeResolver('text', customResolver, true);
```
or simply:
```ts
formRenderingService.setComponentTypeResolver('text', () => CustomWidgetComponent, true);
```
#### Dynamic component mapping
Alternatively your resolver may return different component types based on `FormFieldModel` state and condition:
```ts
let customResolver: ComponentTypeResolver = (field: FormFieldModel): Type<{}> => {
if (field) {
let params = field.params;
}
return UnknownWidgetComponent;
};
formRenderingService.setComponentTypeResolver('text', customResolver, true);
```
### Default component mappings
Stencil Name | Field Type | Component Type |
| --- | --- | --- |
| Text | text | TextWidgetComponent |
| Number | integer | NumberWidgetComponent |
| Multi-line text | multi-line-text | MultilineTextWidgetComponentComponent |
| Checkbox | boolean | CheckboxWidgetComponent |
| Dropdown | dropdown | DropdownWidgetComponent |
| Date | date | DateWidgetComponent |
| Amount | amount | AmountWidgetComponent |
| Radio buttons | radio-buttons | RadioButtonsWidgetComponent |
| Hyperlink | hyperlink | HyperlinkWidgetComponent |
| Display value | readonly | DisplayValueWidgetComponent |
| Display text | readonly-text | DisplayTextWidgetComponentComponent |
| Typeahead | typeahead | TypeaheadWidgetComponent |
| People | people | PeopleWidgetComponent |
| Group of people | functional-group | FunctionalGroupWidgetComponent |
| Dynamic table | dynamic-table | DynamicTableWidgetComponent |
| N/A | container | ContainerWidgetComponent (layout component) |
| Header | group | ContainerWidgetComponent |
| Attach | upload | AttachWidgetComponent or UploadWidgetComponent (based on metadata) |
| N/A | N/A | UnknownWidgetComponent |
## Replacing default form widgets with custom components
This is a short walkthrough on replacing a standard `Text` widget with a custom component for all Alfresco Activiti forms
rendered within `<activiti-form>` component.
First let's create a simple Alfresco Activiti form with `Text` widgets:
![default text widget](../docassets/images/text-default-widget.png)
Every custom widget must inherit `WidgetComponent` class in order to function properly:
```ts
import { Component } from '@angular/core';
import { WidgetComponent } from 'ng2-activiti-form';
@Component({
selector: 'custom-editor',
template: `
<div style="color: red">Look, I'm a custom editor!</div>
`
})
export class CustomEditorComponent extends WidgetComponent {}
```
Now you will need to add it to the application module or any custom module that is imported into the application one:
```ts
import { NgModule } from '@angular/core';
import { CustomEditorComponent } from './custom-editor.component';
@NgModule({
declarations: [ CustomEditorComponent ],
exports: [ CustomEditorComponent ],
entryComponents: [ CustomEditorComponent ]
})
export class CustomEditorsModule {}
```
Every custom widget should be added into all three module collections: `declarations`, `exports` and `entryComponents`.
If you decided to store custom widgets in a separate dedicated module (and optionally as separate redistributable library)
don't forget to import it into your main application one:
```ts
@NgModule({
imports: [
// ...
CustomEditorsModule
// ...
],
providers: [],
bootstrap: [ AppComponent ]
})
export class AppModule {}
```
Now you can import `FormRenderingService` in any of your Views and override default mapping similar to the following:
```ts
import { Component } from '@angular/core';
import { CustomEditorComponent } from './custom-editor.component';
@Component({...})
export class MyView {
constructor(formRenderingService: FormRenderingService) {
formRenderingService.setComponentTypeResolver('text', () => CustomEditorComponent, true);
}
}
```
At runtime it should look similar to the following:
![custom text widget](../docassets/images/text-custom-widget.png)
## Replacing custom stencils with custom components
This is a short walkthrough on rendering custom Alfresco Activiti stencils by means of custom Angular 2 components.
### Creating custom stencil
First let's create a basic stencil and call it `Custom Stencil 01`:
![custom stencil](../docassets/images/activiti-stencil-01.png)
_Note the `internal identifier` value as it will become a `field type` value when corresponding form is rendered._
Next put some simple html layout for `Form runtime template` and `Form editor template` fields:
```html
<div style="color: blue">Custom activiti stencil</div>
```
Now you are ready to design a test form based on your custom stencil:
![custom stencil form](../docassets/images/activiti-stencil-02.png)
Once wired with a new task it should look like the following within Alfresco Activiti web application:
![custom stencil task](../docassets/images/activiti-stencil-03.png)
### Creating custom widget
If you load previously created task into ADF `<activiti-form>` component you will see something like the following:
![adf stencil](../docassets/images/adf-stencil-01.png)
Let's create an Angular 2 component to render missing content:
```ts
import { Component } from '@angular/core';
import { WidgetComponent } from 'ng2-activiti-form';
@Component({
selector: 'custom-stencil-01',
template: `<div style="color: green">ADF version of custom Activiti stencil</div>`
})
export class CustomStencil01 extends WidgetComponent {}
```
Put it inside custom module:
```ts
import { NgModule } from '@angular/core';
import { CustomStencil01 } from './custom-stencil-01.component';
@NgModule({
declarations: [ CustomStencil01 ],
exports: [ CustomStencil01 ],
entryComponents: [ CustomStencil01 ]
})
export class CustomEditorsModule {}
```
And import into your Application Module
```ts
@NgModule({
imports: [
// ...
CustomEditorsModule
// ...
],
providers: [],
bootstrap: [ AppComponent ]
})
export class AppModule {}
```
Now you can import `FormRenderingService` in any of your Views and provide new mapping:
```ts
import { Component } from '@angular/core';
import { CustomStencil01 } from './custom-stencil-01.component';
@Component({...})
export class MyView {
constructor(formRenderingService: FormRenderingService) {
formRenderingService.setComponentTypeResolver('custom_stencil_01', () => CustomStencil01, true);
}
}
```
At runtime you should now see your custom Angular 2 component rendered in place of the stencils:
![adf stencil runtime](../docassets/images/adf-stencil-02.png)

132
docs/metadata-indicators.md Normal file
View File

@@ -0,0 +1,132 @@
# Walkthrough: adding indicators to clearly highlight information about a node
Every node object in the document list holds metadata information.
All metadata is stored inside `properties` property.
Here's an example of basic image-related metadata fetched from the server:
![](../docassets/images/metadata-01.png)
## Custom column template
```html
<alfresco-document-list ...>
<data-columns>
<data-column key="properties" [sortable]="false">
<template let-value="value">
<adf-metadata-icons [metadata]="value">
</adf-metadata-icons>
</template>
</data-column>
...
</data-columns>
</alfresco-document-list>
```
We are going to declare a column and bind its value to the entire `properties` object of the underlying node. The column will be using our custom `<adf-metadata-icons>` component to display icons based on metadata state.
## MetadataIconsComponent component
Let's create a simple `MetadataIconsComponent` component with a selector set to `adf-metadata-icons` as shown below:
```ts
import { Component, Input } from '@angular/core';
@Component({
selector: 'adf-metadata-icons',
template: `
<div *ngIf="metadata">
<!-- render UI based on metadata -->
</div>
`
})
export class MetadataIconsComponent {
@Input()
metadata: any;
}
```
The component will expose a `metadata` property we can use from the outside and eventually bind data to similar to the following:
```html
<adf-metadata-icons [metadata]="nodeMetadata"></adf-metadata-icons>
```
As you have seen earlier the DataColumn binds to `properties` property of the node, and maps the runtime value as the `value` local variable within the template.
Next we propagate the `value` reference to the `<adf-metadata-icons>` component as `metadata` property.
```html
<data-column key="properties" [sortable]="false">
<template let-value="value">
<adf-metadata-icons [metadata]="value"></adf-metadata-icons>
</template>
</data-column>
```
So once rendered our component will automatically have access to entire set of node metadata. Let's build some visualization of the `cm:versionLabel` property.
For demonstration purposes we are going to display several icons if underlying node has version `2.0`, and just a plain text version value for all other versions.
```html
<div *ngIf="metadata">
<ng-container *ngIf="metadata['cm:versionLabel'] === '2.0'">
<md-icon>portrait</md-icon>
<md-icon>photo_filter</md-icon>
<md-icon>rotate_90_degrees_ccw</md-icon>
</ng-container>
<div *ngIf="metadata['cm:versionLabel'] !== '2.0'">
{{metadata['cm:versionLabel']}}
</div>
</div>
```
Note: For a list of the icons that can be used with `<md-icon>` component please refer to this resource: [material.io/icons](https://material.io/icons/)
## Testing component
You will need to enable `versioning` feature for the Document List to be able to upload multiple versions of the file instead of renaming duplicates.
Drag and drop any image file to upload it and ensure it has `1.0` displayed in the column:
![](../docassets/images/metadata-02.png)
Now drop the same file again to upload a new version of the file.
You should now see icons instead of version label.
![](../docassets/images/metadata-03.png)
You can see on the screenshot above that only files with version `2.0` got extra icons.
## Conclusion
The full source code of the component can be found below:
```ts
import { Component, Input } from '@angular/core';
@Component({
selector: 'adf-metadata-icons',
template: `
<div *ngIf="metadata">
<ng-container *ngIf="metadata['cm:versionLabel'] === '2.0'">
<md-icon>portrait</md-icon>
<md-icon>photo_filter</md-icon>
<md-icon>rotate_90_degrees_ccw</md-icon>
</ng-container>
<div *ngIf="metadata['cm:versionLabel'] !== '2.0'">
{{metadata['cm:versionLabel']}}
</div>
</div>
`
})
export class MetadataIconsComponent {
@Input()
metadata: any;
}
```
You can use this idea to build more complex indication experience based on the actual metadata state.

30
docs/sites-dropdown.component.md Normal file
View File

@@ -0,0 +1,30 @@
# Sites Dropdown component
Displays a dropdown menu to show and interact with the sites of the current user.
![Dropdown sites](../docassets/images/document-list-dropdown-list.png)
<!-- markdown-toc start - Don't edit this section. npm run toc to generate it-->
<!-- toc -->
- [Basic Usage](#basic-usage)
* [Events](#events)
<!-- tocstop -->
<!-- markdown-toc end -->
## Basic Usage
```html
<adf-sites-dropdown
(change)="getSiteContent($event)">
</adf-sites-dropdown>
```
### Events
| Name | Returned Type | Description |
| --- | --- | --- |
| change | [SiteModel](https://github.com/Alfresco/alfresco-ng2-components/blob/master/ng2-components/ng2-alfresco-core/src/models/site.model.ts) | emitted when user selects a site. When default option is selected an empty model is emitted |

144
docs/stencils.md Normal file
View File

@@ -0,0 +1,144 @@
# Form Stencils with Angular 2
Form component provides basic support for custom stencils created with Activiti stencil editor.
## Installing
Configuring support for stencils requires the following configuration for your `index.html` file:
```html
<!-- Stencils integration -->
<script src="node_modules/ng2-activiti-form/stencils/runtime.ng1.js"></script>
<script src="node_modules/ng2-activiti-form/stencils/runtime.adf.js"></script>
<script src="http://<activiti-app-root>/app/rest/script-files/controllers"></script>
```
Where `<activiti-app-root>` should be replaced with a valid url pointing to your Activiti installation, for example:
```html
<script src="http://localhost:9999/activiti-app/app/rest/script-files/controllers"></script>
```
- `/app/rest/script-files/controllers`
provides all stencil controllers stored within Activiti
- `runtime.ng1.js`
provides a compatibility layer for controllers created with Angular 1
(this is to avoid runtime errors when loading Angular 1 code into `<activiti-form>` component)
- `runtime.adf.js`
provides API for stencil management and registration,
i.e. mapping html templates with corresponding controller classes
## Creating new stencil
Create a new stencil and add a new item called `ng2 component 01`.
The internal identifier in this case should be `ng2_component_01`.
This value will be used as field type when form gets rendered.
## Form runtime template
This should be a valid Angular 2 component template that you want to render in `<activiti-form>` component:
```html
<div>
<div>Angular2 Component</div>
<div>Created by: {{name}}</div>
</div>
```
## Form editor template
This can be any html layout to be rendered as a component placeholder in Activiti Form Designer.
```html
<div>
<div style="color: blue">
Angular2 Component 01
</div>
</div>
```
## Custom component controller
This field should contain JavaScript code for Angular 2 component class.
_Note: If you are using TypeScript then you should be putting transpiled JavaScript code here,
you can try official [TypeScript playground](http://www.typescriptlang.org/play/)
to see how TS code gets transpiled into JS._
### JavaScript code
```js
var SampleClass1 = (function () {
function SampleClass1() {
this.name = 'Denys';
console.log('ng2_component_01 ctor');
}
SampleClass1.prototype.ngOnInit = function () {
console.log('OnInit called');
};
return SampleClass1;
}());
```
### TypeScript code
The TypeScript version of the code above is:
```ts
import { OnInit } from '@angular/core';
class SampleClass1 implements OnInit {
constructor() {
console.log('ctor called');
}
ngOnInit() {
console.log('OnInit called');
}
}
```
### Mapping template with component class
In order to map **form runtime template** with the corresponding component class
you will need to register both parts with `adf.registerComponent(identifier, class)` api:
```js
if (adf) {
adf.registerComponent('ng2_component_01', SampleClass1);
}
```
### Final result
```js
var SampleClass1 = (function () {
function SampleClass1() {
this.name = 'Denys';
console.log('ng2_component_01 ctor');
}
SampleClass1.prototype.ngOnInit = function () {
console.log('OnInit called');
};
return SampleClass1;
}());
if (adf) {
adf.registerComponent('ng2_component_01', SampleClass1);
}
```
## Runtime result
When rendered on the form this stencil item should look like the following:
```html
Angular2 Component
Created by: Denys
```
ADF Form component will automatically assemble and compile a valid Angular 2 component on the fly.

6
docs/summary.json Normal file
View File

@@ -0,0 +1,6 @@
[
{ "title": "Form Extensibility and Customisation", "file": "extensibility.md" },
{ "title": "Form Stencils with Angular 2", "file": "stencils.md" },
{ "title": "Theming", "file": "theming.md" },
{ "title": "Walkthrough: adding indicators to highlight information about a node", "file": "metadata-indicators.md" }
]

14
docs/theming.md
View File

@@ -1,9 +1,10 @@
# Theming your Alfresco ADF app
### Using a pre-built theme
Alfresco ADF comes prepackaged with several pre-built theme css files. These theme files also
## Using a pre-built theme
Angular Material comes prepackaged with several pre-built theme css files. These theme files also
include all of the styles for core (styles common to all components), so you only have to include a
single css file for Alfresco ADF in your app.
single css file for Angular Material in your app.
You can include a theme file directly into your application from
`ng2-alfresco-core/prebuilt-themes`
@@ -29,7 +30,7 @@ Or you can add it directly in your index.html
<link href="node_modules/ng2-alfresco-core/prebuilt-themes/adf-blue-orange.css" rel="stylesheet">
```
### Defining a custom theme
## Defining a custom theme
When you want more customization than a pre-built theme offers, you can create your own theme file. You need to include the packages only what you really use in your application.
@@ -76,10 +77,11 @@ $theme: mat-light-theme($primary, $accent, $warn);
Notes: if you are using the Generator or the demo shell you need only to change the`/app/theme.scss` with your set of colors
#### Multiple themes
### Multiple themes
You can create multiple themes for your application:
##### Example of defining multiple themes:
#### Example of defining multiple themes
```scss
@import '~@angular/material/theming';