Skip to content

5. How to Customize Your Client

Jump to bottom
Nick Mitchell edited this page Jun 29, 2020 · 9 revisions

How to Customize Your Client?

Once you have your own Kui client, you can customize the following common Kui configurations:

  • About the Client — product description, tutorial, contacts, and etc.
  • Proxy — the server side of a browser-based Kui client.
  • Font Size — choose the base font size.
  • User Interface — React Component Libary selection, and etc.

Configure About

You can customize the About Window to display your product description, contacts and etc. As shown in the following screenshot, About Window uses menus to show navigational information. Users can click to browse content under each menu. See Source Code

Source Code of the About Window

For Kui to find your customized configuration, you need to place the following code in config.d/about.json under your client configuration directory.

{
  "menus": [
    {
      "label": "Overview",
      "items": [
        {
          "mode": "about",
          "content": "about:content",
          "contentType": "text/markdown"
        },
        { "mode": "version", "contentFrom": "version --full" }
      ]
    }
  ],
  "links": [
    { "label": "Home Page", "href": "http://kui.tools" },
    { "label": "Github", "href": "https://github.com/IBM/kui" },
    { "label": "Bugs", "href": "https://github.com/IBM/kui/issues/new" },
    { "label": "Kubectl Help", "command": "kubectl --help" },
    { "label": "API Resources", "command": "kubectl api-resources" }
  ]
}

Language

Kui supports multiple languages(locales) for About. Once you have your translation files in i18n/ under your client configuration directory, you can use it directly in your about.json. Kui will automatically translate the strings. The following example shows the about_en_US.json used by the about.json above.

{
  "about": "About",
  "about:content": "[![Kui: The CLI with a GUI twist](icons/svg/kui-wide.svg)](http://kui.tools)\n\n**Kui** is a platform for enhancing the terminal experience with visualizations. It provides users a modern alternative to ASCII terminals and web-based consoles. It provides tool developers an opportunity to unify these experiences.",
  "theme": "Themes",
  "Configure": "Configure",
  "tutorial": "Getting Started",
  "version": "Version",
  "Home Page": "Home Page",
  "Github": "Github",
  "Bugs": "Bugs"
}
About Window Properties
Name Type Required Description
menus Menu[] required A collection of expandable menu
links Link[] optional A collection of external links or command-lines
Menu Properties
Name Type Required Description
label string required title of a menu
items Mode[] required a collection of menu items
Mode Properties
Name Type Required Description
mode string required title of a menu item
content string required menu item page content
contentType ContentType required type of the content
Link Properties
Name Type Required Description
label string required title of a link item
href string optional if command exits external link
command string optional if href exits Kui will execute the command-line when user clicks this link item

Configure Proxy

When Kui proxy spawns a pseudoTerminal process, it will launch bin/bash or powsershell.exec (for windows) by default. You can change this via shellExec (shell executable) and shellOpts (shell options) in config.d/proxy.json under your client configuration directory.

Base Font Size

The default base font size is 14px. All fonts will be relative to that base. You may choose an alternative from 12px, 14px, 16px, and 18px by modifying the htmlCss field in your config.d/style.json. For example, to use a 16px base font size:

{
  "htmlCss": "kui--16px",
  ...
}

Unlike most other changes, after this change you must restart the webpack watcher in order to observe the change.

Customize User Interface

You can customize the UI of your client through the following <Kui/> component properties.

Input Properties

Name Type Required Description
noPromptContext boolean optional do not display any extra information beside the > prompt. Default: false
prompt string optional characters to display before every <input>. Default: "/"

Session Properties

Name Type Required Description
Loading ReactNode optional session init started view
reinit ReactNode optional session was severed; reinit started view
loadingError (err: Error) => ReactNode optional session could not be established; error view
loadingDone (repl: REPL) => ReactNode optional session established! welcome to your session view
showWelcomeMax number optional maximum number of times to show loadingDone to users; If set to -1 (default), always show
Displaying a Loading Done/Welcome Message

To display a message to the user to welcome them to Kui, use the loadingDone property. By default, in browser-based clients, you should see a default loading done message. You may either customize the strings in this default UI, or provide your own UI.

Option 1: I want the default UI, but with custom strings

In your client directory, create a file i18n/resources_en_US.json (and similarly for any other locales you want to support). The following strings will be used to fill in the default UI:

{
  "Successfully connected to your cluster": "Successfully connected to your cluster",
  "Please wait while we connect to your cluster": "Please wait while we connect to your cluster",
  "Lost connection to your cluster": "Lost connection to your cluster",
  "Attempting to reconnect...": "Attempting to reconnect\u2026",
  "Error connecting to your cluster": "Error connecting to your cluster",
  "loadingDone:content": "To learn more, try [getting started](#kuiexec?command=getting%20started)"
}

For the last string, you may provide a Markdown-formatted string. This special kuiexec syntax tells the Kui Markdown renderer to execute a Kui command onClick.

Option 2: I want my own UI

When instantiation the <Kui/> client, pass a loadingDone property that provides your custom UI. For example:

import { REPL } from '@kui-shell/core'
import KuiIcon from '../icons/png/Welcome.png'

function loadingDone(repl: REPL) {
  return (
    <Card titleInHeader bodyInHeader title="titleText" icon={KuiIcon} repl={repl}>
      bodyText
    </Card>
  )
}

The properties titleInHeader and bodyInHeader specify that you want the title and body text to be displayed to the right of the given icon. Otherwise, they will be displayed below the given icon. For example, if your icon is a wide "brand" icon, you may wish for the title and body to be displayed below that icon. If your icon is a square "logo" icon, you may wish for a left-right arrangement.

Your bodyText may be either a ReactNode of your design, or a Markdown-formatted string. For the latter, you may fetch the string via i18n, from a translated resource, and that markdown may include commands to be executed. For example:

import { i18n } from '@kui-shell/core'
const strings = i18n('client', 'welcome') // strings in client/i18n/welcome_xx_yy.json

const bodyText = strings('body')

Where welcome_xx_yy.json contains a field:

{
  "body": "To learn more, try [getting started](#kuiexec?command=getting%20started)"
}

Branding Properties

Name Type Required Description
productName string optional This will be displayed in the upper left of the TopTabStripe. Default: "Kui"

Feature Flags Properties

Name Type Required Description
disableTableTitle boolean optional Disable table breadcrumb title. Default: false
splitTerminals boolean optional Enable Split Terminals. Default: false
enableWatcherAutoPin boolean optional Automatically pin watchable commands to WatchPane. Default: false
sidecarName 'breadcrumb' or 'heroText' boolean Show sidecar name as breadcrumb or hero text. Default: 'breadcrumb'

Theme Properties

Name Type Required Description
components 'carbon' or 'patternfly' optional component libary to use. Default: 'carbon'
topTabNames 'command' or 'fixed' optional show the last executed command? Default: 'fixed'

Client Properties

Name Type Required Description
noBootstrap boolean optional no Kui bootstrap needed?
bottomInput true or React.ReactNode optional operate in bottom Input mode rather than as a conventional Input/Output terminal mode? Default: false
isPopup boolean optional operate in popup mode? Default: false
commandLine string[] optional if in popup mode, execute the given command line
Clone this wiki locally