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.