Skip to content

Toolbar

Jump to bottom
Andy Boughton edited this page Aug 14, 2020 · 3 revisions

API Reference ▸ Toolbar

Toolbar

A Toolbar is an HTML element used for presenting arbitrary user interface widgets. Toolbars are anchored to either the entire Plot or to individual Panels.

Toolbar Methods

Once a toolbar is created on a plot or panel it can be accessed by the attribute named toolbar and has the following methods:

  • toolbar.show()
    Make the toolbar appear. If it doesn't exist yet create it, including creating/positioning all widgets within, and make sure it is set to be visible.

other methods to be documented

Toolbar Layout

A toolbar's layout is a serializable object that describes general settings and individual widgets for the toolbar. For example:

toolbar: {
  widgets: [
    {
      type: "title",
      title: "LocusZoom",
      position: "left"
    }
  ]
}

Supported Layout Directives

Default Toolbar Widget Layout Directives

All widgets are defined with their own layout objects (examples below). Many widgets support different layout directives to do different things. However, there are some widget layout directives that may apply broadly to many widgets:

  • position - String
    Whether to float the widget left or right. Can be "left" or "right". Defaults to "left".

  • color - String
    Color scheme for the widget. Applies to buttons and menus. Possible values are "gray", "red", "orange", "yellow", "green", "blue", and "purple". Defaults to "gray".

Toolbar Widget Types

LocusZoom has the following Toolbar Widgets pre-defined:

Title

Renders arbitrary text with title formatting. Example:

{
  type: "title",
  title: "LocusZoom",
  position: "left"
}
Title - Additional Layout Directives
  • title - String
    Text to render.

Dimensions

Renders text to display the current dimensions of the plot that automatically updates as plot dimensions change. Example:

{
  type: "dimensions",
  position: "left"
}

Region Scale

Renders text to display the current scale of the genome region displayed as defined by the difference between state.start and state.end. Example:

{
  type: "region_scale",
  position: "left"
}

Download SVG

Renders a button to allow for downloading the current plot as an SVG image. Example:

{
  type: "download",
  color: "green",
  position: "left"
}
Unique directives
  • button_html - String Text or HTML to display for the button caption
  • button_title - String
    Value of the title attribute for the button (shown by browsers automatically on hover, i.e. help text).
  • filename- String The filename to use when saving the plot (default: locuszoom.svg)

Download PNG

Renders a button to allow for downloading the current plot as a PNG image. Example:

{
  type: "download_png",
  color: "green",
  position: "left"
}
Unique directives
  • button_html - String Text or HTML to display for the button caption
  • button_title - String
    Value of the title attribute for the button (shown by browsers automatically on hover, i.e. help text).
  • filename- String The filename to use when saving the plot (default: locuszoom.png)

Filter Field

Allow the user to interactively modify filters for the specified datalayer so that only certain points are shown, based on the value typed into the text box. If an invalid value is provided, a red border is shown and the filter is cleared.

    {
        type: 'filter_field',
        position: 'right',
        layer_name: 'coaccessibility',
        field: 'access:score',
        field_display_html: 'Score',
        operator: '>=',
        data_type: 'number',
    }
Unique directives
  • layer_name - String The name/ID of the data layer to be controlled by this widget
  • field - String The field to be filtered. If no default filter is provided in the original layout, it will be created automatically when a value is entered.
  • field_display_html - String Human-friendly representation of the field name shown to users
  • operator - String The data layer filter operator to use.
  • data_type - String What type coercion to apply to the user-entered value when using this filter: 'number' or 'string' (default: string)
  • filter_id - String (optional) More than one filter can be specified using the same operator (this is most useful for inequality comparisons- "!=a and != b"). This lets the widget know which of the multiple filters is controlled by this widget.
  • input_size - *number (optional, default=4) The width of the input field, in number of characters

Toggle Legend

Renders a button that toggles display of the legend for the current panel. Will only work on panel toolbars.

{
    type: "toggle_legend",
    position: "right"
}

Remove Panel

Renders a button that will remove the parent panel from the plot. Will only work on panel toolbars. Example:

{
  type: "remove_panel",
  color: "red",
  position: "right"
}

Move Panel Up

Renders a button to allow for moving the panel up relative to other panels in terms of y-index. Will only work on panel toolbars. Example:

{
  type: "move_panel_up",
  color: "blue",
  position: "right"
}

Move Panel Down

Renders a button to allow for moving the panel down relative to other panels in terms of y-index. Will only work on panel toolbars. Example:

{
  type: "move_panel_down",
  color: "blue",
  position: "right"
}

Resize to data

Renders a button that resizes the panel to fit all available data. Useful for tracks such as genes, where an arbitrary amount of data may be shown in an initially fixed height. Will only work on panel toolbars.

{
    type: "resize_to_data",
    position: "right"
}
Unique directives
  • button_html - String Text or HTML to display for the button caption
  • button_title - String
    Value of the title attribute for the button (shown by browsers automatically on hover, i.e. help text).

Menu

Renders button with arbitrary text that, when clicked, toggles the appearance of a menu with arbitrary HTML. Example:

{
  type: "menu",
  button_html: "Click Me",
  button_title: "Description to show on mouse over",
  menu_html: "Lorem ipsum dolor sit amet",
  position: "left"
}
Menu - Additional Layout Directives

  • button_html - String
    HTML to render inside the button.

  • button_title - String
    Value of the title attribute for the button (shown by browsers automatically on hover, i.e. help text).

  • menu_html - String
    HTML to render inside the menu object which can be toggled to appear below the button (sized to its content) as the button is clicked.

Display Options

This panel-level toolbar widget creates a button that lets the user change between several different (pre-set) display options. For example, points can be colored based on different fields, or the same data can be drawn according to different size or coloring schemes. (solid color, gradient, etc)

{
    type: 'display_options',
    position: 'right',
    color: 'blue',
    // Below: special config specific to this widget
    button_html: 'Display options...',
    button_title: 'Control how plot items are displayed',
    layer_name: 'associationpvaluescatalog',
    default_config_display_name: 'Basic plot (default)', // display name for the default plot color option (allow user to revert to plot defaults without duplicating here)
    options: [{
        display_name: "First option",
        display: {
            color: "#FF0000"
        }
    }]
Unique directives

  • button_html - String Text or HTML to display for the button caption

  • button_title - String Mouseover text for the button

  • layer_name - String The name of the data layer that this button controls. A given set of display options will only control one data layer within the panel where the button lives.

  • default_config_display_name - String The display options button automatically captures the original coloring configuration for the data layer, so as to avoid duplication. This option controls what name is used to refer to that coloring configuration on the dropdown with a list of display choices.

  • fields_whitelist - Array, Optional By default, the display_options dropdown knows how to control some of the most common display settings used by data layers. If your data layer has custom configuration, you can override the list of known fields, and the button will then attempt to find (or set) layout keys with matching names. If this field is omitted, the default fields that can be controlled are: "color", "fill_opacity", "filters", "label", "legend", "point_shape", "point_size", "tooltip", "tooltip_positioning".

  • options - Array Specify a series of ways that the plot can be drawn. Each option is an object with the keys specified below.

Options specification

  • display_name - String The human-friendly label to show when referring to this option in the dropdown.

  • display - Object Specify a set of standard layout directives for each data point, for the fields this button knows how to control (as set in fields_whitelist, above). Each key supports the full syntax and power available to these options in a data layer, including scalable parameters. For example: colors can be a gradient, and point size / shape can be controlled conditionally based on field value.

Set state

Set a particular field in plot.state to a specific value. Since some data sources and rendering options depend on the value of a field in plot.state, this can be used to modify requests dynamically- eg, to let users select a custom LD panel. (the built-in predefined toolbar button ldlz2_pop_selector is a special case of this widget)

Because this sets global options (plot.state), this button will only work on plot toolbars.

{

    type: 'set_state',
    position: 'right',
    color: 'blue',
    button_html: 'LD Population: ',
    show_selected: true,
    button_title: 'Select LD Population: ',
    state_field: 'ld_pop',
    // This list below is hardcoded to work with the UMich LDServer, default 1000G populations
    //  It can be customized to work with other LD servers that specify population differently
    // https://portaldev.sph.umich.edu/ld/genome_builds/GRCh37/references/1000G/populations
    options: [
        { display_name: 'ALL (default)', value: 'ALL' },
        { display_name: 'AFR', value: 'AFR' },
        { display_name: 'AMR', value: 'AMR' },
        { display_name: 'EAS', value: 'EAS' },
        { display_name: 'EUR', value: 'EUR' },
        { display_name: 'SAS', value: 'SAS' }
    ]
}
Unique directives
  • button_html - String Text or HTML to display for the button caption
  • button_title - String
    Value of the title attribute for the button (shown by browsers automatically on hover, i.e. help text).
  • show_selected - Boolean Whether to show the selected value as part of the button label (default false)
  • state_field- String The name of the field in plot.state that is controlled by this button
  • options- Array An array of objects. Each option is an object that specifies display_name (shown in the UI) and value (saved in plot.state when the option is selected).
Clone this wiki locally