@docmaps/widget v1.12.1
Official Docmaps Widget
An embeddable widget for displaying Docmaps data, built with Lit and D3.
To see the widget in action, check out the Docmap explorer demo site!
Usage
The widget can be retrieved via CDN, or via NPM if your project already uses NPM.
Retrieving via CDN
You can directly pull in the widget in an HTML file without installing anything like so:
<head>
<script type='module' src='https://cdn.jsdelivr.net/npm/@docmaps/widget@latest/dist/index.min.js'></script>
</head>
<body>
<docmaps-widget doi='doi-to-render' serverurl='https://example.com'></docmaps-widget>
</body>Installing with NPM
If your project already uses NPM, you can install the widget like so:
npm install @docmaps/widgetThen, add the widget to your page:
<script>
import '@docmaps/widget';
</script>
<docmaps-widget doi="doi-to-render" serverurl="https://example.com"></docmaps-widget>Supported attributes
These attributes can be added to the <docmaps-widget> tag to configure the widget's behavior.
| Attribute | Description |
|---|---|
doi | The DOI of the paper to render |
serverurl | The URL of the server from which the docmap will be fetched. The widget will make a request to this server's GET /docmap_for/doi?subject={doi} endpoint, which must be implemented by the server in accordance with the official Docmaps API spec. |
If you prefer to pass a docmap directly to the widget, you must do so after the widget has been mounted, like so:
<head>
<script type='module' src='https://cdn.jsdelivr.net/npm/@docmaps/widget@latest/dist/index.min.js'></script>
</head>
<body>
<docmaps-widget id='my-widget'></docmaps-widget>
</body>
<script>
customElements.whenDefined('docmaps-widget') // wait for the custom docmaps-widget element to be defined
.then(() => {
const widgetElement = document.getElementById('my-widget');
widgetElement.docmap = {
// docmap here
};
});
</script>For examples of docmaps to feed into the widget here, see the examples directory.
Screenshots
Graph view:
Clicking a node opens the detail view:
Development
Running the server locally
pnpm run devThis starts the server on http://localhost:5173
Running the tests
The first time you run the tests, you will need to install browsers for Playwright to use
pnpm run install:browsersAll tests
pnpm run testUnit tests
pnpm run test:unitIntegration tests
To see the tests run in step-by-step, you can open the Playwright UI like this. The Playwright UI is an amazing tool because it lets you see screenshots of each step of the test, and it automatically reruns the tests when you make changes.
pnpm run test:integration:uiAlternatively, you can run the tests headlessly and see results in the terminal:
pnpm run test:integrationBy default, the tests only run in chromium locally. To run in chromium, firefox, and webkit, you can run:
# Headless
pnpm run test:integration:all-browsers
# With UI
pnpm run test:integration:ui:all-browsers