mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2025-07-24 17:32:15 +00:00
[ADF-2463] Moved user guide pages to a subfolder (#3083)
* [ADF-2463] Moved user guide to a subfolder * [ADF-2463] Fixed broken links and images
This commit is contained in:
Andy Stark
committed by
Eugenio Romano
Eugenio Romano
parent
6490260c5d
commit
126e73f5f3
58
docs/user-guide/angular-material-design.md
Normal file
58
docs/user-guide/angular-material-design.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# Angular Material Design
|
||||
|
||||
Google's
|
||||
[Material Design](https://material.io/guidelines/material-design/introduction.html)
|
||||
is an example of a _design language_, a
|
||||
general set of principles and ideas that are used to give designs a
|
||||
consistent look and feel. A design language might be used in-house by
|
||||
a company to maintain a "family resemblance" between its products or to
|
||||
produce user-friendly signage. Material Design is Google's approach to
|
||||
keeping user interfaces consistent between apps, using insights from
|
||||
product design and cognitive psychology.
|
||||
|
||||
[Angular Material](https://material.angular.io/) is a set of components,
|
||||
styles and other GUI elements
|
||||
that follow the Material Design guidelines. ADF uses Angular Material
|
||||
to implement its components but you can also use it directly when
|
||||
creating your own components or modifying the ones provided by ADF.
|
||||
|
||||
## Themes
|
||||
|
||||
Material Design doesn't enforce one single color scheme but it does
|
||||
specify a number of **themes**. A theme is a set of colors in various
|
||||
shades, each of which lends itself to a particular task in the GUI.
|
||||
For example, using the suggested shades for status bars, backgrounds
|
||||
and shadows helps to give the correct emphasis to these elements and
|
||||
ensure they look familiar to the user. The Material Design
|
||||
[themes documentation](https://material.io/guidelines/style/color.html#color-themes)
|
||||
has more information as well as color swatches and other resources.
|
||||
|
||||
An advantage of using themes is that one theme can easily be replaced
|
||||
by another - the CSS styling is designed so that a given class name in one theme plays
|
||||
an equivalent role in all other themes. See the [Theming](theming.md) page
|
||||
for details of how to apply an off-the-shelf theme to your ADF app or to
|
||||
create your own theme.
|
||||
|
||||
## Components
|
||||
|
||||
Angular Material implements a variety of GUI components. These include
|
||||
controls like radio buttons and checkboxes but also structures for layout
|
||||
(lists, grids, etc) and navigation (toolbars, sidebars, menus). See the
|
||||
[components section](https://material.angular.io/components/categories) of
|
||||
the Angular Material docs for more information.
|
||||
|
||||
## Icons
|
||||
|
||||
Material Design has extensive
|
||||
[guidelines](https://material.io/guidelines/style/icons.html) for the design
|
||||
of icons. These images serve as visual indicators for GUI functions and data
|
||||
elements (eg, a small graphic of a person could denote a user). A selection of
|
||||
standard icons is also available for common items. For example, a microphone
|
||||
icon indicates audio input while a magnifying glass emphasizes a search box.
|
||||
See the Material Design
|
||||
[system icon docs](https://material.io/guidelines/style/icons.html#icons-system-icons)
|
||||
for further information and to download the set of standard icon images.
|
||||
|
||||
## See also
|
||||
|
||||
- [Theming](theming.md)
|
||||
265
docs/user-guide/extensibility.md
Normal file
265
docs/user-guide/extensibility.md
Normal file
@@ -0,0 +1,265 @@
|
||||
---
|
||||
Added: v2.0.0
|
||||
---
|
||||
# Form Extensibility and Customisation
|
||||
|
||||
_Note: it is assumed you are familiar with Alfresco Process Services (powered by 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 APS forms
|
||||
rendered within `<adf-form>` component.
|
||||
|
||||
First let's create a simple APS form with `Text` widgets:
|
||||
|
||||
|
||||
|
||||
Every custom widget must inherit `WidgetComponent` class in order to function properly:
|
||||
|
||||
```ts
|
||||
import { Component } from '@angular/core';
|
||||
import { WidgetComponent } from '@alfresco/adf-core';
|
||||
|
||||
@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:
|
||||
|
||||
|
||||
|
||||
## Replacing custom stencils with custom components
|
||||
|
||||
This is a short walkthrough on rendering custom APS stencils by means of custom Angular components.
|
||||
|
||||
### Creating custom stencil
|
||||
|
||||
First let's create a basic stencil and call it `Custom Stencil 01`:
|
||||
|
||||
|
||||
|
||||
_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:
|
||||
|
||||
|
||||
|
||||
Once wired with a new task it should look like the following within APS web application:
|
||||
|
||||
|
||||
|
||||
### Creating custom widget
|
||||
|
||||
If you load previously created task into ADF `<adf-form>` component you will see something like the following:
|
||||
|
||||
|
||||
|
||||
Let's create an Angular component to render missing content:
|
||||
|
||||
```ts
|
||||
import { Component } from '@angular/core';
|
||||
import { WidgetComponent } from '@alfresco/adf-core';
|
||||
|
||||
@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 component rendered in place of the stencils:
|
||||
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
- [Form field model](../core/form-field.model.md)
|
||||
- [Form rendering service](../core/form-rendering.service.md)
|
||||
- [Form component](../core/form.component.md)
|
||||
- [Widget component](../insights/widget.component.md)
|
||||
220
docs/user-guide/internationalization.md
Normal file
220
docs/user-guide/internationalization.md
Normal file
@@ -0,0 +1,220 @@
|
||||
---
|
||||
Added: v2.2.0
|
||||
---
|
||||
# Internationalization in ADF
|
||||
|
||||
Internationalization (abbreviated to i18n) is the process of providing UI messages
|
||||
and captions in different human languages to make them easier for readers of those
|
||||
languages to understand. ADF provides full support for i18n in apps. The process does
|
||||
require some extra effort in planning and designing the UI but once implemented, it is
|
||||
fairly straightforward to maintain.
|
||||
|
||||
## Contents
|
||||
|
||||
- [I18n concepts](#i18n-concepts)
|
||||
- [ADF support for i18n](#adf-support-for-i18n)
|
||||
- [Using the translate pipe](#using-the-translate-pipe)
|
||||
- [Adding your own messages](#adding-your-own-messages)
|
||||
- [Interpolations](#interpolations)
|
||||
- [Selecting the display language](#selecting-the-display-language)
|
||||
- [Support for i18n within ADF components](#support-for-i18n-within-adf-components)
|
||||
- [See also](#see-also)
|
||||
|
||||
## I18n concepts
|
||||
|
||||
The main idea behind i18n is to avoid adding natural language text directly into the
|
||||
HTML. Instead, UI messages are represented by short strings known as
|
||||
**keys**. Keys are not displayed directly; they are used to look up the actual text
|
||||
in a list of predefined messages. A typical key/message pair might look like the
|
||||
following:
|
||||
|
||||
"CS_URL_ERROR": "Content Services address doesn't match the URL format"
|
||||
|
||||
Separate lists are kept for each language supported by the app, so for German, the
|
||||
same message would be defined as:
|
||||
|
||||
"CS_URL_ERROR": "Content Services-Adresse nicht im richtigen URL-Format"
|
||||
|
||||
Note that the key is the same in both cases. As long as the UI only ever refers to
|
||||
the keys then changing languages is a simple matter of changing the look-up list.
|
||||
|
||||
## ADF support for i18n
|
||||
|
||||
ADF implements i18n for more than ten languages internally in the display text for
|
||||
components, so you can try out some simple messages without any configuration. The
|
||||
keys are defined in a set of files in the `lib/core/i18n` folder in the ADF sources.
|
||||
|
||||
The files are named according to standard
|
||||
[two-letter language codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes),
|
||||
so `en.json` is the look-up list for English, etc. An excerpt from `en.json` is shown
|
||||
below:
|
||||
|
||||
```json
|
||||
{
|
||||
"FORM": {
|
||||
"START_FORM": {
|
||||
"TITLE": "Start Form"
|
||||
},
|
||||
"PREVIEW": {
|
||||
"IMAGE_NOT_AVAILABLE": "Preview not available"
|
||||
},
|
||||
"FIELD": {
|
||||
"LOCALSTORAGE" : "Local storage",
|
||||
"SOURCE": "Select source from ",
|
||||
"UPLOAD": "UPLOAD",
|
||||
"REQUIRED": "*Required",
|
||||
...
|
||||
```
|
||||
|
||||
The hierarchical structure is referred to in the UI using the familiar "dot"
|
||||
notation (so `FORM.START_FORM.TITLE` would be the key for the "Start Form"
|
||||
string here). This is useful for grouping related messages and providing
|
||||
singular and plural versions, among other things.
|
||||
|
||||
The [Translation service](../core/translation.service.md) defines the `get` method to
|
||||
get the translation of a key in the current language. A simple component might
|
||||
contain code like this:
|
||||
|
||||
```ts
|
||||
import { Component, OnInit } from '@angular/core';
|
||||
|
||||
import { TranslationService } from "@alfresco/adf-core";
|
||||
|
||||
@Component({
|
||||
selector: 'app-home',
|
||||
templateUrl: './home.component.html',
|
||||
styleUrls: ['./home.component.css']
|
||||
})
|
||||
export class HomeComponent implements OnInit {
|
||||
|
||||
constructor(private trans: TranslationService) { }
|
||||
|
||||
translatedText: string = "";
|
||||
|
||||
ngOnInit() {
|
||||
this.trans.get("FORM.START_FORM.TITLE").subscribe(translation => {
|
||||
this.translatedText = translation;
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
...with very simple corresponding HTML:
|
||||
|
||||
```html
|
||||
{{translatedText}}
|
||||
```
|
||||
|
||||
In the browser, this is displayed as:
|
||||
|
||||
|
||||
|
||||
English is used by default but you can easily change the language with the
|
||||
`use` method:
|
||||
|
||||
```ts
|
||||
ngOnInit() {
|
||||
this.trans.use("de");
|
||||
|
||||
this.trans.get("FORM.START_FORM.TITLE").subscribe(translation => {
|
||||
this.translatedText = translation;
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
The user will now see:
|
||||
|
||||
|
||||
|
||||
Note that an unrecognized key will be returned unchanged as the "translation".
|
||||
If you see strings like "FORM.START_FORM.TITLE" displayed in your app then you
|
||||
should check you are using the key correctly.
|
||||
|
||||
## Using the translate pipe
|
||||
|
||||
Using `TranslationService.get` is straightforward but it is often more
|
||||
convenient to add translation keys directly into your page's HTML.
|
||||
Use the `translate` pipe to convert a key in the page directly to the
|
||||
corresponding text. For example, the following will display the
|
||||
"Start Form" text as above but without any code or variables in the
|
||||
component's `.ts` file:
|
||||
|
||||
{{ "FORM.START_FORM.TITLE" | translate }}
|
||||
|
||||
## Adding your own messages
|
||||
|
||||
The built-in translations certainly won't cover everything you will need for
|
||||
your app but you can easily replace them with your own lists. This involves
|
||||
making copies of the existing lists in your app's folder and adding your
|
||||
own keys. See the [Translation service](../core/translation.service.md) page for
|
||||
full details and examples.
|
||||
|
||||
## Interpolations
|
||||
|
||||
Translation messages have support for _interpolation_ (ie, including another
|
||||
string at a specified position within a message). This is very useful for
|
||||
messages whose content can change at runtime. For example, in the built-in
|
||||
`en.json` there is the `CORE.PAGINATION.ITEMS_RANGE` key:
|
||||
|
||||
```json
|
||||
...
|
||||
"CORE": {
|
||||
...
|
||||
"PAGINATION": {
|
||||
"ITEMS_RANGE": "Showing {{ range }} of {{ total }}",
|
||||
"ITEMS_PER_PAGE": "Items per page",
|
||||
...
|
||||
},
|
||||
...
|
||||
```
|
||||
|
||||
The sections in curly braces are _interpolation variables_ that you supply
|
||||
at runtime. You can specify them by passing an extra parameter to
|
||||
`TranslationService.get`; this is an object whose properties have the same
|
||||
names as the interpolation variables in the string:
|
||||
|
||||
```ts
|
||||
this.trans.get(
|
||||
"CORE.PAGINATION.ITEMS_RANGE",
|
||||
{
|
||||
range: "1..10",
|
||||
total: "122"
|
||||
}
|
||||
).subscribe(translation => {
|
||||
this.translatedText = translation;
|
||||
});
|
||||
```
|
||||
|
||||
You can use interpolations with the `translate` pipe in a similar way:
|
||||
|
||||
{{ "CORE.PAGINATION.ITEMS_RANGE" | translate: { range: "1..10", total: "122"} }}
|
||||
|
||||
## Selecting the display language
|
||||
|
||||
ADF provides a [Language Menu component](../core/language-menu.component.md) that
|
||||
you can add to a page to let the user choose their preferred language. The
|
||||
available languages are defined in the `app.config.json` file for the app.
|
||||
|
||||
Note that when the user selects an item from the menu, it simply changes the "locale"
|
||||
preference (which you can get via the [User Preferences service](../core/user-preferences.service.md)).
|
||||
The `translate` pipe reacts automatically to this and changes the page text
|
||||
immediately to the new language. However, text added via a variable set using
|
||||
`TranslationService.get`, as in the example above, will not be updated like this;
|
||||
you will need to get a new translation and set the variable's value again explicitly
|
||||
from the code.
|
||||
|
||||
See the [Language Menu component](../core/language-menu.component.md) page for further
|
||||
details and usage examples.
|
||||
|
||||
## Support for i18n within ADF components
|
||||
|
||||
Some components allow you to use translation keys in places where you would normally
|
||||
supply your own messages directly. For example, the
|
||||
[Data Column component](../core/data-column.component.md) can accept a key instead of
|
||||
normal text to specify the column title. Consult the documentation for a
|
||||
component to see if it has built-in support for i18n.
|
||||
|
||||
## See also
|
||||
|
||||
- [Translation service](../core/translation.service.md)
|
||||
- [Language Menu component](../core/language-menu.component.md)
|
||||
135
docs/user-guide/metadata-indicators.md
Normal file
135
docs/user-guide/metadata-indicators.md
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
Added: v2.0.0
|
||||
---
|
||||
# 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:
|
||||
|
||||
|
||||
|
||||
## Custom column template
|
||||
|
||||
```html
|
||||
<alfresco-document-list ...>
|
||||
<data-columns>
|
||||
<data-column key="properties" [sortable]="false">
|
||||
<ng-template let-value="value">
|
||||
<adf-metadata-icons [metadata]="value">
|
||||
</adf-metadata-icons>
|
||||
</ng-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">
|
||||
<ng-template let-value="value">
|
||||
<adf-metadata-icons [metadata]="value"></adf-metadata-icons>
|
||||
</ng-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'">
|
||||
<mat-icon>portrait</mat-icon>
|
||||
<mat-icon>photo_filter</mat-icon>
|
||||
<mat-icon>rotate_90_degrees_ccw</mat-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 `<mat-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:
|
||||
|
||||
|
||||
|
||||
Now drop the same file again to upload a new version of the file.
|
||||
You should now see icons instead of version label.
|
||||
|
||||
|
||||
|
||||
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'">
|
||||
<mat-icon>portrait</mat-icon>
|
||||
<mat-icon>photo_filter</mat-icon>
|
||||
<mat-icon>rotate_90_degrees_ccw</mat-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.
|
||||
144
docs/user-guide/stencils.md
Normal file
144
docs/user-guide/stencils.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Form Stencils
|
||||
|
||||
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 AngularJS (aka Angular 1x)
|
||||
(this is to avoid runtime errors when loading AngularJS 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 component template that you want to render in `<activiti-form>` component:
|
||||
|
||||
```html
|
||||
<div>
|
||||
<div>Angular 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">
|
||||
Angular Component 01
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
## Custom component controller
|
||||
|
||||
This field should contain JavaScript code for Angular 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
|
||||
Angular Component
|
||||
Created by: Denys
|
||||
```
|
||||
|
||||
ADF Form component will automatically assemble and compile a valid Angular component on the fly.
|
||||
8
docs/user-guide/summary.json
Normal file
8
docs/user-guide/summary.json
Normal file
@@ -0,0 +1,8 @@
|
||||
[
|
||||
{ "title": "Angular Material Design", "file": "angular-material-design.md" },
|
||||
{ "title": "Form Extensibility and Customisation", "file": "extensibility.md" },
|
||||
{ "title": "Internationalization in ADF", "file": "internationalization.md" },
|
||||
{ "title": "Theming", "file": "theming.md" },
|
||||
{ "title": "Typography", "file": "typography.md" },
|
||||
{ "title": "Walkthrough - adding indicators to highlight information about a node", "file": "metadata-indicators.md" }
|
||||
]
|
||||
141
docs/user-guide/theming.md
Normal file
141
docs/user-guide/theming.md
Normal file
@@ -0,0 +1,141 @@
|
||||
---
|
||||
Added: v2.0.0
|
||||
---
|
||||
# Theming an ADF app
|
||||
|
||||
The [Material Design](https://material.io/guidelines/material-design/introduction.html)
|
||||
specification doesn't specify a single color scheme. Instead it uses the concept
|
||||
of color **themes** to allow designers some flexibility in their choice of colors.
|
||||
|
||||
A theme is a palette based around two main colors: the **primary** color (used widely
|
||||
throughout the app) and the **accent** color (used mainly for highlighting and calling
|
||||
out specific UI elements). Each of these colors is defined in a number of shades. For
|
||||
example, a blue/orange theme could define shades like the following:
|
||||
|
||||
|
||||
|
||||
Each shade is related to a particular purpose or set of purposes within the app. So for
|
||||
example, the shade that works best for text isn't necessarily the same shade you would use
|
||||
for flat areas of color. Material Design provides a number of
|
||||
[standard themes](https://material.io/guidelines/style/color.html#color-themes)
|
||||
with shades that are carefully chosen for each purpose within the UI. The CSS files are
|
||||
designed so that the names are consistent between themes (so the same "purpose" will always
|
||||
have the same class name across CSS files). This makes it easy to switch themes simply by
|
||||
changing a few CSS definitions. Material Design also defines the relationship between
|
||||
the different shades, so you can calculate your own color values or, more straightforwardly, use
|
||||
an [online palette design tool](http://mcg.mbitson.com/).
|
||||
|
||||
See the [Material Design Style page](https://material.io/guidelines/style/color.html#) for
|
||||
more information about color concepts.
|
||||
|
||||
## 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 Angular Material in your app.
|
||||
|
||||
You can include a theme file directly into your application from
|
||||
`@alfresco/adf-core/prebuilt-themes`
|
||||
|
||||
Available pre-built themes:
|
||||
* `adf-blue-orange.css`
|
||||
* `adf-blue-purple.css`
|
||||
* `adf-cyan-orange.css`
|
||||
* `adf-cyan-purple.css`
|
||||
* `adf-green-orange.css`
|
||||
* `adf-green-purple.css`
|
||||
* `adf-indigo-pink.css`
|
||||
* `adf-pink-bluegrey.css`
|
||||
* `adf-purple-green.css`
|
||||
|
||||
If you're using Angular CLI you can include one of the prebuilt themes in your `styles.scss` file:
|
||||
```css
|
||||
@import '~@alfresco/adf-core/prebuilt-themes/adf-blue-orange.css';
|
||||
```
|
||||
Or you can add it directly in your index.html
|
||||
|
||||
```html
|
||||
<link href="node_modules/ng2-alfresco-core/prebuilt-themes/adf-blue-orange.css" rel="stylesheet">
|
||||
```
|
||||
|
||||
## Defining a custom theme
|
||||
|
||||
When you want more customization than a pre-built theme offers, you can create your own theme file. You only need to include the packages you actually use in your application.
|
||||
|
||||
```scss
|
||||
/*
|
||||
* Include only packages that you are using (and core by default)
|
||||
*/
|
||||
@import '~@alfresco/adf-content-services/theming';
|
||||
@import '~@alfresco/adf-process-services/theming';
|
||||
@import '~@alfresco/adf-insights/theming';
|
||||
@import '~@alfresco/adf-core/theming';
|
||||
|
||||
@import '~@angular/material/theming';
|
||||
|
||||
@include mat-core($alfresco-typography);
|
||||
|
||||
$primary: mat-palette($alfresco-accent-orange);
|
||||
$accent: mat-palette($alfresco-accent-purple);
|
||||
$warn: mat-palette($alfresco-warn);
|
||||
$theme: mat-light-theme($primary, $accent, $warn);
|
||||
|
||||
@include angular-material-theme($theme);
|
||||
|
||||
@include adf-content-services-theme($theme);
|
||||
@include adf-process-services-theme($theme);
|
||||
@include adf-insights-theme($theme);
|
||||
@include adf-core-theme($theme);
|
||||
```
|
||||
|
||||
Notes: if you are using the Generator or the demo shell you need only to change the`/src/custom-style.scss` with your set of colors
|
||||
|
||||
### Multiple themes
|
||||
|
||||
You can create multiple themes for your application:
|
||||
|
||||
#### Example of defining multiple themes
|
||||
|
||||
```scss
|
||||
@import '~@alfresco/adf-content-services/theming';
|
||||
@import '~@alfresco/adf-process-services/theming';
|
||||
@import '~@alfresco/adf-insights/theming';
|
||||
@import '~@alfresco/adf-core/theming';
|
||||
@import '~@angular/material/theming';
|
||||
...
|
||||
|
||||
@include mat-core();
|
||||
|
||||
$primary: mat-palette($alfresco-accent-orange);
|
||||
$accent: mat-palette($alfresco-accent-purple);
|
||||
$warn: mat-palette($alfresco-warn);
|
||||
|
||||
$theme: mat-light-theme($primary, $accent, $warn);
|
||||
$dark-theme: mat-dark-theme($primary, $accent, $warn);
|
||||
|
||||
@include adf-core-theme($theme);
|
||||
...like above
|
||||
|
||||
.adf-dark-theme {
|
||||
@include adf-core-theme($dark-theme);
|
||||
...like above
|
||||
}
|
||||
```
|
||||
Any component with the `add-dark-theme` class will use the dark theme, while other components will fall back to the default.
|
||||
|
||||
|
||||
## Default reusable class
|
||||
|
||||
```css
|
||||
.adf-hide-small // Display none vieweport <960px
|
||||
.adf-hide-xsmall // Display none vieweport <600px
|
||||
|
||||
.adf-primary-color // Primary color
|
||||
.accent-color // Accent color
|
||||
.warn-color // Warn color
|
||||
.primary-contrast-text-color // Default contrast color for primary color
|
||||
.accent-contrast-text-color // Default contrast color for accent color
|
||||
.background-color // Dialog background color
|
||||
.primary-background-color // Primary background color
|
||||
.accent-background-color // Default background color for accent
|
||||
```
|
||||
78
docs/user-guide/typography.md
Normal file
78
docs/user-guide/typography.md
Normal file
@@ -0,0 +1,78 @@
|
||||
---
|
||||
Added: v2.0.0
|
||||
---
|
||||
# ADF Typography
|
||||
|
||||
## What is typography?
|
||||
|
||||
Typography configuration lets you change the style of the text in your ADF app
|
||||
|
||||
## Customization
|
||||
|
||||
To get started you need to include your custom font in the `/src/index.html` header:
|
||||
|
||||
```html
|
||||
<link href="https://fonts.googleapis.com/css?family=Muli" rel="stylesheet">
|
||||
```
|
||||
|
||||
After you need to change your `/src/custom-style.scss` to include the new font:
|
||||
|
||||
```scss
|
||||
/*
|
||||
* Include only packages that you are using (and core by default)
|
||||
*/
|
||||
@import '~@angular/material/theming';
|
||||
@import '~ng2-alfresco-core/styles/theming';
|
||||
@import '~ng2-alfresco-core/styles/index';
|
||||
@import '~ng2-activiti-analytics/styles/index';
|
||||
@import '~ng2-activiti-diagrams/styles/index';
|
||||
@import '~ng2-activiti-form/styles/index';
|
||||
@import '~ng2-activiti-processlist/styles/index';
|
||||
@import '~ng2-activiti-tasklist/styles/index';
|
||||
@import '~ng2-alfresco-datatable/styles/index';
|
||||
@import '~ng2-alfresco-documentlist/styles/index';
|
||||
@import '~ng2-alfresco-login/styles/index';
|
||||
@import '~ng2-alfresco-upload/styles/index';
|
||||
@import '~ng2-alfresco-userinfo/styles/index';
|
||||
|
||||
$custom-typography: mat-typography-config(
|
||||
$font-family: 'Muli, Roboto, "Helvetica Neue", sans-serif',
|
||||
$display-4: mat-typography-level(112px, 112px, 300),
|
||||
$display-3: mat-typography-level(56px, 56px, 400),
|
||||
$display-2: mat-typography-level(45px, 48px, 400),
|
||||
$display-1: mat-typography-level(34px, 40px, 400),
|
||||
$headline: mat-typography-level(24px, 32px, 400),
|
||||
$title: mat-typography-level(20px, 32px, 500),
|
||||
$subheading-2: mat-typography-level(16px, 28px, 400),
|
||||
$subheading-1: mat-typography-level(15px, 24px, 400),
|
||||
$body-2: mat-typography-level(14px, 24px, 500),
|
||||
$body-1: mat-typography-level(14px, 20px, 400),
|
||||
$caption: mat-typography-level(12px, 20px, 400),
|
||||
$button: mat-typography-level(14px, 14px, 500),
|
||||
$input: mat-typography-level(16px, 1.25, 400)
|
||||
);
|
||||
|
||||
@include mat-core($custom-typography);
|
||||
|
||||
$primary: mat-palette($alfresco-accent-orange);
|
||||
$accent: mat-palette($alfresco-accent-purple);
|
||||
$warn: mat-palette($alfresco-warn);
|
||||
$theme: mat-light-theme($primary, $accent, $warn);
|
||||
|
||||
@include angular-material-theme($theme);
|
||||
|
||||
@include alfresco-core-theme($theme);
|
||||
@include adf-analytics-theme($theme);
|
||||
@include adf-diagrams-theme($theme);
|
||||
@include adf-form-theme($theme);
|
||||
@include adf-processlist-theme($theme);
|
||||
@include adf-tasklist-theme($theme);
|
||||
@include alfresco-datatable-theme($theme);
|
||||
@include alfresco-documentlist-theme($theme);
|
||||
@include alfresco-login-theme($theme);
|
||||
@include alfresco-upload-theme($theme);
|
||||
@include alfresco-userinfo-theme($theme);
|
||||
|
||||
```
|
||||
|
||||
for more details about typography refer to [Material 2 documentation](https://github.com/angular/material2/blob/master/guides/typography.md)
|
||||
Reference in New Issue
Block a user