@eqproject/eqp-filters-next

Table of contents

• Getting started
• API
• Use cases
• Credits

Required

• Angular Material installed and imported
• @angular-material-components/datetime-picker (v2.0.4)
• @angular-material-components/moment-adapter
• Moment.js

Getting started

This package allows the definition of filters to be used on a data list of any type. With eqp-filters you can configure different types of filters (to choose from a predefined set) or create a custom filter to inject into the directive itself.

Notes

The directive does not really apply the filter but dynamically composes the filter to be returned to the user.

Step 1: Install eqp-dynamic-filters:

NPM

npm install --save @eqproject/eqp-filters

Step 2: Import the EqpDashboardModule :

import { EqpFiltersModule } from '@eqproject/eqp-filters';

@NgModule({
  declarations: [AppComponent],
  imports: [EqpFiltersModule],
  bootstrap: [AppComponent]
})
export class AppModule {}

API

Inputs

Input	Type	Default	Required	Description
[filtersConfig]	Array<FilterConfig>	-	yes	Array of FilterConfig Objects
[resultType]	FilterResultType	BASIC	yes	It allows you to define the type of result to be returned to the calling component, when the "Apply Filters" button is pressed. The possible values ​​are, 1-BASIC: returns an object that will contain as many properties as there are filters valued, each property will have a name and value consistent with the filter configuration; 2-ADVANCED: Returns a complex object to use as LinqPredicate
[usingMode]	FilterMode	WITH_CARD	yes	It allows you to define the method of use and the graphic aspect of the directive. Possible values are, 1-WITH_CARD: an expandable card is rendered and the filters are displayed in the mat-card-content. When you apply filters in the card-header, the applied filters are summarized 2-WITH_BUTTON: a button is rendered (with the same style as the previous card-header). Pressing the button opens a modal containing all the filters. When filters are applied or reset, the modal closes and the applied filters are summarized in the button
[filterTitle]	string	Filtri	no	Allows you to define the label to show as a title for the filters
[filterAppliedTitle]	string	Filtri applicati:	no	Allows you to define the label to show in the header of the card when there are filters applied
[applyFilterLabel]	string	Filtra	no	Allows you to define the button label to apply filters
[resetAllFilterLabel]	string	Reset	no	Allows you to define the button label to reset filters
[showExpandend]	boolean	false	no	When using usingMode = WITH_CARD it allows to define the starting state of the card. If TRUE then part open otherwise collapsed
[currentCultureSelected]	string	it-IT	yes	It allows you to define the culture (and the relative language) to be used for the localization of dates
[applyOnInit]	boolean	false	no	If TRUE then invokes the filterSelected output event at the init of the component. To be used when you want to give a starting value to some filters
[saveFilter]	boolean	false	no	If it assumes the value TRUE then the filter saving function will be active; the user can, after setting the different conditions, click on the 'Save filters' button to store the current filter status. This operation can be done several times in order to memorize more filters with different conditions. If the property is TRUE then it is mandatory to define the saveFilterID input
[saveFilterID]	string	-	no	If saveFilter is TRUE then this input is required and must contain a unique name that identifies the component. This unique value will be used to store the different filters configured by the user.
[saveFilterButtonLabel]	string	Salva filtro	no	If saveFilter is TRUE then this input allows you to define the label to show for the save filter button
[saveFilterTitle]	string	Inserire il nome per questo filtro	no	If saveFilter is TRUE then this input allows you to define the title of the modal for entering the name of the filter to be saved
[saveFilterConfirmLabel]	string	Conferma	no	If saveFilter is TRUE then this input allows you to define the label of the confirm button for saving the filters
[saveFilterAbortLabel]	string	Annulla	no	If saveFilter is TRUE then this input allows you to define the label of the cancel button for saving filters
[restoreSavedFilterTooltip]	string	Ricarica filtro	no	It allows you to define the tooltip to be shown to reload a filter from those previously saved (default value: 'Reload filter'). This input is used only when saveFilter = TRUE
[removeSavedFilterTooltip]	string	Elimina filtro	no	It allows you to define the tooltip to be displayed to delete a filter from those previously saved (default value: 'Delete filter'). This input is used only when saveFilter = TRUE
[savedFilterLabel]	string	Filtri salvati	no	If saveFilter is TRUE then this input allows you to define the section label that shows all previously saved filters (default value: 'Saved Filters')
[useInitialValueOnReset]	boolean	true	no	If TRUE then when the RESET key is pressed for the filters that had default start values ​​then those values ​​will be reset, otherwise if FALSE all the filters will be deleted
[filterPreventRemovalTooltip]	string	Non è possibile rimuovere questo filtro	no	Allows you to redefine the label to be shown as a tooltip when you hover the mouse over a filter for which PreventRemoval = TRUE (i.e. when deletion is prevented for a filter)
[saveLastFilter]	boolean	false	no	If TRUE saves the last user selected filters and if the parameter applyOnInit is TRUE they will be restored and applied.
[savedLastFilterName]	string	Ultimi filtri usati	no	If saveLastFilter is TRUE then this input allows you to define the name of the last selected filters.
[leftCollapseIcon]	boolean	true	no	If TRUE and usingMode == FilterMode.WITH_CARD then shows the arrow to expand/collapse the card on the left side of the header, otherwise shows it on the right side.
[showAppliedFiltersIcon]	boolean	false	no	If TRUE, usingMode == FilterMode.WITH_CARD and the user selected some filters then shows a filter icon on the left of the header title. To change this icon color you can use its own css class named eqp-filters-applied-filter-icon.

Outputs

Output	Event Arguments	Required	Description
[filtersSelected]	EventEmitter<any>	yes	Invoked when buttons are pressed to apply or reset filters. Returns as a parameter the object (in case of resultType = BASIC) or the array of complex objects (if resultType = ADVANCED) with the results of the applied filters.
[customFiltersSavedValueLoaded]	EventEmitter<any>	yes	Output event fired when filters are reloaded from localstorage and the current filter expects an external template. This event is invoked only if the filter has an external template and only if the storage of the filters has been requested for eqp-filters. The complete filter configuration is passed as an event parameter.

Models used

FilterConfig Model: class for configure each individual filter

Property	Description	Type	Examples
FilterID	Unique Filter ID string	string	-
FilterClass	Set the dimension of the filter control	FilterSizeClass	SMALL;MEDIUM;LARGE;CUSTOM
CustomFilterClasses	If FilterClass == FilterSizeClass.CUSTOM sets the custom defined classes on the filter control	string	-
Label	Set the label for the filter	string	-
PropertyName	Property name of the array objects on which the filter is to be applied	string	Name
PropertyObject	Property value of the array objects on which the filter is to be applied (default null)	any	-
InputType	Enum that define the type of the filter control to show	InputType	The possible values are: Text, Number, Date, Datetime, CvlEnum, Cvl, Boolean, BooleanCvl, CustomTemplate
WherePartType	It defines, in the case of resultType = ADVANCED, the type of logical comparison operator to be made	WherePartType	A value to be chosen between Equal, NotEqual, StringContains, StringNotContains, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, ContainsElement, NotContainsElement
CvlConfig	Set the configuration for type CVL filter (it's mandatory when InputType = CvlEnum or InputType = Cvl or InputType = BooleanCvl)	FilterCvlConfig	-
Externaltemplate	Defines an external template to pass to the directive and which contains a custom filter (defined by the user who uses the directive)	TemplateRef<any>	-
CustomWherePartFunction	Allows you to define an external custom function to be invoked for the current filter when the APPLY FILTERS or RESET buttons are pressed	Function	-
CustomAppliedFilterInfoFunction	It allows you to define the custom function to return the value of the applied filter, to be shown in the header of the card	Function	-
ChildElementPropertyName	For filters of type ContainsElement and NotContainsElement that rely on applying a where part with the operator ANY of LINQ then this property allows you to define the name of the property of the child objects on which to apply the where part. In this case, the name of the property containing the child list will go into PropertyName.	string	-
PreventRemoval	Allows you to disable the cancellation of the filter for the user. By default it assumes the value FALSE (if true then the X button will not be shown in the summary of the applied filters)	boolean	-

Enums description

EnumType	Description	Notes
FilterClass	Allow the define the dimensione of the filter	SMALL apply the col-4 bootstrap class, MEDIUM apply the col-8 bootstrap class and LARGE apply the col-12 bootstrap class
InputType	Allow the define the type of the input control to show for the filter	Text: show an input text; Number:show an input number; Date: show a material datepicker; CvlEnum: show an eqp-select for the enumData type defined on the CvlConfig for the filter; Cvl: show an eqp-select for the arrayData defined on the CvlConfig for the filter; Boolean: show a material slide; BooleanCvl: show an eqp-select for the arrayData defined on the CvlConfig for the boolean filter value with states(NULL,TRUE, FALSE); CustomTemplate: show an external ng-template passed to the directive
WherePartType	It defines, in the case of resultType = ADVANCED, the type of logical comparison operator to be made	-
FilterResultType	Defines the type of the object to return when the apply filters button is pressed	-
FilterMode	Defines how the directive is to be used	WITH_CARD (default value): show a mat-card with expandable content. In the mat-card-content the filters are showed; WITH_BUTTON: show a button. When the button is pressed, a mat-dialog window are open with all the configured filters

Static exposed functions

Name	Returned Type	Parameters	Examples
CreateStandardFilterConfig	FilterConfig	filterID: string, label: string, propertyName: string, type: InputType, wherePartType: WherePartType, filterClass?: FilterSizeClass, filterCvlConfig?: FilterCvlConfig, externaltemplate?: TemplateRef<any>, customWherePartFunction? : Function, childElementPropertyName?: string	-

FilterCvlConfig Model: class for configure the eqp-select for the filter of types: Cvl, CvlEnum or BooleanCvl

Property	Description	Type	Examples
EnumData	Se la CVL si basa su un enumeratore allora in questa proprietà va definito il type dell'enumeratore da usare. In questo modo la sorgente dati della CVL sarà l'insieme dei valori definiti per l'enumeratore	any	-
ArrayData	If the CVL is based on an array then in this property the array to be shown as the data source of the CVL must be defined	any[]	-
ArrayKeyProperty	In the case of ArrayData defined it allows to indicate the property of the objects of the array to bind to the filter	string	-
ArrayValueProperty	In the case of ArrayData defined, it allows you to indicate the property of the objects to be displayed in the filter	string	-
IsSearchable	If TRUE then it shows the search field within the CVL	boolean	-
ShowCancelButton	If TRUE then it shows the button to clear the CVL selection	boolean	-
SearchText	Allows you to define the label for the search field	string	-
IsMultiSelect	It allows you to define the multi-selection of CVL values	boolean	-
BindFullObject	It allows to define if in the CVL the binding must consider the whole object or only the property defined inside ArrayKeyProperty	boolean	-

Static exposed functions

Name	Returned Type	Parameters	Examples
CreateFilterCVLConfig	FilterCvlConfig	enumData?: any, arrayData?: any, arrayKeyProperty?: any, arrayValueProperty?: any, isMultiSelect?: boolean, isSearchable?: boolean, showCancelButton?: boolean, searchText?: string, bindFullObject?: boolean	-

Use cases

Use Example in class :

Define selector in html

<eqp-dynamic-filters [filtersConfig]="filters" (filtersSelected)="filtersSelected($event)"></eqp-dashboard>

CASE 1:Text type filter configuration

    filters: FilterConfig[];
    
    let textFilter: FilterConfig = FilterConfig.CreateStandardFilterConfig("TEXT_FILTER", "Name", "Name", InputType.Text, WherePartType.Equal);
    this.filters.push(textFilter);

CASE 2: Number type filter configuration

    filters: FilterConfig[];
    
    let numberFilter: FilterConfig = FilterConfig.CreateStandardFilterConfig("NUMBER_FILTER", "Counter", "Filtro Numero", InputType.Number, WherePartType.Equal);
    this.filters.push(numberFilter);

CASE 3: Boolean type filter configuration

    filters: FilterConfig[];
    
    let booleanFilter: FilterConfig = FilterConfig.CreateStandardFilterConfig("BOOLEAN_FILTER","Bool Filter", "IsValid", InputType.Boolean, WherePartType.Equal);
     this.filters.push(booleanFilter);

CASE 4: CVL Enum type filter configuration

    filters: FilterConfig[];
    
    //Assuming you define a GenderEnum type enumerator with the values MALE and FEMALE
    
    let enumCvlConfig: FilterCvlConfig = FilterCvlConfig.CreateFilterCVLConfig(GenderEnum, null, null, null, false, true, true);
    let enumFilter: FilterConfig = FilterConfig.CreateStandardFilterConfig("CVL_ENUM_FILTER", "Gender", "Gender", InputType.CvlEnum, WherePartType.Equal, null, enumCvlConfig);
    this.filters.push(enumFilter);

CASE 5: Date type filter configuration

    filters: FilterConfig[];
    
    let filterDateStart: FilterConfig = FilterConfig.CreateStandardFilterConfig("DATE_FILTER", "Start date","StartDate", InputType.Date, WherePartType.GreaterThanOrEqual, FilterSizeClass.SMALL);
    this.filters.push(filterDateStart);

CASE 6: Datetime type filter configuration

    filters: FilterConfig[];
    
    let filterDateStart: FilterConfig = FilterConfig.CreateStandardFilterConfig("DATETIME_FILTER", "Start datetime","StartDatetime", InputType.Datetime, WherePartType.GreaterThanOrEqual, FilterSizeClass.SMALL);
    this.filters.push(filterDateStart);

CASE 7: CVL type filter configuration

    filters: FilterConfig[];
    
    let cvlConfig: FilterCvlConfig = FilterCvlConfig.CreateFilterCVLConfig(null, [{ key: 1, value: "Value 1"}, { key: 2, value: "Value 2"}, { key: 3, value: "Value 3"}], "key", "value", false, true, true, null, true);
    let cvlFilter: FilterConfig = FilterConfig.CreateStandardFilterConfig("CVL_FILTER", "Cvl", "CvlValue", InputType.Cvl, WherePartType.Equal, null, cvlConfig);
    this.filters.push(cvlFilter);

CASE 8: Boolean CVL type filter configuration (this is the typical case of a non-mandatory Boolean)

    filters: FilterConfig[];
    
    let booleanCvlConfig: FilterCvlConfig = FilterCvlConfig.CreateFilterCVLConfig(null, [{ key: true, value: "Yes"}, { key: false, value: "No"}], "key", "value", false, true, true, null, false);
    let booleanCvlFilter: FilterConfig = FilterConfig.CreateStandardFilterConfig("CVL_BOOLEAN_FILTER", "Boolean Cvl", "BooleanCvlValue", InputType.BooleanCvl, WherePartType.Equal, null, booleanCvlConfig);
    this.filters.push(booleanCvlFilter);

CASE 9: Custom Template type filter configuration (this is the typical case of a non-mandatory Boolean)

    <ng-template #externalFilter let-filter="filter">
        <mat-form-field>
            <mat-label>{{ filter.Label }}</mat-label>
            <input matInput [(ngModel)]="filter.PropertyObject">
      </mat-form-field>
    </ng-template>

    
    //Define this ViewChild on ts
    @ViewChild('externalFilter', { static: true }) externalFilter: TemplateRef<any>;
    
    //Define this function on ts
    createCustomFilterValue(filterConfig, context) {
        let result = {};

        result[filterConfig.PropertyName] = filterConfig.PropertyObject;
        return result;
    }
    
    //On the filter configuring method
    filters: FilterConfig[];
    
    let filterExternal: FilterConfig = FilterConfig.CreateStandardFilterConfig("PROVA_TEMPLATE_ESTERNO","Template esterno","Surname", InputType.CustomTemplate, WherePartType.Equal, FilterSizeClass.SMALL);
    filterExternal.Externaltemplate = this.externalFilter;
    filterExternal.CustomWherePartFunction = (config, context) => this.createCustomFilterValue(config, this);

    this.filters.push(filterExternal);
    

CASE 10: eqp-filters with active save functionality

    <eqp-dynamic-filters [filtersConfig]="filters" [saveFilter]="true" [saveFilterID]="'testFiltri'"                            [saveFilterID]="'provaFiltri'" (filtersSelected)="filtersSelected($event)"                     (customFiltersSavedValueLoaded)="customFiltersSavedValueLoaded($event)" [usingMode]="2" [resultType]="2" [applyOnInit]="true" ></eqp-dynamic-filters>

    
    //On the filter configuring method
    filters: FilterConfig[];
    
    let textFilter: FilterConfig = FilterConfig.CreateStandardFilterConfig("PROVA_TEXT_ID", "Nome", "Name", InputType.Text, WherePartType.Equal);
    this.filters.push(textFilter);

    
    customFiltersSavedValueLoaded(filterConfig:FilterConfig) {
    if(!filterConfig)
      return;

    //If the current filter has an external template (with custom function defined) then 
    //here the value of the PropertyObject property of filterConfig must be forced with the value of the properties 
    //used inside the external template. In this way eqp-filters will be able to retrieve the value to be saved also 
    //for custom filters
    //For example: filterConfig.PropertyObject = context.customFilterPropertyValue;
  }
    

Credits

This library has been developed by EqProject SRL, for more info contact: info@eqproject.it