Initial draft of "Custom Controls in Cilantro" #43

Merged
merged 4 commits into from Feb 26, 2014

Conversation

Projects
None yet
3 participants
Owner

bruth commented Feb 24, 2014

Fix #41

+date: 2014-02-23
+---
+
+This is the next article in the [Configuring Cilantro Like a Pro]({% post_url 2014-02-16-configuring-cilantro-like-a-pro %}) series. To recap, a configuration system is being 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.
@naegelyd

naegelyd Feb 24, 2014

Collaborator

Change ...is being integrated into Cilantro... to ...has been integrated into Cilantro... since the configuration system is there already.

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

naegelyd Feb 24, 2014

Collaborator

Change ...continous numerical requires... to ...continuous numerical data requires.... This adds clarity and fixes misspelling of continous.

@naegelyd

naegelyd Feb 24, 2014

Collaborator

Change A search box if... to A search box is...

@naegelyd

naegelyd Feb 24, 2014

Collaborator

Consider changing ...requires an operator and lower and upper bound inputs. to ...requires an operator and lower and/or upper bound inputs. since they technically don't require both a lower AND upper bound but can be used with just one of those values.

+
+### 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](https://github.com/cbmi/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 some domain-specific assumptions for making the query controls easier to use.
@naegelyd

naegelyd Feb 24, 2014

Collaborator

Change ...workflow as well as integration some domain-specific... to ...workflow as well as integration of some domain-specific....

+- `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 and 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.
@naegelyd

naegelyd Feb 24, 2014

Collaborator

Change ...the state of the UI and return a query condition... to ...the state of the UI to return a query condition... to remove repetitive ands.

+
+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 and 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 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).
@naegelyd

naegelyd Feb 24, 2014

Collaborator

Change Since this is case... to Since this is the case...

+
+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 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 rated at.
@naegelyd

naegelyd Feb 24, 2014

Collaborator

Change ...prediction score rated at. to ...prediction score is rated at.

+ ...
+```
+
+The next task is handle 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"
@naegelyd

naegelyd Feb 24, 2014

Collaborator

Consider adding a link out to Avocado and show what operators are valid and what they mean.

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

naegelyd Feb 24, 2014

Collaborator

Change ...which takes operator and... to ...which takes an operator and...

+To use it with the SIFT field, the instance configuration option can be set:
+
+```javascript
+c.config.set('fields.instances.64.forms.controls', ['sift']);
@naegelyd

naegelyd Feb 24, 2014

Collaborator

Consider explaining what 64 is here if this was not already discussed elsewhere.

+
+We will walk through creating a real-world control defined in Varify that enables querying variants by the [SIFT prediction score](http://sift.jcvi.org/). 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.
+
+Although some geneticists may know these cutoffs, it is certainly not first-hand knowledge. 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.
@murphyke

murphyke Feb 25, 2014

Owner

The first sentence might be better as "Not all users may know the numeric cutoff; furthermore, ..."

+ ...
+```
+
+The next task is handle 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](https://docs.djangoproject.com/en/1.5/ref/models/querysets/#field-lookups).
@murphyke

murphyke Feb 25, 2014

Owner

Typo in first sentence. Maybe "The next task is getting ..." or equivalent?

+
+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 or 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](https://github.com/cbmi/cilantro/issues/437).
@murphyke

murphyke Feb 25, 2014

Owner

Typo: "one or" should be "one of".

bruth added a commit that referenced this pull request Feb 26, 2014

Merge pull request #43 from cbmi/issue-41
Initial draft of "Custom Controls in Cilantro"

@bruth bruth merged commit be62e48 into gh-pages Feb 26, 2014

@bruth bruth deleted the issue-41 branch Feb 26, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment