# Module: ext/lz-dynamic-urls

Optional LocusZoom extension: must be included separately, and after LocusZoom has been loaded

This plugin exports helper functions, but does not modify the global registry. It does not require `LocusZoom.use`.

Demonstrates a mechanism by which the plot can be loaded to a specific initial state based on the URL query string (and, optionally, to update the URL bar when the plot state changes, with back button support)

This makes it possible to create "direct links" to a particular plot of interest (and go back to a previous state as the user interacts with the page). Optionally, there is support for custom callbacks to connect the URL to arbitrarily complex plot behaviors.

To use in an environment without special JS build tooling, simply load the extension file as JS from a CDN (after any dependencies):

    <script src="https://cdn.jsdelivr.net/npm/locuszoom@INSERT_VERSION_HERE/dist/ext/lz-dynamic-urls.min.js" type="application/javascript"></script>

To use with ES6 modules, import the helper functions and use them with your layout:

    import LzDynamicUrls from 'locuszoom/esm/ext/lz-dynamic-urls';

After loading, bind the plot and URL as follows:

    // Declares which fields in plot.state will be mapped to and from the URL, eg `plot.state.chr` -> `example.com?chrom=X`
    const stateUrlMapping = {chr: "chrom", start: "start", end: "end"};
    // Fetch initial position from the URL, or use some defaults
    let initialState = LzDynamicUrls.paramsFromUrl(stateUrlMapping);
    if (!Object.keys(initialState).length) {
        initialState = {chr: 10, start: 114550452, end: 115067678};
    }
    layout = LocusZoom.Layouts.get("plot", "standard_association", {state: initialState});
    const plot = LocusZoom.populate("#lz-plot", data_sources, layout);
    // Once the plot has been created, we can bind it to the URL as follows. This will cause the URL to change whenever
    //  the plot region changes, or, clicking the back button in your browser will reload the last region viewed
    LzDynamicUrls.plotUpdatesUrl(plot, stateUrlMapping);
    LzDynamicUrls.plotWatchesUrl(plot, stateUrlMapping);

    // NOTE: If you are building a page that adds/removes plots on the fly, event listeners will be cleaned up when
    //   the destructor `plot.destroy()` is called

Source:
  - ext/lz-dynamic-urls.js, line 1

### Methods

#### (inner) paramsFromUrl(mapping, queryStringopt) → {object}

Extract plot parameters from the URL query string. Very useful for setting up the plot on initial page load.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`mapping` | object |  |  | How to map elements of plot state to URL param fields. Hash of {plotFieldName: urlParamName} entries (both values should be unique)
`queryString` | string | <optional> | 'window.location.search' | The query string to parse

Source:
  - ext/lz-dynamic-urls.js, line 120

##### Returns:

Plot parameter values

Type
  object

#### (inner) plotUpdatesUrl(plot, mapping, callbackopt) → {function}

Update the URL whenever the plot state changes

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`plot` | Plot |  | A reference to the LZ plot
`mapping` | object |  | How to map elements of plot state to URL param fields. Hash of {plotFieldName: urlParamName} entries (both values should be unique)
`callback` | function | <optional> | Specify how plot data will be serialized into query params The default behavior is to extract all the URL params from plot.state as the only source. Signature is function(plot, mapping, eventContext)

Source:
  - ext/lz-dynamic-urls.js, line 164

##### Listens to Events:

- event:state_changed

##### Returns:

The function handle for the new listener (allows cleanup if plot is removed later)

Type
  function

#### (inner) plotWatchesUrl(plot, mapping, callbackopt) → {function}

Allows the plot to monitor changes in the URL and take action when the URL changes.

For example, this enables using the browser back button to jump to a previous plot after user interaction.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`plot` | Plot |  | A reference to the LZ plot
`mapping` | object |  | How to map elements of plot state to URL param fields. Hash of {plotFieldName: urlParamName} entries (both values should be unique)
`callback` | function | <optional> | Specify how the plot acts on information read in from query params. The default behavior is to push the data into `plot.state` Signature is function(plot, plotDataFromQueryString)

Source:
  - ext/lz-dynamic-urls.js, line 140

##### Returns:

The function handle for the new listener (allows cleanup if plot is removed later)

Type
  function