node package manager

fenix-ui-filter

FENIX Filter

var Filter = require('fenix-ui-filter');
 
var filter = new Filter({
        el : "#filter",
        selectors : {
            sel_1 : { /* selector configuration goes here */ }, 
            sel_2 : { ... }
        }
    });

Commands

  • npm run build : builds in production mode
  • npm run build:demo : called after npm run build, builds the demo folder
  • npm run dev : launch webpack-dev-server for develop. Once server is started, its default url is http://localhost:8080/webpack-dev-server/
  • npm t : automated test

Configuration

Check fx-filter/config/config.js to have a look of the default configuration.

Parameter Type Default Value Example Description
el CSS3 Item/JavaScript DOM element/jQuery DOM element - "#container" component container
selectors Object - - The filter instance's selectors to render. Check the Item configuration.
template HTML - - The filter template to render selector with a specific layout.
pluginRegistry object { } - Keyset: plugins' ids. Value: object. path: plugin module path
focusedItemClassName string "focused" "my-focused" CSS class applied to make a selector focused
mandatoryItemClassName string "mandatory" "my-mandatory" CSS class applied to make a selector mandatory
disabledItemClassName string "disabled" "my-disabled"' CSS class applied to make a selector disabled
outputFormat string "plain" plain , fenix, catalog Default output format of getValues() fn
direction string "append" "prepend" Direction of how the selector are added (if no template is provided)
ensureAtLeast number -1 1/td> Min number of selector per filter instance
summaryEl CSS3 Item/JavaScript DOM element/jQuery DOM element - "#summary-container" Container of the summary
summaryRender function - - Custom renderer for summary
values Object - { values : { indicator : ["cod_001"], year : [{value: "2000", parent: "from"}, {value: "2016", parent: "to"}]} }, labels: { ... } Initial filter values, use plain format
cache boolean false true whether or not to use FENIX bridge cache
environment string 'develop' 'production' Server environment
lang string 'EN' 'IT' Multilingual
common object { template : { hideRemoveButton: true, hideSwitch: true, hideHeaderIcon: true } } -/td> Common selector configuration. This will override the selector configuration

Item configuration

This is the schema of a selector configuration

{
 sel_1 : { // this will appear within the result of .getValues() 
 
    classNames : "...", //custom CSS class for selector container 
     
    selector : {}, // configuration of the selector 
    
    selectors : {}, // in case of group selector  
    
    semantic : boolean, // in case of semantic group selector 
    
    cl : {}, // specifies the code-list to use as selector source 
     
    enumeration : {}, // specifies the enumeration to use as selector source 
    
    template : {}, //configuration of the template in which the selector is rendered 
     
    dependencies : {}, // in case the selector has dependencies with other selectors 
     
    format : {} // configuration for .getValues() in case is not plain 
        
    validation: {} // validation 
     
    }
}

Item

{
...
selector : { 
 
    id : "...", // id of the selector plugin to use. Check available selectors 
 
    type : "...", // additional selector configuration. Ex: id:"input", type:"text" 
 
    source : [ {value: "selector", label: "Item"} ], // static selector source. Merged to `cl` configuration 
 
    default : [...], // default selector values 
 
    disabled : false, // in case the selector is disabled by default 
 
    config : {} // wrapped lib configuration 
    
    backlist: [] // list of the code to exclude from selector 
 
 }
...
}

Code-list / Enumeration as selector source

This configuration proxies the information to D3S code-list / enumeration services

{
...
    cl : { 
    
        uid : "...", // code-list/enumeration uid 
        
        version : "...", // code-list/enumeration version 
        
        level : "...", // code-list/enumeration initial selection level 
        
        levels : "...", // starting from `level`, how many code-list/enumeration levels to include 
    
    },
    
    enumeration : {
    
        // as above 
    
    }
...
}

Template

{
...
    template : { 
    
        hideSwitch: true, // hide selector enable/disable switcher 
        
        hideTitle : true, // Hide Title, 
        
        hideDescription : true, // Hide description, 
        
        hideHeader : true, // Hide Header, 
        
        hideRemoveButton : false, // Hide remove button 
        
        title : "..." // selector title, 
        
        description : "..." // selector title, 
 
    }
...
}

Dependencies between selectors

{
...
        dependencies: {
            //@ for special selection 
            "@all": {id: "ensure_unset", event: "disable"} // obj, array of obj, 
            sel_2 : {id: "parent", event: "select"}
        },
...
}

The previous configuration as to be read as following: say this is the configuration of sel_1, it has two dependencies. The first one is a dependencies with all the selectors: when any of the selectors of the specific instance trigger the stated event, the ensure_unset callback is called. The second one, when 'sel_2' trigger the select event, call the parent callback

Available dependencies

NB: not all dependencies are compatible with all the available selectors. Check the compatibility tables.

  • min : set the payload value as min value of the selector
  • parent : refresh the selector source considering the payload value as parent code
  • focus : if the payload value is equal to the selector id, set the selector state to focused
  • ensure_unset : ensure that the payload value is not selected in the specific selector
  • disable : disable selector
  • process : use a D3P process to populate a selector. The dependency configuration will be [{id: "process", event:"...", args : { uid: <resource_uid>, version: <resource_version>, body: <place_d3p_process_here>, indexValueColumn: <number>, indexLabelColumn: <number>, payloadIncludes: [ <selector_id>, <"@all"> ]}] and if the string {{{codes}}} (NB: three brackets!) will be found within the <place_d3p_process_here> it will be replaced with the concatenation of the codes that triggered the dependency call.

Available events

NB: these are different events from filter global events

  • select : triggered when an selector's selector is selected
  • disable : triggered when an selector is disabled
  • change : triggered when an selector change its state
  • ready : triggered each selector is rendered
  • remove : triggered each selector is removed

Compatibility tables

TODO

Format

{
...
    format : { // configuration for .getValues() in case is not plain 
    
        output : "codes", // codes || enumeration || time. If format is 'fenix' 
        
        uid : "myUid", // override code-list uid config 
        
        version : "myVersion", // override code-list version config 
        
        dimension : "myDimension", // override dimension uid, default is the selector id 
    
    } 
...
}

Validation

{
    ...
    validation : { 
       mandatory : true //mandatory selector. Default false 
    }
    
...
}

Available selectors

The following are the default available selectors. The plugin registry can be extended with the pluginRegistry configuration. In order to choose a specific selector specify the correspondent id in selector.id configuratino for each selector. ## Dropdown

Wrapped lib: selectize.js

//specific configuration 
...
selector : {
 
    hideButtons : true, //hide all buttons, 
    hideSelectAllButton: true, //Hide select all button 
    hideClearAllButton : true, //Hide clear all button 
    ...
    config : {
        maxItems: 1, // Max amount of selected selectors, 
        placeholder: "Please select",
        plugins: ['remove_button'], //in combination with mode:'multi' create a 'X' button to remove selectors 
        mode: 'multi'
    }
}
...

Input

Wrapped lib: native HTML elements

//specific configuration 
...
selector : {
    ...
    type : "...", // to specify the input type. Every HTML input type is allowed 
}
...

Textarea

Wrapped lib: native HTML elements

//specific configuration 
...
selector : {
    ...
    config : {
        row: 100,
        cols: 150
    }
}
...

Range

Wrapped lib: ion.rangeSlider.js

//frequent config, check lib doc form more 
...
selector : {
    ...
    format: "YYYY/MM/DD", //any moment js format 
    config: {
        min: 100, /min range
        max: 200, // max range 
        type: "double" // range type 
    }
}
...

Sortable

Wrapped lib: sortable.js

//specific configuration 
...
selector : {
    ...
    config : {
        groups: { // Configure groups: in case source selector has parent config [{value: ".", label: "X", parent: "group1"}] 
            group1: 'Group 1', // group id and title 
            },
        selectorRender : function ( model ) { }; //custom selector render function 
        }
    }
...

Time

Wrapped lib: Bootstrap 3 Datepicker

Tree

Wrapped lib: jstree

//specific configuration 
...
selector : {
    ...
    max : 2, //max number of selectable selectors 
    lazy : true, //lazy loading of children selectors 
    hideFilter : true, //hide filter 
    hideButtons : true, //hide all buttons, 
    hideSelectAllButton: true, //Hide select all button 
    hideClearAllButton : true, //Hide clear all button 
    hideFooter : true, //hide footer 
    hideSummary : true, //Hide selection summary, 
    ...
    },
summaryRender : function ( selector ) {} // custom summary render function 
...

Groups

It is possible to define a group selector. There are two kind of group selectors:

  • standard group selector
  • semantic group selector

A standard group selector is a group of selectors in each selector is active at the same time. It is a selector that contains many selectors. This is useful, for example, when a specific information can be described with different attributes (e.g. contact information contains name, surname, role, etc.).

A semantic group selectors is a group of selectors in which only one can be active. This is useful, for example, when a specific information can be selected in different manners (e.g. time selection, with a calendar or a range).

Filter layout definition

It is possible to specify where a selector has to be rendered. FENIX Filter looks for data-selector=":id" or data-group=":id" where :id is the selector/group id within its el. In case no container will be found, FENIX filter will add (append/prepend according to configuration) the container to its el.

It is possible to pass an HTML template using the template configuration that will be attached to the el.

Demo

Browse the demo folder to visualize a showcase of the available selectors and configuration examples.

API

//This is an example 
filter.getValues("fenix");
  • filter.getValues(format, includedItems) : get filter values according to the specific format. Available format are 'plain' (default and optional), includedItems filter the selectors to include in the result catalog, fenix. For more info che the fx-common/utils doc.
  • filter.setValues(values) : set filter values. The syntax is the same of filter.getValues()
  • filter.on(event, callback[, context]) : pub/sub
  • filter.dispose() : dispose the filter instance
  • filter.reset() : reset filter instance
  • filter.printDefaultSelection() : print default selection of filter.
  • filter.add( selectors ) : add dynamically selectors to filter
  • filter.remove( selectors ) : remove dynamically selectors from filter
  • filter.clear() : clear the filter from all selectors
  • filter.setSources( sources ) : set sources to specifies selectors. sources is an object: keys are the selectors id, values are sources in selector.source format

Events

  • remove : triggered when a selector is removed
  • ready : triggered when the filter and all its initial selectors are rendered
  • change : triggered when a selector state changes (selector selector selected, selector disabled, ecc...)

Output formats

In order to have different output format pass the desired format to filter.getValue( format ) function.

Plain

Default output format.

 
{
    values : {
        sel_1 : ["cod_1"],
        sel_2 : ["fx"]
    },
    labels : {
        sel_1 : {
            cod_1 : "Code One"
        },
        sel_2 : {
            fx : "FENIX"
        }
    },
    valid : true
}

Where the keyset of values and labels is the set of selector ids of the filter. values contains the selected values, labels the labels of selected values. If a selector has no selected value, it is excluded from result.

FENIX

If proper format configuration for each selector is provided, return a D3P process body with the selected values.

Catalog

If proper format configuration for each selector is provided, return a D3S filter body with the selected values.