1
0
mirror of https://github.com/checktheroads/hyperglass synced 2024-05-11 05:55:08 +00:00
Files
checktheroads-hyperglass/docs/docs/ui.mdx
2020-04-18 11:33:44 -07:00

236 lines
16 KiB
Plaintext

---
id: ui
title: Web UI
sidebar_label: Web UI
keywords: [hyperglass, looking glass, web ui, gui, theme, colors, branding]
description: hyperglass Web UI Configuration
---
import Link from "@docusaurus/Link";
import R from "../src/components/Required";
import MiniNote from "../src/components/MiniNote";
import Code from "../src/components/JSXCode";
import Color from "../src/components/Color";
import Font from "../src/components/Font";
import PageLink from "../src/components/PageLink";
<div class="table--full-width" />
The `web` subsection contains multiple subsections of its own, should you wish to customize various aspects of the UI:
| Section | Description | All Options |
| :-------------- | :----------------------------- | :-----------------------------------------: |
| `credit` | Developer credit & GitHub Link | <PageLink to="#credit">➡️</PageLink> |
| `dns_provider` | DNS over HTTPS Provider | <PageLink to="#dns_provider">➡️</PageLink> |
| `external_link` | Link to external site | <PageLink to="#external_link">➡️</PageLink> |
| `greeting` | Greeting Modal | <PageLink to="#greeting">➡️</PageLink> |
| `logo` | Logo & Favicons | <PageLink to="#logo">➡️</PageLink> |
| `opengraph` | [OpenGraph](https://ogp.me/) | <PageLink to="#opengraph">➡️</PageLink> |
| `terms` | Terms & Conditions | <PageLink to="#terms">➡️</PageLink> |
| `theme` | Colors & Fonts | <PageLink to="#theme">➡️</PageLink> |
## `credit`
| Parameter | Type | Default | Description |
| :-------- | :-----: | :-----: | :--------------------------------------------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or disable the display of developer credit & link to hyperglass GitHub repository |
:::note From the developer
If your organization's policy allows, and you don't mind, I request that you keep `credit` enabled. Remember: my goal for this project is get more networks to use looking glasses to make all of our lives easier. Because it's primarily other network operators who will use this tool to begin with, I'd love for any operators that use your looking glass to know where they can get their own.
:::
## `dns_provider`
| Parameter | Type | Default | Description |
| :-------- | :----: | :------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | String | `'cloudflare'` | DNS over HTTPS provider for in-browser DNS resolution. Cloudflare & Google supported. <MiniNote>Must be <Code>cloudflare</Code> or <Code>google</Code></MiniNote> |
## `external_link`
| Parameter | Type | Default | Description |
| :-------- | :-----: | :---------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or disable the display of an external link |
| `title` | String | `'PeeringDB'` | Link title/label |
| `url` | String | `'https://www.peeringdb.com/asn/{primary_asn}'` | Target URL. `{primary_asn}` will be replaced with the `primary_asn` value from <Link to="/docs/configuration#global-settings">Global Settings</Link> |
## `greeting`
| Parameter | Type | Default | Description |
| :--------- | :-----: | :----------- | :------------------------------------------------------------------------------------------- |
| `enable` | Boolean | `false` | Enable or disable the greeting modal. |
| `file` | String | | Path to a [markdown](https://www.markdownguide.org/) file containing the modal body content. |
| `title` | String | `'Welcome'` | Modal title. |
| `button` | String | `'Continue'` | Button text. |
| `required` | Boolean | `false` | If `true` the user must click the button in order to submit a query. |
## `logo`
| Parameter | Type | Default | Description |
| :-------- | :-----: | :------------------------------ | :------------------------------------------- |
| `light` | String | `'images/hyperglass-dark.png'` | Path to logo that will be used in light mode |
| `dark` | String | `'images/hyperglass-light.png'` | Path to logo that will be used in dark mode |
| `width` | Integer | `384` | Maximum logo width in pixels |
| `height` | Integer | | Maximum logo height in pixels |
## `opengraph`
If you're not familiar with [OpenGraph](https://ogp.me/), it's the thing that generates the pretty pictures, titles, and descriptions for links when you post them to sites/tools such as Facebook, Twitter, Slack, etc.
By default, no Opengraph image is set. If you define one with `image`, hyperglass will try to determine the image's dimensions automatically. Or, you can override those dimensions with the `width` and `height` parameters.
| Parameter | Type | Description |
| :-------- | :-----: | :---------------------- |
| `image` | String | Path to opengraph image |
| `width` | Integer | Opengraph image width |
| `height` | Integer | Opengraph image height |
## `terms`
| Parameter | Type | Default | Description |
| :-------- | :-----: | :-------- | :-------------------------------------------------------------------------------------------- |
| `enable` | Boolean | `true` | Enable or display the display of terms & conditions |
| `file` | String | | Path to a plain text or markdown file with content to override the default terms & conditions |
| `title` | String | `'Terms'` | Terms & conditions title |
## `text`
| Parameter | Type | Default | Description |
| :--------------- | :----: | :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cache_prefix` | String | `'Results cached for '` | Text displayed with the cache timeout countdown. |
| `cache_icon` | String | `'Cached Response from {time}'` | Text displayed when a user hovers over the lightning bolt icon, which is displayed when a response from the server was a cached response. `{time}` is replaced with the _original_ query's timestamp. |
| `completed_time` | String | `'Completed in {seconds}'` | Text displayed when a user hovers over the success icon for a query result. `{seconds}` will be replaced with 'n seconds' where n is the time a query took to complete. |
| `fqdn_tooltip` | String | `'Use {protocol}'` | Text displayed when a user hovers over the IPv4 or IPv6 button on an FQDN target resolved by DNS. `{protocol}` is replaced with the relevant IP protocol. |
| `query_location` | String | `'Location'` | Query Location (router) form label. |
| `query_target` | String | `'Target'` | Query Target (IP/hostname/community/AS Path) form label. |
| `query_type` | String | `'Query Type'` | Query Type (BGP Route, Ping, Traceroute, etc.) form label. |
| `query_vrf` | String | `'Routing Table'` | Query VRF form label. |
| `subtitle` | String | `'Network Looking Glass'` | Subtitle text. value. |
| `title` | String | `'hyperglass'` | Title text. |
| `title_mode` | String | `'text_only'` | Set the title mode. <MiniNote>Must be <Code>text_only</Code>, <Code>logo_only</Code>, <Code>logo_subtitle</Code>, or <Code>all</Code></MiniNote> |
:::note Title Mode
The `title_mode` parameter behaves in the following manner:
| Mode | Behavior |
| --------------- | ------------------------------------------------------------------ |
| `text_only` | Shows the `title` and `subtitle` only. |
| `logo_only` | Shows the <Link to="#logo">`logo`</Link> only. |
| `logo_subtitle` | Shows the <Link to="#logo">`logo`</Link> and `subtitle` only. |
| `all` | Shows the <Link to="#logo">`logo`</Link>, `title`, and `subtitle`. |
:::
## `theme`
### Parameters
| Parameter | Type | Description |
| :------------------- | :----: | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| `default_color_mode` | String | Sets the default color mode. Must be `light` or `dark`. If no default mode is specified, hyperglass will use the browser's preferred color mode. |
### Sections
| Section | Description | All Options |
| :------- | :----------- | :----------------------------------: |
| `colors` | Theme colors | <PageLink to="#colors">➡️</PageLink> |
| `fonts` | Theme fonts | <PageLink to="#fonts">➡️</PageLink> |
#### `colors`
| Parameter | Type | Default | Description |
| :---------- | :----: | :--------------------- | :------------------------------------- |
| `primary` | String | | Primary accent color |
| `secondary` | String | | Secondary accent color |
| `success` | String | | Success message/status color |
| `warning` | String | | Warning message/status color |
| `error` | String | | Error message/status color |
| `danger` | String | | Danger message/status color |
| `black` | String | <Color hex="#262626"/> | Used as background color in dark mode |
| `white` | String | <Color hex="#f7f7f7"/> | Used as background color in light mode |
| `red` | String | <Color hex="#d84b4b"/> | Used as `danger` color if undefined |
| `orange` | String | <Color hex="#ff6b35"/> | Used as `error` color if undefined |
| `yellow` | String | <Color hex="#edae49"/> | Used as `warning` color if undefined |
| `green` | String | <Color hex="#35b246"/> | Used as `success` color if undefined |
| `cyan` | String | <Color hex="#118ab2"/> | Used as `primary` color if undefined |
| `blue` | String | <Color hex="#314cb6"/> | Used as `secondary` color if undefined |
| `teal` | String | <Color hex="#35b299"/> | |
| `pink` | String | <Color hex="#f2607d"/> | |
| `purple` | String | <Color hex="#8d30b5"/> | |
| `gray` | String | <Color hex="#c1c7cc"/> | |
#### `fonts`
Currently, only [Google Fonts](https://fonts.google.com/) are supported.
| Parameter | Type | Default | Description |
| :-------- | :----: | :----------------------- | :-------------------------------------- |
| `body` | String | <Font name='Nunito'/> | Main body font |
| `mono` | String | <Font name='Fira Code'/> | Monospace font, used for command output |
## Example
```yaml
web:
credit:
enable: true
dns_provider:
name: google
url: https://dns.google/resolve
external_link:
enable: true
title: PeeringDB
url: https://www.peeringdb.com/asn/{primary_asn}
help_menu:
enable: true
file: null
title: Help
logo:
dark: /images/hyperglass-light.png
favicons: ui/images/favicons/
height: null
light: /images/hyperglass-dark.png
width: 384
opengraph:
height: 1132
image: /images/hyperglass-opengraph.png
width: 7355
terms:
enable: true
file: null
title: Terms
text:
cache: Results will be cached for 2 minutes.
fqdn_tooltip: "Use {protocol}"
query_location: Location
query_target: Target
query_type: Query Type
query_vrf: Routing Table
subtitle: AS65001
title: hyperglass
title_mode: text_only
theme:
default_color_mode: light
colors:
black: "#262626"
blue: "#314cb6"
cyan: "#118ab2"
danger: "#d84b4b"
error: "#ff6b35"
gray: "#c1c7cc"
green: "#35b246"
orange: "#ff6b35"
pink: "#f2607d"
primary: "#118ab2"
purple: "#8d30b5"
red: "#d84b4b"
secondary: "#314cb6"
success: "#35b246"
teal: "#35b299"
warning: "#edae49"
white: "#f7f7f7"
yellow: "#edae49"
fonts:
body: Nunito
mono: Fira Code
```