npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@sfgrp/distinguish

v0.4.0

Published

An interactive key engine that feeds off of [TaxonWorks](https://taxonworks.org)' [API](https://api.taxonworks.org). Distinguish is a product of the [Species File Group](https://speciesfilegroup.org) and its collaborators.

Downloads

138

Readme

distinguish

An interactive key engine that feeds off of TaxonWorks' API. Distinguish is a product of the Species File Group and its collaborators.

Quick start

See Example page.

Details

Interactive keys are tools used by taxonomists and others to diagnosis or seperate one taxon (e.g. a species) from others. Distinguish provides an embedable, web-based, interactive key interface. The key uses logic (the "engine") and data managed in an instance of TaxonWorks. Keys can served locally (e.g. by opening a file in your browser) or on websites. They require an internet connection.

Features

  • Figure descriptors and observations.
  • Multi-language support.
  • Filter by tagged set.
  • Filter by rank (e.g. "Family" or "Genus").
  • Qualitative, quantitative descriptors.
  • Local (file in your browser) or server-based (both require internet access).

Technical

Distinguish is a javascript package. All functionality is driven from a single, parameterized API call.

Install

Package manager

You can install the latest version with the npm CLI command:

npm install @sfgrp/distinguish vue pinia

As an alternative you can use the Yarn CLI command:

yarn add @sfgrp/distinguish vue pinia

CDN

You can copy and paste the following tags into your HTML file.

<script src="https://unpkg.com/vue/dist/vue.global.prod.js"></script>
<script src="https://unpkg.com/vue-demi"></script>
<script src="https://unpkg.com/pinia"></script>
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/style.min.css"
/>
<script src="https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/distinguish.umd.min.js"></script>

Usage

There are two ways to setup Interactive Keys. The easiest way is to let InteractiveKey auto discover your inputs automatically. For that, you simply need to provide a data attribute on your element.

Declarative

Add data-interactive-key="true" attribute to input elements to initialize it. To pass the options you need to add the prefix data- and write the option in kebab-case, like the following example:

<div
  data-interactive-key="true"
  data-observation-matrix-id="1"
  data-project-token="xQ9bKrhfQtHYfro9t6YY0A"
  data-base-url="https://sfg.taxonworks.org/api/v1"
></div>

Imperative

You can initialize it by createInteractiveKey function

<div id="interactive-key"></div>
import { createInteractiveKey } from '@sfgrp/distinguish'
import '@sfgrp/distinguish/dist/style.css'

const app = createInteractiveKey('#interactive-key', options)

Options object

{
  observationMatrixId: '',      // Observation matrix ID
  apiConfig: {
    baseURL: '',                // URL API, e.g https://sfg.taxonworks.org/api/v1
    csrfToken: '',              // CSRF Token. Don't use it with authentification API params.
    projectId: '',              // Project ID. Don't use it with projectToken.
    userToken: '',              // User Token. Don't use it with projectToken and csrfToken.
    projectToken: ''            // Project token. Don't use it with projectId and userToken.
  }
}

Example page

This uses the CDN and Declarative approach.

  • Copy the text below into a file called index.html.
  • Configure the data- options to point to your key.
  • Open that file in your browser.
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/style.min.css"
    />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0"
    />
    <style>
      body {
        margin: 0;
      }
      .standalone-app {
        height: 100vh;
      }
    </style>
    <title>Distinguish</title>
  </head>
  <body>
    <div
      class="standalone-app"
      data-interactive-key="true"
      data-observation-matrix-id="1"
      data-project-token="yourprojecttoken"
      data-base-url="https://<your.taxonworks.server>/api/v1"
    ></div>
    <script src="https://unpkg.com/vue/dist/vue.global.prod.js"></script>
    <script src="https://unpkg.com/vue-demi"></script>
    <script src="https://unpkg.com/pinia"></script>
    <script src="https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/distinguish.umd.min.js"></script>
  </body>
</html>

Deploying a key on-line

GitHub Pages is perhaps the quickest way to deploy your key if you don't have access to your own server.

  • Follow instructions above to setup your repository.
  • Add a page to that repository that looks like the example page.

Troubleshooting

If nothing loads (blank page):

  • Open your Browser's development tools console panel. Reload the page. Errors will appear in red.

If when loaded or during use you see:

  • Request failed with status code 401 - The API configuration parameters are incorrect
  • Request failed with status code 404 - The API URL path or Token is incorrect (the base of the API URL is correct)
  • Network error - The key can not connect to the internet

Building a key (in TaxonWorks)

Distinguish is based of interfaces available inside TaxonWorks. Those interfaces have many additional features facilitating the addition and management of images, curation, annotations, expansion, and editing of the underlying data. To start editing a key find a TaxonWorks provider, or install your own instance. Need help? Chat on Gitter or join a TaxonWorks event.

Contributing

See CONTRIBUTING.md.

License

Distinguish is open source and is presently available under the University of Illinois/NCSA Open Source License.