README.md 7.22 KB
Newer Older
Matija Obreza's avatar
Matija Obreza committed
1
2
3

# Enhance your website with data from Genesys

Matija Obreza's avatar
Matija Obreza committed
4
5
6
Genesys is an openly accessible database on **plant genetic resources** maintained in **genebanks** around the world. This package allows for embedding data from [Genesys](https://www.genesys-pgr.org) into your website.

Instead of hosting and maintaining a separate database, web server and domain name, use **Embedded Genesys** to integrate your genebank collection data directly into the institutional website!
Matija Obreza's avatar
Matija Obreza committed
7

Matija Obreza's avatar
Matija Obreza committed
8
Explore the demo at https://genesys-pgr.p.gitlab.croptrust.org/ui-embedded/
9

Matija Obreza's avatar
Matija Obreza committed
10
## Quickstart
11

Matija Obreza's avatar
Matija Obreza committed
12
Add Javascript dependencies to your page:
Matija Obreza's avatar
Matija Obreza committed
13
14

```html
Matija Obreza's avatar
Matija Obreza committed
15
16
<script src="https://cdn.jsdelivr.net/npm/@genesys-pgr/ui-embedded@1.1.0-alpha5/dist/genesys-deps.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@genesys-pgr/ui-embedded@1.1.0-alpha5/dist/genesys-ui.js"></script>
Matija Obreza's avatar
Matija Obreza committed
17
18

<!-- Recommended: Bootstrap CSS -->
Matija Obreza's avatar
Matija Obreza committed
19
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@4.5.3/dist/css/bootstrap.min.css" />
Matija Obreza's avatar
Matija Obreza committed
20
<!-- Genesys UI CSS -->
Matija Obreza's avatar
Matija Obreza committed
21
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@genesys-pgr/ui-embedded@1.1.0-alpha5/dist/genesys-deps.css" />
Matija Obreza's avatar
Matija Obreza committed
22
23
```

Matija Obreza's avatar
Matija Obreza committed
24
Add a container `<div>` to your HTML page and initialize the Genesys UI with the `<script>`:
Matija Obreza's avatar
Matija Obreza committed
25
26

```html
27
28
29
<div class="container-fluid mb-5" id="genesys-container"></div>

<script type="text/javascript">
Matija Obreza's avatar
Matija Obreza committed
30
31
32
  // Detect language from query string
  const queryLang = document.location.search && document.location.search.substr(1) || undefined;

33
34
35
36
37
  // Embedded Genesys configuration
  const genesysConfig = {
    apiUrl: 'https://api.sandbox.genesys-pgr.org', // Genesys API server
    clientId: 'clientid@genesys', // Client ID
    clientKey: 'changeme', // Client key
Matija Obreza's avatar
Matija Obreza committed
38
    title: 'Genesys:', // HTML title prefix
Matija Obreza's avatar
Matija Obreza committed
39
    language: queryLang, // Use URL query string to use the "detected" language (see above), or specify a constant: 'en', 'es', 'zh-TW'
40
41
42
    filter: { 
      institute: {  code: [ 'ETH013' ] }, // Genesys data filter
    },
Matija Obreza's avatar
Matija Obreza committed
43
44
45
46
47
    accession: {
      pdci: true, // Show PDCI
      subsets: true, // Show list of subsets
      datasets: true, // Show list of datasets
    },
48
49
    shoppingCart: {
      enabled: true, // Enable shopping cart
50
    },
Matija Obreza's avatar
Matija Obreza committed
51
    captchaSiteKey: '<public key for your site>', // Your hCaptcha site key from https://dashboard.hcaptcha.com
Oleksii Savran's avatar
Oleksii Savran committed
52
53
54
55
56
57
58
    map: {
      enabled: true, // Enable map
      baseMap: {
        url: 'https://server.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Base/MapServer/tile/{z}/{y}/{x}/', // tile server url for the base layer
        attribution: 'Tiles &copy; Esri &mdash; Esri, DeLorme, NAVTEQ' // attribution data
      },
    }
59
60
61
62
63
64
65
66
  };

  // Show UI
  genesys.showGenesysUI(document.getElementById('genesys-container'), genesysConfig);

  // Or, to display ONLY "Collection Overview" use:
  // genesys.showOverview(document.getElementById('genesys-container'), genesysConfig);
</script>
Matija Obreza's avatar
Matija Obreza committed
67
68
```

Matija Obreza's avatar
Matija Obreza committed
69
70
71
**Note:** Please see available configuration options in the *Configuration options* section below.

**Note:** Any website that uses the Genesys API must be registered. Please contact helpdesk@genesys-pgr.org to obtain API keys for use in your environment. 
Matija Obreza's avatar
Matija Obreza committed
72

Matija Obreza's avatar
Matija Obreza committed
73
74

# Configuration options
Matija Obreza's avatar
Matija Obreza committed
75
76
77
78
79
80
81

The `genesysConfig` argument to `showGenesysUI()` is a simple map of various settings you can pass 
to *@geneesys-pgr/ui-embedded*:


|Property|Default|Description|
|---|---|---|
Matija Obreza's avatar
Matija Obreza committed
82
|`apiUrl`       | *https://api.sandbox.genesys-pgr.org* | Production Genesys API is at https://api.genesys-pgr.org<br />Sandbox API is at https://api.sandbox.genesys-pgr.org |
Matija Obreza's avatar
Matija Obreza committed
83
84
85
|`clientId`     | **Required** | Please contact helpdesk@genesys-pgr.org to obtain API keys for use in your environment.<br />The API keys are limited to your website and will not work on a different domain. |
|`clientSecret` | **Required** | Ditto. |
|`filter`       |`undefined` | Allows for narrowing the scope of requested accession data from Genesys API. <br />To filter for accessions from your genebank, use: `{ institute: { code: ['XXX000'] } }` with the FAO WIEWS Code of your genebank. Default `undefined` value will return all accessions. |
Matija Obreza's avatar
Matija Obreza committed
86
|`language`|*en*| Specify the language of the user interface.<br />Fully supported: `en`, `zh-TW`<br />Partially supported: `es` |
Matija Obreza's avatar
Matija Obreza committed
87
|`title`| *Genesys:* | HTML page title prefix |
Matija Obreza's avatar
Matija Obreza committed
88
89
| `accession` | `{ ... }` | See *Accession* configuration options |
| `shoppingCart` | `{ ... }` | See *Shopping cart* configuration options |
Oleksii Savran's avatar
Oleksii Savran committed
90
| `map` | `{ ... }` | See *Map* configuration |
91
92
93

Additional configuration options are described below.

Matija Obreza's avatar
Matija Obreza committed
94
95
96
97
98
99
100
101
102
103
104
## Accession options

Features can be toggled by setting corresponding property **on** (set to `true`) or **off** (`false`):

|Property|Default|Description|
|---|---|---|
|`subsets`|`true`| Display the list of **subsets** on accession details page |
|`datasets`|`true`| Display the list of C&E **datasets** on accession details page |
|`pdci`|`true`| Display passport data completeness index (PDCI) information on accession details page |


Matija Obreza's avatar
Matija Obreza committed
105
## Shopping cart and captcha options
106

Matija Obreza's avatar
Matija Obreza committed
107
The shopping cart is **disabled by default**. 
108

Matija Obreza's avatar
Matija Obreza committed
109
110
111
To allow users to add accessions to the cart, access the cart and submit requests for material you must explicity enable the shopping cart and specify the captcha site key in your configuration:

```js
112
const genesysConfig = {
Matija Obreza's avatar
Matija Obreza committed
113
  captchaSiteKey: '<public key for your site>', // Your hCaptcha site key from https://dashboard.hcaptcha.com
114
  shoppingCart: {
Matija Obreza's avatar
Matija Obreza committed
115
    enabled: true, // Enable shopping cart
116
117
118
119
120
121
122
123
  },
};
```

|Property|Default|Description|
|---|---|---|
|`enabled`|`false`| Toggle Shopping cart functionality |

Matija Obreza's avatar
Matija Obreza committed
124
125
126
127
128
129
**Note:** The request for material form includes an **hCaptcha** check. Valid public and private keys for your **hCaptcha** account must be registered with Genesys. Please contact helpdesk@genesys-pgr.org for support.

When `captchaSiteKey` is missing, the **Shopping cart** functionality is automatically disabled.


## Map configuration
Oleksii Savran's avatar
Oleksii Savran committed
130
131
132
133
134
135

The map is **disabled by default**. To allow users to see map of accession collecting site on accession details page and access the map page you must explicity enable it in your configuration and provide a tile server URL and an attribution data for the base map layer:

|Property|Default|Description|
|---|---|---|
|`enabled`|`false`| Toggle map functionality |
136
137
|`height`|`'400px'`| Height of the map of accessions (use a CSS expression) |
|`baseMap`|`{ url: ..., attribution: ... }`| See `url` and `attribution` below. |
Matija Obreza's avatar
Matija Obreza committed
138
139
|`baseMap.url`|[World_Light_Gray_Base](https://server.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Light_Gray_Base/MapServer/tile/{z}/{y}/{x}/)| Tile server template URL for the base map layer. |
|`baseMap.attribution`|Tiles &copy; ...| Map base layer attribution. |
Oleksii Savran's avatar
Oleksii Savran committed
140

Matija Obreza's avatar
Matija Obreza committed
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
# Translating Embedded Genesys

Help us make *Embedded Genesys* available in your language or improve the current translations at
**https://www.transifex.com/crop-trust/embedded-genesys/content/**

We welcome your contributions!


# License and Disclaimer

This software is licensed under the Apache License, Version 2.0 (the "License").

You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.