This chapter describes how to customize the Che-Theia interface and branding. Customization is possible for the following elements:

  • Welcome page and About dialogue:

    • Product name

    • Product logo

    • Description

    • List of helpful resources (Help section of the Welcome page)

To start using the customized Che-Theia:

  1. Build a container image with the customized Che-Theia.

  2. Define an editor meta.yaml that uses the custom image.

  3. Create a workspace from a devfile using the custom editor.

Defining custom branding values for Che-Theia

This section describes how to customize definitions of basic branding elements of Che-Theia.

Procedure

Create a product.json file with a new name of the product, logo, description, and list of hyperlinks on the Welcome page (an example of product.json:

{
    "name": "Red Hat CodeReady Workspaces",  (1)
    "icon": "codeready-workspaces-icon.png", (2)
    "logo": {                                (3)
        "dark": "codeready-workspaces-logo-light.png",
        "light": "codeready-workspaces-logo-dark.png"
    },
    "welcome": {                             (4)
        "title": "Welcome to Your Workspace",
        "links": ["website", "documentation"]
    },
    "links": {                               (5)
        "website": {
            "name": "Discover CodeReady Workspaces",
            "url": "https://developers.redhat.com/products/codeready-workspaces/overview"
        },
        "documentation": {
            "name": "Browse Documentation",
            "url": "https://www.redhat.com/docs"
        }
    }
}
1 name: tab title for the Welcome page and the About dialogue.
2 icon: icon for the Welcome page tab title.
3 logo: product logo for dark and light themes on the Welcome page (maximum height 80 px) and in the About dialogue (maximum height 100 px). Use an image with a transparent background. Define a relative path, an absolute path, or a URL to an image.
4 welcome: the behavior of the Welcome page. Customize the invitation title and the links in the Help section. When the welcome/links property is not defined, the Welcome page displays the links from the links section.
5 links: list of helpful resources for the product. Use tags to group links for better findability.

To use only one logo image for both dark and light themes:

{
    ...
    "logo": "product-logo.png"
    ...
}

Building a Che-Theia container image with custom branding

This section describes how to build a Che-Theia container image with custom branding applied.

Prerequisites
  • A product.json file with custom branding definitions

Procedure
  1. Download an example Dockerfile.

  2. In the Dockerfile directory, create a branding/ sub-directory. Place the custom product.json file and logo images into the branding/ directory.

  3. Build the container image with Che-Theia and push the image to a container registry:

    $ docker build -t username/che-theia-codeready-workspaces:next .
    $ docker push username/che-theia-codeready-workspaces:next

Testing Che-Theia with custom branding

This section describes how to test a customized Che-Theia by opening a new workspace with custom branding.

Prerequisites
  • Che-Theia container image built with custom branding definitions

Procedure

To test a custom Che-Theia image, create a new meta.yaml file describing a custom cheEditor, and use it in a devfile for the testing workspace.

  1. Download the latest Che-Theia meta.yaml from the plug-in registry

  2. Replace the image value in the containers section to point to the custom Che-Theia container image.

  3. Create a workspace using the sample che-theia-branding-example devfile to apply the changes:

    factory contribute
    metadata:
      name: che-theia-all
    projects:
      - name: che-cheia-branding-example
        source:
          location: 'https://github.com/che-samples/che-theia-branding-example.git'
          type: git
          branch: master
    components:
      - type: cheEditor
        reference: >-
          https://raw.githubusercontent.com/che-samples/che-theia-branding-example/master/che-editor.meta.yaml
    apiVersion: 1.0.0
  4. Run the workspace to see the changes:

    • The dark theme of Che-Theia:

      welcome dark
      about dark
    • The light theme of Che-Theia:

      welcome light
      about light
Tags: