# distinguish 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. ## Quick start See [Example page](#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 node module. All functionality is driven from a single, parameterized API call. ## Install ### Package manager You can install the latest version with the npm CLI command: ```bash npm install @sfgrp/distinguish ``` As an alternative you can use the Yarn CLI command: ```bash yarn add @sfgrp/distinguish ``` ### CDN You can copy and paste the following tags into your HTML file. ```html ``` ## 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: ```html
``` ### Imperative You can initialize it by `createInteractiveKey` function ```html ``` ```javascript import { createInteractiveKey } from '@sfgrp/distinguish' import '@sfgrp/distinguish/dist/style.css' const app = createInteractiveKey('#interactive-key', options) ``` ### Options object ```javascript { 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](#cdn) and [Declarative](#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. ```html