Skip to content

Latest commit

 

History

History
96 lines (73 loc) · 4.55 KB

README.md

File metadata and controls

96 lines (73 loc) · 4.55 KB
Raw

XRAS User Interface Components

User interface components for XRAS implemented in JavaScript using React.

Resource Catalog

This component provides a user interface to browse available Resources and their features, with the ability to filter the list for easier browsing.

Example

<div id="resource-catalog-react"></div>
<script type="module">
  import { resourceCatalog } from "https://esm.sh/@xras/[email protected]?exports=resourceCatalog";
  resourceCatalog({
    apiUrl: "/path/to/catalog.json",
    allowedCategories: [],
    allowedFilters: [],
    excludedCategories: [],
    excludedFilters: [],
    target: document.getElementById("resource-catalog-react"),
  });
</script>

Options

Option Values Required
apiUrl The URL for your Resource Catalog True
allowedCategories A list of filter categories that you want displayed. Ex: ["Resource Type", "Specialized Hardware"] False
allowedFilters A list of filters you want users to see. Ex: ["GPU Compute"] False
excludedCategories A list of filter categories that you want hidden from users. Ex: ["Specialized Support", "Specialized Hardware"] False
excludedFilters A list of filters that you want hidden from users. Ex: ["ACCESS Allocated", "ACCESS OnDemand"] False
excludedResources A list of Resources that you want hidden from users. Ex: ["ACCESS Credits"] False
target The DOM element where the component will be rendered. True

Note: Avoid combining allowedCategories and excludedCategories, or allowedFilters and excludedFilters. If an invalid combination is found, it will default to what is specified in the allowed* options

CSS

The XRAS user interface components rely on Bootstrap 5 styles as well as their own stylesheet. How these stylesheets should be included depends on whether the site already uses Bootstrap 5.

Sites with Bootstrap 5

Sites that are already using Bootstrap 5 can simply add the component CSS in the document head:

<link rel="stylesheet" href="https://esm.sh/@xras/[email protected]/dist/xras-ui.css" />

Sites without Bootstrap 5

Sites that do not use Bootstrap 5 should also include bootstrap.css:

<link
  rel="stylesheet"
  href="https://esm.sh/@xras/[email protected]/dist/bootstrap.css"
/>
<link rel="stylesheet" href="https://esm.sh/@xras/[email protected]/dist/xras-ui.css" />

In order for the Bootstrap styles to be applied, the component target element needs to be wrapped in elements with Bootstrap classes. These classes act as a namespace for the Bootstrap classes to prevent conflicts with the rest of the site's CSS:

<div class="bootstrap">
  <div class="bootstrap-variables">
    <div class="bootstrap-fonts">
      <div id="resource-catalog-react"></div>
    </div>
  </div>
</div>

The bootstrap-variables and bootstrap-fonts classes on the inner wrapper are used to apply Bootstrap's default CSS variables and fonts, respectively, to the components. These classes are optional and can be omitted if the site defines its own typography rules and Bootstrap CSS variables.

Shadow DOM

The Bootstrap namespacing described in the previous section prevents the Bootstrap styles from interfering with the host site's styles, but it does not prevent the host site's stylesheet from applying to the components. For complete isolation of the components from the host site's styles, render the component in the shadow DOM using the shadowTarget helper function:

<div id="resource-catalog-react"></div>
<script type="module">
  import {
    resourceCatalog,
    shadowTarget,
  } from "https://esm.sh/@xras/[email protected]?exports=resourceCatalog,shadowTarget";
  resourceCatalog({
    apiUrl: "/path/to/catalog.json",
    target: shadowTarget(document.getElementById("resource-catalog-react")),
  });
</script>

When using the shadow DOM, the stylesheets are injected into the shadow root by shadowTarget and do not need to be added to the document head.