odata-dynamic-filter

VueJS dynamic filter component with TypeScript support for querying OData endpoints

Usage no npm install needed!

<script type="module">
  import odataDynamicFilter from 'https://cdn.skypack.dev/odata-dynamic-filter';
</script>

README

odata-dynamic-filter

VueJS dynamic filter component with TypeScript support for querying OData endpoints.

This component generates a form with filters based on the fields provided. When clicking the search button it will emit an object with a search query string for OData endpoints.

Installation

NPM

npm install odata-dynamic-filter

Yarn

yarn add odata-dynamic-filter

Global registration on entry point

import DynamicFilter from 'odata-dynamic-filter';
import 'odata-dynamic-filter/dist/odata-dynamic-filter.css';

Vue.component('dynamic-filter', DynamicFilter);

Local registration on a component

import DynamicFilter from 'odata-dynamic-filter';
import 'odata-dynamic-filter/dist/odata-dynamic-filter.css';

new Vue({
    el: '#app',
    components: {
        'dynamic-filter': DynamicFilter
    }
});

Local registration using Class Style Component syntax

import DynamicFilter from 'odata-dynamic-filter';
import 'odata-dynamic-filter/dist/odata-dynamic-filter.css';

@Component({
    components: {
        DynamicFilter
    }
})
export default class App extends Vue {}

Template

<template>
    <dynamic-filter></dynamic-filter>
</template>

Props

fields: Array<DynamicFilterField>

This will be an array of fields and will be used to generate the dynamic filter form.

The fields are of type DynamicFilterField which you can import as follows:

import { DynamicFilterField } from 'odata-dynamic-filter';

The properties of this object are:

fieldName: string

This is the name of the property of the model you will be filtering in OData. Supports nested properties to filter by. For example, assume you have a Person model with a list of Cars, providing the value: 'Cars[]/Brand' would let you query by the brands of the cars owned by each person.

label: string

This is the label that will be visible for this field on the input of the form.

type: DynamicFilterFieldType

This is the type of input you want to render for the current field. The options are on an enum that you can import as follows:

import { DynamicFilterFieldType } from 'odata-dynamic-filter';

This enum has the following structure which is very descriptive:

enum DynamicFilterFieldType {
    TEXT = 1,
    NUMBER = 2,
    DOUBLE = 3,
    CHECKBOX = 4,
    DATEPICKER = 5,
    DROPDOWN = 6,
    MULTIPLE_DROPDOWN = 7
}

The TEXT type renders a text input for string values.

The NUMBER type renders an input which only allows numbers. This also allows decimals, which OData interprets as being of type decimal by default.

The DOUBLE type renders an input which only allows numbers. Use this type if you need to specify that the number type is a double.

The CHECKBOX type renders a checkbox which is used for boolean values of true/false.

The DATEPICKER type renders an input with a mask for dates in the dd/MM/yyyy format. However, the value in the generated query string will be in the yyyy-mm-dd format.

The DROPDOWN type lets you define an array of options of possible values to filter by.

The MULTIPLE_DROPDOWN type works like the DROPDOWN type but additionally lets you select multiple values at the same time.

options: Array<DynamicFilterSelectOption>

Only applies for fields of type DROPDOWN or MULTIPLE_DROPDOWN. These are the options that will display on the dropdown control.

It can be imported as follows:

import { DynamicFilterSelectOption } from 'odata-dynamic-filter';

The DynamicFilterSelectOption object has the following properties:

label: string

This is the label text displayed for the option.

value: any

Value of the option. If the field is of type MULTIPLE_DROPDOWN, it can only be a string. OData doesn't allow the use of the 'contains' operator on numbers.

selected: boolean

Whether the option is selected by default.

valueModifierIndex: number

This is the index of the value modifier function to use in the array of functions of the valueModifiers prop. Below is an explanation of how this prop works.

valueModifiers: Array<(value: any) => any>

The valueModifiers prop is an array of functions that you may want to apply to the values you will be filtering by before generating the query string. To choose which function to use on each field, you would provide the index of the function in the valueModifierIndex property of the field.

For example, you may have the following valueModifiers variable (TypeScript):

const valueModifiers: Array<(value: any) => any> = [
    (value: any) => {
        return value / 2;
    },
    (value: any) => { 
        return value * 2;
    }
];

Here we have two functions that could be used as value modifiers for your fields. To choose which one to use you would make the valueModifierIndex have the value 0 or 1 depending on which you want to use.

queryStringAsObjectProperty: boolean

This prop just indicates whether to append the '?$filter=' string fragment before the final query string or not. A value of false adds it, which means the generated query string will be appended to a request URL of an endpoint with OData support. This also means you will not be using the generated query string as a property of a JavaScript object of params.

title: string

This will be the title to display in the form. Not providing a value will just not display any title.

buttonClass: string

This will override the class used for the buttons in the component. This way you can insert your own button styles or button classes from any css framework.

andOperatorColor: string

Sometimes you want the entire row of a form where you selected the and operator to have a background color so that it can be easily differentiated from a row using the or operator. This prop defines the color that will be used. Any HTML supported color is valid.

orOperatorColor: string

This would be the prop used for the background color of or rows.

languageIsoCode: string

This is an ISO code meaning the language to be used for the labels. Currently only English and Spanish are supported. The codes are 'en' and 'es' respectively. To use another language read the i18n prop below.

i18n: Labels

This prop is an object that define the labels used in the component. Below is an example of the object used internally for the English language.

{
    languageIsoCode: 'en',
    selectFields: 'Select the fields',
    inputsPlaceholder: 'Value',
    dropdownPlaceholder: 'Select an option',
    multipleSelection: 'selected options',
    resetButton: 'Reset',
    searchButton: 'Search',
    comparativeOperators: {
        contains: 'Contains',
        equal: 'Equal to',
        greater: 'Greater than',
        less: 'Less than',
        greaterOrEqual: 'Greater or equal to',
        lessOrEqual: 'Less or equal to'
    },
    logicalOperators: {
        and: 'And',
        or: 'Or'
    }
}

Events

@search

This is the event emitted when the search button is clicked. It will pass a Filter object as argument. This object will have the properties with the generated query strings for OData.

query: string

This is the OData query string generated by the component.

queryNotNested: string

This provides the query string based on a property of the model.

The Filter model can be imported as follows:

import { Filter } from 'odata-dynamic-filter';

@reset

Event emitted when the component is resetted to its initial state.

Thanks to the Solvex company for the help and support: https://solvex.com.do/