Throughput Annotation Widget
npm install throughput-widget
 
The Throughput Annotation Widget is a lightweight web component that allows web users to view Throughput annotations on a dataset, and to add new annotations after authenticating through ORCID.
Built with the Stencil toolchain, the widget is easy to integrate into Vue, React, and Angular applications, or a static HTML webpage.
This project is an open project, and contributions are welcome from any individual. All contributors to this project are bound by a code of conduct. Please review and follow this code of conduct as part of your contribution.
* Shane Loeffler 
* Brian Grivna 
Issues and bug reports are always welcome. Code clean-up, and feature additions can be done either through pull requests to project forks or branches.
All products of the Throughput Annotation Project are licensed under an MIT License unless otherwise noted.
1. Install npm.
2. Clone the repository and run npm install in its root directory.
3. In src/index.html, set identifier, link, additional-type properties for the data resource to be annotated. Additionally, set orcid-client-id, which is required unless the optional read-only-mode property is set to true.
4. Run with npm run start.
5. View the widget in a browser at http://localhost:3333.
6. Hack away and send us pull requests or issues!
Minimal examples of widget integration into Vue, React, Angular, and static HTML can be found in the examples directory. All examples use read-only-mode.
#### Register with ORCID
If you plan to use the widget in read-only-mode, skip this step.
To add annotations, widget users must first authenticate through ORCID. We encourage devs to register for the public ORCID API so they can freely manage post-authentication redirects for their site.
Separate registrations are required for the ORCID production and ORCID sandbox sites.
Once registered, an ORCID Client ID (e.g. APP-1234567890ABCDEF) will be provided. This is passed to the widget in the orcid-client-id property, described below.
#### Install the widget
For Vue, React, and Angular applications, install the widget with npm:
npm install throughput-widget
For static HTML pages, import the widget with the following tag:
``
Vue, React, and Angular can use this tag as an alternative to npm.
#### properties
Once installed, your application will have access to the component.
It accepts the following properties:
| property | Required | Description |
| -------- | --------| -----------|
| identifier | Required | re3data identifier for top-level data resource. |link
| | Required | Identifies a dataset within the top-level data resource. |additional-type
| | Required | Identifies the data type associated with link. |read-only-mode
| | Optional bool (def. false) | If true, the "Add Annotation" UI will be hidden. |orcid-client-id
| | Required if read-only-mode=false | The ORCID client ID to be used for authentication. |use-orcid-sandbox
| | Optional bool (def. false) | If false, use ORCID production for authentication. If true, use ORCID sandbox |
Databases registered within Throughput use the re3data identifier as a UID. For example, the Neotoma Paleoecology Database has a re3data landing page at https://www.re3data.org/repository/r3d100011761, and a UID within Throughput of r3d100011761.
Within an individual database, individual data elements are identified using both an identifier, and an additional-type. These are defined by the database themselves. For example, in a data service that provides access to data at multiple granularity, it might be the case that there is a collectionunit with an identifier 1223, and also a site with the same identifier ID. The use of the additional-type together with the identifier is intended to add flexibility for the data resource in managing and querying annotations.
Vue, React, and Angular each require additional changes to make use of the widget, detailed below.
#### Vue
In src/main.js, import the widget and tell Vue to ignore the widget element:
`javascript`
import { applyPolyfills, defineCustomElements } from 'throughput-widget/loader';
Vue.config.ignoredElements = ["throughput-widget"];
applyPolyfills().then(() => {
defineCustomElements();
});
The widget will be added to the .vue template file, as an HTML element. Add the widget to your dataset template, and pass in props. Note the Vue-specific syntax for the link prop. this.dsid is the dataset page's ID.
`html`
:link.prop="this.dsid"
additional-type="[your dataset type]"
orcid-client-id="[your ORCID client ID]"
/>
NOTE: If the widget is to be run in read-only mode, you can omit the orcid-client-id.
#### React
In App.js, import the widget:
`javascript`
import { applyPolyfills, defineCustomElements } from 'throughput-widget/loader';
applyPolyfills().then(() => {
defineCustomElements();
});
Add the widget to your dataset template, and pass in props. Note the React-specific syntax for the link prop. dsid is the dataset page's ID.
`html`
link={dsid}
additional-type="[your dataset type]"
orcid-client-id="[your ORCID client ID]"
/>
#### Angular
In app.module.ts, add CUSTOM_ELEMENTS_SCHEMA to the imports from @angular/core, then include it in AppModule's schemas list. Repeat for other modules that use the widget.
`javascript
// ...
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core'; // import CUSTOM_ELEMENTS_SCHEMA
@NgModule({
// ...
schemas: [CUSTOM_ELEMENTS_SCHEMA] // add CUSTOM_ELEMENTS_SCHEMA to AppModule and other modules using the widget
})
export class AppModule { }
`
In main.ts, import and call defineCustomElements():
`javascript
// ...
import { defineCustomElements } from 'throughput-widget/loader';
// ...
defineCustomElements();
`
Add the widget to your dataset template, and pass in props. Note the Angular-specific syntax for the link prop. dsid is the dataset page's ID.
`html`
link="{{ dsid }}"
additional-type="[your dataset type]"
orcid-client-id="[your ORCID client ID]"
>
#### Static HTML
Add the imported tag to your dataset page(s):
`html`
link="[your dataset ID]"
additional-type="[your dataset type]"
orcid-client-id="[your ORCID client ID]"
>
These currently include:
`CSS`
--badge-background-color
--badge-border-color
--badge-font-color
--modal-background-color
--modal-font-color
--modal-card-color
--widget-font-family
They can be added to your site's CSS like so: css`
throughput-widget {
--badge-background-color: red;
}
The widget pulls annotations from the Throughput Annotation Database using the Annotation API. Annotations are added by individuals, or through scripted workflows and are searchable using the API.
Once a user authenticates through ORCID, the widget can be used to annotate a dataset. These annotations are maintained on Throughput, but can be accessed by any individual.
This project is to be evaluated using the following metrics:
* COMPLETE -- Active npm registry page.
* Download activity for the npm` module
* Number of data services using the Throughput widget
* Number of annotations added using the widget
