Skip to content

Panel

Jump to bottom
Christopher Clark edited this page Sep 28, 2016 · 11 revisions

API Reference ▸ Panel

Panel

A Panel is a region of a plot, typically occupying the full plot width but only a portion of the vertical space, stacked along the y-axis with other panels.

Panel Methods

Panel objects can be accessed through a plot object by id within the panels object. For instance, a panel with an id of "foo" could be accessed from the plot object by plot.panels.foo. Supported panel methods are:

  • panel.addDataLayer(layout)
    Add a new data layer with the data layer layout (object) provided. Will automatically add at the top (depth/z-index) of the panel unless explicitly directed differently in the layout provided.

  • panel.setDimensions([width, height])
    Set the dimensions for the panel. If passed with no arguments will calculate optimal size based on layout directives and the available area within the plot. If passed discrete width (number) and height (number) will attempt to resize the panel to them, but may be limited by minimum dimensions defined on the plot or panel.

Panel Widgets

Panels have a few widgets for various special use cases.

Panel Curtain

The panel curtain, like the plot curtain is an HTML overlay that obscures the entire panel. It can be styled arbitrarily and display arbitrary messages. It is useful for reporting error messages visually to an end user when the error renders the panel unusable.

Use the curtain by invoking the following methods:

  • panel.curtain.show([content[, css]])
    Generate the curtain. Any content (string) argument passed will be displayed in the curtain as raw HTML. CSS (object) can be passed which will apply styles to the curtain and its content.

  • panel.curtain.update([content[, css]])
    Update the content and css of the curtain that's currently being shown. This method also adjusts the size and positioning of the curtain to ensure it still covers the entire panel with no overlap.

  • panel.curtain.hide()
    Remove the curtain.

Panel Loader

The panel loader is a small HTML overlay that appears in the lower left corner of the panel. It cannot be styled arbitrarily but can show a custom message and show a minimalist loading bar that can be updated to specific completion percentages or be animated.

Use the loader by invoking the following methods:

  • panel.loader.show([content]])
    Generate the loader. Any content (string) argument passed will be displayed in the string as raw HTML. If no content is supplied the message in the loader will default to "Loading..."

  • panel.loader.update([content[, percent]])
    Update the content (string) and, optionally, the percent (number) complete of the loader that's currently being shown. This method also adjusts the positioning of the loader to ensure it still appears in the lower left corner of the panel. Percents will automatically be limited to a range of 1 to 100 and, if passed, will stop all animations in progress.

  • panel.loader.setPercentCompleted(percent)
    Sets the loading bar in the loader to precentage width equal to the percent (number) value passed. Percents will automatically be limited to a range of 1 to 100. Will stop all animations in progress.

  • panel.loader.animate()
    Adds a class to the loading bar that makes it loop infinitely in a loading animation.

  • panel.loader.hide()
    Remove the loader.

Panel Events and Hooks

There are several events that a LocusZoom panel can "emit" when appropriate and LocusZoom supports registering "hooks" for these events which are essentially custom functions intended to fire at certain times.

The following panel-level events are currently supported:

  • layout_changed - context: panel
    Any aspect of the panel's layout (including dimensions or state) has changed.

  • data_requested - context: panel
    A request for new data from any data source used in the panel has been made.

  • data_rendered - context: panel
    Data from a request has been received and rendered in the panel.

  • element_clicked - context: element A data element in any of the panel's data layers has been clicked.

To register a hook for any of these events use the panel's on() method like so:

var plot = LocusZoom.populate(selector, data_sources, layout);
var panel = plot.addPanel(panel_layout);
panel.on("data_requested", function(){
  console.log("data requested for LocusZoom panel" + this.id);
});
panel.on("data_rendered", function(){
  console.log("data rendered for LocusZoom panel" + this.id);
});

In the above example we log to the console a message containing the panel's ID whenever data is requested and subsequently rendered.

There can be arbitrarily many functions registered to the same event. They will be executed in then order they were registered. The this context bound to each event hook function is dependent on the type of event, as denoted above. For example, when data_requested is emitted the context for this in the event hook will be the panel itself, but when element_clicked is emitted the context for this in the event hook will be the element that was clicked.

Panel Layout

A panel's layout is a serializable object that describes every customizable feature of the panel with nested values. It should only ever contain scalar values, arrays, and objects - no functions!

Example:

var panel_layout = {
  id: "panel1",
  width: 100,
  height: 100,
  data_layers: [
    ...
  ],
  ...
}

Supported Layout Directives

General

  • title - String
    A string denoting the title of the panel. If defined this will appear in large font in the upper left corner of the panel, independent of the panel's margins. Panel titles are rendered as text elements inside the SVG of the plot, so HTML will not be rendered.

  • description - String
    A string denoting a description of the panel. If defined, and if the panel's controls parameter is defined and is set to enable description, then this value can be visible by way of a button in the controls element for the panel. Panel descriptions are HTML elements positioned over the plot, so arbitrary HTML in a description definition will be rendered. Not defined by default.

  • y_index - Number
    An integer ranging from 0 to n-1 denoting the panel's position relative to other n panels in a vertical orientation in the plot. If not defined this value will be automatically assigned in the order the panel is added to the plot.

  • inner_border - String
    A string denoting the color (hex value, rgb, rgba, hsl, etc.) for a border to be rendered showing the clip area of the data layers for the panel. Any axes that are rendered will effectively represent this border, but for the edges where an axis may not be rendered it may still be preferable to bound the data region with a line. If not defined then the inner border will not be rendered.

Dimensions and Geometry

  • width - Number
    Discrete width, in pixels, of the panel. Subject to being limited by panel.min_width.

  • height - Number
    Discrete height, in pixels, of the panel. Subject to being limited by panel.min_height.

  • min_width - Number
    Minimum discrete width, in pixels, allowable for the panel. Able influence the min_width value on the parent layout.

  • min_height - Number
    Minimum discrete height, in pixels, allowable for the panel. Able influence the min_height value on the parent layout.

  • origin - Object
    An object that defines where the panel will be positioned in the plot (by the panel's top left corner) expressed as discrete pixel coordinates.

    • origin.x - Number
      X-offset, in pixels, for the top-left corner of the panel (relative to the LocusZoom plot).

    • origin.y - Number
      Y-offset, in pixels, for the top-left corner of the panel (relative to the LocusZoom plot).
      NOTE: SVG y values go from the top down, so the SVG origin of (0,0) is in the top left corner.

  • proportional_width - Number
    Width of the panel expressed as a proportion of the available width of the LocusZoom plot. Value should be a number in the range of 0.0 to 1.0, with 1.0 meaning 100%.

  • proportional_height - Number
    Height of the panel expressed as a proportion of the available height of the LocusZoom plot. Value should be a number in the range of 0.0 to 1.0, with 1.0 meaning 100%.

  • proportional_origin - Object
    An object that defines where the panel will be positioned in the plot (by the panel's top left corner) expressed as proportions of the plot's dimensions.

    • proportional_origin.x - Number
      X-offset, as a proportion of the plot's width, for the top-left corner of the panel (for example, 50% would be expressed as 0.5).

    • proportional_origin.y - Number
      Y-offset, as a proportion of the plot's height, for the top-left corner of the panel (for example, 25% would be expressed as 0.25).

  • margin - Object
    An object that defines the margins between a panel's boundaries and its content.

    • margin.top - Number
      Margin, in pixels, from the top edge of a panel to its content

    • margin.right - Number
      Margin, in pixels, from the right edge of a panel to its content

    • margin.bottom - Number
      Margin, in pixels, of the bottom edge of a panel to its content

    • margin.left - Number
      Margin, in pixels, of the left edge of a panel to its content

Axes

  • axes - Object
    An object that defines axes for a panel, by axis ID. Supported axis IDs are only x, y1, and y2.

    Example:

panel {
  axes:
    x: { ... },
    y1: { ... },
    y2: { ... }
  }
}

  • axes.{x|y1|y2}.label - String
    Static label to appear on the axis.

  • axes.{x|y1|y2}.label_function - String
    The name of a LabelFunction for creating a dynamic label relative to the values in state. See Label Functions for more details. If set this will override any label value.

  • axes.{x|y1|y2}.label_offset - Number
    Distance, in pixels, to shift the axis label away from its axis. This value is interpreted differently for each axis ID (e.g. for the x axis this value shift the label downward, for y1 it shifts the label to the left, and for y2 it shifts the label to the right).

  • axes.{x|y1|y2}.tick_format - String
    If defined and set to "region" then the values on the axis will be interpreted as region/position values and formatted accordingly.

  • axes.{x|y1|y2}.ticks - Array
    An array of discrete ticks to apply to the axis. If not provided then ticks will be automatically generated. The ticks array can be a simple list of discrete numbers, like so:

x: { 
  ticks: [ 0, 10, 20, 30, 40 ]
}

Or the ticks array can be an array of objects for finer control over how each tick is rendered. For example:

x: { 
  ticks: [ 
    {
      x: 10,
      text: "infectious diseases",
      style: { color: "#FF0000", "text-anchor": "start" },
      transform: "rotate(45)"
    },
    {
      x: 200,
      text: "mental disorders",
      style: { color: "#00DD00", "text-anchor": "start" },
      transform: "rotate(45)"
    },
    ...
  ]
}

Supported values for tick objects:

  • axes.{x|y1|y2}.ticks[t].x - Number
    X value (in terms of the data set, not pixels on the plot) for which the tick should be rendered.

  • axes.{x|y1|y2}.ticks[t].text - String
    Text to use the visible label for the tick.

  • axes.{x|y1|y2}.ticks[t].style - Object
    Object describing styles for the tick label. Conforms to the d3 standard style object specification.

  • axes.{x|y1|y2}.ticks[t].transform - String
    Transformation string to apply to the tick label. See SVG transform documentation for supported syntax.

Interaction

  • interaction - Object
    An object that defines which interaction behaviors (e.g. panning and zooming) are enabled and how those interactions are linked between panels.

    • interaction.drag_background_to_pan - Boolean
      Whether clicking and dragging the panel's background should move (pan) the panel horizontally along the x axis

    • interaction.scroll_to_zoom - Boolean
      Whether scrolling the mouse wheel when hovering over the panel should zoom the panel relative to the x axis (scroll up to zoom in, scroll down to zoom out)

    • interaction.drag_x_ticks_to_scale - Boolean
      Whether ticks on the x axis should have drag enabled on them to allow moving (panning) along the x axis with click+drag or scaling the x axis with shift+click+drag

    • interaction.drag_y1_ticks_to_scale - Boolean
      Whether ticks on the y1 axis should have drag enabled on them to allow moving (panning) along the y1 axis with click+drag or scaling the y1 axis with shift+click+drag

    • interaction.drag_y2_ticks_to_scale - Boolean
      Whether ticks on the y2 axis should have drag enabled on them to allow moving (panning) along the y2 axis with click+drag or scaling the y2 axis with shift+click+drag

    • interaction.x_linked - Boolean
      Whether any interactions on this panel that affect the x axis should be broadcast to other x-linked panels

    • interaction.y1_linked - Boolean
      Whether any interactions on this panel that affect the y1 axis should be broadcast to other y1-linked panels

    • interaction.y2_linked - Boolean
      Whether any interactions on this panel that affect the y2 axis should be broadcast to other y2-linked panels

Complex Object Layout Directives

  • dashboard - Object
    A Dashboard layout object. Will be automatically displayed as a mouse-enabled overlay along the top of the panel if defined with components.

  • data_layers - Array
    An array of Data Layer layout objects. Will automatically be rendered bottom-to-top (in terms of page depth) in the order defined here excepting where data layer layout defines a z_index value.

Clone this wiki locally