{"id":26662900,"url":"https://github.com/speciesfilegroup/distinguish","last_synced_at":"2025-06-29T21:40:39.370Z","repository":{"id":144428995,"uuid":"473758994","full_name":"SpeciesFileGroup/distinguish","owner":"SpeciesFileGroup","description":"Interactive key engine that feeds off of TaxonWorks API","archived":false,"fork":false,"pushed_at":"2023-03-01T19:59:37.000Z","size":277,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-04-14T07:50:26.097Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SpeciesFileGroup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-03-24T20:12:22.000Z","updated_at":"2024-04-14T07:50:26.098Z","dependencies_parsed_at":null,"dependency_job_id":"57784e37-0465-477d-a7dc-5154c0e7a73a","html_url":"https://github.com/SpeciesFileGroup/distinguish","commit_stats":{"total_commits":77,"total_committers":3,"mean_commits":"25.666666666666668","dds":"0.11688311688311692","last_synced_commit":"c2b5a2b87165275b89c820a5de72e816e0443b96"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpeciesFileGroup%2Fdistinguish","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpeciesFileGroup%2Fdistinguish/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpeciesFileGroup%2Fdistinguish/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpeciesFileGroup%2Fdistinguish/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SpeciesFileGroup","download_url":"https://codeload.github.com/SpeciesFileGroup/distinguish/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245476707,"owners_count":20621699,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-25T14:18:52.142Z","updated_at":"2025-03-25T14:18:52.614Z","avatar_url":"https://github.com/SpeciesFileGroup.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# distinguish\n\nAn 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.\n\n## Quick start\n\nSee [Example page](#example-page).\n\n## Details\n\nInteractive 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.\n\n## Features\n\n- Figure descriptors and observations.\n- Multi-language support.\n- Filter by tagged set.\n- Filter by rank (e.g. \"Family\" or \"Genus\").\n- Qualitative, quantitative descriptors.\n- Local (file in your browser) or server-based (both require internet access).\n\n## Technical\n\nDistinguish is a javascript package. All functionality is driven from a single, parameterized API call.\n\n## Install\n\n### Package manager\n\nYou can install the latest version with the npm CLI command:\n\n```bash\nnpm install @sfgrp/distinguish vue pinia\n```\n\nAs an alternative you can use the Yarn CLI command:\n\n```bash\nyarn add @sfgrp/distinguish vue pinia\n```\n\n### CDN\n\nYou can copy and paste the following tags into your HTML file.\n\n```html\n\u003cscript src=\"https://unpkg.com/vue/dist/vue.global.prod.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://unpkg.com/vue-demi\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://unpkg.com/pinia\"\u003e\u003c/script\u003e\n\u003clink\n  rel=\"stylesheet\"\n  href=\"https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/style.min.css\"\n/\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/distinguish.umd.min.js\"\u003e\u003c/script\u003e\n```\n\n## Usage\n\nThere 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.\n\n### Declarative\n\nAdd `data-interactive-key=\"true\"` attribute to input elements to initialize it.\nTo pass the options you need to add the prefix `data-` and write the option in kebab-case, like the following example:\n\n```html\n\u003cdiv\n  data-interactive-key=\"true\"\n  data-observation-matrix-id=\"1\"\n  data-project-token=\"xQ9bKrhfQtHYfro9t6YY0A\"\n  data-base-url=\"https://sfg.taxonworks.org/api/v1\"\n\u003e\u003c/div\u003e\n```\n\n### Imperative\n\nYou can initialize it by `createInteractiveKey` function\n\n```html\n\u003cdiv id=\"interactive-key\"\u003e\u003c/div\u003e\n```\n\n```javascript\nimport { createInteractiveKey } from '@sfgrp/distinguish'\nimport '@sfgrp/distinguish/dist/style.css'\n\nconst app = createInteractiveKey('#interactive-key', options)\n```\n\n### Options object\n\n```javascript\n{\n  observationMatrixId: '',      // Observation matrix ID\n  apiConfig: {\n    baseURL: '',                // URL API, e.g https://sfg.taxonworks.org/api/v1\n    csrfToken: '',              // CSRF Token. Don't use it with authentification API params.\n    projectId: '',              // Project ID. Don't use it with projectToken.\n    userToken: '',              // User Token. Don't use it with projectToken and csrfToken.\n    projectToken: ''            // Project token. Don't use it with projectId and userToken.\n  }\n}\n```\n\n### Example page\n\nThis uses the [CDN](#cdn) and [Declarative](#declarative) approach.\n\n- Copy the text below into a file called `index.html`.\n- Configure the `data-` options to point to your key.\n- Open that file in your browser.\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n  \u003chead\u003e\n    \u003cmeta charset=\"UTF-8\" /\u003e\n    \u003clink\n      rel=\"stylesheet\"\n      href=\"https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/style.min.css\"\n    /\u003e\n    \u003cmeta\n      name=\"viewport\"\n      content=\"width=device-width, initial-scale=1.0\"\n    /\u003e\n    \u003cstyle\u003e\n      body {\n        margin: 0;\n      }\n      .standalone-app {\n        height: 100vh;\n      }\n    \u003c/style\u003e\n    \u003ctitle\u003eDistinguish\u003c/title\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003cdiv\n      class=\"standalone-app\"\n      data-interactive-key=\"true\"\n      data-observation-matrix-id=\"1\"\n      data-project-token=\"yourprojecttoken\"\n      data-base-url=\"https://\u003cyour.taxonworks.server\u003e/api/v1\"\n    \u003e\u003c/div\u003e\n    \u003cscript src=\"https://unpkg.com/vue/dist/vue.global.prod.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"https://unpkg.com/vue-demi\"\u003e\u003c/script\u003e\n    \u003cscript src=\"https://unpkg.com/pinia\"\u003e\u003c/script\u003e\n    \u003cscript src=\"https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/distinguish.umd.min.js\"\u003e\u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### Deploying a key on-line\n\n[GitHub Pages](https://pages.github.com/) is perhaps the quickest way to deploy your key if you don't have access to your own server.\n\n- Follow instructions above to setup your repository.\n- Add a page to that repository that looks like the [example page](#example-page).\n\n### Troubleshooting\n\nIf nothing loads (blank page):\n\n- Open your Browser's development tools console panel. Reload the page. Errors will appear in red.\n\nIf when loaded or during use you see:\n\n- `Request failed with status code 401` - The API configuration parameters are incorrect\n- `Request failed with status code 404` - The API URL path or Token is incorrect (the base of the API URL is correct)\n- `Network error` - The key can not connect to the internet\n\n## Building a key (in TaxonWorks)\n\nDistinguish 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](https://docs.taxonworks.org/guide/start-a-project.html#finding-a-collaborating-provider), or [install your own instance](https://github.com/SpeciesFileGroup/install_taxonworks). Need help? [Chat on Gitter](https://gitter.im/SpeciesFileGroup/taxonworks) or [join a TaxonWorks event](https://speciesfilegroup.org/events.html).\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nDistinguish is open source and is presently available under the [University of Illinois/NCSA Open Source License](https://en.wikipedia.org/wiki/University_of_Illinois/NCSA_Open_Source_License).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeciesfilegroup%2Fdistinguish","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspeciesfilegroup%2Fdistinguish","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeciesfilegroup%2Fdistinguish/lists"}