Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    @wikipathways/pvjspublic

    Pvjs

    JavaScript-based biological pathway diagram viewer. Used in WikiPathways.

    Beta

    The beta tag given to this version means that it is not advisable to use it in production. There are some known issues and it has not been fully cross browser tested.

    Having said that, most of the desired functionality does work as intended in most modern browsers.

    Note: If you need to use the stable version of Pvjs see this README.

    Contents

    Installation

    Using a Module Bundler (Webpack)

    We recommend using a module bundler like Webpack in your project. If you're doing this, just install and import Pvjs. All examples will assume you are using this method and not the UMD bundle.

    Note that Pvjs does come with some styles which will be automatically picked up by Webpack.

    npm install @wikipathways/pvjs --save
    
    // Somewhere in your project
    import { Pvjs } from '@wikipathways/pvjs';

    Using the UMD bundle

    Pvjs comes with a UMD bundle that you can include in your HTML page. It's available under dist/index.js. Once you've included the bundle, Pvjs is available under the Pvjs namespace.

    
    ### <a name="umd"></a>Using the UMD bundle
    Pvjs comes with a UMD bundle that you can include in your HTML page. It's available under `dist/index.js`. Once you've included the bundle, Pvjs is available under the `Pvjs` namespace.
    
    1. Copy `dist/index.js`, `dist/style.css`, and all of `dist/assets` into your project assets (tip: use a task runner like gulp)
    2. Include `index.js` and `style.css` in your project's head tag:
    
    ```html
    <script src="assets/pvjs/index.js"></script>
    <link rel="stylesheet" href="assets/pvjs/style.css" />
    

    Alternatively, just use it from the unpkg CDN:

    <script src="https://unpkg.com/@wikipathways/pvjs/dist/index.js"></script>
    <link rel="stylesheet" href="https://unpkg.com/@wikipathways/pvjs/dist/style.css" />

    React Usage

    If you are already using React then you can directly use the React component.

    Basic Example

    Use the component as below. Pvjs will fill whatever container it is in, so it is a good idea to place it inside a container with set dimensions.

    import React from 'react';
    import ReactDOM from 'react-dom';
    import { Pvjs } from '@wikipathways/pvjs';
     
    ReactDOM.render(
        <Pvjs
            wpId="WP4"
        />,
        document.getElementById('root')
    );

    Props

    • wpId: Required. A string for the WikiPathways ID of the desired pathway. E.g. 'WP4'.
    • version: Default = 0. A number for the version of the pathway. 0 is latest.
    • onReady: Function that is called with the list of entities in the diagram when the diagram has finished loading. You can use this to get the entityIds for other props.
    • onEntityClick: Function that is called with the entity whenever a diagram entity has been clicked.
    • onPanZoomChange: Function that is called whenever the diagram is panned or zoomed. It is called with an object with the form: { x: number, y: number, zoomLevel: number }. The coordinates in the object are relative to the diagram dimensions.
    • detailPanelEnabled: Default = true. Indicates whether the annotations pop-up will be shown when an entity is clicked.
    • panZoomLocked: Default = false. Indicates whether the user can manually pan and zoom the diagram. Note, changes to pannedEntities and zoomedEntities will still have an effect if this is true.
    • showPanZoomControls: Default = true. Indicates whether the controls for panning and zooming are shown.
    • highlightedEntities: Default = []. Array of objects for highlighted diagram entities. Objects in this array look like { entityId: string, color: string }. Color can be any CSS color. See the advanced example.
    • hiddenEntities: Default = []. Array of entityIds. See the advanced example.
    • pannedEntities: Default = []. Array of entityIds. See the advanced example.
    • zoomedEntities: Default = []. Array of entityIds. See the advanced example. Note, that zoomed does not also mean panned. In most cases, an entityId in zoomedEntities should also be in pannedEntities.
    • zoomLevel: Default = 1. Number indicating the level of zoom the diagram should be at. 1 = no zoom in/out.
    • panCoordinates: Default: {x: 0, y: 0}. Relative coordinates to pan to. x is relative to the diagram width and y the diagram height. E.g. {x: 0.5, y: 0.5} will pan half way across the x and y axis.

    Note that pannedCoordinates and zoomLevel take precedence over pannedEntities and zoomedEntities.

    Advanced Example

    import React, { Component } from 'react';
    import { Pvjs } from '@wikipathways/pvjs';
     
    class MyPvjsComponent extends Component {
      constructor(props) {
        super(props);
     
        this.state = {
          highlightedEntities: [],
          hiddenEntities: [],
          zoomedEntities: [],
          pannedEntities: [],
        }
      }
     
      onEntityClick = entity => {
        // This will highlight an entity red, whenever it is clicked
        this.setState(state => {
          return {
            highlightedEntities: state.highlightedEntities.concat([
              {
                entityId: entity.id,
                color: 'red', // Color can be any CSS color
              },
            ]),
          }
        });
      }
     
      onPvjsReady = entityList => {
        // Find the entity with TCA cycle as the node text
        const TCA = entityList.find(singleEntity => singleEntity.textContent === 'TCA Cycle');
        const BRCA1 = entityList.find(singleEntity => singleEntity.textContent === 'BRCA1');
     
        this.setState({
          highlightedEntities: [{entityId: TCA.id, color: 'blue'}],
          pannedEntities: [TCA.id],
          zoomedEntities: [TCA.id],
          hiddenEntities: ['daafb'],
        });
      }
     
      render() {
        const { highlightedEntities, hiddenEntities, zoomedEntities, pannedEntities } = this.state;
     
        return (
          <div style={{width: '100vw', height: '100vh'}}>
            <Pvjs
              wpId="WP4"
              version={0}
              onReady={this.onPvjsReady}
              onEntityClick={this.onEntityClick}
              highlightedEntities={highlightedEntities}
              hiddenEntities={hiddenEntities}
              zoomedEntities={zoomedEntities}
              pannedEntities={pannedEntities}
              detailPanelEnabled={false}
            />
          </div>
        )
      }
    }

    Web Component

    The web component allows you to use Pvjs without React. To use it, first make sure that Pvjs is available on the page in which you're using it. The easiest way to do this is to include the UMD bundle in your pages head. If you're using a module bundler, just make sure Pvjs is included in your build process (normally in index.js).

    Example

    An example is served at this gist.

    Attributes

    • wp-id: Required. A string for the WikiPathways ID of the desired pathway. E.g. 'WP4'.
    • version: Default = 0. A number for the version of the pathway. 0 is latest.
    • detail-panel-enabled: Indicates whether the annotations pop-up will be shown when an entity is clicked.
    • pan-zoom-locked: Indicates whether the user can manually pan and zoom the diagram. Note, changes via the Manipulation API will still take effect.
    • show-pan-zoom-controls: Indicates whether the controls for panning and zooming are shown.
    • ready: Indicates when the diagram is fully loaded and ready for manipulating. You cannot set this.
    • highlighted-entities: Comma separated list of entityId:color maps. E.g. d8bae:red. You may set this using the API.
    • panned-entities: Comma separated list of entity IDs that are panned to. You may set this using the API.
    • zoomed-entities: Comma separated list of entity IDs that are zoomed to. You may set this using the API.
    • hidden-entities: Comma separated list of entity IDs that are hidden. You may set this using the API.

    Properties

    These properties are not reflected in the DOM attributes.

    • entities: The list of entity objects in the diagram. This is null until the diagram is ready.

    Events

    • ready: This is fired when the diagram is ready. entities is provided in the detail object for convenience. See this gist.

    Manipulating

    The custom element provides a custom API that allows you to programmatically manipulate the diagram.

    Example

    An example is served at this gist.

    Methods

    zoomOn

    This method accepts a single entity ID or an array of entity IDs. If a single entity is given then the diagram will zoom and pan to that entity. If an array is given, the diagram will zoom and pan to the area defined by all of those entities.

    zoomOn(entity_id: string | string[])
    panTo

    Basically the same as zoomOn but without the zooming.

    panTo(entity_id: string | string[])
    highlightOn

    Attributes

    highlightOn(entity_id: string, color: string)
    highlightOff
    highlightOff(entity_id: string)
    toggleHighlight
    toggleHighlight(entity_id: string)
    hide
    hide(entity_id: string)
    show
    show(entity_id: string)
    toggleHidden
    toggleHidden(entity_id: string)
    resetPan
    resetPan()
     
    ##### toggleHidden
    ```javascript
    toggleHidden(entity_id: string)
    resetPan
    resetPan()
    resetZoom
    resetZoom()
    resetHighlighted

    Un-highlight all highlighted entities. Accepts an optional exclude array that will exclude the given entities from being reset.

    resetHighlighted(exclude?: string[])
    resetHidden

    Show all hidden entities. Accepts an optional exclude array that will exclude the given entities from being reset.

    resetHidden(exclude?: string[])
    reset

    Reset the pan, zoom, hidden, and highlighted entities

    reset()

    Contributions & Bugs

    We love pull requests! If you want to contribute to Pvjs then please feel free to make a pull request. The GitHub page is available here.

    If you find a bug please check the issue tracker to see if it hasn't already been reported. If not, then please create a new issue. If you can then we would love for you to make a fix for it in a pull request.

    Funding

    Keywords

    none

    install

    npm i @wikipathways/pvjs

    Downloadsweekly downloads

    0

    version

    4.0.4

    license

    Apache-2.0

    repository

    githubgithub

    last publish

    collaborators

    • avatar
    • avatar
    • avatar