1.6.0 • Published 3 months ago

@genesys-pgr/ui-embedded v1.6.0

Weekly downloads
16
License
Apache-2.0
Repository
gitlab
Last release
3 months ago

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

<script src="https://cdn.jsdelivr.net/npm/@genesys-pgr/ui-embedded/dist/genesys-deps.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@genesys-pgr/ui-embedded/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/dist/genesys-deps.css" />

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

<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
      overviews: {
        'aegis': false, // Don't display the AEGIS Overview
      }
    },
    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
      },
    },
    i18n: {
      en: {
        translations: {
          // No customizations
        }
      },
      es: {
        translations: {
          // No customizations
        }
      }
    }
  };

  // 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:

PropertyDefaultDescription
apiUrlhttps://api.sandbox.genesys-pgr.orgProduction Genesys API is at https://api.genesys-pgr.orgSandbox API is at https://api.sandbox.genesys-pgr.org
clientIdRequiredPlease contact helpdesk@genesys-pgr.org to obtain API keys for use in your environment.The API keys are limited to your website and will not work on a different domain.
clientSecretRequiredDitto.
filterundefinedAllows for narrowing the scope of requested accession data from Genesys API. 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.
languageenSpecify the language of the user interface.Fully supported: en, zh-TWPartially supported: es
i18n{ ... }See Customizing translations
titleGenesys: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):

PropertyDefaultDescription
subsetstrueDisplay the list of subsets on accession details page
datasetstrueDisplay the list of C&E datasets on accession details page
pdcitrueDisplay passport data completeness index (PDCI) information on accession details page
overviews{ ... }Allows for disabling individual sections in the display of Overviews

Disabling individual Overview sections

The Overviews sections display the number of accessions by different categories. The following categories are available and enabled by default:

OverviewEnabledDescription
institute.codefalseNumber of accessions by FAO Institute Code of the holding genebank
institute.country.code3falseNumber of accessions by the country of the holding genebank
cropNametrueCrop name as submitted to Genesys
crop.shortNametrueGenesys crop
sampStattrueBiological status of accession
taxonomy.genustrueGenus name
taxonomy.genusSpeciestrueSpecies name
taxonomy.grinTaxonomySpecies.nametrueSpecies name according to GRIN-Taxonomy (auto-detected by Genesys)
taxonomy.currentTaxonomySpecies.nametrueThe current species name according to GRIN-Taxonomy
countryOfOrigin.code3trueCountry of origin
donorCodetrueFAO WIEWS Institute code of the accession donor institute
mlsStatustrueAccession status in the Multi-lateral System of the ITPGRFA
availabletrueAccession availability
duplSitetrueFAO WIEWS Institute code where accessions are safety-duplicated
storagetrueType of germplasm storage
breederCodetrueFAO WIEWS Insitute code of the institute that bred the material
aegisfalseStatus of accession in European AEGIS network
sgsvtrueAccessions safety-backed up in Svalbard Global Seed Vault

To disable the AEGIS and Institute code sections in the Overviews, the update your config to include:

const genesysConfig = {
    ..., // other configuration options
    accession: {
      ... // other accession options
      overviews: {
        'aegis': false, // Don't display the AEGIS Overview
        'institute.code': false, // Exclude summary by FAO Institude Code
      },
    },
    ... // other configuration
}

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:

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

PropertyDefaultDescription
enabledfalseToggle map functionality
height'400px'Height of the map of accessions (use a CSS expression)
baseMap{ url: ..., attribution: ... }See url and attribution below.
baseMap.urlWorld_Light_Gray_BaseTile server template URL for the base map layer.
baseMap.attributionTiles © ...Map base layer attribution

Translating Embedded Genesys

Embedded Genesys is developed in English. The en/translations.json lists all labels currently in use by the library. The library is translated by friends in our community members to other languages, listed in src/locales.

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!

Customizing translations

It is possible that the translations bundled with the library do not match your needs. You may customize translations of individual labels by listing them in the i18n property of the genesysConfig.

const genesysConfig = {
  i18n: {
    es: { // customizations for Spanish labels
      translations: { // 'translations' is mandatory
        "pagetitle": {
          "accessionList": "Accesiones" // customize the translation of 'pagetitle.accessionList'
        }
      }
    }
}

Note: the complete list of labels is available in en/translations.json.

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.