README.md

# Enhance your website with data from Genesys

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!

Explore the demo at https://genesys-pgr.p.gitlab.croptrust.org/ui-embedded/

## Quickstart

Add Javascript dependencies to your page:

```html
<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>

<!-- Recommended: Bootstrap CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@4.5.3/dist/css/bootstrap.min.css" />
<!-- Genesys UI CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@genesys-pgr/ui-embedded@1.1.0-alpha5/dist/genesys-deps.css" />
```

Add a container `<div>` to your HTML page and initialize the Genesys UI with the `<script>`:

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

<script type="text/javascript">
  // Detect language from query string
  const queryLang = document.location.search && document.location.search.substr(1) || undefined;

  // Embedded Genesys configuration
  const genesysConfig = {
    apiUrl: 'https://api.sandbox.genesys-pgr.org', // Genesys API server
    clientId: 'clientid@genesys', // Client ID
    clientKey: 'changeme', // Client key
    title: 'Genesys:', // HTML title prefix
    language: queryLang, // Use URL query string to use the "detected" language (see above), or specify a constant: 'en', 'es', 'zh-TW'
    filter: { 
      institute: {  code: [ 'ETH013' ] }, // Genesys data filter
    },
    accession: {
      pdci: true, // Show PDCI
      subsets: true, // Show list of subsets
      datasets: true, // Show list of datasets
    },
    shoppingCart: {
      enabled: true, // Enable shopping cart
    },
    captchaSiteKey: '<public key for your site>', // Your hCaptcha site key from https://dashboard.hcaptcha.com
    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
      },
    }
  };

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

  // Or, to display ONLY "Collection Overview" use:
  // genesys.showOverview(document.getElementById('genesys-container'), genesysConfig);
</script>
```

**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. 


# Configuration options

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


|Property|Default|Description|
|---|---|---|
|`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 |
|`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. |
|`language`|*en*| Specify the language of the user interface.<br />Fully supported: `en`, `zh-TW`<br />Partially supported: `es` |
|`title`| *Genesys:* | HTML page title prefix |
| `accession` | `{ ... }` | See *Accession* configuration options |
| `shoppingCart` | `{ ... }` | See *Shopping cart* configuration options |
| `map` | `{ ... }` | See *Map* configuration |

Additional configuration options are described below.

## 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 |


## Shopping cart and captcha options

The shopping cart is **disabled by default**. 

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
const genesysConfig = {
  captchaSiteKey: '<public key for your site>', // Your hCaptcha site key from https://dashboard.hcaptcha.com
  shoppingCart: {
    enabled: true, // Enable shopping cart
  },
};
```

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

**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

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 |
|`height`|`'400px'`| Height of the map of accessions (use a CSS expression) |
|`baseMap`|`{ url: ..., attribution: ... }`| See `url` and `attribution` below. |
|`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. |

# 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.