FENIX Filter

var Filter = require('fx-filter/start');

var filter = new Filter({
        el : "#filter",
        items : {
            sel_1 : { /* selector configuration goes here */ }, 
            sel_2 : { ... }
        }
    });

Configuration

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

Parameter	Type	Default Value	Example	Description
el	CSS3 Selector/JavaScript DOM element/jQuery DOM element	-	"#container"	component container
items	Object	-	-	The filter instance's selectors to render. Check the Selector configuration.
template	HTML	-	-	The filter template to render selector with a specific layout.
pluginRegistry	object	{ 'dropdown': { path: selectorPath + 'dropdown' }, 'tree': { path: selectorPath + 'tree' }, 'input': { path: selectorPath + 'input' }, 'range': { path: selectorPath + 'range' }, 'time': { path: selectorPath + 'time' }, 'sortable': { path: selectorPath + 'sortable' } }	-	Keyset: plugins' ids. Value: object. path: plugin module path
focusedSelectorClassName	string	"focused"	"my-focused"	CSS class applied to make a selector focused
mandatorySelectorClassName	string	"mandatory"	"my-mandatory"	CSS class applied to make a selector mandatory
disabledSelectorClassName	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 Selector/JavaScript DOM element/jQuery DOM element	-	"#summary-container"	Container of the summary
summaryRender	function	-	-	Custom renderer for summary
values	Object	-	{ indicator : ["cod_001"], year : [{value: "2000", parent: "from"}, {value: "2016", parent: "to"}]}	Custom renderer for summary
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

Selector configuration

This is the schema of a selector configuration

{
 sel_1 : { // this will appear within the result of .getValues()
 
    className : "...", //custom CSS class for selector container
     
    selector : {}, // configuration of the selector
    
    selectors : {}, // in case of semantic 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
     
    }
}

Selector

{
...
selector : { 
 
    id : "...", // id of the selector plugin to use. Check available selectors
 
    type : "...", // additional selector configuration. Ex: id:"input", type:"text"
 
    source : [ {value: "item", 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
        
        hideHeader : true, // Hide Header,
        
        hideRemoveButton : false, // Hide remove button
        
        title : "..." // 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}} 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 item is selected
• disable : triggered when an selector is disabled

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 item.

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 items,
        placeholder: "Please select",
        plugins: ['remove_button'], //in combination with mode:'multi' create a 'X' button to remove items
        mode: 'multi'
    }
}
...

Input

Wrapped lib: native HTML elements

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

Range

Wrapped lib: ion.rangeSlider.js

//frequent config, check lib doc form more
...
selector : {
    ...
    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 item has parent config [{value: ".", label: "X", parent: "group1"}]
            group1: 'Group 1', // group id and title
            },
        itemRender : function ( model ) { }; //custom item render function
        }
    }
...

Time

Wrapped lib: Bootstrap 3 Datepicker

Tree

Wrapped lib: jstree

//specific configuration
...
selector : {
    ...
    max : 2, //max number of selectable items
    lazy : true, //lazy loading of children items
    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 ( item ) {} // custom summary render function
...

Semantic

It is possible to define a semantic selector. A semantic selector 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-semantic=":id" where :id is the selector/semantic 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, includedSelectors) : get filter values according to the specific format. Available format are 'plain' (default and optional), includedSelectors 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 item 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.