alfresco-ng2-components/docs/core/card-view.component.md

Added, Status

Added	Status
v2.0.0	Active

Card View component

Displays a configurable property list renderer.

Basic Usage

<adf-card-view
    [properties]="[{label: 'My Label', value: 'My value'}]"
    [editable]="false">
</adf-card-view>

Properties

Name	Type	Default	Description
properties	CardViewItem[]	-	(required) The custom view to render
editable	boolean	-	If the component editable or not
displayEmpty	boolean	true	Whether to show empty properties in non-editable mode

Details

You define the property list, the CardViewComponent does the rest. Each property represents a card view item (a row) in the card view component. At the time of writing three a few kind of card view item (property type) is supported out of the box (e.g: text item and date item) but you can define your own custom types as well.

Editing

The card view can optionally allow its properties to be edited. You can control the editing of the properties in two level.

• global level - via the editable parameter of the card-view.component
• property level - in each property via the editable attribute

If you set the global editable parameter to false, no properties can be edited regardless of what is set inside the property.

See the Card View Update service page for details on how to use the service to respond to clicks and edits in a card view. You can use this, for example, to save the edits within your application or to highlight a clicked item.

Defining properties

Properties is an array of models which one by one implements the CardViewItem interface.

export interface CardViewItem {
    label: string;
    value: any;
    key: string;
    default?: any;
    type: string;
    displayValue: string;
    editable?: boolean;
    icon?: string;
}

At the moment these are the models supported:

• CardViewTextItemModel - for text items
• CardViewMapItemModel - for map items
• CardViewDateItemModel - for date items
• CardViewDatetimeItemModel - for datetime items
• CardViewBoolItemModel - for bool items (checkbox)
• CardViewIntItemModel - for integers items
• CardViewFloatItemModel - for float items

Each of them extends the abstract CardViewBaseItemModel class to add some custom functionality to the basic behaviour.

 this.properties = [
    new CardViewTextItemModel({
        label: 'Name',
        value: 'Spock',
        key: 'name',
        default: 'default bar' ,
        multiline: false,
        icon: 'icon';
    }),
    new CardViewMapItemModel({
        label: 'My map',
        value: new Map([['999', 'My Value']]),
        key: 'map',
        default: 'default map value' ,
        clickable: true
    }),
    new CardViewDateItemModel({
        label: 'Date of birth',
        value: someDate,
        key: 'date-of-birth',
        default: new Date(),
        format: '<any format that momentjs accepts>',
        editable: true
    }),
    new CardViewDatetimeItemModel({
        label: 'Datetime of birth',
        value: someDatetime,
        key: 'datetime-of-birth',
        default: new Date(),
        format: '<any format that momentjs accepts>',
        editable: true
    }),
    new CardViewBoolItemModel({
        label: 'Vulcanian',
        value: true,
        key: 'vulcanian',
        default: false
    }),
    new CardViewIntItemModel({
        label: 'Intelligence',
        value: 213,
        key: 'intelligence',
        default: 1
    }),
    new CardViewFloatItemModel({
        label: 'Mental stability',
        value: 9.9,
        key: 'mental-stability',
        default: 0.0
    }),
    ...
]

Card Text Item

CardViewTextItemModel is a property type for text properties.

const textItemProperty = new CardViewTextItemModel(options);

Name	Type	Default	Description
label*	string	---	The label to render
value*	any	---	The original value
key*	string	---	the key of the property. Have an important role when editing the property.
default	any	---	The default value to render in case the value is empty
displayValue*	string	---	The value to render
editable	boolean	false	Whether the property editable or not
clickable	boolean	false	Whether the property clickable or not
icon	string	The material icon to show against the clickable property
multiline	string	false	Single or multiline text
pipes	CardViewTextItemPipeProperty[]	[]	Pipes to be applied on the displayValue

Using pipes in Card Text Item

You can use pipes for text items almost the same way as you would do it in your template. You can provide an array of pipes with additional pipeParameters like this:

const myWonderfulPipe1: PipeTransform = <whatever PipeTransform implmentation>;
const myWonderfulPipe2: PipeTransform = <whatever PipeTransform implmentation>;

new CardViewTextItemModel({
    label: 'some label',
    value: someValue,
    key: 'some-key',
    pipes: [
	{ pipe: myWonderfulPipe1, params: ['first-param', 'second-param'] },
	{ pipe: myWonderfulPipe2, params: ['first-param', 'second-param'] }
    ]
});

Card Map Item

CardViewMapItemModel is a property type for map properties.

const mapItemProperty = new CardViewMapItemModel(options);

Name	Type	Default	Description
label*	string	---	The label to render
value*	Map	---	A map that contains the key value pairs
key*	string	---	the key of the property.
default	any	---	The default value to render in case the value is empty
displayValue*	string	---	The value to render
clickable	boolean	false	Whether the property clickable or not

Card Date Item

CardViewDateItemModel is a property type for date properties.

const dateItemProperty = new CardViewDateItemModel(options);

Name	Type	Default	Description
label*	string	---	The label to render
value*	any	---	The original value
key*	string	---	the key of the property.
default	any	---	The default value to render in case the value is empty
displayValue*	any	---	The value to render
editable	boolean	false	Whether the property editable or not
format	boolean	"MMM DD YYYY"	any format that momentjs accepts

Card Datetime Item

CardViewDatetimeItemModel is a property type for datetime properties.

const datetimeItemProperty = new CardViewDatetimeItemModel(options);

Name	Type	Default	Description
label*	string	---	The label to render
value*	any	---	The original value
key*	string	---	the key of the property.
default	any	any	The default value to render in case the value is empty
displayValue*	string	---	The value to render
editable	boolean	false	Whether the property editable or not
format	boolean	"MMM DD YYYY HH:mm"	any format that momentjs accepts

Card Bool Item

CardViewBoolItemModel is a property type for boolean properties.

const boolItemProperty = new CardViewBoolItemModel(options);

Name	Type	Default	Description
label*	string	---	The label to render
value*	boolean	---	The original value
key*	string	---	the key of the property.
default	boolean	false	The default value to render in case the value is empty
displayValue*	boolean	---	The value to render
editable	boolean	false	Whether the property editable or not

Card Int Item

CardViewIntItemModel is a property type for integer properties.

const intItemProperty = new CardViewIntItemModel(options);

Name	Type	Default	Description
label*	string	---	The label to render
value*	integer	---	The original value
key*	string	---	the key of the property.
default	integer	---	The default value to render in case the value is empty
displayValue*	integer	---	The value to render
editable	boolean	false	Whether the property editable or not

Card Float Item

CardViewFloatItemModel is a property type for float properties.

const floatItemProperty = new CardViewFloatItemModel(options);

Name	Type	Default	Description
label*	string	---	The label to render
value*	float	---	The original value
key*	string	---	the key of the property.
default	float	---	The default value to render in case the value is empty
displayValue*	float	---	The value to render
editable	boolean	false	Whether the property editable or not

Defining your custom card Item

Card item components are loaded dynamically, which makes you able to define your own custom component for the custom card item type.

Let's consider you want to have a stardate type to display Captain Picard's birthday (47457.1). For this, you need to do the following steps.

1. Define the Model for the custom type

Your model has to extend the CardViewBaseItemModel and implement the CardViewItem and DynamicComponentModel interface. (You can check how the CardViewTextItemModel is implemented for further guidance.)

import { CardViewBaseItemModel, CardViewItem, DynamicComponentModel } from '@alfresco/adf-core';

export class CardViewStarDateItemModel extends CardViewBaseItemModel implements
CardViewItem, DynamicComponentModel {
    type: string = 'star-date';

    get displayValue() {
        return this.convertToStarDate(this.value) || this.default;
    }

    private convertToStarDate(starTimeStamp: number): string {
        // Do the magic
    }
}

2. Define the Component for the custom type

Create your custom card view item component. Defining the selector is not important, being it a dinamically loaded component, so you can give any selector name to it, but it makes sense to follow the angular standards.

@Component({
    selector: 'card-view-stardateitem' // For example
    ...
})
export class CardViewStarDateItemComponent {
    @Input()
    property: CardViewStarDateItemModel;

    @Input()
    editable: boolean;

    constructor(private cardViewUpdateService: CardViewUpdateService) {}

    isEditable() {
        return this.editable && this.property.editable;
    }

    showStarDatePicker() {
        ...
    }
}

To make your component editable, you can have a look on either the CardViewTextItemComponent' or on the CardViewDateItemComponent's source.

3. Add you custom component to your module's entryComponents list

For Angular to be able to load your custom component dynamically, you have to register your component in your modules entryComponents.

@NgModule({
    imports: [...],
    declarations: [
        CardViewStarDateItemComponent
    ],
    entryComponents: [
        CardViewStarDateItemComponent
    ],
    exports: [...]
})
export class MyModule {}

4. Bind your custom component to the custom model type, enabling Angular's dynamic component loader to find it.

For mapping each type to their Component, there is the CardItemTypeService. This service extends the DynamicComponentMapper abstract class. This CardItemTypeService is responible for the type resolution, it contains all the default components (e.g.: text, date, etc...) also. In order to make your component available, you need to extend the list of possible components.

You can extend this list the following way:

@Component({
    ...
    providers: [ CardItemTypeService ] // If you don't want to pollute the main instance of the CardItemTypeService service
    ...
})
export class SomeParentComponent {

    constructor(private cardItemTypeService: CardItemTypeService) {
        cardItemTypeService.setComponentTypeResolver('star-date', () => CardViewStarDateItemComponent);
    }
}

See also

• Card view update service