@sfgrp/distinguish 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +70 -29
  2. package/dist/distinguish.es.js +2631 -8168
  3. package/dist/distinguish.umd.js +6 -50
  4. package/dist/style.css +1 -1
  5. package/package.json +22 -22
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # distinguish
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
5
  ## Quick start
6
6
 
@@ -8,43 +8,54 @@ See [Example page](#example-page).
8
8
 
9
9
  ## Details
10
10
 
11
- 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.
11
+ 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.
12
12
 
13
13
  ## Features
14
14
 
15
- * Figure descriptors and observations.
16
- * Multi-language support.
17
- * Filter by tagged set.
18
- * Filter by rank (e.g. "Family" or "Genus").
19
- * Qualitative, quantitative descriptors.
20
- * Local (file in your browser) or server-based (both require internet access).
15
+ - Figure descriptors and observations.
16
+ - Multi-language support.
17
+ - Filter by tagged set.
18
+ - Filter by rank (e.g. "Family" or "Genus").
19
+ - Qualitative, quantitative descriptors.
20
+ - Local (file in your browser) or server-based (both require internet access).
21
21
 
22
22
  ## Technical
23
23
 
24
- Distinguish is a node module. All functionality is driven from a single, parameterized API call.
24
+ Distinguish is a javascript package. All functionality is driven from a single, parameterized API call.
25
25
 
26
26
  ## Install
27
27
 
28
28
  ### Package manager
29
+
29
30
  You can install the latest version with the npm CLI command:
30
31
 
31
32
  ```bash
32
- npm install @sfgrp/distinguish
33
+ npm install @sfgrp/distinguish vue pinia
33
34
  ```
35
+
34
36
  As an alternative you can use the Yarn CLI command:
37
+
35
38
  ```bash
36
- yarn add @sfgrp/distinguish
39
+ yarn add @sfgrp/distinguish vue pinia
37
40
  ```
38
41
 
39
42
  ### CDN
43
+
40
44
  You can copy and paste the following tags into your HTML file.
41
45
 
42
46
  ```html
43
- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/style.min.css">
47
+ <script src="https://unpkg.com/vue/dist/vue.global.prod.js"></script>
48
+ <script src="https://unpkg.com/vue-demi"></script>
49
+ <script src="https://unpkg.com/pinia"></script>
50
+ <link
51
+ rel="stylesheet"
52
+ href="https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/style.min.css"
53
+ />
44
54
  <script src="https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/distinguish.umd.min.js"></script>
45
55
  ```
46
56
 
47
57
  ## Usage
58
+
48
59
  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.
49
60
 
50
61
  ### Declarative
@@ -53,7 +64,7 @@ Add `data-interactive-key="true"` attribute to input elements to initialize it.
53
64
  To pass the options you need to add the prefix `data-` and write the option in kebab-case, like the following example:
54
65
 
55
66
  ```html
56
- <div
67
+ <div
57
68
  data-interactive-key="true"
58
69
  data-observation-matrix-id="1"
59
70
  data-project-token="xQ9bKrhfQtHYfro9t6YY0A"
@@ -62,11 +73,13 @@ To pass the options you need to add the prefix `data-` and write the option in k
62
73
  ```
63
74
 
64
75
  ### Imperative
76
+
65
77
  You can initialize it by `createInteractiveKey` function
66
78
 
67
79
  ```html
68
80
  <div id="interactive-key"></div>
69
81
  ```
82
+
70
83
  ```javascript
71
84
  import { createInteractiveKey } from '@sfgrp/distinguish'
72
85
  import '@sfgrp/distinguish/dist/style.css'
@@ -75,6 +88,7 @@ const app = createInteractiveKey('#interactive-key', options)
75
88
  ```
76
89
 
77
90
  ### Options object
91
+
78
92
  ```javascript
79
93
  {
80
94
  observationMatrixId: '', // Observation matrix ID
@@ -87,54 +101,81 @@ const app = createInteractiveKey('#interactive-key', options)
87
101
  }
88
102
  }
89
103
  ```
104
+
90
105
  ### Example page
106
+
91
107
  This uses the [CDN](#cdn) and [Declarative](#declarative) approach.
92
- * Copy the text below into a file called `index.html`.
93
- * Configure the `data-` options to point to your key.
94
- * Open that file in your browser.
108
+
109
+ - Copy the text below into a file called `index.html`.
110
+ - Configure the `data-` options to point to your key.
111
+ - Open that file in your browser.
95
112
 
96
113
  ```html
97
114
  <!DOCTYPE html>
98
115
  <html lang="en">
99
116
  <head>
100
117
  <meta charset="UTF-8" />
101
- <link rel="icon" href="/favicon.ico" />
102
- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/style.min.css" />
103
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
118
+ <link
119
+ rel="stylesheet"
120
+ href="https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/style.min.css"
121
+ />
122
+ <meta
123
+ name="viewport"
124
+ content="width=device-width, initial-scale=1.0"
125
+ />
126
+ <style>
127
+ body {
128
+ margin: 0;
129
+ }
130
+ .standalone-app {
131
+ height: 100vh;
132
+ }
133
+ </style>
104
134
  <title>Distinguish</title>
105
135
  </head>
106
136
  <body>
107
- <div
137
+ <div
138
+ class="standalone-app"
108
139
  data-interactive-key="true"
109
140
  data-observation-matrix-id="1"
110
141
  data-project-token="yourprojecttoken"
111
142
  data-base-url="https://<your.taxonworks.server>/api/v1"
112
143
  ></div>
144
+ <script src="https://unpkg.com/vue/dist/vue.global.prod.js"></script>
145
+ <script src="https://unpkg.com/vue-demi"></script>
146
+ <script src="https://unpkg.com/pinia"></script>
113
147
  <script src="https://cdn.jsdelivr.net/npm/@sfgrp/distinguish@latest/dist/distinguish.umd.min.js"></script>
114
148
  </body>
115
149
  </html>
116
150
  ```
117
151
 
118
152
  ### Deploying a key on-line
153
+
119
154
  [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.
120
- * Follow instructions above to setup your repository.
121
- * Add a page to that repository that looks like the [example page](#example-page).
155
+
156
+ - Follow instructions above to setup your repository.
157
+ - Add a page to that repository that looks like the [example page](#example-page).
122
158
 
123
159
  ### Troubleshooting
160
+
124
161
  If nothing loads (blank page):
125
- * Open your Browser's development tools console panel. Reload the page. Errors will appear in red.
126
162
 
127
- If when loaded or during use you see:
128
- * `Request failed with status code 401` - The API configuration parameters are incorrect
129
- * `Request failed with status code 404` - The API URL path or Token is incorrect (the base of the API URL is correct)
130
- * `Network error` - The key can not connect to the internet
163
+ - Open your Browser's development tools console panel. Reload the page. Errors will appear in red.
131
164
 
165
+ If when loaded or during use you see:
166
+
167
+ - `Request failed with status code 401` - The API configuration parameters are incorrect
168
+ - `Request failed with status code 404` - The API URL path or Token is incorrect (the base of the API URL is correct)
169
+ - `Network error` - The key can not connect to the internet
132
170
 
133
171
  ## Building a key (in TaxonWorks)
134
- 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](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).
172
+
173
+ 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](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).
135
174
 
136
175
  ## Contributing
176
+
137
177
  See [CONTRIBUTING.md](CONTRIBUTING.md).
138
178
 
139
- ## Lisence
179
+ ## License
180
+
140
181
  Distinguish 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).