From 60526c292ef7b06b8e1022b60a078d58082e61ef Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Thu, 15 Dec 2016 14:45:55 +0000 Subject: [PATCH 001/102] Update README --- README | 185 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 182 insertions(+), 3 deletions(-) diff --git a/README b/README index 769e6ad4..44a574df 100644 --- a/README +++ b/README @@ -1,9 +1,188 @@ +# Genoverse + Genoverse is a portable, customizable, back-end independent JavaScript and HTML5 based genome browser which allows the user to explore data in a dynamic and interactive manner. Data is visualized in the browser, meaning Genoverse can be installed on any website and show data from a wide range of online or local sources. -Genoverse works with a variety of formats, such as XML, JSON, BED, VCF, GFF, GFF3 or delimited text files, and can be customized to parse and display any data source as required. +Genoverse works with a variety of formats, such as XML, JSON, BED, BAM, VCF, GFF, or delimited text files, and can be customized to parse and display any data source as required. + +Genoverse works using a system of **tracks** - essentially horizontal sections of the genome browser which display **features** - genes, variants, etc. with defined genomic start and end points. Each track has its own data, set stored in a **model**, a method for displaying that data, stored in a **view**, and a **controller** to manage the creation of DOM elements, and user interactions with them. + +Tracks can have multiple models and views, which allows for switching between displays at different zoom levels. An example of this would be a track where you show genes when looking at a large region of a chromosome, and then switch to showing transcripts as the user zooms in. + +In addition to this, Genoverse has a set of plugins, which allow additional functionality beyond the core genome browser. These include a control panel for adding and removing tracks, and interacting with the browser more easily, a way to add controls to each individual track, and a way to enable drag and drop of local data files onto the genome browser. + +## Installation + +1. Download the latest version from GitHub + ``` + git clone git@github.com:wtsi-web/Genoverse.git + ``` + +2. Embed Genoverse using either + ```html + + ``` + + which comes with jQuery and jQuery UI included, or + ```html + + ``` + + if you already have them in the page + +3. Add a script tag or JavaScript file which initializes Genoverse, e.g. + ```html + + ``` + +## Configuration + +Genoverse has a large number of configurable properties, in order to allow customization. A basic example with two tracks (a scalebar and some genes) and no plugins would be + +```js +var genoverse = new Genoverse({ + genome: 'grch38', + tracks: [ Genoverse.Track.Scalebar, Genoverse.Track.Gene ] +}); +``` + +The following properties can be provided to the constructor for Genoverse: + +#### DOM element + +container (default `undefined`) +: A DOM node, jQuery selector, or string to create a jQuery selector (e.g. `"#genoverse"`) inside which the instance of Genoverse will be created. +If `undefined`, a `
` element will be appended to `document.body`. + +width (default `1000`) +: The width that the `container` DOM element will be + +#### Genomic coordinates + +chr (default `1`) +: A string or number defining the initial chromosome to display + +start (default `1`) +: A string or number defining the initial start position + +end (default `1000000`) +: A string or number defining the initial end position + +genome (default `undefined`) +: The genome to be used. Can be: + + - an object with keys of the number/letter/name of the chromosomes, and values in the form `{ "size": 10000 }`. + Additionally an array of bands can be supplied for each chromosome for drawing purposes - see [js/genomes/grch38.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/js/genomes/grch38.js) for an example. + - a string (e.g. `"grch38"`) which will be used to obtain a javascript file from the [js/genomes](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/genomes) directory + - `undefined`, in which case `chromosomeSize` **MUST** be set (see below) + +chromosomeSize (default `undefined`) +: If `genome` not is provided, `chromosomeSize` **MUST** be set to the length of the chromosome. +If `genome` is provided, `chromosomeSize` will be set to the chromosome's `size` property, as defined by the genome object. + +#### What is displayed + +tracks (default `[]`) +: An array of `Genoverse.Track` definitions to be displayed + +highlights (default `[]`) +: An array of regions to highlight, in the form +`{ "start": 100, "end", 200, "label": "My highlight", "removable": false }`. +`label` defaults to "start-end" (e.g. "100-200") if not provided. +If `removable === false`, the highlight cannot be removed. + +plugins (default `[]`) +: An array of `Genoverse.Plugins` to be used (from the [js/plugins](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/plugins) directory), e.g. +`[ "controlPanel", "trackControls" ]` +The strings in this array correspond to the namespace of each plugin, which are the same as their file names. + +#### Interaction with the URL + +urlParamTemplate (default `"r=__CHR__:__START__-__END__"`) +: The template used to alter the web browser's URL. Should contain placeholders for chr, start and end. +If `false` or empty string, no changes will be made to the URL when navigation occurs. + +useHash (default `undefined`) +: Determines how the browser's URL gets updated on navigation. Can be: + + - `true` - use `window.location.hash` + - `false` - use `window.history.pushState` + - `undefined` - use `window.history.pushState` if present in the browser, else use `window.location.hash` + +#### User actions + +dragAction (default `"scroll"`) +: The action performed when a mouse drag happens on the genome browser. Can be: + + - `"scroll"` - Move the browser left or right + - `"select"` - Select the region + - `"off"` - Do nothing + +wheelAction (default `"off"`) +: The action performed when a mouse drag happens on the genome browser. Can be: + + - `"zoom"` - Zoom in or out + - `"off"` - Do nothing + +isStatic (default `false`) +: If `true`, will stop drag, select and zoom actions occurring + +#### Saving user configurations + +saveable (default `false`) +: If `true`, track configuration and ordering will be saved in `window.sessionStorage`/`window.localStorage` (defined by `storageType`, below) so that users will see the same display when they refresh the page + +storageType (default `"sessionStorage"`) +: The storage object used to save track configuration. Set to `"localStorage"` for permanence. +See Mozilla's [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) and [localStorage](https://developer.mozilla.org/en/docs/Web/API/Window/localStorage) documentation for further details. + +saveKey (default empty string) +: The default key used in configuration storage is `"genoverse"`. `saveKey` will be appended to this to allow different configurations for different instances of Genoverse. + +#### Default track display settings + +autoHideMessages (default `true`) +: Determines whether to collapse track messages (toggleable pop-outs on the left side of a track's image) by default when the user interacts with the genome browser + +trackAutoHeight (default `false`) +: Determines whether to automatically resize tracks to show all their features (can be overridden by `track.autoHeight`) + +hideEmptyTracks (default `true`) +: Determines whether to hide an automatically resized tracks if it has no features, or to show it empty (can be overridden by `track.hideEmpty`) + +## Plugins + +Genoverse has a number of plugins to extend its core functionality. These plugins are as follows: + +controlPanel +: Adds + + - a "Tracks" button to the top left of the genome browser, which when clicked displays a list of enabled and available tracks, to be added or removed. + - a suite of buttons to the right of the genome browser, for scrolling, zooming and selecting regions of the genome + - the `karyotype` plugin + +karyotype +: Adds an ideogram of the chromosome being used by the genome browser, with a marker showing the currently viewed region. The marker and be dragged and resized to change region, and chromosome bands can be jumped to by clicked on them. + +trackControls +: Adds a toggleable pop-out menu to the right side of the track, containing buttons to view track information, remove the track, toggle the track between fixed height and auto resizing, and change track filters/configuration settings, if there are any. + +resizer +: Adds a draggable handle to the bottom of each track, to allow the user to resize it to their desired height. If this plugin is not in use, tracks can only be resized to show all features currently in view. + +focusRegion +: Adds a button to the control panel to move the viewpoint to a particular region of the genome. The `controlPanel` plugin will be added if not already in use. + +fullscreen +: Adds a button to the control panel to enable the toggling of a full screen view of the genome browser. The `controlPanel` plugin will be added if not already in use. -More information coming soon. If you have any questions, please contact info@genoverse.org +tooltips +: Adds a button to the control panel to enable the toggling of a help tooltips for the genome browser. The `controlPanel` plugin will be added if not already in use. -Example: http://genoverse.org +fileDrop +: Adds the ability to drag and drop a local data file onto the genome browser, and have its data displayed as a track. From 6bd86ea44c9140158e5979db578560c56204ea2d Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Thu, 15 Dec 2016 14:46:25 +0000 Subject: [PATCH 002/102] Rename README to README.md --- README => README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename README => README.md (100%) diff --git a/README b/README.md similarity index 100% rename from README rename to README.md From 26875f7ea93543f1414c3f014abb9883c32d7410 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Thu, 15 Dec 2016 14:56:43 +0000 Subject: [PATCH 003/102] Update README.md --- README.md | 160 +++++++++++++++++++++++++++--------------------------- 1 file changed, 80 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index 44a574df..4f0e1a72 100644 --- a/README.md +++ b/README.md @@ -53,136 +53,136 @@ var genoverse = new Genoverse({ The following properties can be provided to the constructor for Genoverse: -#### DOM element +### DOM element -container (default `undefined`) -: A DOM node, jQuery selector, or string to create a jQuery selector (e.g. `"#genoverse"`) inside which the instance of Genoverse will be created. +#### container (default `undefined`) +A DOM node, jQuery selector, or string to create a jQuery selector (e.g. `"#genoverse"`) inside which the instance of Genoverse will be created. If `undefined`, a `
` element will be appended to `document.body`. -width (default `1000`) -: The width that the `container` DOM element will be +#### width (default `1000`) +The width that the `container` DOM element will be -#### Genomic coordinates +### Genomic coordinates -chr (default `1`) -: A string or number defining the initial chromosome to display +#### chr (default `1`) +A string or number defining the initial chromosome to display -start (default `1`) -: A string or number defining the initial start position +#### start (default `1`) +A string or number defining the initial start position -end (default `1000000`) -: A string or number defining the initial end position +#### end (default `1000000`) +A string or number defining the initial end position -genome (default `undefined`) -: The genome to be used. Can be: +#### genome (default `undefined`) +The genome to be used. Can be: - - an object with keys of the number/letter/name of the chromosomes, and values in the form `{ "size": 10000 }`. - Additionally an array of bands can be supplied for each chromosome for drawing purposes - see [js/genomes/grch38.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/js/genomes/grch38.js) for an example. - - a string (e.g. `"grch38"`) which will be used to obtain a javascript file from the [js/genomes](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/genomes) directory - - `undefined`, in which case `chromosomeSize` **MUST** be set (see below) +- an object with keys of the number/letter/name of the chromosomes, and values in the form `{ "size": 10000 }`. +Additionally an array of bands can be supplied for each chromosome for drawing purposes - see [js/genomes/grch38.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/js/genomes/grch38.js) for an example. +- a string (e.g. `"grch38"`) which will be used to obtain a javascript file from the [js/genomes](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/genomes) directory +- `undefined`, in which case `chromosomeSize` **MUST** be set (see below) -chromosomeSize (default `undefined`) -: If `genome` not is provided, `chromosomeSize` **MUST** be set to the length of the chromosome. +#### chromosomeSize (default `undefined`) +If `genome` not is provided, `chromosomeSize` **MUST** be set to the length of the chromosome. If `genome` is provided, `chromosomeSize` will be set to the chromosome's `size` property, as defined by the genome object. -#### What is displayed +### What is displayed -tracks (default `[]`) -: An array of `Genoverse.Track` definitions to be displayed +#### tracks (default `[]`) +An array of `Genoverse.Track` definitions to be displayed -highlights (default `[]`) -: An array of regions to highlight, in the form +#### highlights (default `[]`) +An array of regions to highlight, in the form `{ "start": 100, "end", 200, "label": "My highlight", "removable": false }`. `label` defaults to "start-end" (e.g. "100-200") if not provided. If `removable === false`, the highlight cannot be removed. -plugins (default `[]`) -: An array of `Genoverse.Plugins` to be used (from the [js/plugins](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/plugins) directory), e.g. +#### plugins (default `[]`) +An array of `Genoverse.Plugins` to be used (from the [js/plugins](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/plugins) directory), e.g. `[ "controlPanel", "trackControls" ]` The strings in this array correspond to the namespace of each plugin, which are the same as their file names. -#### Interaction with the URL +### Interaction with the URL -urlParamTemplate (default `"r=__CHR__:__START__-__END__"`) -: The template used to alter the web browser's URL. Should contain placeholders for chr, start and end. +#### urlParamTemplate (default `"r=__CHR__:__START__-__END__"`) +The template used to alter the web browser's URL. Should contain placeholders for chr, start and end. If `false` or empty string, no changes will be made to the URL when navigation occurs. -useHash (default `undefined`) -: Determines how the browser's URL gets updated on navigation. Can be: +#### useHash (default `undefined`) +Determines how the browser's URL gets updated on navigation. Can be: - - `true` - use `window.location.hash` - - `false` - use `window.history.pushState` - - `undefined` - use `window.history.pushState` if present in the browser, else use `window.location.hash` +- `true` - use `window.location.hash` +- `false` - use `window.history.pushState` +- `undefined` - use `window.history.pushState` if present in the browser, else use `window.location.hash` -#### User actions +### User actions -dragAction (default `"scroll"`) -: The action performed when a mouse drag happens on the genome browser. Can be: +#### dragAction (default `"scroll"`) +The action performed when a mouse drag happens on the genome browser. Can be: - - `"scroll"` - Move the browser left or right - - `"select"` - Select the region - - `"off"` - Do nothing +- `"scroll"` - Move the browser left or right +- `"select"` - Select the region +- `"off"` - Do nothing -wheelAction (default `"off"`) -: The action performed when a mouse drag happens on the genome browser. Can be: +#### wheelAction (default `"off"`) +The action performed when a mouse drag happens on the genome browser. Can be: - - `"zoom"` - Zoom in or out - - `"off"` - Do nothing +- `"zoom"` - Zoom in or out +- `"off"` - Do nothing -isStatic (default `false`) -: If `true`, will stop drag, select and zoom actions occurring +#### isStatic (default `false`) +If `true`, will stop drag, select and zoom actions occurring -#### Saving user configurations +### Saving user configurations -saveable (default `false`) -: If `true`, track configuration and ordering will be saved in `window.sessionStorage`/`window.localStorage` (defined by `storageType`, below) so that users will see the same display when they refresh the page +#### saveable (default `false`) +If `true`, track configuration and ordering will be saved in `window.sessionStorage`/`window.localStorage` (defined by `storageType`, below) so that users will see the same display when they refresh the page -storageType (default `"sessionStorage"`) -: The storage object used to save track configuration. Set to `"localStorage"` for permanence. +#### storageType (default `"sessionStorage"`) +The storage object used to save track configuration. Set to `"localStorage"` for permanence. See Mozilla's [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) and [localStorage](https://developer.mozilla.org/en/docs/Web/API/Window/localStorage) documentation for further details. -saveKey (default empty string) -: The default key used in configuration storage is `"genoverse"`. `saveKey` will be appended to this to allow different configurations for different instances of Genoverse. +#### saveKey (default empty string) +The default key used in configuration storage is `"genoverse"`. `saveKey` will be appended to this to allow different configurations for different instances of Genoverse. -#### Default track display settings +### Default track display settings -autoHideMessages (default `true`) -: Determines whether to collapse track messages (toggleable pop-outs on the left side of a track's image) by default when the user interacts with the genome browser +#### autoHideMessages (default `true`) +Determines whether to collapse track messages (toggleable pop-outs on the left side of a track's image) by default when the user interacts with the genome browser -trackAutoHeight (default `false`) -: Determines whether to automatically resize tracks to show all their features (can be overridden by `track.autoHeight`) +#### trackAutoHeight (default `false`) +Determines whether to automatically resize tracks to show all their features (can be overridden by `track.autoHeight`) -hideEmptyTracks (default `true`) -: Determines whether to hide an automatically resized tracks if it has no features, or to show it empty (can be overridden by `track.hideEmpty`) +#### hideEmptyTracks (default `true`) +Determines whether to hide an automatically resized tracks if it has no features, or to show it empty (can be overridden by `track.hideEmpty`) ## Plugins Genoverse has a number of plugins to extend its core functionality. These plugins are as follows: -controlPanel -: Adds +#### controlPanel +Adds - - a "Tracks" button to the top left of the genome browser, which when clicked displays a list of enabled and available tracks, to be added or removed. - - a suite of buttons to the right of the genome browser, for scrolling, zooming and selecting regions of the genome - - the `karyotype` plugin +- a "Tracks" button to the top left of the genome browser, which when clicked displays a list of enabled and available tracks, to be added or removed. +- a suite of buttons to the right of the genome browser, for scrolling, zooming and selecting regions of the genome +- the `karyotype` plugin -karyotype -: Adds an ideogram of the chromosome being used by the genome browser, with a marker showing the currently viewed region. The marker and be dragged and resized to change region, and chromosome bands can be jumped to by clicked on them. +#### karyotype +Adds an ideogram of the chromosome being used by the genome browser, with a marker showing the currently viewed region. The marker and be dragged and resized to change region, and chromosome bands can be jumped to by clicked on them. -trackControls -: Adds a toggleable pop-out menu to the right side of the track, containing buttons to view track information, remove the track, toggle the track between fixed height and auto resizing, and change track filters/configuration settings, if there are any. +#### trackControls +Adds a toggleable pop-out menu to the right side of the track, containing buttons to view track information, remove the track, toggle the track between fixed height and auto resizing, and change track filters/configuration settings, if there are any. -resizer -: Adds a draggable handle to the bottom of each track, to allow the user to resize it to their desired height. If this plugin is not in use, tracks can only be resized to show all features currently in view. +#### resizer +Adds a draggable handle to the bottom of each track, to allow the user to resize it to their desired height. If this plugin is not in use, tracks can only be resized to show all features currently in view. -focusRegion -: Adds a button to the control panel to move the viewpoint to a particular region of the genome. The `controlPanel` plugin will be added if not already in use. +#### focusRegion +Adds a button to the control panel to move the viewpoint to a particular region of the genome. The `controlPanel` plugin will be added if not already in use. -fullscreen -: Adds a button to the control panel to enable the toggling of a full screen view of the genome browser. The `controlPanel` plugin will be added if not already in use. +#### fullscreen +Adds a button to the control panel to enable the toggling of a full screen view of the genome browser. The `controlPanel` plugin will be added if not already in use. -tooltips -: Adds a button to the control panel to enable the toggling of a help tooltips for the genome browser. The `controlPanel` plugin will be added if not already in use. +#### tooltips +Adds a button to the control panel to enable the toggling of a help tooltips for the genome browser. The `controlPanel` plugin will be added if not already in use. -fileDrop -: Adds the ability to drag and drop a local data file onto the genome browser, and have its data displayed as a track. +#### fileDrop +Adds the ability to drag and drop a local data file onto the genome browser, and have its data displayed as a track. From c1c28526284094c8f71360344073a3e60e68026e Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Thu, 15 Dec 2016 15:00:09 +0000 Subject: [PATCH 004/102] Update README.md --- README.md | 114 +++++++++++++++++++++++++++--------------------------- 1 file changed, 57 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 4f0e1a72..b1833e37 100644 --- a/README.md +++ b/README.md @@ -56,133 +56,133 @@ The following properties can be provided to the constructor for Genoverse: ### DOM element #### container (default `undefined`) -A DOM node, jQuery selector, or string to create a jQuery selector (e.g. `"#genoverse"`) inside which the instance of Genoverse will be created. +> A DOM node, jQuery selector, or string to create a jQuery selector (e.g. `"#genoverse"`) inside which the instance of Genoverse will be created. If `undefined`, a `
` element will be appended to `document.body`. #### width (default `1000`) -The width that the `container` DOM element will be +> The width that the `container` DOM element will be ### Genomic coordinates #### chr (default `1`) -A string or number defining the initial chromosome to display +> A string or number defining the initial chromosome to display #### start (default `1`) -A string or number defining the initial start position +> A string or number defining the initial start position #### end (default `1000000`) -A string or number defining the initial end position +> A string or number defining the initial end position #### genome (default `undefined`) -The genome to be used. Can be: - -- an object with keys of the number/letter/name of the chromosomes, and values in the form `{ "size": 10000 }`. -Additionally an array of bands can be supplied for each chromosome for drawing purposes - see [js/genomes/grch38.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/js/genomes/grch38.js) for an example. -- a string (e.g. `"grch38"`) which will be used to obtain a javascript file from the [js/genomes](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/genomes) directory -- `undefined`, in which case `chromosomeSize` **MUST** be set (see below) +> The genome to be used. Can be: +> +> - an object with keys of the number/letter/name of the chromosomes, and values in the form `{ "size": 10000 }`. +> Additionally an array of bands can be supplied for each chromosome for drawing purposes - see [js/genomes/grch38.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/js/genomes/grch38.js) for an example. +> - a string (e.g. `"grch38"`) which will be used to obtain a javascript file from the [js/genomes](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/genomes) directory +> - `undefined`, in which case `chromosomeSize` **MUST** be set (see below) #### chromosomeSize (default `undefined`) -If `genome` not is provided, `chromosomeSize` **MUST** be set to the length of the chromosome. -If `genome` is provided, `chromosomeSize` will be set to the chromosome's `size` property, as defined by the genome object. +> If `genome` not is provided, `chromosomeSize` **MUST** be set to the length of the chromosome. +> If `genome` is provided, `chromosomeSize` will be set to the chromosome's `size` property, as defined by the genome object. ### What is displayed #### tracks (default `[]`) -An array of `Genoverse.Track` definitions to be displayed +> An array of `Genoverse.Track` definitions to be displayed #### highlights (default `[]`) -An array of regions to highlight, in the form -`{ "start": 100, "end", 200, "label": "My highlight", "removable": false }`. -`label` defaults to "start-end" (e.g. "100-200") if not provided. -If `removable === false`, the highlight cannot be removed. +> An array of regions to highlight, in the form +> `{ "start": 100, "end", 200, "label": "My highlight", "removable": false }`. +> `label` defaults to "start-end" (e.g. "100-200") if not provided. +> If `removable === false`, the highlight cannot be removed. #### plugins (default `[]`) -An array of `Genoverse.Plugins` to be used (from the [js/plugins](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/plugins) directory), e.g. -`[ "controlPanel", "trackControls" ]` -The strings in this array correspond to the namespace of each plugin, which are the same as their file names. +> An array of `Genoverse.Plugins` to be used (from the [js/plugins](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/plugins) directory), e.g. +> `[ "controlPanel", "trackControls" ]` +> The strings in this array correspond to the namespace of each plugin, which are the same as their file names. ### Interaction with the URL #### urlParamTemplate (default `"r=__CHR__:__START__-__END__"`) -The template used to alter the web browser's URL. Should contain placeholders for chr, start and end. -If `false` or empty string, no changes will be made to the URL when navigation occurs. +> The template used to alter the web browser's URL. Should contain placeholders for chr, start and end. +> If `false` or empty string, no changes will be made to the URL when navigation occurs. #### useHash (default `undefined`) -Determines how the browser's URL gets updated on navigation. Can be: - -- `true` - use `window.location.hash` -- `false` - use `window.history.pushState` -- `undefined` - use `window.history.pushState` if present in the browser, else use `window.location.hash` +> Determines how the browser's URL gets updated on navigation. Can be: +> +> - `true` - use `window.location.hash` +> - `false` - use `window.history.pushState` +> - `undefined` - use `window.history.pushState` if present in the browser, else use `window.location.hash` ### User actions #### dragAction (default `"scroll"`) -The action performed when a mouse drag happens on the genome browser. Can be: - -- `"scroll"` - Move the browser left or right -- `"select"` - Select the region -- `"off"` - Do nothing +> The action performed when a mouse drag happens on the genome browser. Can be: +> +> - `"scroll"` - Move the browser left or right +> - `"select"` - Select the region +> - `"off"` - Do nothing #### wheelAction (default `"off"`) -The action performed when a mouse drag happens on the genome browser. Can be: - -- `"zoom"` - Zoom in or out -- `"off"` - Do nothing +> The action performed when a mouse drag happens on the genome browser. Can be: +> +> - `"zoom"` - Zoom in or out +> - `"off"` - Do nothing #### isStatic (default `false`) -If `true`, will stop drag, select and zoom actions occurring +> If `true`, will stop drag, select and zoom actions occurring ### Saving user configurations #### saveable (default `false`) -If `true`, track configuration and ordering will be saved in `window.sessionStorage`/`window.localStorage` (defined by `storageType`, below) so that users will see the same display when they refresh the page +> If `true`, track configuration and ordering will be saved in `window.sessionStorage`/`window.localStorage` (defined by `storageType`, below) so that users will see the same display when they refresh the page #### storageType (default `"sessionStorage"`) -The storage object used to save track configuration. Set to `"localStorage"` for permanence. -See Mozilla's [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) and [localStorage](https://developer.mozilla.org/en/docs/Web/API/Window/localStorage) documentation for further details. +> The storage object used to save track configuration. Set to `"localStorage"` for permanence. +> See Mozilla's [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) and [localStorage](https://developer.mozilla.org/en/docs/Web/API/Window/localStorage) documentation for further details. #### saveKey (default empty string) -The default key used in configuration storage is `"genoverse"`. `saveKey` will be appended to this to allow different configurations for different instances of Genoverse. +> The default key used in configuration storage is `"genoverse"`. `saveKey` will be appended to this to allow different configurations for different instances of Genoverse. ### Default track display settings #### autoHideMessages (default `true`) -Determines whether to collapse track messages (toggleable pop-outs on the left side of a track's image) by default when the user interacts with the genome browser +> Determines whether to collapse track messages (toggleable pop-outs on the left side of a track's image) by default when the user interacts with the genome browser #### trackAutoHeight (default `false`) -Determines whether to automatically resize tracks to show all their features (can be overridden by `track.autoHeight`) +> Determines whether to automatically resize tracks to show all their features (can be overridden by `track.autoHeight`) #### hideEmptyTracks (default `true`) -Determines whether to hide an automatically resized tracks if it has no features, or to show it empty (can be overridden by `track.hideEmpty`) +> Determines whether to hide an automatically resized tracks if it has no features, or to show it empty (can be overridden by `track.hideEmpty`) ## Plugins Genoverse has a number of plugins to extend its core functionality. These plugins are as follows: #### controlPanel -Adds - -- a "Tracks" button to the top left of the genome browser, which when clicked displays a list of enabled and available tracks, to be added or removed. -- a suite of buttons to the right of the genome browser, for scrolling, zooming and selecting regions of the genome -- the `karyotype` plugin +> Adds +> +> - a "Tracks" button to the top left of the genome browser, which when clicked displays a list of enabled and available tracks, to be added or removed. +> - a suite of buttons to the right of the genome browser, for scrolling, zooming and selecting regions of the genome +> - the `karyotype` plugin #### karyotype -Adds an ideogram of the chromosome being used by the genome browser, with a marker showing the currently viewed region. The marker and be dragged and resized to change region, and chromosome bands can be jumped to by clicked on them. +> Adds an ideogram of the chromosome being used by the genome browser, with a marker showing the currently viewed region. The marker and be dragged and resized to change region, and chromosome bands can be jumped to by clicked on them. #### trackControls -Adds a toggleable pop-out menu to the right side of the track, containing buttons to view track information, remove the track, toggle the track between fixed height and auto resizing, and change track filters/configuration settings, if there are any. +> Adds a toggleable pop-out menu to the right side of the track, containing buttons to view track information, remove the track, toggle the track between fixed height and auto resizing, and change track filters/configuration settings, if there are any. #### resizer -Adds a draggable handle to the bottom of each track, to allow the user to resize it to their desired height. If this plugin is not in use, tracks can only be resized to show all features currently in view. +> Adds a draggable handle to the bottom of each track, to allow the user to resize it to their desired height. If this plugin is not in use, tracks can only be resized to show all features currently in view. #### focusRegion -Adds a button to the control panel to move the viewpoint to a particular region of the genome. The `controlPanel` plugin will be added if not already in use. +> Adds a button to the control panel to move the viewpoint to a particular region of the genome. The `controlPanel` plugin will be added if not already in use. #### fullscreen -Adds a button to the control panel to enable the toggling of a full screen view of the genome browser. The `controlPanel` plugin will be added if not already in use. +> Adds a button to the control panel to enable the toggling of a full screen view of the genome browser. The `controlPanel` plugin will be added if not already in use. #### tooltips -Adds a button to the control panel to enable the toggling of a help tooltips for the genome browser. The `controlPanel` plugin will be added if not already in use. +> Adds a button to the control panel to enable the toggling of a help tooltips for the genome browser. The `controlPanel` plugin will be added if not already in use. #### fileDrop -Adds the ability to drag and drop a local data file onto the genome browser, and have its data displayed as a track. +> Adds the ability to drag and drop a local data file onto the genome browser, and have its data displayed as a track. From 52243a26e599b3f8556ccc2d671f12728988ddb1 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Thu, 15 Dec 2016 15:02:00 +0000 Subject: [PATCH 005/102] Update README.md --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index b1833e37..077d9a0a 100644 --- a/README.md +++ b/README.md @@ -92,19 +92,25 @@ If `undefined`, a `
` element will be appended to `document.body`. #### highlights (default `[]`) > An array of regions to highlight, in the form +> > `{ "start": 100, "end", 200, "label": "My highlight", "removable": false }`. +> > `label` defaults to "start-end" (e.g. "100-200") if not provided. +> > If `removable === false`, the highlight cannot be removed. #### plugins (default `[]`) > An array of `Genoverse.Plugins` to be used (from the [js/plugins](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/plugins) directory), e.g. +> > `[ "controlPanel", "trackControls" ]` +> > The strings in this array correspond to the namespace of each plugin, which are the same as their file names. ### Interaction with the URL #### urlParamTemplate (default `"r=__CHR__:__START__-__END__"`) > The template used to alter the web browser's URL. Should contain placeholders for chr, start and end. +> > If `false` or empty string, no changes will be made to the URL when navigation occurs. #### useHash (default `undefined`) @@ -139,6 +145,7 @@ If `undefined`, a `
` element will be appended to `document.body`. #### storageType (default `"sessionStorage"`) > The storage object used to save track configuration. Set to `"localStorage"` for permanence. +> > See Mozilla's [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) and [localStorage](https://developer.mozilla.org/en/docs/Web/API/Window/localStorage) documentation for further details. #### saveKey (default empty string) From 12531cb2fe2f6049aa71570cec42d825b4a52eb7 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Thu, 15 Dec 2016 15:14:45 +0000 Subject: [PATCH 006/102] Update README.md --- README.md | 55 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 28 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 077d9a0a..6c9cd4ab 100644 --- a/README.md +++ b/README.md @@ -32,13 +32,13 @@ In addition to this, Genoverse has a set of plugins, which allow additional func if you already have them in the page 3. Add a script tag or JavaScript file which initializes Genoverse, e.g. - ```html - - ``` + ```html + + ``` ## Configuration @@ -46,8 +46,8 @@ Genoverse has a large number of configurable properties, in order to allow custo ```js var genoverse = new Genoverse({ - genome: 'grch38', - tracks: [ Genoverse.Track.Scalebar, Genoverse.Track.Gene ] + genome: 'grch38', + tracks: [ Genoverse.Track.Scalebar, Genoverse.Track.Gene ] }); ``` @@ -76,13 +76,14 @@ If `undefined`, a `
` element will be appended to `document.body`. #### genome (default `undefined`) > The genome to be used. Can be: > -> - an object with keys of the number/letter/name of the chromosomes, and values in the form `{ "size": 10000 }`. -> Additionally an array of bands can be supplied for each chromosome for drawing purposes - see [js/genomes/grch38.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/js/genomes/grch38.js) for an example. -> - a string (e.g. `"grch38"`) which will be used to obtain a javascript file from the [js/genomes](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/genomes) directory -> - `undefined`, in which case `chromosomeSize` **MUST** be set (see below) +> - an object with keys of the number/letter/name of the chromosomes, and values in the form `{ "size": 10000 }`. +> Additionally an array of bands can be supplied for each chromosome for drawing purposes - see [js/genomes/grch38.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/js/genomes/grch38.js) for an example. +> - a string (e.g. `"grch38"`) which will be used to obtain a javascript file from the [js/genomes](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/genomes) directory +> - `undefined`, in which case `chromosomeSize` **MUST** be set (see below) #### chromosomeSize (default `undefined`) > If `genome` not is provided, `chromosomeSize` **MUST** be set to the length of the chromosome. +> > If `genome` is provided, `chromosomeSize` will be set to the chromosome's `size` property, as defined by the genome object. ### What is displayed @@ -92,18 +93,18 @@ If `undefined`, a `
` element will be appended to `document.body`. #### highlights (default `[]`) > An array of regions to highlight, in the form -> -> `{ "start": 100, "end", 200, "label": "My highlight", "removable": false }`. -> +``` +{ "start": 100, "end", 200, "label": "My highlight", "removable": false } +``` > `label` defaults to "start-end" (e.g. "100-200") if not provided. > > If `removable === false`, the highlight cannot be removed. #### plugins (default `[]`) > An array of `Genoverse.Plugins` to be used (from the [js/plugins](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/plugins) directory), e.g. -> -> `[ "controlPanel", "trackControls" ]` -> +``` +[ "controlPanel", "trackControls" ] +``` > The strings in this array correspond to the namespace of each plugin, which are the same as their file names. ### Interaction with the URL @@ -125,15 +126,15 @@ If `undefined`, a `
` element will be appended to `document.body`. #### dragAction (default `"scroll"`) > The action performed when a mouse drag happens on the genome browser. Can be: > -> - `"scroll"` - Move the browser left or right -> - `"select"` - Select the region -> - `"off"` - Do nothing +> - `"scroll"` - Move the browser left or right +> - `"select"` - Select the region +> - `"off"` - Do nothing #### wheelAction (default `"off"`) > The action performed when a mouse drag happens on the genome browser. Can be: > -> - `"zoom"` - Zoom in or out -> - `"off"` - Do nothing +> - `"zoom"` - Zoom in or out +> - `"off"` - Do nothing #### isStatic (default `false`) > If `true`, will stop drag, select and zoom actions occurring @@ -169,9 +170,9 @@ Genoverse has a number of plugins to extend its core functionality. These plugin #### controlPanel > Adds > -> - a "Tracks" button to the top left of the genome browser, which when clicked displays a list of enabled and available tracks, to be added or removed. -> - a suite of buttons to the right of the genome browser, for scrolling, zooming and selecting regions of the genome -> - the `karyotype` plugin +> - a "Tracks" button to the top left of the genome browser, which when clicked displays a list of enabled and available tracks, to be added or removed. +> - a suite of buttons to the right of the genome browser, for scrolling, zooming and selecting regions of the genome +> - the `karyotype` plugin #### karyotype > Adds an ideogram of the chromosome being used by the genome browser, with a marker showing the currently viewed region. The marker and be dragged and resized to change region, and chromosome bands can be jumped to by clicked on them. From 255c131496c44c2a061634c3252f03dbe8bd301b Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Thu, 15 Dec 2016 15:21:09 +0000 Subject: [PATCH 007/102] Create plugins.md --- docs/plugins.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/plugins.md diff --git a/docs/plugins.md b/docs/plugins.md new file mode 100644 index 00000000..4d2e045e --- /dev/null +++ b/docs/plugins.md @@ -0,0 +1,32 @@ +# Plugins + +The `Genoverse.Plugins` namespace contains a set of plugins to extend the core functionality of Genoverse. + +These plugins, located in the [js/plugins](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/plugins) directory, are as follows: + +### controlPanel +Adds + - a "Tracks" button to the top left of the genome browser, which when clicked displays a list of enabled and available tracks, to be added or removed. + - a suite of buttons to the right of the genome browser, for scrolling, zooming and selecting regions of the genome + - the `karyotype` plugin + +### karyotype +Adds an ideogram of the chromosome being used by the genome browser, with a marker showing the currently viewed region. The marker and be dragged and resized to change region, and chromosome bands can be jumped to by clicked on them. + +### trackControls +Adds a toggleable pop-out menu to the right side of the track, containing buttons to view track information, remove the track, toggle the track between fixed height and auto resizing, and change track filters/configuration settings, if there are any. + +### resizer +Adds a draggable handle to the bottom of each track, to allow the user to resize it to their desired height. If this plugin is not in use, tracks can only be resized to show all features currently in view. + +### focusRegion +Adds a button to the control panel to move the viewpoint to a particular region of the genome. The `controlPanel` plugin will be added if not already in use. + +### fullscreen +Adds a button to the control panel to enable the toggling of a full screen view of the genome browser. The `controlPanel` plugin will be added if not already in use. + +### tooltips +Adds a button to the control panel to enable the toggling of a help tooltips for the genome browser. The `controlPanel` plugin will be added if not already in use. + +### fileDrop +Adds the ability to drag and drop a local data file onto the genome browser, and have its data displayed as a track. From 6fcd63837b0d48deb33cfc969dd0e2f148476ec2 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Thu, 15 Dec 2016 15:24:50 +0000 Subject: [PATCH 008/102] Create configuration.md --- docs/configuration.md | 122 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 docs/configuration.md diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..871c2b17 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,122 @@ +# Configuration + +Genoverse has a large number of configurable properties, in order to allow customization. A basic example with two tracks (a scalebar and some genes) and no plugins would be + +```js +var genoverse = new Genoverse({ + genome: 'grch38', + tracks: [ Genoverse.Track.Scalebar, Genoverse.Track.Gene ] +}); +``` + +The following properties can be provided to the constructor for Genoverse: + +### DOM element + +#### container (default `undefined`) +> A DOM node, jQuery selector, or string to create a jQuery selector (e.g. `"#genoverse"`) inside which the instance of Genoverse will be created. +If `undefined`, a `
` element will be appended to `document.body`. + +#### width (default `1000`) +> The width that the `container` DOM element will be + +### Genomic coordinates + +#### chr (default `1`) +> A string or number defining the initial chromosome to display + +#### start (default `1`) +> A string or number defining the initial start position + +#### end (default `1000000`) +> A string or number defining the initial end position + +#### genome (default `undefined`) +> The genome to be used. Can be: +> +> - an object with keys of the number/letter/name of the chromosomes, and values in the form `{ "size": 10000 }`. +> Additionally an array of bands can be supplied for each chromosome for drawing purposes - see [js/genomes/grch38.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/js/genomes/grch38.js) for an example. +> - a string (e.g. `"grch38"`) which will be used to obtain a javascript file from the [js/genomes](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/genomes) directory +> - `undefined`, in which case `chromosomeSize` **MUST** be set (see below) + +#### chromosomeSize (default `undefined`) +> If `genome` not is provided, `chromosomeSize` **MUST** be set to the length of the chromosome. +> +> If `genome` is provided, `chromosomeSize` will be set to the chromosome's `size` property, as defined by the genome object. + +### What is displayed + +#### tracks (default `[]`) +> An array of `Genoverse.Track` definitions to be displayed + +#### highlights (default `[]`) +> An array of regions to highlight, in the form +``` +{ "start": 100, "end", 200, "label": "My highlight", "removable": false } +``` +> `label` defaults to "start-end" (e.g. "100-200") if not provided. +> +> If `removable === false`, the highlight cannot be removed. + +#### plugins (default `[]`) +> An array of `Genoverse.Plugins` to be used (from the [js/plugins](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/plugins) directory), e.g. +``` +[ "controlPanel", "trackControls" ] +``` +> The strings in this array correspond to the namespace of each plugin, which are the same as their file names. + +### Interaction with the URL + +#### urlParamTemplate (default `"r=__CHR__:__START__-__END__"`) +> The template used to alter the web browser's URL. Should contain placeholders for chr, start and end. +> +> If `false` or empty string, no changes will be made to the URL when navigation occurs. + +#### useHash (default `undefined`) +> Determines how the browser's URL gets updated on navigation. Can be: +> +> - `true` - use `window.location.hash` +> - `false` - use `window.history.pushState` +> - `undefined` - use `window.history.pushState` if present in the browser, else use `window.location.hash` + +### User actions + +#### dragAction (default `"scroll"`) +> The action performed when a mouse drag happens on the genome browser. Can be: +> +> - `"scroll"` - Move the browser left or right +> - `"select"` - Select the region +> - `"off"` - Do nothing + +#### wheelAction (default `"off"`) +> The action performed when a mouse drag happens on the genome browser. Can be: +> +> - `"zoom"` - Zoom in or out +> - `"off"` - Do nothing + +#### isStatic (default `false`) +> If `true`, will stop drag, select and zoom actions occurring + +### Saving user configurations + +#### saveable (default `false`) +> If `true`, track configuration and ordering will be saved in `window.sessionStorage`/`window.localStorage` (defined by `storageType`, below) so that users will see the same display when they refresh the page + +#### storageType (default `"sessionStorage"`) +> The storage object used to save track configuration. Set to `"localStorage"` for permanence. +> +> See Mozilla's [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) and [localStorage](https://developer.mozilla.org/en/docs/Web/API/Window/localStorage) documentation for further details. + +#### saveKey (default empty string) +> The default key used in configuration storage is `"genoverse"`. `saveKey` will be appended to this to allow different configurations for different instances of Genoverse. + +### Default track display settings + +#### autoHideMessages (default `true`) +> Determines whether to collapse track messages (toggleable pop-outs on the left side of a track's image) by default when the user interacts with the genome browser + +#### trackAutoHeight (default `false`) +> Determines whether to automatically resize tracks to show all their features (can be overridden by `track.autoHeight`) + +#### hideEmptyTracks (default `true`) +> Determines whether to hide an automatically resized tracks if it has no features, or to show it empty (can be overridden by `track.hideEmpty`) From 9980deeb9fdc404f7c114fa3093529fcafe7a782 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Thu, 15 Dec 2016 15:31:07 +0000 Subject: [PATCH 009/102] Update README.md --- README.md | 145 +----------------------------------------------------- 1 file changed, 2 insertions(+), 143 deletions(-) diff --git a/README.md b/README.md index 6c9cd4ab..f60c931b 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Genoverse works using a system of **tracks** - essentially horizontal sections o Tracks can have multiple models and views, which allows for switching between displays at different zoom levels. An example of this would be a track where you show genes when looking at a large region of a chromosome, and then switch to showing transcripts as the user zooms in. -In addition to this, Genoverse has a set of plugins, which allow additional functionality beyond the core genome browser. These include a control panel for adding and removing tracks, and interacting with the browser more easily, a way to add controls to each individual track, and a way to enable drag and drop of local data files onto the genome browser. +In addition to this, Genoverse has a set of [plugins](docs/plugins.md), which allow additional functionality beyond the core genome browser. These include a control panel for adding and removing tracks, and interacting with the browser more easily, a way to add controls to each individual track, and a way to enable drag and drop of local data files onto the genome browser. ## Installation @@ -51,146 +51,5 @@ var genoverse = new Genoverse({ }); ``` -The following properties can be provided to the constructor for Genoverse: +For more details about these properties, see [here](docs/configuration.md). -### DOM element - -#### container (default `undefined`) -> A DOM node, jQuery selector, or string to create a jQuery selector (e.g. `"#genoverse"`) inside which the instance of Genoverse will be created. -If `undefined`, a `
` element will be appended to `document.body`. - -#### width (default `1000`) -> The width that the `container` DOM element will be - -### Genomic coordinates - -#### chr (default `1`) -> A string or number defining the initial chromosome to display - -#### start (default `1`) -> A string or number defining the initial start position - -#### end (default `1000000`) -> A string or number defining the initial end position - -#### genome (default `undefined`) -> The genome to be used. Can be: -> -> - an object with keys of the number/letter/name of the chromosomes, and values in the form `{ "size": 10000 }`. -> Additionally an array of bands can be supplied for each chromosome for drawing purposes - see [js/genomes/grch38.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/js/genomes/grch38.js) for an example. -> - a string (e.g. `"grch38"`) which will be used to obtain a javascript file from the [js/genomes](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/genomes) directory -> - `undefined`, in which case `chromosomeSize` **MUST** be set (see below) - -#### chromosomeSize (default `undefined`) -> If `genome` not is provided, `chromosomeSize` **MUST** be set to the length of the chromosome. -> -> If `genome` is provided, `chromosomeSize` will be set to the chromosome's `size` property, as defined by the genome object. - -### What is displayed - -#### tracks (default `[]`) -> An array of `Genoverse.Track` definitions to be displayed - -#### highlights (default `[]`) -> An array of regions to highlight, in the form -``` -{ "start": 100, "end", 200, "label": "My highlight", "removable": false } -``` -> `label` defaults to "start-end" (e.g. "100-200") if not provided. -> -> If `removable === false`, the highlight cannot be removed. - -#### plugins (default `[]`) -> An array of `Genoverse.Plugins` to be used (from the [js/plugins](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/plugins) directory), e.g. -``` -[ "controlPanel", "trackControls" ] -``` -> The strings in this array correspond to the namespace of each plugin, which are the same as their file names. - -### Interaction with the URL - -#### urlParamTemplate (default `"r=__CHR__:__START__-__END__"`) -> The template used to alter the web browser's URL. Should contain placeholders for chr, start and end. -> -> If `false` or empty string, no changes will be made to the URL when navigation occurs. - -#### useHash (default `undefined`) -> Determines how the browser's URL gets updated on navigation. Can be: -> -> - `true` - use `window.location.hash` -> - `false` - use `window.history.pushState` -> - `undefined` - use `window.history.pushState` if present in the browser, else use `window.location.hash` - -### User actions - -#### dragAction (default `"scroll"`) -> The action performed when a mouse drag happens on the genome browser. Can be: -> -> - `"scroll"` - Move the browser left or right -> - `"select"` - Select the region -> - `"off"` - Do nothing - -#### wheelAction (default `"off"`) -> The action performed when a mouse drag happens on the genome browser. Can be: -> -> - `"zoom"` - Zoom in or out -> - `"off"` - Do nothing - -#### isStatic (default `false`) -> If `true`, will stop drag, select and zoom actions occurring - -### Saving user configurations - -#### saveable (default `false`) -> If `true`, track configuration and ordering will be saved in `window.sessionStorage`/`window.localStorage` (defined by `storageType`, below) so that users will see the same display when they refresh the page - -#### storageType (default `"sessionStorage"`) -> The storage object used to save track configuration. Set to `"localStorage"` for permanence. -> -> See Mozilla's [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) and [localStorage](https://developer.mozilla.org/en/docs/Web/API/Window/localStorage) documentation for further details. - -#### saveKey (default empty string) -> The default key used in configuration storage is `"genoverse"`. `saveKey` will be appended to this to allow different configurations for different instances of Genoverse. - -### Default track display settings - -#### autoHideMessages (default `true`) -> Determines whether to collapse track messages (toggleable pop-outs on the left side of a track's image) by default when the user interacts with the genome browser - -#### trackAutoHeight (default `false`) -> Determines whether to automatically resize tracks to show all their features (can be overridden by `track.autoHeight`) - -#### hideEmptyTracks (default `true`) -> Determines whether to hide an automatically resized tracks if it has no features, or to show it empty (can be overridden by `track.hideEmpty`) - -## Plugins - -Genoverse has a number of plugins to extend its core functionality. These plugins are as follows: - -#### controlPanel -> Adds -> -> - a "Tracks" button to the top left of the genome browser, which when clicked displays a list of enabled and available tracks, to be added or removed. -> - a suite of buttons to the right of the genome browser, for scrolling, zooming and selecting regions of the genome -> - the `karyotype` plugin - -#### karyotype -> Adds an ideogram of the chromosome being used by the genome browser, with a marker showing the currently viewed region. The marker and be dragged and resized to change region, and chromosome bands can be jumped to by clicked on them. - -#### trackControls -> Adds a toggleable pop-out menu to the right side of the track, containing buttons to view track information, remove the track, toggle the track between fixed height and auto resizing, and change track filters/configuration settings, if there are any. - -#### resizer -> Adds a draggable handle to the bottom of each track, to allow the user to resize it to their desired height. If this plugin is not in use, tracks can only be resized to show all features currently in view. - -#### focusRegion -> Adds a button to the control panel to move the viewpoint to a particular region of the genome. The `controlPanel` plugin will be added if not already in use. - -#### fullscreen -> Adds a button to the control panel to enable the toggling of a full screen view of the genome browser. The `controlPanel` plugin will be added if not already in use. - -#### tooltips -> Adds a button to the control panel to enable the toggling of a help tooltips for the genome browser. The `controlPanel` plugin will be added if not already in use. - -#### fileDrop -> Adds the ability to drag and drop a local data file onto the genome browser, and have its data displayed as a track. From 6b45a8fe0b790047cadab6c1cc6cb78a02eed719 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Thu, 15 Dec 2016 15:32:52 +0000 Subject: [PATCH 010/102] Update README.md --- README.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/README.md b/README.md index f60c931b..10afa63b 100644 --- a/README.md +++ b/README.md @@ -39,17 +39,5 @@ In addition to this, Genoverse has a set of [plugins](docs/plugins.md), which al }); ``` - -## Configuration - -Genoverse has a large number of configurable properties, in order to allow customization. A basic example with two tracks (a scalebar and some genes) and no plugins would be - -```js -var genoverse = new Genoverse({ - genome: 'grch38', - tracks: [ Genoverse.Track.Scalebar, Genoverse.Track.Gene ] -}); -``` - -For more details about these properties, see [here](docs/configuration.md). + For more details about configuration properties, see [here](docs/configuration.md). From 11f5e570601623f5c7e64805dfb7a6776d37c3c8 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Thu, 15 Dec 2016 15:35:19 +0000 Subject: [PATCH 011/102] Create tracks.md --- docs/tracks.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/tracks.md diff --git a/docs/tracks.md b/docs/tracks.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/docs/tracks.md @@ -0,0 +1 @@ + From 86333c90aaffbe723e2f468c2ff5206e37728706 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Thu, 15 Dec 2016 15:36:48 +0000 Subject: [PATCH 012/102] Update README.md --- README.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 10afa63b..3df0d72b 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Data is visualized in the browser, meaning Genoverse can be installed on any web Genoverse works with a variety of formats, such as XML, JSON, BED, BAM, VCF, GFF, or delimited text files, and can be customized to parse and display any data source as required. -Genoverse works using a system of **tracks** - essentially horizontal sections of the genome browser which display **features** - genes, variants, etc. with defined genomic start and end points. Each track has its own data, set stored in a **model**, a method for displaying that data, stored in a **view**, and a **controller** to manage the creation of DOM elements, and user interactions with them. +Genoverse works using a system of [**tracks**](docs/tracks.md) - essentially horizontal sections of the genome browser which display **features** - genes, variants, etc. with defined genomic start and end points. Each track has its own data set stored in a **model**, a method for displaying that data, stored in a **view**, and a **controller** to manage the creation of DOM elements, and user interactions with them. Tracks can have multiple models and views, which allows for switching between displays at different zoom levels. An example of this would be a track where you show genes when looking at a large region of a chromosome, and then switch to showing transcripts as the user zooms in. @@ -15,21 +15,21 @@ In addition to this, Genoverse has a set of [plugins](docs/plugins.md), which al ## Installation 1. Download the latest version from GitHub - ``` - git clone git@github.com:wtsi-web/Genoverse.git - ``` + ``` + git clone git@github.com:wtsi-web/Genoverse.git + ``` 2. Embed Genoverse using either - ```html - - ``` - - which comes with jQuery and jQuery UI included, or - ```html - - ``` + ```html + + ``` + + which comes with jQuery and jQuery UI included, or + ```html + + ``` - if you already have them in the page + if you already have them in the page 3. Add a script tag or JavaScript file which initializes Genoverse, e.g. ```html From b06a7e52b802b8e6fc4fe614b76d83bacdd8d80f Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Thu, 15 Dec 2016 15:37:35 +0000 Subject: [PATCH 013/102] Create genoverse_api.md --- docs/genoverse_api.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/genoverse_api.md diff --git a/docs/genoverse_api.md b/docs/genoverse_api.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/docs/genoverse_api.md @@ -0,0 +1 @@ + From 1de5251351c714f0d2520053be55f05420451bde Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 11:23:25 +0000 Subject: [PATCH 014/102] Update configuration.md --- docs/configuration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 871c2b17..a540342c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -13,7 +13,8 @@ The following properties can be provided to the constructor for Genoverse: ### DOM element -#### container (default `undefined`) +#### container +###### Default `undefined` > A DOM node, jQuery selector, or string to create a jQuery selector (e.g. `"#genoverse"`) inside which the instance of Genoverse will be created. If `undefined`, a `
` element will be appended to `document.body`. From 762f09c3334ecc3099cc32dd70be0e8e8e54df2d Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 11:23:56 +0000 Subject: [PATCH 015/102] Update configuration.md --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index a540342c..418a8511 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -14,7 +14,7 @@ The following properties can be provided to the constructor for Genoverse: ### DOM element #### container -###### Default `undefined` +*Default `undefined`* > A DOM node, jQuery selector, or string to create a jQuery selector (e.g. `"#genoverse"`) inside which the instance of Genoverse will be created. If `undefined`, a `
` element will be appended to `document.body`. From c1a07d7ce97645bc98da4e9ecba2ee202b246217 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 11:24:11 +0000 Subject: [PATCH 016/102] Update configuration.md --- docs/configuration.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 418a8511..b2ad25f0 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -13,8 +13,7 @@ The following properties can be provided to the constructor for Genoverse: ### DOM element -#### container -*Default `undefined`* +#### container (default `undefined`) > A DOM node, jQuery selector, or string to create a jQuery selector (e.g. `"#genoverse"`) inside which the instance of Genoverse will be created. If `undefined`, a `
` element will be appended to `document.body`. From 001d255714ad52f200e3f1123366bc0561e8f924 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 11:24:55 +0000 Subject: [PATCH 017/102] Update configuration.md --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index b2ad25f0..871c2b17 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -13,7 +13,7 @@ The following properties can be provided to the constructor for Genoverse: ### DOM element -#### container (default `undefined`) +#### container (default `undefined`) > A DOM node, jQuery selector, or string to create a jQuery selector (e.g. `"#genoverse"`) inside which the instance of Genoverse will be created. If `undefined`, a `
` element will be appended to `document.body`. From a84d9df089481dc60684437aa7f0b1ce03f362ff Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 12:14:29 +0000 Subject: [PATCH 018/102] Update genoverse_api.md --- docs/genoverse_api.md | 76 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) diff --git a/docs/genoverse_api.md b/docs/genoverse_api.md index 8b137891..598392d0 100644 --- a/docs/genoverse_api.md +++ b/docs/genoverse_api.md @@ -1 +1,77 @@ +# Genoverse API +The following are methods that can be called on an instance of Genoverse to perform actions required by UI changes external to the instance (i.e. from the website you have integrated Genoverse into). + +#### genoverse.addTracks(tracks [, after ]) +> Add a number of tracks to the genome browser +> Argument | Type | Description +> --- | --- | --- +> tracks | Array | An array of `Genoverse.Track` class definitions to be added +> after | Integer or undefined | The existing track after which the new tracks will be inserted. For example, if the existing tracks are `[ A, B, C, D, E ]`, `genoverse.addTracks([ X, Y ], 2)` will result in `[ A, B, X, Y, C, D, E ]`. If `undefined` , the tracks will be inserted after the existing tracks. + +#### genoverse.addTrack(track [, after ]) +> Add a single track to the genome browser +> Argument | Type | Description +> --- | --- | --- +> track | `Genoverse.Track` class | A `Genoverse.Track` class definition to be added +> after | Integer or undefined | See `genoverse.addTracks` + +#### genoverse.removeTracks(tracks) +> Remove a number of tracks from the genome browser +> Argument | Type | Description +> --- | --- | --- +> tracks | Array | An array of existing `Genoverse.Track` instances to be removed + +#### genoverse.removeTrack(track) +> Remove a single track from the genome browser +> Argument | Type | Description +> --- | --- | --- +> track | `Genoverse.Track` instance | An existing `Genoverse.Track` instance to be removed + +#### genoverse.addHighlights(highlights) +> Add a number of highlighted regions to the genome browser +> Argument | Type | Description +> --- | --- | --- +> tracks | Array | An array of highlighted regions to be added. See [configuration](configuration.md#highlights-default-) for the structure of highlights. + +#### genoverse.addHighlight(highlight) +> Add a single highlighted regions to the genome browser +> Argument | Type | Description +> --- | --- | --- +> highlight | Object | A highlighted region to be added. See [configuration](configuration.md#highlights-default-) for the structure of highlights. + +#### genoverse.moveTo(start, end [, update] [, keepLength]) +> Moves the viewpoint to the region between `start` and `end` +> Argument | Type | Description +> --- | --- | --- +> start | Integer | a number between `1` and `genoverse.chromosomeSize` +> end | Integer | a number between `start` and `genoverse.chromosomeSize` +> update | Boolean or undefined | If `true`, the URL will be updated with the new `start` and `end` +> keepLength | Boolean or undefined | if `true`, the new viewpoint will have the same zoom level as before (`end - start` remains unchanged), centered on the given `start` and `end`. + +#### genoverse.setWidth(width) +> Resizes the `container` element for the instance of Genoverse +> Argument | Type | Description +> --- | --- | --- +> width | Integer | The pixel width to resize to + +#### genoverse.on(events, [, onTracks ], callback) +> Execute functions before or after Genoverse or Genoverse.Track functions +> Argument | Type | Description +> --- | --- | --- +> events | String | One or more space-separated events. Events are function names with an uppercase first letter, appended to "before" or "after", e.g. "beforeAddTrack" or "afterSetWidth". +> onTracks | `"tracks"` or `Genoverse.Track` instance | If present, the callback will be executed on any track in the genome browser. *Note that providing a specific track instance does not mean the callback will be executed only for that track.* If omitted (i.e. `genoverse.on(events, callback)`, the callback will be executed on the instance of Genoverse. +> callback | Function | The function to be executed for all of the space-separated events + +#### genoverse.on(events [, onTracks ]) +> Execute functions before or after Genoverse or Genoverse.Track functions +> Argument | Type | Description +> --- | --- | --- +> events | Object | An object whose keys are one or more space-separated events (see above), and whose values are the functions to be executed for those events +> onTracks | `"tracks"` or `Genoverse.Track` instance | See above + +#### genoverse.reset() +> Removes all existing data visualizations, and recreates them + +#### genoverse.destroy() +> Removes the instance of Genoverse from the web page From 44b8249dfccb953b4904b0271e946f2a001e1886 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 12:16:08 +0000 Subject: [PATCH 019/102] Update genoverse_api.md --- docs/genoverse_api.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/genoverse_api.md b/docs/genoverse_api.md index 598392d0..b931465b 100644 --- a/docs/genoverse_api.md +++ b/docs/genoverse_api.md @@ -4,6 +4,7 @@ The following are methods that can be called on an instance of Genoverse to perf #### genoverse.addTracks(tracks [, after ]) > Add a number of tracks to the genome browser +> > Argument | Type | Description > --- | --- | --- > tracks | Array | An array of `Genoverse.Track` class definitions to be added @@ -11,6 +12,7 @@ The following are methods that can be called on an instance of Genoverse to perf #### genoverse.addTrack(track [, after ]) > Add a single track to the genome browser +> > Argument | Type | Description > --- | --- | --- > track | `Genoverse.Track` class | A `Genoverse.Track` class definition to be added @@ -18,30 +20,35 @@ The following are methods that can be called on an instance of Genoverse to perf #### genoverse.removeTracks(tracks) > Remove a number of tracks from the genome browser +> > Argument | Type | Description > --- | --- | --- > tracks | Array | An array of existing `Genoverse.Track` instances to be removed #### genoverse.removeTrack(track) > Remove a single track from the genome browser +> > Argument | Type | Description > --- | --- | --- > track | `Genoverse.Track` instance | An existing `Genoverse.Track` instance to be removed #### genoverse.addHighlights(highlights) > Add a number of highlighted regions to the genome browser +> > Argument | Type | Description > --- | --- | --- > tracks | Array | An array of highlighted regions to be added. See [configuration](configuration.md#highlights-default-) for the structure of highlights. #### genoverse.addHighlight(highlight) > Add a single highlighted regions to the genome browser +> > Argument | Type | Description > --- | --- | --- > highlight | Object | A highlighted region to be added. See [configuration](configuration.md#highlights-default-) for the structure of highlights. #### genoverse.moveTo(start, end [, update] [, keepLength]) > Moves the viewpoint to the region between `start` and `end` +> > Argument | Type | Description > --- | --- | --- > start | Integer | a number between `1` and `genoverse.chromosomeSize` @@ -51,12 +58,14 @@ The following are methods that can be called on an instance of Genoverse to perf #### genoverse.setWidth(width) > Resizes the `container` element for the instance of Genoverse +> > Argument | Type | Description > --- | --- | --- > width | Integer | The pixel width to resize to #### genoverse.on(events, [, onTracks ], callback) > Execute functions before or after Genoverse or Genoverse.Track functions +> > Argument | Type | Description > --- | --- | --- > events | String | One or more space-separated events. Events are function names with an uppercase first letter, appended to "before" or "after", e.g. "beforeAddTrack" or "afterSetWidth". @@ -65,6 +74,7 @@ The following are methods that can be called on an instance of Genoverse to perf #### genoverse.on(events [, onTracks ]) > Execute functions before or after Genoverse or Genoverse.Track functions +> > Argument | Type | Description > --- | --- | --- > events | Object | An object whose keys are one or more space-separated events (see above), and whose values are the functions to be executed for those events From 37eed50a3bb040367c49eb2720db7d2e86b2aeac Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 14:10:20 +0000 Subject: [PATCH 020/102] Update genoverse_api.md --- docs/genoverse_api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/genoverse_api.md b/docs/genoverse_api.md index b931465b..41991fca 100644 --- a/docs/genoverse_api.md +++ b/docs/genoverse_api.md @@ -61,7 +61,7 @@ The following are methods that can be called on an instance of Genoverse to perf > > Argument | Type | Description > --- | --- | --- -> width | Integer | The pixel width to resize to +> width | Integer | The width to resize to, in pixel #### genoverse.on(events, [, onTracks ], callback) > Execute functions before or after Genoverse or Genoverse.Track functions From e50b7b78d449ff6a91e808d2e999fd2d4057bb2d Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 14:23:37 +0000 Subject: [PATCH 021/102] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3df0d72b..c55ef4ae 100644 --- a/README.md +++ b/README.md @@ -39,5 +39,5 @@ In addition to this, Genoverse has a set of [plugins](docs/plugins.md), which al }); ``` - For more details about configuration properties, see [here](docs/configuration.md). + See [index.html](/index.html) for example configuration, or the [documentation](docs/configuration.md) for more details about configuration properties. From 45406ab953374dc3312a4fff66bbadd22548db3f Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 14:26:34 +0000 Subject: [PATCH 022/102] Update README.md --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index c55ef4ae..0e7bdff9 100644 --- a/README.md +++ b/README.md @@ -40,4 +40,9 @@ In addition to this, Genoverse has a set of [plugins](docs/plugins.md), which al ``` See [index.html](/index.html) for example configuration, or the [documentation](docs/configuration.md) for more details about configuration properties. + +Once initalized, the instance of Genoverse is avaliable as a jQuery data attribute on the container DOM element, and can be accessed by +```javascript +var genoverse = $(container).data('genoverse'); +``` From c1d696fb2176da5235aa9ca3ea0916ef0bf45b98 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 14:28:05 +0000 Subject: [PATCH 023/102] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0e7bdff9..34ba9347 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Genoverse is a portable, customizable, back-end independent JavaScript and HTML5 Data is visualized in the browser, meaning Genoverse can be installed on any website and show data from a wide range of online or local sources. -Genoverse works with a variety of formats, such as XML, JSON, BED, BAM, VCF, GFF, or delimited text files, and can be customized to parse and display any data source as required. +Genoverse works with a variety of formats, such as JSON, BED, BAM, VCF, GFF, delimited text files, or XML, and can be customized to parse and display any data source as required. Genoverse works using a system of [**tracks**](docs/tracks.md) - essentially horizontal sections of the genome browser which display **features** - genes, variants, etc. with defined genomic start and end points. Each track has its own data set stored in a **model**, a method for displaying that data, stored in a **view**, and a **controller** to manage the creation of DOM elements, and user interactions with them. From 3b18c1203c851460cdb2dd0c16bfb77eac55e603 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 15:02:30 +0000 Subject: [PATCH 024/102] Update tracks.md --- docs/tracks.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tracks.md b/docs/tracks.md index 8b137891..895e8f28 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -1 +1,3 @@ +# Tracks +Genoverse's tracks are responsible for obtaining data from a source (a URL, file, or JavaScript array) and visualizing it in the genome browser. From 8b4be19692a77e9afb3907581746dbf82fe9a6d3 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 15:02:59 +0000 Subject: [PATCH 025/102] Create genoverse_all_functions --- docs/genoverse_all_functions | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/genoverse_all_functions diff --git a/docs/genoverse_all_functions b/docs/genoverse_all_functions new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/docs/genoverse_all_functions @@ -0,0 +1 @@ + From 2286feb3357fda158171f658f989a3c298f4b131 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 15:03:16 +0000 Subject: [PATCH 026/102] Create track_view --- docs/track_view | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/track_view diff --git a/docs/track_view b/docs/track_view new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/docs/track_view @@ -0,0 +1 @@ + From 7226ecac81d5654f252933627886bd042d39fd2b Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 15:03:22 +0000 Subject: [PATCH 027/102] Create track_model --- docs/track_model | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/track_model diff --git a/docs/track_model b/docs/track_model new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/docs/track_model @@ -0,0 +1 @@ + From c5d6d689340b07d664cc8f180c7fda0ab7a4f7b2 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 15:03:34 +0000 Subject: [PATCH 028/102] Create track_controllers --- docs/track_controllers | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/track_controllers diff --git a/docs/track_controllers b/docs/track_controllers new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/docs/track_controllers @@ -0,0 +1 @@ + From 6f0ca0ec89a10bd03fb0d2c093b0abe2aee051f5 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 15:03:42 +0000 Subject: [PATCH 029/102] Rename track_view to track_views.md --- docs/{track_view => track_views.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{track_view => track_views.md} (100%) diff --git a/docs/track_view b/docs/track_views.md similarity index 100% rename from docs/track_view rename to docs/track_views.md From 3290a444c0b1fe247890fe3916a096b8ac60a712 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 15:03:52 +0000 Subject: [PATCH 030/102] Rename track_model to track_models.md --- docs/{track_model => track_models.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{track_model => track_models.md} (100%) diff --git a/docs/track_model b/docs/track_models.md similarity index 100% rename from docs/track_model rename to docs/track_models.md From 01586f296eca1d5971a0a3888757b594be1658dd Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 15:04:01 +0000 Subject: [PATCH 031/102] Rename track_controllers to track_controllers.md --- docs/{track_controllers => track_controllers.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{track_controllers => track_controllers.md} (100%) diff --git a/docs/track_controllers b/docs/track_controllers.md similarity index 100% rename from docs/track_controllers rename to docs/track_controllers.md From becdb64394ef8af2f6bfa912b1f43a0450d92daa Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 15:05:17 +0000 Subject: [PATCH 032/102] Rename genoverse_all_functions to genoverse_all_functions.md --- docs/{genoverse_all_functions => genoverse_all_functions.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{genoverse_all_functions => genoverse_all_functions.md} (100%) diff --git a/docs/genoverse_all_functions b/docs/genoverse_all_functions.md similarity index 100% rename from docs/genoverse_all_functions rename to docs/genoverse_all_functions.md From e0599c455bb9f8c9f546fb868a88905307521f82 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Fri, 16 Dec 2016 15:06:54 +0000 Subject: [PATCH 033/102] Create track_types.md --- docs/track_types.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/track_types.md diff --git a/docs/track_types.md b/docs/track_types.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/docs/track_types.md @@ -0,0 +1 @@ + From 63647dea961ec4b72839b25ef5779040f7aa2dae Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 10:12:57 +0000 Subject: [PATCH 034/102] Rename docs/track_controllers.md to docs/track/controllers.md --- docs/{track_controllers.md => track/controllers.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{track_controllers.md => track/controllers.md} (100%) diff --git a/docs/track_controllers.md b/docs/track/controllers.md similarity index 100% rename from docs/track_controllers.md rename to docs/track/controllers.md From 36524673bacb7d354376dc6ca60ace6b54963e97 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 10:13:13 +0000 Subject: [PATCH 035/102] Rename docs/track_views.md to docs/track/views.md --- docs/{track_views.md => track/views.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{track_views.md => track/views.md} (100%) diff --git a/docs/track_views.md b/docs/track/views.md similarity index 100% rename from docs/track_views.md rename to docs/track/views.md From e23602017a833bba0856107b1748e2e343ac5446 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 10:13:24 +0000 Subject: [PATCH 036/102] Rename docs/track_types.md to docs/track/library.md --- docs/{track_types.md => track/library.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{track_types.md => track/library.md} (100%) diff --git a/docs/track_types.md b/docs/track/library.md similarity index 100% rename from docs/track_types.md rename to docs/track/library.md From 565f3bd196d3a47f6de2c3355ff9d223cfeee33e Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 10:13:33 +0000 Subject: [PATCH 037/102] Rename docs/track_models.md to docs/track/models.md --- docs/{track_models.md => track/models.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{track_models.md => track/models.md} (100%) diff --git a/docs/track_models.md b/docs/track/models.md similarity index 100% rename from docs/track_models.md rename to docs/track/models.md From 7a2f0fbdc847451ed3f2894b94c2aff9d3288623 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 10:17:12 +0000 Subject: [PATCH 038/102] docs/track -> docs/tracs --- docs/{track => tracks}/controllers.md | 0 docs/{track => tracks}/library.md | 0 docs/{track => tracks}/models.md | 0 docs/{track => tracks}/views.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename docs/{track => tracks}/controllers.md (100%) rename docs/{track => tracks}/library.md (100%) rename docs/{track => tracks}/models.md (100%) rename docs/{track => tracks}/views.md (100%) diff --git a/docs/track/controllers.md b/docs/tracks/controllers.md similarity index 100% rename from docs/track/controllers.md rename to docs/tracks/controllers.md diff --git a/docs/track/library.md b/docs/tracks/library.md similarity index 100% rename from docs/track/library.md rename to docs/tracks/library.md diff --git a/docs/track/models.md b/docs/tracks/models.md similarity index 100% rename from docs/track/models.md rename to docs/tracks/models.md diff --git a/docs/track/views.md b/docs/tracks/views.md similarity index 100% rename from docs/track/views.md rename to docs/tracks/views.md From 851adaa735bc96dd0196082c7d0ae870279003df Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 10:17:55 +0000 Subject: [PATCH 039/102] Create configuration.md --- docs/tracks/configuration.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/tracks/configuration.md diff --git a/docs/tracks/configuration.md b/docs/tracks/configuration.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/docs/tracks/configuration.md @@ -0,0 +1 @@ + From 8235fc1533ddf82bf3519a97373c8dbead3eb111 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 10:43:23 +0000 Subject: [PATCH 040/102] Update tracks.md --- docs/tracks.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) diff --git a/docs/tracks.md b/docs/tracks.md index 895e8f28..b0a9c06f 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -1,3 +1,103 @@ # Tracks Genoverse's tracks are responsible for obtaining data from a source (a URL, file, or JavaScript array) and visualizing it in the genome browser. + +Tracks are defined in the `Genoverse.Track` namespace. Each track has its own data, set stored in a [`Genoverse.Track.Model`](docs/track_model.md), a method for displaying that data, stored in a [`Genoverse.Track.View`](docs/track_view.md), and a [`Genoverse.Track.Controller`](docs/track_controller.md) to manage the creation of DOM elements, and user interactions with them. + +Tracks and their MVC components are object-oriented, created using Dean Edward's [Base.js](http://dean.edwards.name/weblog/2006/03/base/) library. This library provides the `extend` function for inheritance, and the ability to call `this.base()` inside any inherited function in order to access it parent's method of the same name, for example: + +```javascript +// Adapted from the example on http://dean.edwards.name/weblog/2006/03/base/ +var Parent = Base.extend({ + method: function() { + alert("Hello World!"); + } +}); + +var Child = Parent.extend({ + method: function() { + // call the "super" method + this.base(); + // add some code + alert("Hello again!"); + } +}); + +new Child().method(); +// ==> Hello World! +// ==> Hello again! +``` + +## Configuration + +The tracks to be used by an instance of Genoverse are defined by the [tracks configuration property](docs/configuration.md#tracks-default-). This is an array containing either tracks from the [library](js/Track/library), or extensions of them or `Genoverse.Track` itself, for example: + +```javascript +[ + Genoverse.Track.Scalebar, + Genoverse.Track.Gene.extend({ + url: 'http://my.website.com/path/to/gene/data?chr=__CHR__&start=__START__&end=__END__' + }), + Genoverse.Track.extend({ + id: 'myTrack', + name: 'My track', + url: 'http://my.website.com/path/to/track/data?chr=__CHR__&start=__START__&end=__END__' + }) +] +``` + +This would create a genome browser with three tracks - a scalebar, genes from your data source (rather than the default, which is Ensembl's REST API), and a set of rectangles drawn based on start and end coordinates given by `http://my.website.com/path/to/track/data`. + +Track definitions can be extended to inherit or overwrite any functions existing in the `Genoverse.Track`, `Genoverse.Track.Model`, `Genoverse.Track.View` or `Genoverse.Track.Controller` namespaces, without having to know which namespace those functions are in. For example, the `draw` function is located in `Genoverse.Track.View`, but you can create a track which extends it as follows: + +```javascript + Genoverse.Track.MyTrack = Genoverse.Track.extend({ + draw: function () { + // Do my drawing operations + + this.base.apply(this, arguments); // Call the parent function will all the input arguments + } + }); +``` + +The same is true for non-function properties of the MVC components. This makes it easy to create your own tracks without having to explicitly define their models, views and controllers. It should be noted, however, that if you want, for example, a reusable view, you will need to create a `Genoverse.Track.View`, at which point it is important to know what properties belong to it. + +For more details of the properties and functions which can be extended or overwritten to create new types of tracks, see [here](docs/tracks/configuration.md). + +## Multiple models and views + +In addition to its default configuration, a track can also have multiple models and views, which are swapped in and out depending on the size of the region being viewed in the genome browser. These region size configurations are defined using numerical keys whose values are objects of properties to be used at or below those sizes. A good example of this is `Genoverse.Track.Gene`, which is defined as: + +```javascript +Genoverse.Track.extend({ + ... + 2000000: { // This one applies when > 2M base-pairs per screen + labels : false + }, + 100000: { // more than 100K but less then 2M + labels : true, + model : Genoverse.Track.Model.Gene.Ensembl, + view : Genoverse.Track.View.Gene.Ensembl + }, + 1: { // > 1 base-pair, but less then 100K + labels : true, + model : Genoverse.Track.Model.Transcript.Ensembl, + view : Genoverse.Track.View.Transcript.Ensembl + } +}); +``` + +In regions between 1 (inclusive) and 100kb (exclusive), transcripts are displayed, with labels. In regions between 100k (inclusive) and 2Mb (exclusive), genes are displayed with labels. Above 2Mb (inclusive), genes are displayed without labels. Note that the 2Mb configuration does not provide a model or view class - these are copied from the previous (next biggest) configuration. If smaller configurations do not provide model or view classes, the values for `track.model` and `track.view` are used. These default to `Genoverse.Track.Model` and `Genoverse.Track.View`. + +Another example would be: + +```javascript +Genoverse.Track.extend({ + ... + bump: true, + 10000: false, + 5000: { bump: false } +}); +``` + +In this case, features in the track are "bumped" - moved vertically within the track so that no features overlap horizontally - between 1 and 4999bp. Between 5000 and 9999bp, the features are not bumped. At 10kb and above, features are not displayed. At all times, the track will use instances of `Genoverse.Track.Model` and `Genoverse.Track.View`. In fact, in this scenario the track has two views - one with bumping, the other without - but only one model, since no model properties are changed between configurations. From 3a6884a249f12d3df5c4ec30105f8c69c6eac6df Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 10:44:38 +0000 Subject: [PATCH 041/102] Update tracks.md --- docs/tracks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tracks.md b/docs/tracks.md index b0a9c06f..2db9d46a 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -30,7 +30,7 @@ new Child().method(); ## Configuration -The tracks to be used by an instance of Genoverse are defined by the [tracks configuration property](docs/configuration.md#tracks-default-). This is an array containing either tracks from the [library](js/Track/library), or extensions of them or `Genoverse.Track` itself, for example: +The tracks to be used by an instance of Genoverse are defined by the [tracks configuration property](docs/configuration.md#tracks-default-). This is an array containing either tracks from the [library](docs/tracks/library.md), or extensions of them or `Genoverse.Track` itself, for example: ```javascript [ From d416d6d482d3e7d5c0f314347abff19c1d21fb97 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 10:46:39 +0000 Subject: [PATCH 042/102] Update tracks.md --- docs/tracks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tracks.md b/docs/tracks.md index 2db9d46a..bf1cc292 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -2,7 +2,7 @@ Genoverse's tracks are responsible for obtaining data from a source (a URL, file, or JavaScript array) and visualizing it in the genome browser. -Tracks are defined in the `Genoverse.Track` namespace. Each track has its own data, set stored in a [`Genoverse.Track.Model`](docs/track_model.md), a method for displaying that data, stored in a [`Genoverse.Track.View`](docs/track_view.md), and a [`Genoverse.Track.Controller`](docs/track_controller.md) to manage the creation of DOM elements, and user interactions with them. +Tracks are defined in the `Genoverse.Track` namespace. Each track has its own data, set stored in a [`Genoverse.Track.Model`](/docs/tracks/models.md), a method for displaying that data, stored in a [`Genoverse.Track.View`](/docs/tracks/views.md), and a [`Genoverse.Track.Controller`](/docs/tracks/controllers.md) to manage the creation of DOM elements, and user interactions with them. Tracks and their MVC components are object-oriented, created using Dean Edward's [Base.js](http://dean.edwards.name/weblog/2006/03/base/) library. This library provides the `extend` function for inheritance, and the ability to call `this.base()` inside any inherited function in order to access it parent's method of the same name, for example: @@ -30,7 +30,7 @@ new Child().method(); ## Configuration -The tracks to be used by an instance of Genoverse are defined by the [tracks configuration property](docs/configuration.md#tracks-default-). This is an array containing either tracks from the [library](docs/tracks/library.md), or extensions of them or `Genoverse.Track` itself, for example: +The tracks to be used by an instance of Genoverse are defined by the [tracks configuration property](/docs/configuration.md#tracks-default-). This is an array containing either tracks from the [library](/docs/tracks/library.md), or extensions of them or `Genoverse.Track` itself, for example: ```javascript [ @@ -62,7 +62,7 @@ Track definitions can be extended to inherit or overwrite any functions existing The same is true for non-function properties of the MVC components. This makes it easy to create your own tracks without having to explicitly define their models, views and controllers. It should be noted, however, that if you want, for example, a reusable view, you will need to create a `Genoverse.Track.View`, at which point it is important to know what properties belong to it. -For more details of the properties and functions which can be extended or overwritten to create new types of tracks, see [here](docs/tracks/configuration.md). +For more details of the properties and functions which can be extended or overwritten to create new types of tracks, see [here](/docs/tracks/configuration.md). ## Multiple models and views From 7293f82c08db681396048fe28371ea99e09694b5 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 10:49:01 +0000 Subject: [PATCH 043/102] Update tracks.md --- docs/tracks.md | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/tracks.md b/docs/tracks.md index bf1cc292..da2abc6a 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -9,9 +9,9 @@ Tracks and their MVC components are object-oriented, created using Dean Edward's ```javascript // Adapted from the example on http://dean.edwards.name/weblog/2006/03/base/ var Parent = Base.extend({ - method: function() { - alert("Hello World!"); - } + method: function() { + alert("Hello World!"); + } }); var Child = Parent.extend({ @@ -34,15 +34,15 @@ The tracks to be used by an instance of Genoverse are defined by the [tracks con ```javascript [ - Genoverse.Track.Scalebar, - Genoverse.Track.Gene.extend({ - url: 'http://my.website.com/path/to/gene/data?chr=__CHR__&start=__START__&end=__END__' - }), - Genoverse.Track.extend({ - id: 'myTrack', - name: 'My track', - url: 'http://my.website.com/path/to/track/data?chr=__CHR__&start=__START__&end=__END__' - }) + Genoverse.Track.Scalebar, + Genoverse.Track.Gene.extend({ + url: 'http://my.website.com/path/to/gene/data?chr=__CHR__&start=__START__&end=__END__' + }), + Genoverse.Track.extend({ + id : 'myTrack', + name : 'My track', + url : 'http://my.website.com/path/to/track/data?chr=__CHR__&start=__START__&end=__END__' + }) ] ``` @@ -51,13 +51,13 @@ This would create a genome browser with three tracks - a scalebar, genes from yo Track definitions can be extended to inherit or overwrite any functions existing in the `Genoverse.Track`, `Genoverse.Track.Model`, `Genoverse.Track.View` or `Genoverse.Track.Controller` namespaces, without having to know which namespace those functions are in. For example, the `draw` function is located in `Genoverse.Track.View`, but you can create a track which extends it as follows: ```javascript - Genoverse.Track.MyTrack = Genoverse.Track.extend({ - draw: function () { - // Do my drawing operations - - this.base.apply(this, arguments); // Call the parent function will all the input arguments - } - }); +Genoverse.Track.MyTrack = Genoverse.Track.extend({ + draw: function () { + // Do my drawing operations + + this.base.apply(this, arguments); // Call the parent function will all the input arguments + } +}); ``` The same is true for non-function properties of the MVC components. This makes it easy to create your own tracks without having to explicitly define their models, views and controllers. It should be noted, however, that if you want, for example, a reusable view, you will need to create a `Genoverse.Track.View`, at which point it is important to know what properties belong to it. @@ -94,9 +94,9 @@ Another example would be: ```javascript Genoverse.Track.extend({ ... - bump: true, - 10000: false, - 5000: { bump: false } + bump : true, + 10000 : false, + 5000 : { bump: false } }); ``` From 81eae885098b6c32bdf7bb3aa80b4a39833a280c Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 10:49:17 +0000 Subject: [PATCH 044/102] Update tracks.md --- docs/tracks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tracks.md b/docs/tracks.md index da2abc6a..fb88ebca 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -36,7 +36,7 @@ The tracks to be used by an instance of Genoverse are defined by the [tracks con [ Genoverse.Track.Scalebar, Genoverse.Track.Gene.extend({ - url: 'http://my.website.com/path/to/gene/data?chr=__CHR__&start=__START__&end=__END__' + url: 'http://my.website.com/path/to/gene/data?chr=__CHR__&start=__START__&end=__END__' }), Genoverse.Track.extend({ id : 'myTrack', From 438d0f0f4ed441d4fecaca507b0e5d9712e0085f Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 10:53:45 +0000 Subject: [PATCH 045/102] Update tracks.md --- docs/tracks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tracks.md b/docs/tracks.md index fb88ebca..b2ba89e8 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -60,7 +60,7 @@ Genoverse.Track.MyTrack = Genoverse.Track.extend({ }); ``` -The same is true for non-function properties of the MVC components. This makes it easy to create your own tracks without having to explicitly define their models, views and controllers. It should be noted, however, that if you want, for example, a reusable view, you will need to create a `Genoverse.Track.View`, at which point it is important to know what properties belong to it. +The same is true for non-function properties of the MVC components. This makes it easy to create your own tracks without having to explicitly define their models, views and controllers. It should be noted however that if you want, for example, a reusable view, you will need to create a `Genoverse.Track.View`, at which point it is important to know what properties belong to it. For more details of the properties and functions which can be extended or overwritten to create new types of tracks, see [here](/docs/tracks/configuration.md). From e97c2a1618febd7c87ca23fc00ca6d5d876cbc04 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 11:15:36 +0000 Subject: [PATCH 046/102] Update tracks.md --- docs/tracks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tracks.md b/docs/tracks.md index b2ba89e8..e5f0cc90 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -87,7 +87,7 @@ Genoverse.Track.extend({ }); ``` -In regions between 1 (inclusive) and 100kb (exclusive), transcripts are displayed, with labels. In regions between 100k (inclusive) and 2Mb (exclusive), genes are displayed with labels. Above 2Mb (inclusive), genes are displayed without labels. Note that the 2Mb configuration does not provide a model or view class - these are copied from the previous (next biggest) configuration. If smaller configurations do not provide model or view classes, the values for `track.model` and `track.view` are used. These default to `Genoverse.Track.Model` and `Genoverse.Track.View`. +In regions between 1 (inclusive) and 100kb (exclusive), transcripts are displayed, with labels. In regions between 100k (inclusive) and 2Mb (exclusive), genes are displayed with labels. Above 2Mb (inclusive), genes are displayed without labels. Note that the 2Mb configuration does not provide a model or view class - these are copied from the previous (next biggest numerical key, i.e. 100000) configuration. If smaller configurations do not provide model or view classes, the values for `track.model` and `track.view` are used. These default to `Genoverse.Track.Model` and `Genoverse.Track.View`. Another example would be: From 79ebaaad34cd20762f7778a8f009918b3943a47e Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 14:27:33 +0000 Subject: [PATCH 047/102] Update configuration.md --- docs/tracks/configuration.md | 131 +++++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) diff --git a/docs/tracks/configuration.md b/docs/tracks/configuration.md index 8b137891..c217a977 100644 --- a/docs/tracks/configuration.md +++ b/docs/tracks/configuration.md @@ -1 +1,132 @@ +# Track configuration + +The following are properties for `Genoverse.Track` and its MVC components. These can be overwritten to customize the way tracks get data and display it in the browser. + +### Track display, resizing, and reordering + +#### name (default `undefined`) +> The name of the track, which appears in its label on the left of the genome browser + +#### height (default `12`) +> The initial height in pixels of the DOM element containing the track + +#### resizable (default `true`) +> Determines whether the track's height can changed. Can be: +> +> - `true` - the user can resize the track +> - `false` - the track cannot be resized +> - `"auto"` - the track will automatically resize to show all features, but the user cannot resize it themselves + +#### autoHeight (default `undefined`) +> Determines whether the track automatically resize so that all the features are visible. Can be: +> +> - `true` - identical to `resizable = "auto"`, above +> - `false` - the track will not automatically resize +> - `undefined` - the track will use [`genoverse.trackAutoHeight`](/docs/configuration.md#trackautoheight-default-false) to set `track.autoHeight` + +#### hideEmpty (default `undefined`) +> If the track automatically resizes, determines whether should it be hidden when there are no features +> +> - `true` - the track will be hidden if there are no features in view +> - `false` - the track will be displayed if there are no features in view +> - `undefined` - the track will use [`genoverse.hideEmptyTracks`](/docs/configuration.md#hideemptytracks-default-true) to set `track.hideEmpty` + +#### margin (default `2`) +> The whitespace in pixels between this track and the one below it in the genome browser. This will appear as extra pixels in height at the bottom of the track. + +#### border (default `true`) +> If `true`, the track will have a 1px grey bottom border + +#### unsortable (default `false`) +> If `true`, the track cannot be moved by the user. If `false`, a drag handle will appear next to the track's name, allowing the user to change its vertical position within the genome browser. + + +### Fetching data + +#### url (default `undefined`) +> The URL template used to fetch data from a server. Can contain placeholders for `__ASSEMBLY__`, `__CHR__`, `__START__`, and `__END__`, for example +> ``` +> http://my.website.com/__ASSEMBLY__/path/to/track/data?chr=__CHR__&start=__START__&end=__END__ +> ``` +> These placeholders will be replaces with `genoverse.assembly`, `genoverse.chr`, and the start and end for the request respectively, before data is fetched from the server. + +#### urlParams (default `undefined`) +> An object of query parameters to be added to each request for data, for example: +> ``` +> url: "http://my.website.com/data?chr=__CHR__&start=__START__&end=__END__", +> urlParams: { "foo": "bar" } +> ``` +> will result in a URL like `http://my.website.com/data?chr=1&start=1&end=10000&foo=bar` + +#### data (default `undefined`) +> Will be used instead of fetching data from a source, if defined as an array of objects (these objects should fulfill the requirements of a Genoverse **feature**). `track.url` is not required if `track.data` is supplied. + +#### allData (default `false`) +> If `true`, the initial request for data is assumed to contain all the track's data for the current chromosome. No subsequent requests will be made as the user navigates the genome. + +#### dataType (default `"json"`) +> The dataType setting to be used in the [jQuery.ajax](http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings) requests to get data for the track + +#### xhrFields (default `undefined`) +> The xhrFields setting to be used in the [jQuery.ajax](http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings) requests to get data for the track + +### Drawing features + +#### featureHeight (default `undefined`) +> The height of each feature, if `feature.height` is not set. If `undefined`, will be set to `track.height` + +#### featureMargin (default `{ top: 3, right: 1, bottom: 1, left: 0 }`) +> The space in pixels around each feature, used when positioning the feature on the canvas, and for bumping (below). If any property is left undefined, it will default to 0. Top and right margins can be overwritten for individual features using `feature.marginTop` and `feature.marginRight`. To draw features that should touch each other (e.g. bases of sequence), `featureMargin` should be set to `{ top: 0, right: 0, bottom: 0, left: 0 }`. + +#### color (default `"#000000"`) +> The color for each features, if `feature.color` is not set + +#### fontColor (default `undefined`) +> The default color for feature labels. If `undefined`, a feature's label color will be `feature.color`, or `track.color` (above), in that order of precedence. + +#### fontWeight (default ` "normal"`) +> Combined with `fontHeight` and `fontFamily` to set the font for the canvas element used to draw the track's features + +#### fontHeight (default `10`) +> Combined with `fontWeight` and `fontFamily` to set the font for the canvas element used to draw the track's features. Value is given in pixels. + +#### fontFamily (default `"sans-serif"`) +> Combined with `fontHeight` and `fontWeight` to set the font for the canvas element used to draw the track's features + +#### labels (default `true`) +> Determines how feature labels are drawn. Can be: +> +> - `true` - display a feature's label directly below the feature, at the start of the feature +> - `"overlay"` - display a feature's label within the feature, if the feature is wide enough to contain the label, in the center of the feature +> - `"separate"` - display all features' labels on a separate canvas, below all of the features, in line with the start of their feature. Labels will be bumped (see below) to ensure they are all visible. +> - `false` - do not display feature labels + +#### repeatLabels (default `false`) +> If `true`, a feature's label is repeated along the length of the feature, such that an instance of the label will always be in view + +#### bump (default `false`) +> Determines whether features are moved vertically within the track so that the do not overlap horizontally. Can be: +> +> - `true` - features are moved vertically +> - `false` - features are not moved vertically, and can overlap +> `"labels"` - features are not moved vertically, but if `track.labels === true`, `track.labels` is set to `"separate"`, so labels can be bumped while features are not + +#### depth (default `undefined`) +> If set to an integer, this is the maximum bumping depth for features in the track. Features which need to be moved vertically to beyond this depth (e.g. if depth = 2 and three features have the same start and end) will not be drawn. + +#### threshold (default `Infinity`) +> The integer size of region above which the track's features are not drawn. Synonymous with `[numerical key]: false` ([see here](/docs/tracks.md#multiple-models-and-views)), such that +> ``` +> Genoverse.Track.extend({ threshold: 100000 }) +> ``` +> and +> ``` +> Genoverse.Track.extend({ 100000: false }) +> ``` +> have the same effect. + +### Interacting with features + +#### clickTolerance (default `0`) +> Pixels of tolerance added to a click position when finding features for popup menus, when scale < 1. Increase to make it easier to click on small features (e.g. 1bp variants) when looking at large regions, at the cost of possibly showing feature menus for more features than expected. From 3932e73e26428946ea2ea75a8c74a7edb8627166 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 14:28:16 +0000 Subject: [PATCH 048/102] Update configuration.md --- docs/configuration.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/configuration.md b/docs/configuration.md index 871c2b17..d92976f7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -31,6 +31,9 @@ If `undefined`, a `
` element will be appended to `document.body`. #### end (default `1000000`) > A string or number defining the initial end position +#### assembly (default `undefined`) +> A string defining the assembly, which can be used by [track URL templates](/docs/tracks/configuration.md#url-default-undefined) + #### genome (default `undefined`) > The genome to be used. Can be: > From f76aa4ef6d229b6d685794aa18cc16440f1ecf7b Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 14:29:55 +0000 Subject: [PATCH 049/102] Update configuration.md --- docs/tracks/configuration.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/tracks/configuration.md b/docs/tracks/configuration.md index c217a977..ba5eebb5 100644 --- a/docs/tracks/configuration.md +++ b/docs/tracks/configuration.md @@ -40,7 +40,6 @@ The following are properties for `Genoverse.Track` and its MVC components. These #### unsortable (default `false`) > If `true`, the track cannot be moved by the user. If `false`, a drag handle will appear next to the track's name, allowing the user to change its vertical position within the genome browser. - ### Fetching data #### url (default `undefined`) @@ -48,7 +47,7 @@ The following are properties for `Genoverse.Track` and its MVC components. These > ``` > http://my.website.com/__ASSEMBLY__/path/to/track/data?chr=__CHR__&start=__START__&end=__END__ > ``` -> These placeholders will be replaces with `genoverse.assembly`, `genoverse.chr`, and the start and end for the request respectively, before data is fetched from the server. +> These placeholders will be replaces with [`genoverse.assembly`](/docs/configuration.md#assembly-default-undefined), `genoverse.chr`, and the start and end for the request respectively, before data is fetched from the server. #### urlParams (default `undefined`) > An object of query parameters to be added to each request for data, for example: From 2b41594b07feffe94d75a4e16e7c0a7c5cf6fd15 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 19 Dec 2016 15:04:23 +0000 Subject: [PATCH 050/102] Update plugins.md --- docs/plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins.md b/docs/plugins.md index 4d2e045e..9848a967 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -14,7 +14,7 @@ Adds Adds an ideogram of the chromosome being used by the genome browser, with a marker showing the currently viewed region. The marker and be dragged and resized to change region, and chromosome bands can be jumped to by clicked on them. ### trackControls -Adds a toggleable pop-out menu to the right side of the track, containing buttons to view track information, remove the track, toggle the track between fixed height and auto resizing, and change track filters/configuration settings, if there are any. +Adds a toggleable pop-out menu on the right side of the track, containing buttons to view track information, remove the track, toggle the track between fixed height and auto resizing, and change track filters/configuration settings, if there are any. ### resizer Adds a draggable handle to the bottom of each track, to allow the user to resize it to their desired height. If this plugin is not in use, tracks can only be resized to show all features currently in view. From 399ec4d697e3c71bd24381a0e1444d9d0c169090 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 20 Dec 2016 17:15:04 +0000 Subject: [PATCH 051/102] Update tracks.md --- docs/tracks.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/docs/tracks.md b/docs/tracks.md index e5f0cc90..6fd1fa2d 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -101,3 +101,72 @@ Genoverse.Track.extend({ ``` In this case, features in the track are "bumped" - moved vertically within the track so that no features overlap horizontally - between 1 and 4999bp. Between 5000 and 9999bp, the features are not bumped. At 10kb and above, features are not displayed. At all times, the track will use instances of `Genoverse.Track.Model` and `Genoverse.Track.View`. In fact, in this scenario the track has two views - one with bumping, the other without - but only one model, since no model properties are changed between configurations. + +## Allowing a user to change a track's configuration + +As well as multiple models and views, it is possible to add user controls to tracks, providing the [trackControls plugin](/docs/plugins.md#trackcontrols) is enabled. This plugin provides a pop-out menu on the right side of the track, containing a set of buttons for interacting with the track. + +It is possible to prepend additional controls to this menu by defining `controls` and `configSettings` properties for a track. + +The `controls` property should be an array containing elements which are either + +- a HTML string including a `"data-control"` attribute that can be made into a [jQuery](http://api.jquery.com/jQuery/#jQuery2) object +- a jQuery object with a [data](http://api.jquery.com/jQuery.data/) `"control"` value, which will be cloned (data and events bound to the object will be included in the clone) +- an object as follows: + + ```javascript + { + "type": "select", // A type of DOM node + "name": "myControl", // Equivalent of data-control attribute + "options": [ // other types of DOM node can be give, and don't require an options property + { "value": "typeA", "text": "Type A" }, + { "value": "typeB", "text": "Type B" }, + ] + } + ``` + +In each case, the data-control attribute will be used as keys in the `configSettings` property (below), and the values of the control's option DOM elements will be used as keys within that. Alternatively, for non-select controls, a click handler could be added directly to the control, to perform modifications to the track. + +### An example + +```javascript +Genoverse.Track.Gene.extend({ + controls: [ + '', + '' + ], + configSettings : { + coding: { + all : { featureFilter: false }, + coding : { featureFilter: function (feature) { return feature.biotype == 'protein_coding'; } }, + noncoding : { featureFilter: function (feature) { return feature.biotype != 'protein_coding'; } } + }, + colorscheme: { + ensembl : { setFeatureColor: function (f) { this.base(f); } }, + red : { setFeatureColor: function (f) { f.color = 'red'; } }, + black : { setFeatureColor: function (f) { f.color = 'black'; } } + } + }, + + setConfig: function (type, config) { + this.base(type, config); + + if (type === 'colorscheme') { + this.legendTrack[config === 'ensembl' ? 'enable' : 'disable'](); + } else if (!this.legendTrack.disabled) { + this.legendTrack.disable(); + this.legendTrack.enable(); + } + } +}), +``` + +This example defines a gene track with two additional controls: one to filter genes based on their biotype, and a second to change the color used to draw those genes. The `setConfig` function disables the gene's legend when the genes are all one color. From c289e70b1275e9b1a662a99bf29bcbb84ceb0ae9 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 20 Dec 2016 17:15:55 +0000 Subject: [PATCH 052/102] Update tracks.md --- docs/tracks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tracks.md b/docs/tracks.md index 6fd1fa2d..d7359c83 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -166,7 +166,7 @@ Genoverse.Track.Gene.extend({ this.legendTrack.enable(); } } -}), +}) ``` This example defines a gene track with two additional controls: one to filter genes based on their biotype, and a second to change the color used to draw those genes. The `setConfig` function disables the gene's legend when the genes are all one color. From 9e389c566858d9b2a61859d01a8f368b728d0343 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 3 Jan 2017 10:35:04 +0000 Subject: [PATCH 053/102] Update tracks.md --- docs/tracks.md | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/docs/tracks.md b/docs/tracks.md index d7359c83..9287bb3c 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -150,20 +150,9 @@ Genoverse.Track.Gene.extend({ noncoding : { featureFilter: function (feature) { return feature.biotype != 'protein_coding'; } } }, colorscheme: { - ensembl : { setFeatureColor: function (f) { this.base(f); } }, - red : { setFeatureColor: function (f) { f.color = 'red'; } }, - black : { setFeatureColor: function (f) { f.color = 'black'; } } - } - }, - - setConfig: function (type, config) { - this.base(type, config); - - if (type === 'colorscheme') { - this.legendTrack[config === 'ensembl' ? 'enable' : 'disable'](); - } else if (!this.legendTrack.disabled) { - this.legendTrack.disable(); - this.legendTrack.enable(); + ensembl : { setFeatureColor: function (f) { this.base(f); } }, + red : { setFeatureColor: function (f) { f.color = 'red'; }, legend: false }, + black : { setFeatureColor: function (f) { f.color = 'black'; }, legend: false } } } }) From 5767d9b015c58fd101ce3d7cf3b5c800c0f8af29 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Wed, 4 Jan 2017 11:12:10 +0000 Subject: [PATCH 054/102] Update tracks.md --- docs/tracks.md | 70 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 54 insertions(+), 16 deletions(-) diff --git a/docs/tracks.md b/docs/tracks.md index 9287bb3c..ab6d38a9 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -130,32 +130,70 @@ In each case, the data-control attribute will be used as keys in the `configSett ### An example ```javascript -Genoverse.Track.Gene.extend({ +Genoverse.Track.extend({ + data: [ + { chr: 1, start: 1, end: 1000, type: 'A', subtype: 1, color: 'black' }, + { chr: 1, start: 2000, end: 3000, type: 'A', subtype: 2, color: 'blue' }, + { chr: 1, start: 4000, end: 5000, type: 'B', subtype: 2, color: 'orange' }, + { chr: 1, start: 6000, end: 7000, type: 'B', subtype: 1, color: 'purple' } + ], controls: [ - '' + + '' + + '' + + '' + + '', + '', '' + '' + + '', + $('Squish').on('click', function () { + var track = $(this).text(function (i, text) { return /Un/.test(text) ? 'Squish' : 'Unsquish'; }).data('track'); + track.setConfig('squish', !track.config.squish); + }) ], - configSettings : { - coding: { - all : { featureFilter: false }, - coding : { featureFilter: function (feature) { return feature.biotype == 'protein_coding'; } }, - noncoding : { featureFilter: function (feature) { return feature.biotype != 'protein_coding'; } } + configSettings: { + type: { + all : { featureFilter: false }, + a : { featureFilter: function (feature) { return feature.type == 'A'; } }, + b : { featureFilter: function (feature) { return feature.type == 'B'; } } + }, + subtype: { + all : { featureFilter: false }, + 1 : { featureFilter: function (feature) { return feature.subtype == 1; } }, + 2 : { featureFilter: function (feature) { return feature.subtype == 2; } } }, colorscheme: { - ensembl : { setFeatureColor: function (f) { this.base(f); } }, - red : { setFeatureColor: function (f) { f.color = 'red'; }, legend: false }, - black : { setFeatureColor: function (f) { f.color = 'black'; }, legend: false } + default : { beforeDrawFeature: $.noop }, + red : { beforeDrawFeature: function (f) { f.color = 'red'; } }, + green : { beforeDrawFeature: function (f) { f.color = 'green'; } } + }, + squish: { + true: { + featureHeight : 2, + featureMargin : { top: 1, right: 1, bottom: 1, left: 0 }, + labels : false + }, + false: { + featureHeight : 6, + featureMargin : { top: 2, right: 2, bottom: 2, left: 0 }, + labels : true + } } + }, + defaultConfig: { + type : 'all', + subtype : 'all', + colorscheme : 'default', + squish : false } }) ``` -This example defines a gene track with two additional controls: one to filter genes based on their biotype, and a second to change the color used to draw those genes. The `setConfig` function disables the gene's legend when the genes are all one color. +This example defines a track with four controls: one to filter features based on their `type` attribute, and a second to filter features based on their `subtype` attribute, a third to change the color used to draw those features, and a fourth to "squish" the features, giving them a smaller height and removing their labels. The `defaultConfig` attribute defines the initial state of those controls. Note that `featureFilter` controls can be combined so that, for example, it is possible to display only those features of type A and subtype 1. From 208cc8ba3d6436cbe72b110b4e6d280d8f183ccd Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Wed, 4 Jan 2017 11:39:23 +0000 Subject: [PATCH 055/102] Update tracks.md --- docs/tracks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tracks.md b/docs/tracks.md index ab6d38a9..de679fa6 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -170,7 +170,7 @@ Genoverse.Track.extend({ 2 : { featureFilter: function (feature) { return feature.subtype == 2; } } }, colorscheme: { - default : { beforeDrawFeature: $.noop }, + default : { beforeDrawFeature: false }, red : { beforeDrawFeature: function (f) { f.color = 'red'; } }, green : { beforeDrawFeature: function (f) { f.color = 'green'; } } }, From 8131e517e71d661de6bb854d23857d7664162454 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 10 Jan 2017 16:01:03 +0000 Subject: [PATCH 056/102] Create api.md --- docs/tracks/api.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/tracks/api.md diff --git a/docs/tracks/api.md b/docs/tracks/api.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/docs/tracks/api.md @@ -0,0 +1 @@ + From 6f8c8c999032a25d5ab247a730562be62c36f14f Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 10 Jan 2017 16:05:08 +0000 Subject: [PATCH 057/102] Update api.md --- docs/tracks/api.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/tracks/api.md b/docs/tracks/api.md index 8b137891..7b05f183 100644 --- a/docs/tracks/api.md +++ b/docs/tracks/api.md @@ -1 +1,5 @@ +#### track.setConfig(config) +> set config with a hash +#### track.setConfig(type, name) +> set config with two strings From 0c07a5264d29d52c9e07a8bf66207904fceb9694 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 10 Jan 2017 16:07:18 +0000 Subject: [PATCH 058/102] Update configuration.md --- docs/tracks/configuration.md | 48 ++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/docs/tracks/configuration.md b/docs/tracks/configuration.md index ba5eebb5..89eaa099 100644 --- a/docs/tracks/configuration.md +++ b/docs/tracks/configuration.md @@ -129,3 +129,51 @@ The following are properties for `Genoverse.Track` and its MVC components. These #### clickTolerance (default `0`) > Pixels of tolerance added to a click position when finding features for popup menus, when scale < 1. Increase to make it easier to click on small features (e.g. 1bp variants) when looking at large regions, at the cost of possibly showing feature menus for more features than expected. +### Changing track settings + +#### configSettings (default `undefined`) +> An object defining properties of the track (including its models, views, and controller) which can be changed after initialization, as follows: +> ```javascript +> { +> example1: { +> config1: { property1: "a", property2: "b", function1: function () { ... }, ... }, +> config2: { property1: "x", property2: "y", function1: function () { ... }, ... } +> }, +> example2: { +> config1: { property3: "a", property4: "b", function2: function () { ... }, ... }, +> config2: { property3: "x", property4: "y", function2: function () { ... }, ... } +> } +> } +> ``` +> See [`track.setConfig`](/docs/tracks/api.md#tracksetconfigconfig) for details of how to change between different settings. + +#### defaultSettings (default `undefined`) +> An object defining which `configSettings` are used on track initialization, in the form: +> ```javascript +> { example1: "config1", example2: "config2" } +> ``` +> __Required__ when `configSettings` is provided. + +#### controls (default `undefined`) +> An array providing users with the ability to change the track's configuration, providing the [trackControls plugin](/docs/plugins.md#trackcontrols) is enabled. +> The elements of the array can be: +> +> - a HTML string including a `"data-control"` attribute that can be made into a [jQuery](http://api.jquery.com/jQuery/#jQuery2) object +> - a jQuery object with a [data](http://api.jquery.com/jQuery.data/) `"control"` value, which will be cloned (data and events bound to the object will be included in the clone) +> - an object as follows: +> +> ```javascript +> { +> "type": "select", // A type of DOM node +> "name": "myControl", // Equivalent of data-control attribute +> "options": [ // other types of DOM node can be give, and don't require an options property +> { "value": "typeA", "text": "Type A" }, +> { "value": "typeB", "text": "Type B" }, +> ] +> } +> ``` +> +> In each case, the data-control attribute will be used as keys in the `configSettings` property (above), and the values of the control's option DOM elements will be used as keys within that. Alternatively, for non-select controls, a click handler could be added directly to the control, to perform modifications to the track. +> + +[See here](/docs/tracks.md#allowing-a-user-to-change-a-tracks-configuration) for more information about track configurations. From a2e9e017111080d373e6201bc1c3fcf6ad2d1a86 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 10 Jan 2017 16:09:08 +0000 Subject: [PATCH 059/102] Update configuration.md --- docs/tracks/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tracks/configuration.md b/docs/tracks/configuration.md index 89eaa099..774bb097 100644 --- a/docs/tracks/configuration.md +++ b/docs/tracks/configuration.md @@ -147,7 +147,7 @@ The following are properties for `Genoverse.Track` and its MVC components. These > ``` > See [`track.setConfig`](/docs/tracks/api.md#tracksetconfigconfig) for details of how to change between different settings. -#### defaultSettings (default `undefined`) +#### defaultConfig (default `undefined`) > An object defining which `configSettings` are used on track initialization, in the form: > ```javascript > { example1: "config1", example2: "config2" } From beee3eac7c30956e9221f5e24160b7d47fe77d1e Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 10 Jan 2017 16:10:34 +0000 Subject: [PATCH 060/102] Update tracks.md --- docs/tracks.md | 21 +-------------------- 1 file changed, 1 insertion(+), 20 deletions(-) diff --git a/docs/tracks.md b/docs/tracks.md index de679fa6..bc43a8ed 100644 --- a/docs/tracks.md +++ b/docs/tracks.md @@ -106,26 +106,7 @@ In this case, features in the track are "bumped" - moved vertically within the t As well as multiple models and views, it is possible to add user controls to tracks, providing the [trackControls plugin](/docs/plugins.md#trackcontrols) is enabled. This plugin provides a pop-out menu on the right side of the track, containing a set of buttons for interacting with the track. -It is possible to prepend additional controls to this menu by defining `controls` and `configSettings` properties for a track. - -The `controls` property should be an array containing elements which are either - -- a HTML string including a `"data-control"` attribute that can be made into a [jQuery](http://api.jquery.com/jQuery/#jQuery2) object -- a jQuery object with a [data](http://api.jquery.com/jQuery.data/) `"control"` value, which will be cloned (data and events bound to the object will be included in the clone) -- an object as follows: - - ```javascript - { - "type": "select", // A type of DOM node - "name": "myControl", // Equivalent of data-control attribute - "options": [ // other types of DOM node can be give, and don't require an options property - { "value": "typeA", "text": "Type A" }, - { "value": "typeB", "text": "Type B" }, - ] - } - ``` - -In each case, the data-control attribute will be used as keys in the `configSettings` property (below), and the values of the control's option DOM elements will be used as keys within that. Alternatively, for non-select controls, a click handler could be added directly to the control, to perform modifications to the track. +It is possible to prepend additional controls to this menu by defining [`configSettings`](/docs/tracks/configuration.md#configsettings-default-undefined), [`defaultConfig`](/docs/tracks/configuration.md#defaultconfig-default-undefined), and [`controls`](/docs/tracks/configuration.md#controls-default-undefined), properties for a track. ### An example From aabf105033c15f113a157e5f16a1f78f90dff862 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 10 Jan 2017 16:12:09 +0000 Subject: [PATCH 061/102] Update configuration.md --- docs/tracks/configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tracks/configuration.md b/docs/tracks/configuration.md index 774bb097..b226bd6a 100644 --- a/docs/tracks/configuration.md +++ b/docs/tracks/configuration.md @@ -165,10 +165,10 @@ The following are properties for `Genoverse.Track` and its MVC components. These > ```javascript > { > "type": "select", // A type of DOM node -> "name": "myControl", // Equivalent of data-control attribute +> "name": "example1", // Equivalent of data-control attribute > "options": [ // other types of DOM node can be give, and don't require an options property -> { "value": "typeA", "text": "Type A" }, -> { "value": "typeB", "text": "Type B" }, +> { "value": "config1", "text": "Config 1" }, +> { "value": "config2", "text": "Config 2" }, > ] > } > ``` From 3c23112b13e2cc7db7a3e78350825b6ab7dcdf26 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 10 Jan 2017 17:02:36 +0000 Subject: [PATCH 062/102] Update api.md --- docs/tracks/api.md | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/docs/tracks/api.md b/docs/tracks/api.md index 7b05f183..72cca357 100644 --- a/docs/tracks/api.md +++ b/docs/tracks/api.md @@ -1,5 +1,26 @@ -#### track.setConfig(config) -> set config with a hash +The following are methods that can be called on a Genoverse.Track instance to perform actions required by UI changes external to the instance (i.e. from the website you have integrated Genoverse into). #### track.setConfig(type, name) -> set config with two strings +> Set the track's [configuration](/docs/tracks/configuration.md#changing-track-settings) after initalization +> Argument | Type | Description +> --- | --- | --- +> type | String | One of the keys in `track.configSettings` +> name | String | One of the keys in `track.configSettings[type]` + +#### track.setConfig(config) +> Set the track's [configuration](/docs/tracks/configuration.md#changing-track-settings) after initalization +> Argument | Type | Description +> --- | --- | --- +> config | Object | An object in the form `{ type1: "name1", type2, "name2" }`, where each `type` and `name` fulfills the criteria of `track.setConfig(type, name)` (above) + +#### track.remove() +> Remove the track from the genome browser + +#### track.disable() +> Hide the track in the genome browser, without removing it + +#### track.enable() +> Show the track in the genome browser, if it had previously been disabled + +#### track.reset() +> Clears all data stored by the track's models and views, removes the images that have been drawn by the track so far, and then requests new data, and creates new images for the current location in the genome browser From 1141c09a5e72951ab16315377f3a6db9a47fdd3c Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 10 Jan 2017 17:04:38 +0000 Subject: [PATCH 063/102] Update api.md --- docs/tracks/api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tracks/api.md b/docs/tracks/api.md index 72cca357..d8e43ff7 100644 --- a/docs/tracks/api.md +++ b/docs/tracks/api.md @@ -2,6 +2,7 @@ The following are methods that can be called on a Genoverse.Track instance to pe #### track.setConfig(type, name) > Set the track's [configuration](/docs/tracks/configuration.md#changing-track-settings) after initalization +> > Argument | Type | Description > --- | --- | --- > type | String | One of the keys in `track.configSettings` @@ -9,6 +10,7 @@ The following are methods that can be called on a Genoverse.Track instance to pe #### track.setConfig(config) > Set the track's [configuration](/docs/tracks/configuration.md#changing-track-settings) after initalization +> > Argument | Type | Description > --- | --- | --- > config | Object | An object in the form `{ type1: "name1", type2, "name2" }`, where each `type` and `name` fulfills the criteria of `track.setConfig(type, name)` (above) From b3977a0c6966c6bc8c7c8556ce5bc4298a230797 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 10 Jan 2017 17:04:57 +0000 Subject: [PATCH 064/102] Update api.md --- docs/tracks/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tracks/api.md b/docs/tracks/api.md index d8e43ff7..a5faa53a 100644 --- a/docs/tracks/api.md +++ b/docs/tracks/api.md @@ -13,7 +13,7 @@ The following are methods that can be called on a Genoverse.Track instance to pe > > Argument | Type | Description > --- | --- | --- -> config | Object | An object in the form `{ type1: "name1", type2, "name2" }`, where each `type` and `name` fulfills the criteria of `track.setConfig(type, name)` (above) +> config | Object | An object in the form `{ type1: "name1", type2, "name2" }`, where each `type` and `name` fulfills the criteria of `track.setConfig(type, name)`, above #### track.remove() > Remove the track from the genome browser From 9008116f9494630118e48dba69bbffb2bbe4f2c5 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 16 Jan 2017 14:39:35 +0000 Subject: [PATCH 065/102] Update genoverse_api.md --- docs/genoverse_api.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/genoverse_api.md b/docs/genoverse_api.md index 41991fca..2fa318e3 100644 --- a/docs/genoverse_api.md +++ b/docs/genoverse_api.md @@ -46,13 +46,14 @@ The following are methods that can be called on an instance of Genoverse to perf > --- | --- | --- > highlight | Object | A highlighted region to be added. See [configuration](configuration.md#highlights-default-) for the structure of highlights. -#### genoverse.moveTo(start, end [, update] [, keepLength]) +#### genoverse.moveTo(chr, start, end [, update] [, keepLength]) > Moves the viewpoint to the region between `start` and `end` > > Argument | Type | Description > --- | --- | --- -> start | Integer | a number between `1` and `genoverse.chromosomeSize` -> end | Integer | a number between `start` and `genoverse.chromosomeSize` +> chr | String or undefined | The name of a chromosome defined by `genoverse.genome`. If `genoverse.genome` is undefined, `chr` must be undefined, or the current value of `genoverse.chr`. +> start | Integer | A number between `1` and `genoverse.chromosomeSize` +> end | Integer | A number between `start` and `genoverse.chromosomeSize` > update | Boolean or undefined | If `true`, the URL will be updated with the new `start` and `end` > keepLength | Boolean or undefined | if `true`, the new viewpoint will have the same zoom level as before (`end - start` remains unchanged), centered on the given `start` and `end`. From 242c905021aeb1a8980947fb105d2079cff66c72 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 13 Feb 2017 10:23:02 +0000 Subject: [PATCH 066/102] Update and rename genoverse_api.md to api.md --- docs/{genoverse_api.md => api.md} | 49 +++++++++++++++++++++++++++++-- 1 file changed, 47 insertions(+), 2 deletions(-) rename docs/{genoverse_api.md => api.md} (67%) diff --git a/docs/genoverse_api.md b/docs/api.md similarity index 67% rename from docs/genoverse_api.md rename to docs/api.md index 2fa318e3..bc78c688 100644 --- a/docs/genoverse_api.md +++ b/docs/api.md @@ -1,6 +1,8 @@ -# Genoverse API +# API -The following are methods that can be called on an instance of Genoverse to perform actions required by UI changes external to the instance (i.e. from the website you have integrated Genoverse into). +The following are methods that can be called on an instance of Genoverse or Genoverse.Track to perform actions required by UI changes external to the instance (i.e. from the website you have integrated Genoverse into). + +## Genoverse API #### genoverse.addTracks(tracks [, after ]) > Add a number of tracks to the genome browser @@ -84,5 +86,48 @@ The following are methods that can be called on an instance of Genoverse to perf #### genoverse.reset() > Removes all existing data visualizations, and recreates them +#### genoverse.resetTrackHeights() +> Sets all track heights to their initial values + #### genoverse.destroy() > Removes the instance of Genoverse from the web page + +## Genoverse.Track API + +#### track.prop(key [, value ]) +> Get or set a property on the track or it's model, view or controller, without needing to know specifically which of these objects the property belongs to. Also available on `track.model`, `track.view`, and `track.controller` with identical functionality. +> +> Argument | Type | Description +> --- | --- | --- +> key | String | The name of the property to be returned. +> value | Anything | If defined, the value of the property will be set to this argument. If `null`, the property will be removed from its object. + +#### track.setConfig(type, name) +> Set the track's [configuration](/docs/tracks/configuration.md#changing-track-settings) after initalization +> +> Argument | Type | Description +> --- | --- | --- +> type | String | One of the keys in `track.configSettings` +> name | String | One of the keys in `track.configSettings[type]` + +#### track.setConfig(config) +> Set the track's [configuration](/docs/tracks/configuration.md#changing-track-settings) after initalization +> +> Argument | Type | Description +> --- | --- | --- +> config | Object | An object in the form `{ type1: "name1", type2, "name2" }`, where each `type` and `name` fulfills the criteria of `track.setConfig(type, name)`, above + +#### track.remove() +> Remove the track from the genome browser + +#### track.disable() +> Hide the track in the genome browser, without removing it + +#### track.enable() +> Show the track in the genome browser, if it had previously been disabled + +#### track.reset() +> Clears all data stored by the track's models and views, removes the images that have been drawn by the track so far, and then requests new data, and creates new images for the current location in the genome browser + +#### track.resetHeight() +> Sets the track's height to its initial values From 35804c93768edc01e1063fa50cf8100816db0de9 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 13 Feb 2017 10:23:28 +0000 Subject: [PATCH 067/102] Update api.md --- docs/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api.md b/docs/api.md index bc78c688..5ef23259 100644 --- a/docs/api.md +++ b/docs/api.md @@ -130,4 +130,4 @@ The following are methods that can be called on an instance of Genoverse or Geno > Clears all data stored by the track's models and views, removes the images that have been drawn by the track so far, and then requests new data, and creates new images for the current location in the genome browser #### track.resetHeight() -> Sets the track's height to its initial values +> Sets the track's height to its initial value From ded436343feb61737067831d8f002a45df4a2aa8 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 13 Feb 2017 10:23:52 +0000 Subject: [PATCH 068/102] Delete api.md --- docs/tracks/api.md | 28 ---------------------------- 1 file changed, 28 deletions(-) delete mode 100644 docs/tracks/api.md diff --git a/docs/tracks/api.md b/docs/tracks/api.md deleted file mode 100644 index a5faa53a..00000000 --- a/docs/tracks/api.md +++ /dev/null @@ -1,28 +0,0 @@ -The following are methods that can be called on a Genoverse.Track instance to perform actions required by UI changes external to the instance (i.e. from the website you have integrated Genoverse into). - -#### track.setConfig(type, name) -> Set the track's [configuration](/docs/tracks/configuration.md#changing-track-settings) after initalization -> -> Argument | Type | Description -> --- | --- | --- -> type | String | One of the keys in `track.configSettings` -> name | String | One of the keys in `track.configSettings[type]` - -#### track.setConfig(config) -> Set the track's [configuration](/docs/tracks/configuration.md#changing-track-settings) after initalization -> -> Argument | Type | Description -> --- | --- | --- -> config | Object | An object in the form `{ type1: "name1", type2, "name2" }`, where each `type` and `name` fulfills the criteria of `track.setConfig(type, name)`, above - -#### track.remove() -> Remove the track from the genome browser - -#### track.disable() -> Hide the track in the genome browser, without removing it - -#### track.enable() -> Show the track in the genome browser, if it had previously been disabled - -#### track.reset() -> Clears all data stored by the track's models and views, removes the images that have been drawn by the track so far, and then requests new data, and creates new images for the current location in the genome browser From 34fd51b3b89839daa5eb6030fd7a619805f2bff6 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 13 Feb 2017 10:27:59 +0000 Subject: [PATCH 069/102] Update api.md --- docs/api.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/api.md b/docs/api.md index 5ef23259..c779dd19 100644 --- a/docs/api.md +++ b/docs/api.md @@ -131,3 +131,10 @@ The following are methods that can be called on an instance of Genoverse or Geno #### track.resetHeight() > Sets the track's height to its initial value + +#### track.setName(name) +> Changes the name of the track, as displayed in the label to the left of its images. +> +> Argument | Type | Description +> --- | --- | --- +> name | String | The name for the track. From b2d5073993fcd0067f91199fb30da8a0fa83792e Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 13 Feb 2017 10:30:04 +0000 Subject: [PATCH 070/102] Update api.md --- docs/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api.md b/docs/api.md index c779dd19..fbb7692f 100644 --- a/docs/api.md +++ b/docs/api.md @@ -132,7 +132,7 @@ The following are methods that can be called on an instance of Genoverse or Geno #### track.resetHeight() > Sets the track's height to its initial value -#### track.setName(name) +#### track.updateName(name) > Changes the name of the track, as displayed in the label to the left of its images. > > Argument | Type | Description From 437a2aedf5bb86d5d8d96b02dbac2f0a05da7430 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 13 Feb 2017 11:09:41 +0000 Subject: [PATCH 071/102] Update configuration.md --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index d92976f7..3aec8d21 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -38,7 +38,7 @@ If `undefined`, a `
` element will be appended to `document.body`. > The genome to be used. Can be: > > - an object with keys of the number/letter/name of the chromosomes, and values in the form `{ "size": 10000 }`. -> Additionally an array of bands can be supplied for each chromosome for drawing purposes - see [js/genomes/grch38.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/js/genomes/grch38.js) for an example. +> Additionally an array of bands can be supplied for each chromosome for drawing purposes - see [js/genomes/grch38.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/js/genomes/grch38.js) for an example. These files can be created for species present in [Ensembl](http://www.ensembl.org/info/about/species.html) by modifying the example node script [utils/createGenome.js](https://github.com/wtsi-web/Genoverse/blob/gh-pages/utils/createGenome.js) for the species required. > - a string (e.g. `"grch38"`) which will be used to obtain a javascript file from the [js/genomes](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/genomes) directory > - `undefined`, in which case `chromosomeSize` **MUST** be set (see below) From b01382b8b10992cfb0d907c54a71fe05c363b0b5 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 13 Feb 2017 13:38:15 +0000 Subject: [PATCH 072/102] Update api.md --- docs/api.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/api.md b/docs/api.md index fbb7692f..eeb86dce 100644 --- a/docs/api.md +++ b/docs/api.md @@ -66,6 +66,13 @@ The following are methods that can be called on an instance of Genoverse or Geno > --- | --- | --- > width | Integer | The width to resize to, in pixel +#### genoverse.setDragAction(action) +> Sets whether a drag (mousedown, mousemove, mouseup) results in the browser region moving, a region being selected, or nothing +> +> Argument | Type | Description +> --- | --- | --- +> action | String | Can be [`"select"`, `"scroll"`, or `"off"`](/docs/configuration.md#dragaction-default-scroll) + #### genoverse.on(events, [, onTracks ], callback) > Execute functions before or after Genoverse or Genoverse.Track functions > From dc8a8c4e956ad972d5b42a3f8ea1faa6c2b4706e Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 13 Feb 2017 13:40:00 +0000 Subject: [PATCH 073/102] Update api.md --- docs/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api.md b/docs/api.md index eeb86dce..e2a966d8 100644 --- a/docs/api.md +++ b/docs/api.md @@ -67,11 +67,11 @@ The following are methods that can be called on an instance of Genoverse or Geno > width | Integer | The width to resize to, in pixel #### genoverse.setDragAction(action) -> Sets whether a drag (mousedown, mousemove, mouseup) results in the browser region moving, a region being selected, or nothing +> Sets [`genoverse.dragAction`](/docs/configuration.md#dragaction-default-scroll), determining whether a drag (mousedown, mousemove, mouseup) results in the browser region moving, a region being selected, or nothing > > Argument | Type | Description > --- | --- | --- -> action | String | Can be [`"select"`, `"scroll"`, or `"off"`](/docs/configuration.md#dragaction-default-scroll) +> action | `"select"`, `"scroll"`, or `"off"` | The value which `genoverse.dragAction` will be set to #### genoverse.on(events, [, onTracks ], callback) > Execute functions before or after Genoverse or Genoverse.Track functions From 78090f96f950848236a192ff051412af39227453 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 13 Feb 2017 13:48:29 +0000 Subject: [PATCH 074/102] Update api.md --- docs/api.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/api.md b/docs/api.md index e2a966d8..67921e66 100644 --- a/docs/api.md +++ b/docs/api.md @@ -73,6 +73,13 @@ The following are methods that can be called on an instance of Genoverse or Geno > --- | --- | --- > action | `"select"`, `"scroll"`, or `"off"` | The value which `genoverse.dragAction` will be set to +#### genoverse.setWheelAction(action) +> Sets [`genoverse.wheelAction`](/docs/configuration.md#wheelaction-default-off), determining whether a mousewheel scroll zooms the browser in and out, or does nothing +> +> Argument | Type | Description +> --- | --- | --- +> action | `"zoom"` or `"off"` | The value which `genoverse.wheelAction` will be set to + #### genoverse.on(events, [, onTracks ], callback) > Execute functions before or after Genoverse or Genoverse.Track functions > From 81a04677c4e7f73e193038ecd7fa04b8e3aab226 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 13 Feb 2017 16:06:33 +0000 Subject: [PATCH 075/102] Update genoverse_all_functions.md --- docs/genoverse_all_functions.md | 146 ++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) diff --git a/docs/genoverse_all_functions.md b/docs/genoverse_all_functions.md index 8b137891..f900b669 100644 --- a/docs/genoverse_all_functions.md +++ b/docs/genoverse_all_functions.md @@ -1 +1,147 @@ +## Genoverse +### Initialization + +#### genoverse.init() +> Called once the Genoverse instance is created. Sets initial properties of the instance and calls functions to creates its DOM elements, event handlers, tracks and highlights, and set the starting location. + +#### genoverse.addDomElements(width) +> Creates the DOM elements required by the instance of Genoverse +> +> Argument | Type | Description +> --- | --- | --- +> width | Integer | The width for the container DOM element (usually this should be the initial value of `genoverse.width`) + +#### genoverse.addUserEventHandlers() +> Created the event handlers required for users to interact with the instance of Genoverse + +### Configuration + +#### genoverse.loadConfig() +> If `genoverse.saveable` is `true`, configuration will be loaded from `window[genoverse.storageType].getItem(genoverse.saveKey)`. This configuration contains the user's previous tracks, their ordering, heights, and any other [track configuration settings](/docs/tracks/configuration.md#changing-track-settings). If no configuration exists, the default set of tracks will be used instead. + +#### genoverse.saveConfig() +> If `genoverse.saveable` is `true`, the user's current tracks, their ordering, heights, and any other [track configuration settings](/docs/tracks/configuration.md#changing-track-settings) will be saved to `window[genoverse.storageType].getItem(genoverse.saveKey)`. + +#### genoverse.resetConfig() +> If `genoverse.saveable` is `true`, removes all tracks and unremovable highlights, adds the default set of tracks, and removes the value in `genoverse.saveKey` from `window[genoverse.storageType]`. + +### Changing browser location + +#### genoverse.moveTo(chr, start, end [, update] [, keepLength]) +> See the [api documentation](/docs/api.md#genoversemovetochr-start-end--update--keeplength) + +#### genoverse.move(delta) +> Move the browser region a number of pixels left or right. This will be translated into a new chromosomal location based on the current value of `genoverse.scale` (width of the browser's containing DOM element in pixels / size of genomic region being viewed). +> +> **Note:** [`genoverse.moveTo`](/docs/api.md#genoversemovetochr-start-end--update--keeplength) should be used instead to change the location of a Genoverse instance externally. +> +> Argument | Type | Description +> --- | --- | --- +> delta | Integer | The number of pixels to move the browser region by (> 1 for left to right, < 1 for right to left) + +#### genoverse.setRange(start, end [, update] [, keepLength]) +> Sets `genoverse.start` and `genoverse.end`, moving the browser region in the process. +> +> **Note:** [`genoverse.moveTo`](/docs/api.md#genoversemovetochr-start-end--update--keeplength) should be used instead to change the location of a Genoverse instance externally. +> +> Argument | Type | Description +> --- | --- | --- +> start | Integer | A number between `1` and `genoverse.chromosomeSize` +> end | Integer | A number between `start` and `genoverse.chromosomeSize` +> update | Boolean or undefined | If `true`, the URL will be updated with the new `start` and `end` +> keepLength | Boolean or undefined | if `true`, the new viewpoint will have the same zoom level as before (`end - start` remains unchanged), centered on the given `start` and `end`. + +#### genoverse.setScale() +> Sets `genoverse.scale` to (width of the browser's containing DOM element in pixels / size of genomic region being viewed). If the scale changes, forces all tracks to draw new images at the new scale. + +### User events + +#### genoverse.setDragAction(action) +> See the [api documentation](/docs/api.md#genoversesetdragactionaction) + +#### genoverse.setWheelAction(action) +> See the [api documentation](/docs/api.md#genoversesetwheelactionaction) + +#### genoverse.startDragScroll(e) +> Initializes a scroll action +> +> Argument | Type | Description +> --- | --- | --- +> e | [jQuery event](http://api.jquery.com/category/events/) | The user event which starts a scroll operation + +#### genoverse.stopDragScroll([ update ]) +> Ends a scroll action +> +> Argument | Type | Description +> --- | --- | --- +> update | Boolean or undefined | If not `false`, will update the URL to the new location (providing the URL is changeable by the instance of Genoverse) + +#### genoverse.startDragSelect(e) +> Initializes a select action +> +> Argument | Type | Description +> --- | --- | --- +> e | [jQuery event](http://api.jquery.com/category/events/) | The user event which starts a select operation + +#### genoverse.stopDragSelect(e) +> Ends a select action, showing an actions menu for the selected region +> +> Argument | Type | Description +> --- | --- | --- +> e | [jQuery event](http://api.jquery.com/category/events/) | The user event which ends a select operation + +#### genoverse.cancelSelect() +> Hides the region selection element + +#### genoverse.dragSelect(e) +> Resizes the region selection element based on a mousemove event +> +> Argument | Type | Description +> --- | --- | --- +> e | [jQuery event](http://api.jquery.com/category/events/) | The mousemove event + +#### genoverse.keydown(e) +> If the shift key is pressed, region selection is enabled while it is held down (nothing happens if [`genoverse.dragAction`](/docs/configuration.md#dragaction-default-scroll) was already `"select"`). If the escape key is pressed, any popup menus (for track features or the region select menu) are hidden. +> +> Argument | Type | Description +> --- | --- | --- +> e | [jQuery event](http://api.jquery.com/category/events/) | The keydown event + +#### genoverse.keyup(e) +> If the shift key is released, region selection is disabled if it was enabled by pressing the key initially (nothing happens if [`genoverse.dragAction`](/docs/configuration.md#dragaction-default-scroll) was already `"select"`). +> +> Argument | Type | Description +> --- | --- | --- +> e | [jQuery event](http://api.jquery.com/category/events/) | The keyup event + +#### genoverse.mousedown(e) +> Starts a scroll or select action by calling [`genoverse.startDragScroll(e)`](#genoversestartdragscrolle) or [`genoverse.startDragSelect(e)`](#genoversestartdragselecte), based on the value of [`genoverse.dragAction`](/docs/configuration.md#dragaction-default-scroll) +> +> Argument | Type | Description +> --- | --- | --- +> e | [jQuery event](http://api.jquery.com/category/events/) | The mousedown event + +#### genoverse.mouseup(e) +> Ends the current scroll or select action by calling [`genoverse.stopDragScroll(update)`](#genoversestopdragscrollupdate) or [`genoverse.stopDragSelect(e)`](#genoversestp[stopdragselecte), as applicable +> +> Argument | Type | Description +> --- | --- | --- +> e | [jQuery event](http://api.jquery.com/category/events/) | The mouseup event + +#### genoverse.mousemove(e) +> If a scroll action is taking place, moves the browser region as the mouse moves. +> If a region select is taking place, changes the size of the selected region as the mouse moves. +> If [`genoverse.dragAction`](/docs/configuration.md#dragaction-default-scroll) is `"select"` and a region select is not taking place, moves the region select element (a dotted red vertical line) to the location of the mouse pointer. +> +> Argument | Type | Description +> --- | --- | --- +> e | [jQuery event](http://api.jquery.com/category/events/) | The mousemove event + +#### genoverse.mousewheelZoom(e, delta) +> Performs zoom in and zoom out operations +> +> Argument | Type | Description +> --- | --- | --- +> e | [jQuery event](http://api.jquery.com/category/events/) | The user event which will cause a zoom operation +> delta | `1` or `-1` | `1` for zoom in, `-1` for zoom out From 325ac48aa541617976b58e8b77c9899f2156b94c Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 13 Feb 2017 16:08:12 +0000 Subject: [PATCH 076/102] Update genoverse_all_functions.md --- docs/genoverse_all_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/genoverse_all_functions.md b/docs/genoverse_all_functions.md index f900b669..1d2c785e 100644 --- a/docs/genoverse_all_functions.md +++ b/docs/genoverse_all_functions.md @@ -123,7 +123,7 @@ > e | [jQuery event](http://api.jquery.com/category/events/) | The mousedown event #### genoverse.mouseup(e) -> Ends the current scroll or select action by calling [`genoverse.stopDragScroll(update)`](#genoversestopdragscrollupdate) or [`genoverse.stopDragSelect(e)`](#genoversestp[stopdragselecte), as applicable +> Ends the current scroll or select action by calling [`genoverse.stopDragScroll(update)`](#genoversestopdragscroll-update-) or [`genoverse.stopDragSelect(e)`](#genoversestopdragselecte), as applicable > > Argument | Type | Description > --- | --- | --- From 2bccca97ffcf2d6f7e2412e921da6e7584d8cffa Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 13 Feb 2017 16:27:40 +0000 Subject: [PATCH 077/102] Update genoverse_all_functions.md --- docs/genoverse_all_functions.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/genoverse_all_functions.md b/docs/genoverse_all_functions.md index 1d2c785e..38056792 100644 --- a/docs/genoverse_all_functions.md +++ b/docs/genoverse_all_functions.md @@ -145,3 +145,17 @@ > --- | --- | --- > e | [jQuery event](http://api.jquery.com/category/events/) | The user event which will cause a zoom operation > delta | `1` or `-1` | `1` for zoom in, `-1` for zoom out + +#### genoverse.zoomIn([ x ]) +> Calls [`genoverse.setRange`](#genoversesetrangestart-end--update--keeplength) to zoom in, halving the size of the browser region (e.g. 100-200 becomes 125-175). If an `x` argument is provided, the zoom will step towards that point, instead of directly inward. `x`is the difference between the x coordinate of a mousewheel zoom event and the left offset of the browser images on the page. +> +> Argument | Type | Description +> --- | --- | --- +> x | Integer or undefined | The point to zoom towards + +#### genoverse.zoomOut([ x ]) +> Calls [`genoverse.setRange`](#genoversesetrangestart-end--update--keeplength) to zoom out, doubling the size of the browser region (e.g. 100-200 becomes 50-250). If an `x` argument is provided, the zoom will step towards that point, instead of directly outward. `x`is the difference between the x coordinate of a mousewheel zoom event and the left offset of the browser images on the page. +> +> Argument | Type | Description +> --- | --- | --- +> x | Integer or undefined | The point to zoom towards From dda82e9d599e3c90b5656cd881db80a5050c0172 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Mon, 13 Feb 2017 16:56:42 +0000 Subject: [PATCH 078/102] Update genoverse_all_functions.md --- docs/genoverse_all_functions.md | 37 +++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/genoverse_all_functions.md b/docs/genoverse_all_functions.md index 38056792..623bf77c 100644 --- a/docs/genoverse_all_functions.md +++ b/docs/genoverse_all_functions.md @@ -159,3 +159,40 @@ > Argument | Type | Description > --- | --- | --- > x | Integer or undefined | The point to zoom towards + +### Track interactions + +#### genoverse.addTracks +> See the [api documentation](/docs/api.md#genoverseaddtrackstracks--after-) + +#### genoverse.addTrack +> See the [api documentation](/docs/api.md#genoverseaddtracktrack--after-) + +#### genoverse.removeTracks +> See the [api documentation](/docs/api.md#genoverseremovetrackstracks) + +#### genoverse.removeTrack +> See the [api documentation](/docs/api.md#genoverseremovetracktrack) + +#### genoverse.updateTrackOrder(e, ui) +> Called when a user moves track labels to reorder tracks in the browser. Set the moved track's `order` property such that it is between the `order` properties of its new immediate siblings. [`genoverse.sortTracks`](#genoversesorttracks) is then called to update the position of the track's image element. +> +> See [jQuery UI sortable update event](http://api.jqueryui.com/sortable/#event-update) for argument details. + +#### genoverse.sortTracks +> Reorders the tracks' DOM elements based on each track's `order` property, lowest first. + +### URL interactions + +#### genoverse.updateURL +> If [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) is set, the URL will be updated to reflect the current browser region. This will be done either by using `window.history.pushState`, or by updating `window.location.hash`, depending on the value of [`genoverse.useHash`](/docs/configuration.md#usehash-default-undefined). + +#### genoverse.popState +> Called by [`window.onpopstate`](https://developer.mozilla.org/en-US/docs/Web/API/WindowEventHandlers/onpopstate) or [`window.onhashchange`](https://developer.mozilla.org/en/docs/Web/API/WindowEventHandlers/onhashchange) to update the browser region if the user uses the back or forward buttons in their web browser. + +#### genoverse.getURLCoords +> Returns an object in the form `{ "chr": "1", "start": 123, "end": 456 }` by parsing the URL using the value of [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) + +#### genoverse.getQueryString +> Returns a string of [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) with the placeholders replaced with their relevant values, to be used in updating the URL. If [`genoverse.useHash`](/docs/configuration.md#usehash-default-undefined) is `false`, this will be appended to any existing value of `window.location.search` such that other parameters are unchanged. + From e0a4a54b963186af423a524d236be1aeca5a7651 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 14:20:14 +0000 Subject: [PATCH 079/102] Update api.md --- docs/api.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/api.md b/docs/api.md index 67921e66..d0c8bc40 100644 --- a/docs/api.md +++ b/docs/api.md @@ -80,6 +80,14 @@ The following are methods that can be called on an instance of Genoverse or Geno > --- | --- | --- > action | `"zoom"` or `"off"` | The value which `genoverse.wheelAction` will be set to +#### genoverse.closeMenus([ obj ]) +> If `obj` is a Genoverse.Track instance, closes (hides) all popup menus for that track. +> If `obj` is `undefined`, closes all popup menus. +> +> Argument | Type | Description +> --- | --- | --- +> obj | Genoverse.Track instance or undefined | The object whose popup menus will be closed + #### genoverse.on(events, [, onTracks ], callback) > Execute functions before or after Genoverse or Genoverse.Track functions > From 4e8665071c94425e25d6e21098530245fbda3b8f Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 14:21:24 +0000 Subject: [PATCH 080/102] Update api.md --- docs/api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api.md b/docs/api.md index d0c8bc40..e68ecf8a 100644 --- a/docs/api.md +++ b/docs/api.md @@ -80,13 +80,13 @@ The following are methods that can be called on an instance of Genoverse or Geno > --- | --- | --- > action | `"zoom"` or `"off"` | The value which `genoverse.wheelAction` will be set to -#### genoverse.closeMenus([ obj ]) -> If `obj` is a Genoverse.Track instance, closes (hides) all popup menus for that track. -> If `obj` is `undefined`, closes all popup menus. +#### genoverse.closeMenus([ track ]) +> If `track` is a Genoverse.Track instance, closes (hides) all popup menus for that track. +> If `track` is `undefined`, closes all popup menus. > > Argument | Type | Description > --- | --- | --- -> obj | Genoverse.Track instance or undefined | The object whose popup menus will be closed +> track | Genoverse.Track instance or undefined | The object whose popup menus will be closed #### genoverse.on(events, [, onTracks ], callback) > Execute functions before or after Genoverse or Genoverse.Track functions From eb6d389d0555714b51d0e90e6c088900e5866d1a Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 14:23:16 +0000 Subject: [PATCH 081/102] Update genoverse_all_functions.md --- docs/genoverse_all_functions.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/genoverse_all_functions.md b/docs/genoverse_all_functions.md index 623bf77c..e41bed3e 100644 --- a/docs/genoverse_all_functions.md +++ b/docs/genoverse_all_functions.md @@ -196,3 +196,25 @@ #### genoverse.getQueryString > Returns a string of [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) with the placeholders replaced with their relevant values, to be used in updating the URL. If [`genoverse.useHash`](/docs/configuration.md#usehash-default-undefined) is `false`, this will be appended to any existing value of `window.location.search` such that other parameters are unchanged. +### Popup menus + +#### genoverse.makeMenu(features [, event, track ]) +> Creates a popup menu for one or more features. If more than one feature is provided, the popup will contain one link per feature which each create another popup for that feature +> +> Argument | Type | Description +> --- | --- | --- +> features | Feature object or array of feature objects | The feature(s) to make the menu for +> event | [jQuery event](http://api.jquery.com/category/events/) or undefined | The click event that created the menu, used to position the menu at the mouse pointer +> track | Genoverse.Track or undefined | The track which was clicked on + +#### genoverse.makeFeatureMenu(features [, event, track ]) +> Called by [`genoverse.makeMenu`](#genoversemakemenu-features--event--track) to create a popup menu for a single feature +> +> Argument | Type | Description +> --- | --- | --- +> feature | Feature object | The feature to make the menu for +> event | [jQuery event](http://api.jquery.com/category/events/) or undefined | The click event that created the menu, used to position the menu at the mouse pointer +> track | Genoverse.Track instance or undefined | The track which was clicked on + +#### genoverse.closeMenus([ track ]) +> See the [api documentation](/docs/api.md#genoverseclosemenus-track-) From d55c0f16f2174cf7131f1b26a225eff681db42e3 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 14:24:02 +0000 Subject: [PATCH 082/102] Update genoverse_all_functions.md --- docs/genoverse_all_functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/genoverse_all_functions.md b/docs/genoverse_all_functions.md index e41bed3e..6d941ca5 100644 --- a/docs/genoverse_all_functions.md +++ b/docs/genoverse_all_functions.md @@ -208,7 +208,7 @@ > track | Genoverse.Track or undefined | The track which was clicked on #### genoverse.makeFeatureMenu(features [, event, track ]) -> Called by [`genoverse.makeMenu`](#genoversemakemenu-features--event--track) to create a popup menu for a single feature +> Called by [`genoverse.makeMenu`](#genoversemakemenufeatures--event-track-) to create a popup menu for a single feature > > Argument | Type | Description > --- | --- | --- From 2ae30a4670ed0b7dca3a25088a4d2334dd660cfb Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 14:34:55 +0000 Subject: [PATCH 083/102] Update api.md --- docs/api.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/api.md b/docs/api.md index e68ecf8a..7b94f47e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -105,6 +105,12 @@ The following are methods that can be called on an instance of Genoverse or Geno > events | Object | An object whose keys are one or more space-separated events (see above), and whose values are the functions to be executed for those events > onTracks | `"tracks"` or `Genoverse.Track` instance | See above +#### genoverse.once(events, [, onTracks ], callback) +> Like [`genoverse.on`](#genoverseonevents--ontracks--callback), but the functions will only be called one time + +#### genoverse.once(events, [, onTracks ]) +> Like [`genoverse.on`](#genoverseonevents--ontracks-), but the functions will only be called one time + #### genoverse.reset() > Removes all existing data visualizations, and recreates them From 92d2cac192627f6b49d9d6f4cf56c86ede14c24d Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 14:37:59 +0000 Subject: [PATCH 084/102] Update genoverse_all_functions.md --- docs/genoverse_all_functions.md | 46 +++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/genoverse_all_functions.md b/docs/genoverse_all_functions.md index 6d941ca5..5df769c4 100644 --- a/docs/genoverse_all_functions.md +++ b/docs/genoverse_all_functions.md @@ -182,6 +182,14 @@ #### genoverse.sortTracks > Reorders the tracks' DOM elements based on each track's `order` property, lowest first. +### Highlight interactions + +#### genoverse.addHighlights(highlights) +> See the [api documentation](/docs/api.md#genoverseaddhighlightshighlights) + +#### genoverse.addHighlight(highlight) +> See the [api documentation](/docs/api.md#genoverseaddhighlighthighlight) + ### URL interactions #### genoverse.updateURL @@ -218,3 +226,41 @@ #### genoverse.closeMenus([ track ]) > See the [api documentation](/docs/api.md#genoverseclosemenus-track-) + +### Misc + +#### genoverse.on() +> See the [api documentation](/docs/api.md#genoverseonevents--ontracks--callback) + +#### genoverse.once() +> See the [api documentation](/docs/api.md#genoverseonceevents--ontracks--callback) + +#### genoverse.reset() +> See the [api documentation](/docs/api.md#genoversereset) + +#### genoverse.destroy() +> See the [api documentation](/docs/api.md#genoversedestroy) + +#### genoverse.setWidth(width) +> See the [api documentation](/docs/api.md#genoversesetwidthwidth) + +#### genoverse.getChromosomeSize(chr) +> If [`genoverse.genome`](/docs/configuration.md#genome-default-undefined) is an object, returns the size of the chromosome in the genome, else returns [`genoverse.chromosomeSize`](/docs/configuration.md#chromosomesize-default-undefined) +> +> Argument | Type | Description +> --- | --- | --- +> chr | String | The name of the chromosome + +#### genoverse.getSelectorPosition() +> Returns an object in the form `{ "start": 1, "end": 2, "left": 1, "width", 1 }` representing the position of the region selector DOM element. +> `start` and `end` are the genomic coordinates selected by the region, `left` and `width` are the CSS positional values of the element. + +#### genoverse.onTracks(functionName [, arg1, arg2, ...argN ]) +> Calls the function `functionName` on all tracks in the instance of Genoverse, with the arguments provided +> +> Argument | Type | Description +> --- | --- | --- +> functionName | String | The name of the function to call. This function can be in `Genoverse.Track`, `Genoverse.Track.Controller`, `Genoverse.Track.Model`, or `Genoverse.Track.View` +> args | Anything | A list of arguments to be passed to the function being called + + From c1c38e74b84fa5878e0a0966b76b9adecc0ece9b Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 14:39:52 +0000 Subject: [PATCH 085/102] Rename genoverse_all_functions.md to functions.md --- docs/{genoverse_all_functions.md => functions.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{genoverse_all_functions.md => functions.md} (100%) diff --git a/docs/genoverse_all_functions.md b/docs/functions.md similarity index 100% rename from docs/genoverse_all_functions.md rename to docs/functions.md From a5fc2233a8928932d8097159b9785c151d7d6eb4 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 14:46:20 +0000 Subject: [PATCH 086/102] Update functions.md --- docs/functions.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/functions.md b/docs/functions.md index 5df769c4..d0d00faa 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -1,6 +1,8 @@ -## Genoverse +# Genoverse functions -### Initialization +The following are functions that exist in the Genoverse object. Any of these can be overwritten by supplying them as properties in configuration, or have before/after events added to them. + +## Initialization #### genoverse.init() > Called once the Genoverse instance is created. Sets initial properties of the instance and calls functions to creates its DOM elements, event handlers, tracks and highlights, and set the starting location. @@ -15,7 +17,7 @@ #### genoverse.addUserEventHandlers() > Created the event handlers required for users to interact with the instance of Genoverse -### Configuration +## Configuration #### genoverse.loadConfig() > If `genoverse.saveable` is `true`, configuration will be loaded from `window[genoverse.storageType].getItem(genoverse.saveKey)`. This configuration contains the user's previous tracks, their ordering, heights, and any other [track configuration settings](/docs/tracks/configuration.md#changing-track-settings). If no configuration exists, the default set of tracks will be used instead. @@ -26,7 +28,7 @@ #### genoverse.resetConfig() > If `genoverse.saveable` is `true`, removes all tracks and unremovable highlights, adds the default set of tracks, and removes the value in `genoverse.saveKey` from `window[genoverse.storageType]`. -### Changing browser location +## Changing browser location #### genoverse.moveTo(chr, start, end [, update] [, keepLength]) > See the [api documentation](/docs/api.md#genoversemovetochr-start-end--update--keeplength) @@ -55,7 +57,7 @@ #### genoverse.setScale() > Sets `genoverse.scale` to (width of the browser's containing DOM element in pixels / size of genomic region being viewed). If the scale changes, forces all tracks to draw new images at the new scale. -### User events +## User events #### genoverse.setDragAction(action) > See the [api documentation](/docs/api.md#genoversesetdragactionaction) @@ -160,7 +162,7 @@ > --- | --- | --- > x | Integer or undefined | The point to zoom towards -### Track interactions +## Track interactions #### genoverse.addTracks > See the [api documentation](/docs/api.md#genoverseaddtrackstracks--after-) @@ -182,7 +184,7 @@ #### genoverse.sortTracks > Reorders the tracks' DOM elements based on each track's `order` property, lowest first. -### Highlight interactions +## Highlight interactions #### genoverse.addHighlights(highlights) > See the [api documentation](/docs/api.md#genoverseaddhighlightshighlights) @@ -190,7 +192,7 @@ #### genoverse.addHighlight(highlight) > See the [api documentation](/docs/api.md#genoverseaddhighlighthighlight) -### URL interactions +## URL interactions #### genoverse.updateURL > If [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) is set, the URL will be updated to reflect the current browser region. This will be done either by using `window.history.pushState`, or by updating `window.location.hash`, depending on the value of [`genoverse.useHash`](/docs/configuration.md#usehash-default-undefined). @@ -204,7 +206,7 @@ #### genoverse.getQueryString > Returns a string of [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) with the placeholders replaced with their relevant values, to be used in updating the URL. If [`genoverse.useHash`](/docs/configuration.md#usehash-default-undefined) is `false`, this will be appended to any existing value of `window.location.search` such that other parameters are unchanged. -### Popup menus +## Popup menus #### genoverse.makeMenu(features [, event, track ]) > Creates a popup menu for one or more features. If more than one feature is provided, the popup will contain one link per feature which each create another popup for that feature @@ -227,7 +229,7 @@ #### genoverse.closeMenus([ track ]) > See the [api documentation](/docs/api.md#genoverseclosemenus-track-) -### Misc +## Misc #### genoverse.on() > See the [api documentation](/docs/api.md#genoverseonevents--ontracks--callback) From 8d07678a7eed1c4246de43a5e55d6d10cd40ce6c Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 14:47:19 +0000 Subject: [PATCH 087/102] Update functions.md --- docs/functions.md | 134 +++++++++++++++++++++++----------------------- 1 file changed, 67 insertions(+), 67 deletions(-) diff --git a/docs/functions.md b/docs/functions.md index d0d00faa..46ded72b 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -57,6 +57,73 @@ The following are functions that exist in the Genoverse object. Any of these can #### genoverse.setScale() > Sets `genoverse.scale` to (width of the browser's containing DOM element in pixels / size of genomic region being viewed). If the scale changes, forces all tracks to draw new images at the new scale. +## Track interactions + +#### genoverse.addTracks +> See the [api documentation](/docs/api.md#genoverseaddtrackstracks--after-) + +#### genoverse.addTrack +> See the [api documentation](/docs/api.md#genoverseaddtracktrack--after-) + +#### genoverse.removeTracks +> See the [api documentation](/docs/api.md#genoverseremovetrackstracks) + +#### genoverse.removeTrack +> See the [api documentation](/docs/api.md#genoverseremovetracktrack) + +#### genoverse.updateTrackOrder(e, ui) +> Called when a user moves track labels to reorder tracks in the browser. Set the moved track's `order` property such that it is between the `order` properties of its new immediate siblings. [`genoverse.sortTracks`](#genoversesorttracks) is then called to update the position of the track's image element. +> +> See [jQuery UI sortable update event](http://api.jqueryui.com/sortable/#event-update) for argument details. + +#### genoverse.sortTracks +> Reorders the tracks' DOM elements based on each track's `order` property, lowest first. + +## Highlight interactions + +#### genoverse.addHighlights(highlights) +> See the [api documentation](/docs/api.md#genoverseaddhighlightshighlights) + +#### genoverse.addHighlight(highlight) +> See the [api documentation](/docs/api.md#genoverseaddhighlighthighlight) + +## URL interactions + +#### genoverse.updateURL +> If [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) is set, the URL will be updated to reflect the current browser region. This will be done either by using `window.history.pushState`, or by updating `window.location.hash`, depending on the value of [`genoverse.useHash`](/docs/configuration.md#usehash-default-undefined). + +#### genoverse.popState +> Called by [`window.onpopstate`](https://developer.mozilla.org/en-US/docs/Web/API/WindowEventHandlers/onpopstate) or [`window.onhashchange`](https://developer.mozilla.org/en/docs/Web/API/WindowEventHandlers/onhashchange) to update the browser region if the user uses the back or forward buttons in their web browser. + +#### genoverse.getURLCoords +> Returns an object in the form `{ "chr": "1", "start": 123, "end": 456 }` by parsing the URL using the value of [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) + +#### genoverse.getQueryString +> Returns a string of [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) with the placeholders replaced with their relevant values, to be used in updating the URL. If [`genoverse.useHash`](/docs/configuration.md#usehash-default-undefined) is `false`, this will be appended to any existing value of `window.location.search` such that other parameters are unchanged. + +## Popup menus + +#### genoverse.makeMenu(features [, event, track ]) +> Creates a popup menu for one or more features. If more than one feature is provided, the popup will contain one link per feature which each create another popup for that feature +> +> Argument | Type | Description +> --- | --- | --- +> features | Feature object or array of feature objects | The feature(s) to make the menu for +> event | [jQuery event](http://api.jquery.com/category/events/) or undefined | The click event that created the menu, used to position the menu at the mouse pointer +> track | Genoverse.Track or undefined | The track which was clicked on + +#### genoverse.makeFeatureMenu(features [, event, track ]) +> Called by [`genoverse.makeMenu`](#genoversemakemenufeatures--event-track-) to create a popup menu for a single feature +> +> Argument | Type | Description +> --- | --- | --- +> feature | Feature object | The feature to make the menu for +> event | [jQuery event](http://api.jquery.com/category/events/) or undefined | The click event that created the menu, used to position the menu at the mouse pointer +> track | Genoverse.Track instance or undefined | The track which was clicked on + +#### genoverse.closeMenus([ track ]) +> See the [api documentation](/docs/api.md#genoverseclosemenus-track-) + ## User events #### genoverse.setDragAction(action) @@ -162,73 +229,6 @@ The following are functions that exist in the Genoverse object. Any of these can > --- | --- | --- > x | Integer or undefined | The point to zoom towards -## Track interactions - -#### genoverse.addTracks -> See the [api documentation](/docs/api.md#genoverseaddtrackstracks--after-) - -#### genoverse.addTrack -> See the [api documentation](/docs/api.md#genoverseaddtracktrack--after-) - -#### genoverse.removeTracks -> See the [api documentation](/docs/api.md#genoverseremovetrackstracks) - -#### genoverse.removeTrack -> See the [api documentation](/docs/api.md#genoverseremovetracktrack) - -#### genoverse.updateTrackOrder(e, ui) -> Called when a user moves track labels to reorder tracks in the browser. Set the moved track's `order` property such that it is between the `order` properties of its new immediate siblings. [`genoverse.sortTracks`](#genoversesorttracks) is then called to update the position of the track's image element. -> -> See [jQuery UI sortable update event](http://api.jqueryui.com/sortable/#event-update) for argument details. - -#### genoverse.sortTracks -> Reorders the tracks' DOM elements based on each track's `order` property, lowest first. - -## Highlight interactions - -#### genoverse.addHighlights(highlights) -> See the [api documentation](/docs/api.md#genoverseaddhighlightshighlights) - -#### genoverse.addHighlight(highlight) -> See the [api documentation](/docs/api.md#genoverseaddhighlighthighlight) - -## URL interactions - -#### genoverse.updateURL -> If [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) is set, the URL will be updated to reflect the current browser region. This will be done either by using `window.history.pushState`, or by updating `window.location.hash`, depending on the value of [`genoverse.useHash`](/docs/configuration.md#usehash-default-undefined). - -#### genoverse.popState -> Called by [`window.onpopstate`](https://developer.mozilla.org/en-US/docs/Web/API/WindowEventHandlers/onpopstate) or [`window.onhashchange`](https://developer.mozilla.org/en/docs/Web/API/WindowEventHandlers/onhashchange) to update the browser region if the user uses the back or forward buttons in their web browser. - -#### genoverse.getURLCoords -> Returns an object in the form `{ "chr": "1", "start": 123, "end": 456 }` by parsing the URL using the value of [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) - -#### genoverse.getQueryString -> Returns a string of [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) with the placeholders replaced with their relevant values, to be used in updating the URL. If [`genoverse.useHash`](/docs/configuration.md#usehash-default-undefined) is `false`, this will be appended to any existing value of `window.location.search` such that other parameters are unchanged. - -## Popup menus - -#### genoverse.makeMenu(features [, event, track ]) -> Creates a popup menu for one or more features. If more than one feature is provided, the popup will contain one link per feature which each create another popup for that feature -> -> Argument | Type | Description -> --- | --- | --- -> features | Feature object or array of feature objects | The feature(s) to make the menu for -> event | [jQuery event](http://api.jquery.com/category/events/) or undefined | The click event that created the menu, used to position the menu at the mouse pointer -> track | Genoverse.Track or undefined | The track which was clicked on - -#### genoverse.makeFeatureMenu(features [, event, track ]) -> Called by [`genoverse.makeMenu`](#genoversemakemenufeatures--event-track-) to create a popup menu for a single feature -> -> Argument | Type | Description -> --- | --- | --- -> feature | Feature object | The feature to make the menu for -> event | [jQuery event](http://api.jquery.com/category/events/) or undefined | The click event that created the menu, used to position the menu at the mouse pointer -> track | Genoverse.Track instance or undefined | The track which was clicked on - -#### genoverse.closeMenus([ track ]) -> See the [api documentation](/docs/api.md#genoverseclosemenus-track-) - ## Misc #### genoverse.on() From afd826bd02cfd1729eb67ce1a1666d87ccbfc476 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 14:50:33 +0000 Subject: [PATCH 088/102] Update functions.md --- docs/functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/functions.md b/docs/functions.md index 46ded72b..62f5cd51 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -1,6 +1,6 @@ # Genoverse functions -The following are functions that exist in the Genoverse object. Any of these can be overwritten by supplying them as properties in configuration, or have before/after events added to them. +The following are functions that exist in the Genoverse object. Any of these can have before/after events added to them, or be overwritten by supplying them as properties in configuration. ## Initialization From 315ead932496c4d2167374793c5fb5c33dc019c2 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 15:10:22 +0000 Subject: [PATCH 089/102] Update configuration.md --- docs/configuration.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 3aec8d21..8320f075 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -11,7 +11,7 @@ var genoverse = new Genoverse({ The following properties can be provided to the constructor for Genoverse: -### DOM element +## DOM element #### container (default `undefined`) > A DOM node, jQuery selector, or string to create a jQuery selector (e.g. `"#genoverse"`) inside which the instance of Genoverse will be created. @@ -47,7 +47,7 @@ If `undefined`, a `
` element will be appended to `document.body`. > > If `genome` is provided, `chromosomeSize` will be set to the chromosome's `size` property, as defined by the genome object. -### What is displayed +## What is displayed #### tracks (default `[]`) > An array of `Genoverse.Track` definitions to be displayed @@ -68,7 +68,7 @@ If `undefined`, a `
` element will be appended to `document.body`. ``` > The strings in this array correspond to the namespace of each plugin, which are the same as their file names. -### Interaction with the URL +## Interaction with the URL #### urlParamTemplate (default `"r=__CHR__:__START__-__END__"`) > The template used to alter the web browser's URL. Should contain placeholders for chr, start and end. @@ -82,7 +82,7 @@ If `undefined`, a `
` element will be appended to `document.body`. > - `false` - use `window.history.pushState` > - `undefined` - use `window.history.pushState` if present in the browser, else use `window.location.hash` -### User actions +## User actions #### dragAction (default `"scroll"`) > The action performed when a mouse drag happens on the genome browser. Can be: @@ -100,7 +100,7 @@ If `undefined`, a `
` element will be appended to `document.body`. #### isStatic (default `false`) > If `true`, will stop drag, select and zoom actions occurring -### Saving user configurations +## Saving user configurations #### saveable (default `false`) > If `true`, track configuration and ordering will be saved in `window.sessionStorage`/`window.localStorage` (defined by `storageType`, below) so that users will see the same display when they refresh the page @@ -113,7 +113,7 @@ If `undefined`, a `
` element will be appended to `document.body`. #### saveKey (default empty string) > The default key used in configuration storage is `"genoverse"`. `saveKey` will be appended to this to allow different configurations for different instances of Genoverse. -### Default track display settings +## Default track display settings #### autoHideMessages (default `true`) > Determines whether to collapse track messages (toggleable pop-outs on the left side of a track's image) by default when the user interacts with the genome browser From 71c812c1ae99d301fff730076af50ad9d493980c Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 15:10:37 +0000 Subject: [PATCH 090/102] Update configuration.md --- docs/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.md b/docs/configuration.md index 8320f075..13e0c90f 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -20,7 +20,7 @@ If `undefined`, a `
` element will be appended to `document.body`. #### width (default `1000`) > The width that the `container` DOM element will be -### Genomic coordinates +## Genomic coordinates #### chr (default `1`) > A string or number defining the initial chromosome to display From fac0c64556d6155c7c4f4bafba9b9d1c77a5fb77 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 15:11:14 +0000 Subject: [PATCH 091/102] Update functions.md --- docs/functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/functions.md b/docs/functions.md index 62f5cd51..eda32f79 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -43,7 +43,7 @@ The following are functions that exist in the Genoverse object. Any of these can > delta | Integer | The number of pixels to move the browser region by (> 1 for left to right, < 1 for right to left) #### genoverse.setRange(start, end [, update] [, keepLength]) -> Sets `genoverse.start` and `genoverse.end`, moving the browser region in the process. +> Sets [`genoverse.start`](/docs/configuration.md#start-default-1) and [`genoverse.end`](/docs/configuration.md#end-default-1000000), moving the browser region in the process. > > **Note:** [`genoverse.moveTo`](/docs/api.md#genoversemovetochr-start-end--update--keeplength) should be used instead to change the location of a Genoverse instance externally. > From 6fcb959e496a616b52655d027e646da857c481e0 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 15:17:58 +0000 Subject: [PATCH 092/102] Update functions.md --- docs/functions.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/functions.md b/docs/functions.md index eda32f79..7a0d0378 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -12,7 +12,7 @@ The following are functions that exist in the Genoverse object. Any of these can > > Argument | Type | Description > --- | --- | --- -> width | Integer | The width for the container DOM element (usually this should be the initial value of `genoverse.width`) +> width | Integer | The width for the container DOM element (usually this should be the initial value of [`genoverse.width`](/docs/configuration.md#width-default-1000)) #### genoverse.addUserEventHandlers() > Created the event handlers required for users to interact with the instance of Genoverse @@ -20,13 +20,13 @@ The following are functions that exist in the Genoverse object. Any of these can ## Configuration #### genoverse.loadConfig() -> If `genoverse.saveable` is `true`, configuration will be loaded from `window[genoverse.storageType].getItem(genoverse.saveKey)`. This configuration contains the user's previous tracks, their ordering, heights, and any other [track configuration settings](/docs/tracks/configuration.md#changing-track-settings). If no configuration exists, the default set of tracks will be used instead. +> If [`genoverse.saveable`](/docs/configuration.md#saveable-default-false) is `true`, configuration will be loaded from `window[genoverse.storageType].getItem(genoverse.saveKey)`. This configuration contains the user's previous tracks, their ordering, heights, and any other [track configuration settings](/docs/tracks/configuration.md#changing-track-settings). If no configuration exists, the default set of tracks will be used instead. #### genoverse.saveConfig() -> If `genoverse.saveable` is `true`, the user's current tracks, their ordering, heights, and any other [track configuration settings](/docs/tracks/configuration.md#changing-track-settings) will be saved to `window[genoverse.storageType].getItem(genoverse.saveKey)`. +> If [`genoverse.saveable`](/docs/configuration.md#saveable-default-false) is `true`, the user's current tracks, their ordering, heights, and any other [track configuration settings](/docs/tracks/configuration.md#changing-track-settings) will be saved to `window[genoverse.storageType].getItem(genoverse.saveKey)`. #### genoverse.resetConfig() -> If `genoverse.saveable` is `true`, removes all tracks and unremovable highlights, adds the default set of tracks, and removes the value in `genoverse.saveKey` from `window[genoverse.storageType]`. +> If [`genoverse.saveable`](/docs/configuration.md#saveable-default-false) is `true`, removes all tracks and unremovable highlights, adds the default set of tracks, and removes the value in [`genoverse.saveKey`](/docs/configuration.md#savekey-default-empty-string) from `window[genoverse.storageType]`. ## Changing browser location @@ -49,8 +49,8 @@ The following are functions that exist in the Genoverse object. Any of these can > > Argument | Type | Description > --- | --- | --- -> start | Integer | A number between `1` and `genoverse.chromosomeSize` -> end | Integer | A number between `start` and `genoverse.chromosomeSize` +> start | Integer | A number between `1` and [`genoverse.chromosomeSize`](/docs/configuration.md#chromosomesize-default-undefined) +> end | Integer | A number between `start` and [`genoverse.chromosomeSize`](/docs/configuration.md#chromosomesize-default-undefined) > update | Boolean or undefined | If `true`, the URL will be updated with the new `start` and `end` > keepLength | Boolean or undefined | if `true`, the new viewpoint will have the same zoom level as before (`end - start` remains unchanged), centered on the given `start` and `end`. @@ -90,7 +90,7 @@ The following are functions that exist in the Genoverse object. Any of these can ## URL interactions #### genoverse.updateURL -> If [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) is set, the URL will be updated to reflect the current browser region. This will be done either by using `window.history.pushState`, or by updating `window.location.hash`, depending on the value of [`genoverse.useHash`](/docs/configuration.md#usehash-default-undefined). +> If [`genoverse.urlParamTemplate`](/docs/configuration.md#urlparamtemplate-default-r__chr____start__-__end__) is set, the URL will be updated to reflect the current browser region. This will be done either by using [`window.history.pushState`](https://developer.mozilla.org/en-US/docs/Web/API/History_API#The_pushState()_method), or by updating `window.location.hash`, depending on the value of [`genoverse.useHash`](/docs/configuration.md#usehash-default-undefined). #### genoverse.popState > Called by [`window.onpopstate`](https://developer.mozilla.org/en-US/docs/Web/API/WindowEventHandlers/onpopstate) or [`window.onhashchange`](https://developer.mozilla.org/en/docs/Web/API/WindowEventHandlers/onhashchange) to update the browser region if the user uses the back or forward buttons in their web browser. From 6d1b3ec07eaaa791e37ee6e95a82141f4cecf349 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 15:21:37 +0000 Subject: [PATCH 093/102] Update functions.md --- docs/functions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/functions.md b/docs/functions.md index 7a0d0378..b12778b6 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -20,13 +20,13 @@ The following are functions that exist in the Genoverse object. Any of these can ## Configuration #### genoverse.loadConfig() -> If [`genoverse.saveable`](/docs/configuration.md#saveable-default-false) is `true`, configuration will be loaded from `window[genoverse.storageType].getItem(genoverse.saveKey)`. This configuration contains the user's previous tracks, their ordering, heights, and any other [track configuration settings](/docs/tracks/configuration.md#changing-track-settings). If no configuration exists, the default set of tracks will be used instead. +> If [`genoverse.saveable`](/docs/configuration.md#saveable-default-false) is `true`, configuration will be loaded from `window[`[`genoverse.storageType`](/docs/configuration.md#storagetype-default-sessionstorage)`].getItem(`[`genoverse.saveKey`](/docs/configuration.md#savekey-default-empty-string)`)`. This configuration contains the user's previous tracks, their ordering, heights, and any other [track configuration settings](/docs/tracks/configuration.md#changing-track-settings). If no configuration exists, the default set of tracks will be used instead. #### genoverse.saveConfig() -> If [`genoverse.saveable`](/docs/configuration.md#saveable-default-false) is `true`, the user's current tracks, their ordering, heights, and any other [track configuration settings](/docs/tracks/configuration.md#changing-track-settings) will be saved to `window[genoverse.storageType].getItem(genoverse.saveKey)`. +> If [`genoverse.saveable`](/docs/configuration.md#saveable-default-false) is `true`, the user's current tracks, their ordering, heights, and any other [track configuration settings](/docs/tracks/configuration.md#changing-track-settings) will be saved to `window[`[`genoverse.storageType`](/docs/configuration.md#storagetype-default-sessionstorage)`].getItem(`[`genoverse.saveKey`](/docs/configuration.md#savekey-default-empty-string)`)`. #### genoverse.resetConfig() -> If [`genoverse.saveable`](/docs/configuration.md#saveable-default-false) is `true`, removes all tracks and unremovable highlights, adds the default set of tracks, and removes the value in [`genoverse.saveKey`](/docs/configuration.md#savekey-default-empty-string) from `window[genoverse.storageType]`. +> If [`genoverse.saveable`](/docs/configuration.md#saveable-default-false) is `true`, removes all tracks and unremovable highlights, adds the default set of tracks, and removes the value in [`genoverse.saveKey`](/docs/configuration.md#savekey-default-empty-string) from `window[`[`genoverse.storageType`](/docs/configuration.md#storagetype-default-sessionstorage)`]`. ## Changing browser location From c5b33a3c6b349f99f67d721a46fcbdc84fb9a414 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 15:28:58 +0000 Subject: [PATCH 094/102] Update configuration.md --- docs/tracks/configuration.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/tracks/configuration.md b/docs/tracks/configuration.md index b226bd6a..76183526 100644 --- a/docs/tracks/configuration.md +++ b/docs/tracks/configuration.md @@ -2,7 +2,7 @@ The following are properties for `Genoverse.Track` and its MVC components. These can be overwritten to customize the way tracks get data and display it in the browser. -### Track display, resizing, and reordering +## Track display, resizing, and reordering #### name (default `undefined`) > The name of the track, which appears in its label on the left of the genome browser @@ -40,7 +40,7 @@ The following are properties for `Genoverse.Track` and its MVC components. These #### unsortable (default `false`) > If `true`, the track cannot be moved by the user. If `false`, a drag handle will appear next to the track's name, allowing the user to change its vertical position within the genome browser. -### Fetching data +## Fetching data #### url (default `undefined`) > The URL template used to fetch data from a server. Can contain placeholders for `__ASSEMBLY__`, `__CHR__`, `__START__`, and `__END__`, for example @@ -69,7 +69,7 @@ The following are properties for `Genoverse.Track` and its MVC components. These #### xhrFields (default `undefined`) > The xhrFields setting to be used in the [jQuery.ajax](http://api.jquery.com/jQuery.ajax/#jQuery-ajax-settings) requests to get data for the track -### Drawing features +## Drawing features #### featureHeight (default `undefined`) > The height of each feature, if `feature.height` is not set. If `undefined`, will be set to `track.height` @@ -124,12 +124,12 @@ The following are properties for `Genoverse.Track` and its MVC components. These > ``` > have the same effect. -### Interacting with features +## Interacting with features #### clickTolerance (default `0`) > Pixels of tolerance added to a click position when finding features for popup menus, when scale < 1. Increase to make it easier to click on small features (e.g. 1bp variants) when looking at large regions, at the cost of possibly showing feature menus for more features than expected. -### Changing track settings +## Changing track settings #### configSettings (default `undefined`) > An object defining properties of the track (including its models, views, and controller) which can be changed after initialization, as follows: From f51ee3e4605114c7ea0c5750e34ac1e7b57f9a34 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 16:13:56 +0000 Subject: [PATCH 095/102] Update functions.md --- docs/functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/functions.md b/docs/functions.md index b12778b6..05a24874 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -1,6 +1,6 @@ # Genoverse functions -The following are functions that exist in the Genoverse object. Any of these can have before/after events added to them, or be overwritten by supplying them as properties in configuration. +The following are functions that exist in the Genoverse object. Any of these can have before/after hooks added to them, or be overwritten by supplying them as properties in configuration. ## Initialization From 444973a5c93ae2b0f073e342ea2f1e1f4738a94d Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 16:56:20 +0000 Subject: [PATCH 096/102] Create functions.md --- docs/tracks/functions.md | 79 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 docs/tracks/functions.md diff --git a/docs/tracks/functions.md b/docs/tracks/functions.md new file mode 100644 index 00000000..f3ba3388 --- /dev/null +++ b/docs/tracks/functions.md @@ -0,0 +1,79 @@ +## Initialization + +The following functions are called during track creation and do not have before/after hooks. + +#### track.setInterface() +> Creates a `track._interface` object which is used to determine whether properties and functions belong to the track's model, view, or controller + +#### track.setDefaults() +> Sets initial properties of the track instance + +#### track.setDefaultConfig() +> If [`track.defaultConfig`](/docs/tracks/configuration.md#defaultconfig-default-undefined) is defined, uses it to set the current config, and add the correct settings to the track + +#### track.setEvents() +> Can be used to add events to the instance of Genoverse with [`genoverse.on`](/docs/api.md#genoverseonevents--ontracks--callback) if required by a particular type of track. By default does nothing. + +## [MVC interactions](/docs/tracks.md#multiple-models-and-views) + +#### track.setLengthMap() +> Finds [numerical keys](/docs/tracks.md#multiple-models-and-views) in the track definition, and uses them to create a `track.lengthMap` array containing `Genoverse.Track.Model` and `Genoverse.Track.View` instances as required. +> +> `track.lengthMap` is in the form +> ``` +> [ + [ 1, { "model": modelInstance1, "view": viewInstance1 } ], + [ 1000, { "model": modelInstance1000, "view": viewInstance1000 } ], + ... +] +> ``` +> where the first element in each array is the relevant numerical key. +> +> Also creates `track.models` and `tracks.views` objects in the form +> ``` +> track.models = { "1": modelInstance1, "1000": modelInstance1000, ... } +> track.views = { "1": viewInstance1, "1000": viewInstance1000, ... } +> ``` +> Called once during track initalization. Does not have before/after hooks. + +#### track.setMVC() +> Creates the instance of `Genoverse.Track.Controller` required by the track the first time it is called. +> Sets the model and view of a track, based on the current size of the browser region, determined by calling [`track.getSettingsForLength`](#trackgetsettingsforlength). + +#### track.newMVC(object [, functions, properties ]) +> Returns a new instance of a `Genoverse.Track.Model`, `Genoverse.Track.View`, or `Genoverse.Track.Controller` +> +> Argument | Type | Description +> --- | --- | --- +> object | `Genoverse.Track.Model`, `Genoverse.Track.View` or `Genoverse.Track.Controller` class | The class to be instantiated +> functions | Object or undefined | An object whose values are functions to be overwritten in the instance +> properties | Object or undefined | An object whose values are non-function properties to be overwritten in the instance + +#### track.getSettingsForLength() +> Returns the value of [`track.lengthMap`](#tracksetlengthmap) with the lowest first element value which is less that the current size of the browser region + +## [User configuration](/docs/tracks.md#allowing-a-user-to-change-a-tracks-configuration) + +#### track.setConfig() +> See the [api documentation](/docs/api.md#tracksetconfigtype-name) + +#### track.getConfig(type) +> Returns the name of the current [`track.configSetting`](/docs/tracks/configuration.md#configsettings-default-undefined) in use for the given `type` of config +> +> Argument | Type | Description +> --- | --- | --- +> type | String | The type of config setting + +## Enabling and disabling + +#### track.enable() +> See the [api documentation](/docs/api.md#trackenable) + +#### track.disable() +> See the [api documentation](/docs/api.md#trackdisable) + +#### track.reset() +> See the [api documentation](/docs/api.md#trackreset) +> +#### track.remove() +> See the [api documentation](/docs/api.md#trackremove) From f659d154ca90e29008386a26296a645987228750 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 16:56:53 +0000 Subject: [PATCH 097/102] Update functions.md --- docs/tracks/functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tracks/functions.md b/docs/tracks/functions.md index f3ba3388..f12700f5 100644 --- a/docs/tracks/functions.md +++ b/docs/tracks/functions.md @@ -74,6 +74,6 @@ The following functions are called during track creation and do not have before/ #### track.reset() > See the [api documentation](/docs/api.md#trackreset) -> + #### track.remove() > See the [api documentation](/docs/api.md#trackremove) From d2665e126027ba958fb4c23d120f119d93ce1cf0 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 17:05:18 +0000 Subject: [PATCH 098/102] Update functions.md --- docs/tracks/functions.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/tracks/functions.md b/docs/tracks/functions.md index f12700f5..6067409d 100644 --- a/docs/tracks/functions.md +++ b/docs/tracks/functions.md @@ -46,8 +46,8 @@ The following functions are called during track creation and do not have before/ > Argument | Type | Description > --- | --- | --- > object | `Genoverse.Track.Model`, `Genoverse.Track.View` or `Genoverse.Track.Controller` class | The class to be instantiated -> functions | Object or undefined | An object whose values are functions to be overwritten in the instance -> properties | Object or undefined | An object whose values are non-function properties to be overwritten in the instance +> functions | Object or `undefined` | An object whose values are functions to be overwritten in the instance +> properties | Object or `undefined` | An object whose values are non-function properties to be overwritten in the instance #### track.getSettingsForLength() > Returns the value of [`track.lengthMap`](#tracksetlengthmap) with the lowest first element value which is less that the current size of the browser region @@ -77,3 +77,29 @@ The following functions are called during track creation and do not have before/ #### track.remove() > See the [api documentation](/docs/api.md#trackremove) + +## Misc + +#### track.setHeight(height [, forceShow ]) +> Sets `track.height`. If the track needs to be hidden, `track.height` will be set to `0`. +> +> Argument | Type | Description +> --- | --- | --- +> height | Integer | The new height for the track +> forceShow | Boolean or `undefined` | If `true`, `height` will be used even if the track would normally be hidden + +#### track.resetHeight() +> See the [api documentation](/docs/api.md#trackresetheight) + +#### track.addLegend([ config, class ]) +> Creates a `Genoverse.Track.Legend` instance for the track, adding it to the browser. +> Argument | Type | Description +> --- | --- | --- +> config | Object or `undefined` | Properties to be given to the legend class constructor +> class | Child class of `Genoverse.Track.Legend` or `undefined` | The class to be used for the legend. Defaults to `Genoverse.Track.Legend`. + +#### track.updateName(name) +> See the [api documentation](/docs/api.md#trackupdatenamename) + +#### track.prop(key [, value ]) +> See the [api documentation](/docs/api.md#trackpropkey--value-) From 8b2ce5bac626ad7e90bca8dd0f542b2e705a5159 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Tue, 14 Feb 2017 17:05:44 +0000 Subject: [PATCH 099/102] Update functions.md --- docs/tracks/functions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/tracks/functions.md b/docs/tracks/functions.md index 6067409d..bcdc67e6 100644 --- a/docs/tracks/functions.md +++ b/docs/tracks/functions.md @@ -93,6 +93,7 @@ The following functions are called during track creation and do not have before/ #### track.addLegend([ config, class ]) > Creates a `Genoverse.Track.Legend` instance for the track, adding it to the browser. +> > Argument | Type | Description > --- | --- | --- > config | Object or `undefined` | Properties to be given to the legend class constructor From 2fb6434f9b31e8979c6c43993b481ee45946c980 Mon Sep 17 00:00:00 2001 From: Simon Brent Date: Wed, 15 Feb 2017 11:54:53 +0000 Subject: [PATCH 100/102] Update functions.md --- docs/functions.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/functions.md b/docs/functions.md index 05a24874..78e0d688 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -15,7 +15,7 @@ The following are functions that exist in the Genoverse object. Any of these can > width | Integer | The width for the container DOM element (usually this should be the initial value of [`genoverse.width`](/docs/configuration.md#width-default-1000)) #### genoverse.addUserEventHandlers() -> Created the event handlers required for users to interact with the instance of Genoverse +> Creates the event handlers required for users to interact with the instance of Genoverse ## Configuration @@ -264,5 +264,3 @@ The following are functions that exist in the Genoverse object. Any of these can > --- | --- | --- > functionName | String | The name of the function to call. This function can be in `Genoverse.Track`, `Genoverse.Track.Controller`, `Genoverse.Track.Model`, or `Genoverse.Track.View` > args | Anything | A list of arguments to be passed to the function being called - - From 83efcf0b29e4fc3918ad3da3867b7b1f5a4cdde8 Mon Sep 17 00:00:00 2001 From: Boris Burkov Date: Wed, 15 Feb 2017 19:23:30 +0000 Subject: [PATCH 101/102] Update plugins.md * Why plugins? Explained in 2 sentences, as you explained this to me. * Genoverse can asynchronously load plugins itself --- docs/plugins.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/plugins.md b/docs/plugins.md index 9848a967..d46aa4e3 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -1,8 +1,10 @@ # Plugins -The `Genoverse.Plugins` namespace contains a set of plugins to extend the core functionality of Genoverse. +Genoverse browser provides constitutive core functionality. `Genoverse.Plugins` namespace contains a set of optional, additional pieces of functionality - plugins - some projects may need and others might not. -These plugins, located in the [js/plugins](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/plugins) directory, are as follows: +Genoverse can asynchronously load plugins from its [js/plugins](https://github.com/wtsi-web/Genoverse/tree/gh-pages/js/plugins) directory on your server itself. Or you may explicitly import plugins in your html with, for example, `