> For the complete documentation index, see [llms.txt](https://pic-sure.gitbook.io/pic-sure-developer-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pic-sure.gitbook.io/pic-sure-developer-guide/configuring-pic-sure/pic-sure-frontend-configuration.md). # PIC-SURE Frontend Configuration The PIC-SURE Frontend has a few different files used for customization of your installation. The most important of which is the [.env](https://www.npmjs.com/package/dotenv) file which is used for environment variables, feature flags, custom logins, and more. Second is our [configuration.ts](https://github.com/hms-dbmi/PIC-SURE-Frontend/blob/main/src/lib/configuration.ts) file which reads in above variables and flags, as well as branding and other configurations. You can check out an example .env in the root directory, called .env.example. ## Branding ### Theme & Colors We are using some of [Skeleton's](https://www.skeleton.dev/) components and used their design system for our theming. You can create your own theme or modify ours. Place your new theme along side ours here in the file: ``` /pic-sure-themes.ts ``` After, edit the name of the theme in the body tag of the main html file from. > **NOTE:** its important the name in the theme file and the html attribute data-theme matches the > > ```typescript > name: 'YOUR_THEME_NAME_HERE', > ``` ````html ```html ``` ```` {% hint style="info" %} To learn more about themes and to create your own check out Skeleton's theme builder: {% endhint %} ### Text The branding of the PIC-SURE Frontend application can be customized in a few ways. The first is by editing the configuration.json file. This file contains mostly text seen through the application that you my want to customize. the file is located at: ```sh src/lib/assets/configuration.json ``` ### Logo Add your logo and set its path in our main Environment file. ```shellscript VITE_LOGO=./path/to/logo.svg ``` The login screen also has some images with dots, you can customize the up to 5 colors by adding this like to the .env file: ```javascript # You can list 0, 3, or 5 colors in the VITE_DOTS_COLORS_CLASS array VITE_DOTS_COLORS_CLASS='["--color-primary-500", "--color-error-500", "--color-tertiary-500"]' ``` ## Login You can add your own custom login buttons to the frontend. After following the steps to configure the PIC-SURE Auth Micro App here. You can add a corresponding login option to the frontend in the same .env file mentioned above. The application will create the login button(s) when the server starts. If you add new ones, you must restart the server. The following is an example login configuration: ```bash VITE_AUTH_PROVIDER_MODULE_GOOGLE=true VITE_AUTH_PROVIDER_MODULE_GOOGLE_TYPE=AUTH0 VITE_AUTH_PROVIDER_MODULE_GOOGLE_CLIENTID=12345ABCD VITE_AUTH_PROVIDER_MODULE_GOOGLE_CONNECTION=oauth2 VITE_AUTH_PROVIDER_MODULE_GOOGLE_DESCRIPTION="Login with Auth0" VITE_AUTH_PROVIDER_MODULE_GOOGLE_HELPTEXT='Login with your Google account' VITE_AUTH_PROVIDER_MODULE_GOOGLE_ALT=false ``` {% hint style="info" %} All login settings are prefixed with **VITE\_AUTH\_PROVIDER\_MODULE\_** {% endhint %}

Entry	Description
..._GOOGLE	Use this flag to enable or disable to option
..._TYPE	This idicates which type of connection the login button should use. We support Auth0, RAS, and Okta out of the box. See here for more on how to add custom logins
...CLIENTID	The identifier to pass to the IDP for your environment.
...CONNECTION	This is used to indicate to PSAMA or the IDP which type of authentication you are using.
...DESCRIPTION	This will be the login button's text.
...HELPTEXT	(OPTIONAL) You can use this to display some message under the login button. Use it for linking to your help plages, etc.
...ALT	(OPTIONAL) Alt will place the login button at the bottom of the list and use a different, less emphasized button style. Use it for admin or developer logins which differ from the main login method(s).

| Entry | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------- | | VITE\_AUTH0\_TENANT | If you are using auth0 as a long provider, you must set your auth0 tenet. It defaults to the avillachlab tenet. | ## The Tour PIC-SURE Frontend comes with a tour to help the user understand how to use the UI. The tour is customizable by editing the tour configuration file: ``` src/lib/assets/TourConfiguration.json ``` Feel free to copy one of our tours and customize the steps or text. {% hint style="info" %} You can disable to the tour in the features section of your .env file. {% endhint %} | Env setting name | Description | Type | | ---------------------- | ----------------------------------------------------------------------------------------------------------------- | ------- | | EXPLORER\_TOUR | Enable or disable thr tour (on both pages) | Boolean | | VITE\_AUTH\_TOUR\_NAME | The name of the tour object in the TourConfiguration.json mentioned above. This one is used on the Explore page. | String | | VITE\_OPEN\_TOUR\_NAME | The name of the tour object in the TourConfiguration.json mentioned above. This one is used on the Discorver page | String | ## Features If you are using the PIC-SURE All-in-One, the build process will ask you about some of the feature flags you may want to customize. Once the build process is finished there will be a new file called .env in the root folder (otherwise you should make one). Here you make changes to your choices. Most are boolean flags. Feel free to customize them as you see fit or add your own.

Flag Name	Description
VITE_OPEN	Allows unauthorized users to use the discover and/or explorer page. Used to show or hide the "Explore without Login" button. Also used to determine if users should be redirected to the login screen when they do not have a valid token.
VITE_ALLOW_EXPORT	If set to false, the "Prepare for Analysis" button will not be shown and if the user navigates to the export functionality they will see a message about this feature being disabled.
VITE_ALLOW_DOWNLOAD	Enables the user to download the CSV or PFB exported data. Specifically it shows or hides the download button.
VITE_DOWNLOAD_AS_PFB	Enables the user to choose PFB as an export option when exporting the data instead of CSV.
VITE_ALLOW_EXPORT_ENABLED	If enabled, search result rows will have a new action that allows the variable to be added as a exported column.
VITE_DATA_REQUESTS	Enables the data requests page.
VITE_DIST_EXPLORER	Enables the Variable Distributions feature. Hides the button if disabled. (AKA Visualizations)
VITE_VARIANT_EXPLORER	Enables the Variant explorer feature. Hides the button if disabled.
VITE_EXPLORE_TOUR	Enables the tour, the button is not shown if disabled. See tour section above for more.
VITE_EXPLORE_TOUR_SEARCH_TERM	A string. The default search term for the tour to use.
VITE_REQUIRE_CONSENTS	If enabled it will send the user's consents with their queries when required.
VITE_USE_QUERY_TEMPLATE	Some PIC-SURE applications require a base query for user permissions/consents. This enables both creating and using the query templates. The template is created by the PIC-SURE backend and stored in local storage.
VITE_API	Enables the Prepare for Analysis page and navigation button.
VITE_DISCOVER	Enables the Discover page and navigation button. See more about the Discover page below.
VITE_DASHBOARD	Enables the Dashboard page and navigation button.
VITE_ENABLE_SNP_QUERY	Used to determine if the genomic filter button should be shown to the user as well as which options for genomic queries are shown. If set to true, genomic filtering will be available and the SNP genomic query option will be shown as an option on the genomic query builder page.
VITE_ENABLE_GENE_QUERY	Used to determine if the genomic filter button should be shown to the user as well as which options for genomic queries are shown. If set to true, genomic filtering will be available and the Gene query option will be shown as an option on the genomic query builder page.
VITE_DASHBOARD_DRAWER	If enabled the dashboard rows will be clickable and when clicked will open a drawer with more info about the selected row.
VITE_ENABLE_SAMPLE_ID_CHECKBOX	If enabled a checkbox will appear on the first step of the export page which, when checked, will add relevant sample ids to the user's export and query.
VITE_ENABLE_METRICS	If enabled, user actions will be sent to the PIC-SURE Metrics resource and logged.
VITE_CONFIRM_DOWNLOAD	If enabled a confirm box is shown to the user before they download a file they are exporting.
VITE_ENABLE_TERRA_EXPORT	Enables a button to export to terra via a signed AWS url.
VITE_ENABLE_HIERARCHY	Enables a new action in search results to show the Variable's hierarchy tree and allow anyRecordOf[Multi] queries.
VITE_EXPORT_RESULT_TYPE	Result type of non-pfb exports
VITE_ENABLE_TOS	Enables the Terms of Service and adds a link which opens the TOS to the footer.
VITE_MANUAL_ROLE	Enables the BDC specific manual roles page.

## Settings ### Project Settings


VITE_PROJECT_HOSTNAME	The hostname of the website, for example: picsure.hms.harvard.edu
VITE_ORIGIN	The full url, include https:// of the website. For example: https://picsure.hms.harvard.edu/

### Resources Resources are UUIDs that need to be the same as the ones in the MySQL PIC-SURE Database in the Resources table.

Resource Env Name
VITE_RESOURCE_BASE_QUERY	PIC-SURE's own UUID
VITE_RESOURCE_HPDS	Default HPDS's UUID or Authorized. Used on the Explorer page.
VITE_RESOURCE_OPEN_HPDS	Open PIC-SURE's UUID. Passes through the aggregate resource. Used on the Discover page. Can be set to the Default HPDS to bypass the aggregate resource, but this should only be for testing and you should just disable discover instead.
VITE_RESOURCE_VIZ	Used for Variable Distributions and expects VITE_DIST_EXPLORER to be true.
VITE_RESOURCE_METRICS	Used for the PIC-SURE-Metrics resource for logging user actions.

### Variant Explorer Settings

Env setting	Value
VITE_VARIANT_EXPLORER_TYPE	aggregate or full
VITE_VARIANT_EXPLORER_MAX_COUNT	A number indicating the max variants shown, shows an error if there are too many
VITE_VARIANT_EXPLORER_EXCLUDE_COLUMNS	an array of column names to hide

### Google Anaytics You may optionally enable Google Anaytics (GA).


VITE_GOOGLE_ANALYTICS_ID	Your GA ID, if not set GA will be disabled
VITE_GOOGLE_TAG_MANAGER_ID	Your tag manager ID, if not set GA tag manager will be disabled

### Other Settings | Env Setting | Description | Type | | ------------------------------------ | ---------------------------------------------------------------- | --------------------------- | | VITE\_MAX\_DATA\_POINTS\_FOR\_EXPORT | Maximum data points the user is allowed to export at once. | number | | VITE\_DIST\_EXPLORER\_GRAPH\_COLORS | Colors to be used in the variable distrubutions graphs | string array (of hex codes) | | VITE\_MAX\_DATA\_POINTS\_FOR\_EXPORT | The maximum data points the user can have and still export data. | number, defaults to 1000000 |