Package Exports
- ngx-material-entity
- ngx-material-entity/package.json
Readme
NgxMaterialEntity
Create Entities and define how to display them directly on their properties. Can even generate complete and highly customizable CRUD-Tables for them.
Table of Contents
- NgxMaterialEntity
- Table of Contents
- Requirements
- Basic Usage
- PropertyDecorators
- NgxMatEntityInput Configuration
- NgxMatEntityTable Configuration
Requirements
This package relies on the angular material library to render its components.
It also uses bootstrap for responsive design.
Basic Usage
Create your entity
Create your entity and define Metadata directly on the properties:
⚠️ IMPORTANT:
You need to always create an entity with the "new" keyword. Otherwise the metadata on the properties won't get generated.
import { Entity, EntityUtilities, string } from 'ngx-material-entity';
export class MyEntity extends Entity {
/**
* ↓ myString is a string
* ↓ which should be displayed inline
* ↓ and has the label 'My String'
*/
@string({
displayName: 'My String',
displayStyle: 'line'
})
myString: string;
constructor(entity?: MyEntity) {
super();
EntityUtilities.new(this, entity);
}
}
For a list of all decorators and configuration options see PropertyDecorators.
Use the input for your entity property
You can import the NgxMatEntityInputModule
anywhere in your code:
import { NgxMatEntityInputModule } from 'ngx-material-entity';
...
imports: [
NgxMatEntityInputModule
]
...
In the html you can then define:
<ngx-mat-entity-input
[entity]="myEntity"
[propertyKey]="myString">
</ngx-mat-entity-input>
This snippet automatically generates an material input for "myString" based on the metadata you defined earlier.
For a list of all configuration options for the input see PropertyInput Configuration.
Generate a complete CRUD Table for your entity
Create a Service for your entity
In order to use the ngx-material-entites component you have to define a service that handles http-Requests for the entity and extends from the abstract EntityService-Class:
// ↓ It's required that the service can be injected
@Injectable({
providedIn: 'root'
})
export class MyEntityService extends EntityService<MyEntity> {
baseUrl: string = `${environment.apiUrl}/my-entity`;
constructor(private readonly httpClient: HttpClient) {
super(httpClient);
}
}
Define the CRUD-Element
Import the NgxMatEntityTableModule
anywhere in your code:
import { NgxMatEntityTableModule } from 'ngx-material-entity';
...
imports: [
NgxMatEntityTableModule
]
...
In the html you can then define:
<ngx-mat-entity-table
[displayColumns]="displayColumns"
[title]="title"
[EntityServiceClass]="MyEntityService"
[EntityClass]="MyEntity"
[multiSelectActions]="multiSelectActions"
[createDialogTitle]="'Custom Create Dialog Title'">
</ngx-mat-entity-table>
For a list of all configuration options see NgxMatEntityTable Configuration.
PropertyDecorators
The property decorators contain all the metadata of an entity property.
base
Contains information that is universally defined on every property.
/**
* Whether or not the Property is displayed at all.
* @default true
*/
display?: boolean;
/**
* The name of the property used as a label for form fields.
*/
displayName: string;
/**
* Whether or not the Property is required.
* @default true
*/
required?: boolean;
/**
* Whether or not the property gets omitted when creating new Entities.
* @default false
*/
omitForCreate?: boolean;
/**
* Whether or not the property gets omitted when updating Entities.
* @default false
*/
omitForUpdate?: boolean;
/**
* Defines the width of the input property when used inside the default create or edit dialog.
* Has 3 bootstrap values for different breakpoints for simple responsive design.
* @var firstValue: col-lg-{{firstValue}}
* @var secondValue: col-md-{{secondValue}}
* @var thirdValue: col-sm-{{thirdValue}}
*/
defaultWidths?: [cols, cols, cols];
/**
* Specifies order of the input property when used inside the default create or edit dialog.
* Ordering is ascending
* @default -1 (sets this property at the end)
*/
order?: number;
For more information regarding the defaultWidths see the bootstrap guide about the Grid system.
@string default
The "default" display of a string value. Inside a single line mat-input.
override displayStyle: 'line';
/**
* (optional) The minimum required length of the string
*/
minLength?: number;
/**
* (optional) The maximum required length of the string
*/
maxLength?: number;
/**
* (optional) A regex used for validation
*/
regex?: RegExp;
@string dropdown
Displays a string as a dropdown where the user can input one of the defined dropdownValues.
override displayStyle: 'dropdown';
/**
* The values of the dropdown, consisting of a name to display and the actual value
* Can also receive a function to determine the values
*/
dropdownValues: { displayName: string, value: string }[];
@string textbox
Displays a string as a textbox.
override displayStyle: 'textbox';
/**
* (optional) The minimum required length of the string
*/
minLength?: number;
/**
* (optional) The maximum required length of the string
*/
maxLength?: number;
@string autocomplete
Just like the default @string, but the user has additional autocomplete values to quickly input data.
override displayStyle: 'autocomplete';
/**
* The autocomplete values
*/
autocompleteValues: string[];
/**
* (optional) The minimum required length of the string
*/
minLength?: number;
/**
* (optional) The maximum required length of the string
*/
maxLength?: number;
/**
* (optional) A regex used for validation
*/
regex?: RegExp;
@number default
The "default" display of a number value. Inside a single line mat-input.
override displayStyle: 'line';
/**
* (optional) The minimum value of the number
*/
min?: number;
/**
* (optional) The maximum value of the number
*/
max?: number;
@number dropdown
Displays the numbers in a dropdown
override displayStyle: 'dropdown';
/**
* The values of the dropdown, consisting of a name to display and the actual value
* Can also receive a function to determine the values
*/
dropdownValues: { displayName: string, value: number }[];
@boolean toggle
Displays the boolean value as a MatSlideToggle
override displayStyle: 'toggle';
@boolean checkbox
Displays the boolean value as a MatCheckbox
override displayStyle: 'checkbox';
@boolean dropdown
Displays the boolean value as a MatCheckbox
override displayStyle: 'dropdown';
/**
* The name of the true value if displayStyle dropdown is used.
* Can also receive a function to determine the name.
*/
dropdownTrue: string | { (args: unknown): string };
/**
* The name of the false value if displayStyle dropdown is used.
* Can also receive a function to determine the name,
*/
dropdownFalse: string | { (args: unknown): string };
@object default
Displays an entity object inline.
override displayStyle: 'inline';
/**
* (optional) The title of the section containing all object properties. Defaults to the display name.
*/
sectionTitle?: string;
@array
/**
* Base definition for the @array metadata
*/
abstract class ArrayDecoratorConfig extends PropertyDecoratorConfig {
/**
* How to display the items
*/
displayStyle!: 'table' | 'chips';
/**
* The type of the items inside the array
*/
itemType!: DecoratorTypes;
/**
* The error-message to display when the array is required but contains no values
*/
missingErrorMessage?: string;
}
@array entity
/**
* Definition for an array of Entities
*/
export class EntityArrayDecoratorConfig<EntityType extends Entity> extends ArrayDecoratorConfig {
override itemType: DecoratorTypes.OBJECT;
override displayStyle: 'table';
/**
* The EntityClass used for generating the create inputs
*/
EntityClass!: new (entity?: EntityType) => EntityType;
/**
* The definition of the columns to display. Consists of the displayName to show in the header of the row
* and the value, which is a function that generates the value to display inside a column
*/
displayColumns: ArrayTableDisplayColumn<EntityType>[];
/**
* The data for the add-item-dialog.
* Can be omitted when adding items inline.
*/
createDialogData?: CreateDialogData
/**
* Whether or not the form for adding items to the array
* should be displayed inline.
* @default true
*/
createInline?: boolean
}
@array string chips
/**
* Definition for an array of strings displayed as a chips list
*/
export class StringChipsArrayDecoratorConfig extends ArrayDecoratorConfig {
override itemType: DecoratorTypes.STRING;
override displayStyle: 'chips';
/**
* The html inside the delete-button.
* Please note that custom tags such as <mat-icon></mat-icon>
* need to be defined as known elements, otherwise the sanitizer will remove them.
* You can however work around this by using `<span class="material-icons"></span>`
* @default <mat-icon>cancel</mat-icon>
*/
deleteHtml?: string
/**
* (optional) The minimum required length of the string
*/
minLength?: number;
/**
* (optional) The maximum required length of the string
*/
maxLength?: number;
/**
* (optional) A regex used for validation
*/
regex?: RegExp;
}
@array string chips autocomplete
/**
* Definition for an array of autocomplete strings displayed as a chips list
*/
export class AutocompleteStringChipsArrayDecoratorConfig extends ArrayDecoratorConfig {
override itemType: DecoratorTypes.STRING_AUTOCOMPLETE;
override displayStyle: 'chips';
/**
* The html inside the delete-button.
* Please note that custom tags such as <mat-icon></mat-icon>
* need to be defined as known elements, otherwise the sanitizer will remove them.
* You can however work around this by using `<span class="material-icons"></span>`
* @default <mat-icon>cancel</mat-icon>
*/
deleteHtml?: string;
/**
* The autocomplete values
*/
autocompleteValues: string[];
/**
* (optional) The minimum required length of the string
*/
minLength?: number;
/**
* (optional) The maximum required length of the string
*/
maxLength?: number;
/**
* (optional) A regex used for validation
*/
regex?: RegExp;
}
NgxMatEntityInput Configuration
With the property input you can generate an input field based on the metadata you defined on your property.
Configuration options are:
/**
* The entity on which the property exists. Used in conjuction with the "propertyKey"
* to determine the property for which the input should be generated.
*/
@Input()
entity!: EntityType;
/**
* The name of the property to generate the input for. Used in conjuction with the "entity".
*/
@Input()
propertyKey!: keyof EntityType;
/**
* (optional) A custom function to generate the error-message for invalid inputs.
*/
@Input()
getValidationErrorMessage!: (model: NgModel) => string;
/**
* Whether to hide a value if it is omitted for creation.
* Is used internally for the object property.
*/
@Input()
hideOmitForCreate?: boolean;
/**
* Whether to hide a value if it is omitted for editing.
* Is used internally for the object property.
*/
@Input()
hideOmitForEdit?: boolean;
NgxMatEntityTable Configuration
With the ngx-mat-entity-table
component you can create a complete CRUD functionality for your entities.
As this component is highly configurable and allows you to either create your own create and edit implementations or use the default out of the box dialogs for that.
/**
* The title of the table
*/
@Input()
title!: string;
/**
* The definition of the columns to display. Consists of the displayName to show in the header of the row
* and the value, which is a function that generates the value to display inside a column
*/
@Input()
displayColumns!: DisplayColumn<EntityType>[];
/**
* The label on the search bar. Defaults to "Search".
*/
@Input()
searchLabel?: string;
/**
* The label on the button for adding new entities. Defaults to "Create".
*/
@Input()
createButtonLabel?: string;
/**
* The Class of the entities to manage
*/
@Input()
EntityClass!: new (entity?: EntityType) => EntityType;
/**
* The Class of the service that handles the entities.
* Needs to be injectable and an extension of the "EntityService"-Class
*/
@Input()
EntityServiceClass!: new (httpClient: HttpClient) => EntityService<EntityType>;
/**
* Takes a custom edit method which runs when you click on a entity.
* If you don't need any special editing of entries you can also omit this.
* In that case a default edit dialog is generated.
*/
@Input()
edit?: (entity: EntityType) => unknown;
/**
* Takes a method to run when you click on the new button.
* If you don't need anything special you can also omit this.
* In that case a default create dialog is generated.
*/
@Input()
create?: (entity: EntityType) => unknown;
/**
* Defines how the search string of entities is generated.
*/
@Input()
searchString?: (enity: EntityType) => string;
/**
* Defines whether or not the user can add new entities.
*/
@Input()
allowCreate!: boolean;
/**
* Defines whether or not the user can edit entities.
*/
@Input()
allowEdit!: boolean;
/**
* Defines whether or not the user can delete entities.
*/
@Input()
allowDelete!: boolean;
/**
* All Actions that you want to run on multiple entities can be defined here.
* (e.g. download as zip-file or mass delete)
*/
@Input()
multiSelectActions?: MultiSelectAction<EntityType>[];
/**
* The Label for the button that opens all multi-actions.
*/
@Input()
multiSelectLabel?: string;
/**
* The title of the default create-dialog.
*/
@Input()
createDialogTitle!: string;
/**
* The label on the create-button of the default create-dialog. Defaults to "Create".
*/
@Input()
createDialogCreateButtonLabel?: string;
/**
* The label on the cancel-button for the default create-dialog. Defaults to "Cancel".
*/
@Input()
createDialogCancelButtonLabel?: string;
/**
* The title of the default edit-dialog.
*/
@Input()
editDialogTitle!: string;
/**
* The label on the confirm-button of the default edit-dialog. Defaults to "Save".
*/
@Input()
editDialogConfirmButtonLabel?: string;
/**
* The label on the delete-button of the default edit-dialog. Defaults to "Delete".
*/
@Input()
editDialogDeleteButtonLabel?: string;
/**
* The label on the cancel-button for the default edit-dialog. Defaults to "Cancel".
*/
@Input()
editDialogCancelButtonLabel?: string;
/**
* The text inside the confirm delete dialog.
* Each string inside the array is a paragraph.
*/
@Input()
confirmDeleteText?: string[];
/**
* The label on the button that confirms the deletion of an entity.
*/
@Input()
confirmDeleteButtonLabel?: string;
/**
* The label on the button that cancels the deletion of an entity.
*/
@Input()
cancelDeleteButtonLabel?: string;
/**
* The title of the dialog where you have to either confirm or cancel the deletion of an entity.
*/
@Input()
confirmDeleteDialogTitle?: string;
/**
* Whether or not a checkbox needs to be checked before being able to click on the confirm-delete-button
*/
@Input()
confirmDeleteRequireConfirmation?: boolean;
/**
* The text next to the checkbox
*/
@Input()
confirmDeleteConfirmationText?: string
Display Columns
The definition of a column inside the table.
export interface DisplayColumn<EntityType extends Entity> {
/**
* The name inside the header.
*/
displayName: string;
/**
* A method to get the value inside an entry
*/
value: (entity: EntityType) => string;
}
Multiselect Actions
Multiselect Actions appear on the right upper corner and allow you to do actions on all selected entries.
export interface MultiSelectAction<EntityType extends Entity> {
/**
* The name of the action
*/
displayName: string;
/**
* The action itself
*/
action: (entity: EntityType[]) => unknown;
/**
* A method that defines whether or not the action can be used.
* Defaults to true.
*/
enabled?: (entity: EntityType[]) => boolean;
}