Collection

Class Collection

The container that contains one or more group of forms (or list of forms).

Constructor

Collection(schema: CollectionSchema, parent?: Element | null);

Parameters

• schema - an object that define the element.

interface CollectionSchema extends ElementSchema {
  // A collection will contain multiple groups,
  // so we need a group schema here.
  // Note that this group schema doesn't need a `formId` ,
  // it will be generated dynamically when adding new group.
  group: Omit<GroupSchema, 'formId'>;
  rules?: ValidationRuleSchema[];
}

• parent - the parent of this element.

Properties

Methods

static accept

Internal function to validate the input schema, called when generating the element.

Signatures

accept(schema: any): SchemaValidation;

type SchemaValidation = {
  valid: boolean;
  reason?: string;
  infos?: Record<string, string>;
};

Parameters

• schema - schema object.

static create

This method helps to create new Collection dynamically.

Signatures

create(schema: CollectionSchema, parent?: Element | null): Collection;

Parameters

• schema - CollectionSchema object.
• parent - the parent of this element.

Returns

• Collection instance

validate

Validate the element with the current value asynchronously. Firsly, it will trigger the validate event, then trying to validate all the sub elements (if cascade = true) and current group element. If all validations are valid, new value will be set otherwise will be null. Finally, an validated event will be triggered.

Signatures

validate(options?: { cascade?: boolean }): void;

Parameters

• options - The validation options.

{
  // If `true`, all sub elements will be validated
  cascade?: boolean
}

setValue

Set new value to all the sub elements asynchronously. When calling, it will loop through the items of the inputing array, then calling the setValue to each group element, when new value is set to a group element, the value of the current collection is also updated. Finally, a changed event will be triggered for current group element.

Signatures

async setValue(value: any[], options?: { from?: number; autoAdd?: boolean }): any[] | null;

Parameters

• value - The array with new values. Note that the object's properties in each array item have to be mapped with the model fields of the sub group elements.
• options - The options object.

{
  // The index want to set value from, default is `0`
  from?: number;
  // If `true` and the checked array has more items then the current
  // collection's value, then new group will be added automatically.
  autoAdd?: boolean;
}

Returns

• the typed value or null.

addGroup

Add new group and if the value of the added group is valid, then the collection's value is also updated with that group's value.

Signatures

addGroup(): CollectionItem;

Returns

• the CollectionItem instance.

removeGroup

Remove group from the current collection. When calling, it will remove the group, update the collection's value, then validate the collection. Finally, a changed event will be triggered.

Signatures

removeGroup(itemOrIndex: CollectionItem | number): void;

Parameters

• itemOrIndex - The index number of the group item or the CollectionItem instance

clear

This method simply cleans up all valiadtion messages, and also clear all the sub elements.

Signatures

clear(): void;

reset

Reset the element and all sub elements to the default state, clean up the validation messages, and then reset the validation of the element.

Signatures

reset(): void;

shake

Shake the element and all the sub elements (if cascade === true) so that the error message can be shown.

Signatures

shake(options?: { cascade?: boolean }): void;

Parameters

• options - The validation options.

{
  // If `true`, all sub elements will be validated
  cascade?: boolean
}

addField

Add new field to all collection group items.

Signatures

addField(schema: ElementsSchemas, options: { at?: number }): Element[];

Parameters

• options.

{ 
  // The index position that you want to add
  at?: number 
}

Returns

• The array of added element fields

removeField

Remove field from all collection group items.

Signatures

removeField(id: string): (Element | null)[];

Parameters

• id - The removing element id.

Returns

• The removed element field or null if there is no field to be removed.

getSchema

Return current schema including added element field by addField method or removed element field by removeField method.

Signatures

getSchema(): CollectionSchema;

Returns -CollectionSchema.

Inherited Methods

From class Element

From class Evento

Related concepts

• ValidationRuleSchema
• ElementSchema
• CollectionItem