Configure column refiner panels

Here, we will look at configuring the grid column refiner panels. The refiner panels are used to filter and sort data contained in grid columns by specifying criteria or conditions. This feature is facilitated by Caplin Refiner. For detailed information on how this is done, see Sorting and Filtering. Caplin Trader provides three refiner panel variants: text, numerical ranges and date ranges. This page describes how to configure and customise these panels to suit your needs. For information on how to create new panel variants, for example to support other data types, seeCreate a custom refiner panel.

1. Basic configuration

Example configurations for the text, numeric and date refiner panels are as follows. This should be included in a rendererDefinitions.xml file in the appropriate bladeset in your app. The renderers should then be referenced by their type as the headerRenderer of the grid columns in your gridDefinitions.xml file. The date formats may need to be updated to match the unformatted dates used by your grid. It is also recommended that any existing renderers that format dates be updated to use the br.formatting.LocalisedDateFormatter.

<renderer type="caplinx.fxtrader.textRefiner">
    <control className="caplin.control.basic.TextControl">
        <handler className="caplin.element.handler.grid.GridColumnRefinerRendererHandler">
            <attribute name="component" value="caplin.grid.refine.text-refine-component"/>
            <attribute name="filterType" value="WILDCARD"/>
        </handler>
    </control>
</renderer>

<renderer type="caplinx.fxtrader.numericRefiner">
    <control className="caplin.control.basic.TextControl">
        <handler className="caplin.element.handler.grid.GridColumnRefinerRendererHandler">
            <attribute name="component" value="caplin.grid.refine.numeric-refine-component"/>
        </handler>
    </control>
    <upstream>
        <transform className="caplin.element.parser.LocalisedAmountParser"/>
    </upstream>
</renderer>

<renderer type="caplinx.fxtrader.dateRefiner">
    <control className="caplin.control.basic.TextControl">
        <handler className="caplin.element.handler.grid.GridColumnRefinerRendererHandler">
            <attribute name="component" value="caplin.grid.refine.date-refine-component"/>
        </handler>
    </control>
    <upstream>
        <transform className="br.parsing.LocalisedDateParser">
            <attribute name="inputFormats" valueType="json" value='["ll","L","l","MMM","MMMM","MMM YYYY","MMMM YYYY","YYYY"]'></attribute>
            <attribute name="outputFormat" value="YYYYMMDD"></attribute>
        </transform>
    </upstream>
    <downstream>
        <transform className="br.formatting.LocalisedDateFormatter">
            <attribute name="inputFormat" value="YYYYMMDD" />
            <attribute name="outputFormat" value="ll" />
        </transform>
    </downstream>
</renderer>

2. Changing text in the panels

If you want to change any of the text on the panels, for example the unsort button, you can simply override the i18n key by adding a new i18n definition in the .properties file of your aspect. For example, in this file default-aspect/resources/i18n/en/en.properties you would add the following:

ct.grid.refine.sort.none=no sort

This will affect all sorting panels in your app. If you wish to change the label only for specific grid columns, you’ll need to follow the instructions in the next part.

There are actually two templates for the sort buttons; one is used with text and numerical ranges — caplin.grid.refine.default-sorting — and another is used with date ranges — caplin.grid.refine.date-sorting. These are identical except for having different i18n keys.

3. Overriding a template

In this part, you will create a new sorting template to be used globally by all text refiner panels in your application. Say you wanted to make a substantial change to a panel variant, like changing the order of the sorting buttons on the panel so that unsort is displayed first - you’ll need to do a few things:

First, create a new template. In this case we will need to copy the default template caplin.grid.refine.default-sorting and place it inside of a HTML file somewhere in our app, say in the fxtrader bladeset:

<div id="caplinx.fxtrader.refine.sorting">
    <div class="RefinerPanel-buttonGroupLeft">
        <button type="button" class="RefinerPanel-button RefinerPanel-button--sort"
            data-bind="click: setSortOrderNone, css: {'is-active': sortOrderNone}">
            @{ct.grid.refine.sort.none}</button>
        <button type="button" class="RefinerPanel-button RefinerPanel-button--sort"
            data-bind="click: setSortOrderAsc, css: {'is-active': sortOrderAsc}">
            @{ct.grid.refine.sort.ascending}</button>
        <button type="button" class="RefinerPanel-button RefinerPanel-button--sort"
            data-bind="click: setSortOrderDesc, css: {'is-active': sortOrderDesc}">
            @{ct.grid.refine.sort.descending}</button>
    </div>
</div>

In this example we simply re-arranged the buttons; however your own template can be completely different. If you wanted to change the i18n keys or include other elements, you could do that here as well.

The TextRefinerComponentFactory, which creates our GridColumnRefiner component along with its sorting and filtering nodes, uses a default sorting template. Therefore in order to set up a new template, you will need need to create your own component factory. To do this, simply copy the entire TextRefinerComponentFactory class into the app, and replace the default sorting template ‘caplin.grid.refine.default-sorting’ with a new template ‘caplinx.fxtrader.refine.sorting’. The filtering template this component uses can also be changed in this factory.

var ComponentFactory = require('caplin/component/factory/ComponentFactory');
var GenericRefinerPresentationModel = require('caplin/grid/refine/component/presenter/GenericRefinerPresentationModel');
var DefaultSortingPresentationNode = require('caplin/grid/refine/component/presenter/DefaultSortingPresentationNode');
var TextFilteringPresentationNode = require('caplin/grid/refine/component/presenter/TextFilteringPresentationNode');
var GridColumnRefinerPresenterComponent = require('caplin/grid/refine/component/GridColumnRefinerPresenterComponent');
var XmlParser = require('br/util/XmlParser');
var topiarist = require('topiarist');

function AlternateTextRefinerComponentFactory() {}

topiarist.implement(AlternateTextRefinerComponentFactory, ComponentFactory);

AlternateTextRefinerComponentFactory.prototype.createFromXml = function(xml) {
    var parsed = XmlParser.parse(xml);
    var filterType = parsed.getAttribute('filterType');
    var sortingNode = new DefaultSortingPresentationNode('caplinx.fxtrader.refine.sorting');
    var filteringNode = new TextFilteringPresentationNode('caplin.grid.refine.text-filtering', filterType);
    var presentationModel = new GenericRefinerPresentationModel({
        sort: sortingNode,
        filter: filteringNode
    });

    return new GridColumnRefinerPresenterComponent('caplin.grid.refine.refine-panel', presentationModel);
};

caplinx.fxtrader.AlternateTextRefinerComponentFactory = AlternateTextRefinerComponentFactory;

Finally, you will override the alias for the component factory so that the newly customised text refiner panel is used globally. Add the following to your aspect alias.xml, making sure to add it to the appropriate aliases.xml of the bundle that you intend to use:

<alias name="caplin.grid.refine.text-refine-component" class="caplinx.fxtrader.AlternateTextRefinerComponentFactory" />

Now for any columns in your app that use the caplinx.fxtrader.textRefiner header renderer, the unsort button will appear first.