Developed by at The Children's Hospital of Philadelphia Research Institute

Custom Controls in Cilantro

Byron Ruth · February 23 2014

This is the next article in the Configuring Cilantro Like a Pro series. To recap, a configuration system has been integrated into Cilantro to make it simple for application developers to customize components in Cilantro to suit their data or domain needs. The first article discussed setting configuration options, creating and setting custom templates, and what Cilantro calls "logical data types". This article gives an overview and example of creating a custom query control.

What is a query control?

A query control is the interface for setting query conditions. The minimum data that make up a query condition are the concept, field, operator and value. The concept and field ids uniquely identify a query condition and are set by the control itself, so the end user only has to supply the operator and value. In the screenshot from the first article, the input boxes above the chart represent a query control for the field Hemoglobin.

hemoglobin concept

Since hemoglobin is numerical data and has a continuous range, two input boxes are used to allow setting the lower and upper bound of the range. When set, these inputs make up the value of the query condition. The dropdown with a value of "between" defines the operator of the query condition.

As an example, if the lower bound was set to 10, the query condition may result in this:

{
    concept: 10,
    field: 5,
    operator: 'between',
    value: [10, 6400]
}

Built-in Controls

Most data types have a common way to be represented in a query interface. Shown above, continuous numerical data requires an operator and lower and/or upper bound inputs. Categorical data is typically represented as a set of choices that can be selected. A search box is generally most fitting for free-text data.

For this reason, Cilantro comes with a set of built-in controls for each major logical data type. They currently include:

  • date and number - range-based query controls (like in the screenshot above)
  • infograph - list of bars for representing categorical data
  • search - control for searching and browsing available free-text choices

Two simpler controls are included for categorical data, singleSelectionList and multiSelectionList which are standard select and multi-select form fields.

Creating a custom control

Although the built-in controls have proven to be suitable for most cases, custom controls are sometimes required for expressing domain-specific assumptions. As mentioned in the previous article, a primary driver of recent Cilantro development is Varify, the open source clinical DNA sequencing analysis application built on Harvest. Varify defines quite a few custom controls to better facilitate the clinical analysis workflow as well as integration of some domain-specific assumptions for making the query controls easier to use.

We will walk through creating a real-world control defined in Varify that enables querying variants by the SIFT prediction score. For context, a SIFT prediction score is a number between 0 and 1 where a score less than or equal to 0.5 denotes a variant has a damaging effect, while a score greater than 0.5 has a tolerated (benign) effect.

Not all users may know the numeric cutoff; furthermore requiring the user to enter an explicit score does not make sense since all that matters is whether a score falls in one of the two categories. A more suitable control would be a dropdown that contains the choices "Damaging" or "Tolerated" that the end user can choose from.

Before implementing the specifics of the SIFT control, let's quickly go over the requirements of a control and how it fits in to the rest of Cilantro. All controls are views and must inherit from one of the following base control classes (each correspond to a Marionette view class):

  • ControlView
  • ControlItemView
  • ControlCollectionView
  • ControlCompositeView
  • ControlLayout

In most cases the ControlLayout class should be used to provide the most flexibility for laying all the UI components in the control. All controls must be able to do two things, get the state of the UI to return a query condition and set the state of the UI given a query condition. The control classes all implement a get and set method that do nothing by default.

As mentioned above, the field and concept ids uniquely identify a query condition and are set by the control itself. This is because controls are contained within a FieldForm which is contained in a ConceptForm. This hierarchy corresponds to how fields are associated to concepts in the Harvest data model. Since this is the case, a control really only needs to worry about the operator and value and thus only needs to implement the getValue, setValue, getOperator and setOperator methods (which are used internally by the get and set methods).

Given what we know about the SIFT prediction score, we can first create the template to represent the control. As mentioned there are two possible categories the prediction score is rated at.

<select>
    <option value="damaging">Damaging</option>
    <option value="tolerated">Tolerated</option>
</select>

The first thing to do is set the template, define the reused UI elements and any events that we need to handle.

var SiftControl = c.ui.ControlLayout({
    template: 'sift-control',

    ui: {
        'select': 'select',
    },

    events: {
        'change select': 'change'
    }
});

As mentioned in templates API, the template name corresponds to a compiled template registered in the template store. This can be done a number of ways, either set in the cilantro configuration object before Cilantro loads or programmatically before the session starts. See the first article for a reminder on how to do this.

The ui property is a Marionette feature which is a map of identifiers to CSS selectors scoped within this control. That is, once the control is rendered, we can refer to the select DOM element (as defined in the template) using the ui property, e.g. control.ui.select. This will be used below.

The events property is a Backbone feature which is a map of event + selector to the function handler to be called when the event is triggered. In this case, every time the change event is triggered by the select element, we want to call the change method on the control view. The change method is already defined by the control classes so we do not need to define it here.

Now that we have our helper code defined, we can now focus on the relevant get* and set* methods. Since the operator is what toggles between the "damaging" vs. "tolerated" category, the value is actually fixed in this case. Therefore our getValue method looks like this and no setValue needs to be implemented:

    ...

    getValue: function() {
        return 0.5;
    }
    ...

The next task is getting the operator from the state of the UI. This can be done using a simple if/else block. As a side note, lte means "less than or equal to" and gt means "greater than" and they map to Django's field lookup operators.

    ...
    getOperator: function() {
        if (this.ui.select.val() === 'damaging') {
            return 'lte';
        } else {
            return 'gt';
        }
    }
    ...

The final method that needs to be implemented is the setOperator which takes an operator and must update the UI to represent the state.

    ...
    setOperator: function(operator) {
        if (operator === 'lte') {
            this.ui.select.val('damaging');
        } else if (operator == 'gt') {
            this.ui.select.val('tolerated');
        }
    }
    ...

The final control view looks like this:

var SiftControl = c.ui.ControlLayout({
    template: 'sift-control',

    ui: {
        'select': 'select',
    },

    events: {
        'change select': 'change'
    },

    getValue: function() {
        return 0.5;
    },

    getOperator: function() {
        if (this.ui.select.val() === 'damaging') {
            return 'lte';
        } else {
            return 'gt';
        }
    },

    setOperator: function(operator) {
        if (operator === 'lte') {
            this.ui.select.val('damaging');
        } else if (operator == 'gt') {
            this.ui.select.val('tolerated');
        }
    }
});

Integrating a custom control

The controls API provides a store just like the templates API which makes it simple for registering custom controls.

c.controls.set('sift', SiftControl);

To use it with the SIFT field, the instance configuration option can be set:

c.config.set('fields.instances.64.forms.controls', ['sift']);

In this particular example, we are assuming the SIFT field has a surrogate identifier of 64.

What we end up with (not surprisingly) is this basic select box. Although not fancy, it serves it's purpose for hiding complexity in Varify's workflow.

sift control

Conclusion

A core goal of Harvest is to facilitate data discovery by using the data itself to drive the application. This requires that the interfaces for interacting with the data are suitable for the domain and the data itself. Having the ability to create custom controls and quickly integrate them in the application makes Harvest as a whole that much more powerful for rapidly developing domain-specific applications.

We believe that custom controls are going be one of the primary "selling points" when evaluating Harvest for future projects. As a result, we've decided to begin development of a repository (yet to be named) for storing custom controls for different use cases. This repository will be community-driven and pull requests can be submitted at any time for integrating a custom control. For the time being any ideas for query controls can be added to the query control wishlist.