Skip to content

Latest commit

 

History

History
114 lines (81 loc) · 5.73 KB

skinning.md

File metadata and controls

114 lines (81 loc) · 5.73 KB
Raw

Skinning the UI

The UI is designed to be skinnable with very little effort, and the resulting artifacts can be added to a Brooklyn server or distribution.

Creating a Skin

You will need a folder somewhere that contains the theme data you wish to apply. It is recommended that this folder be under source control. It can be a part of a larger project.

Within this folder you will need two files:

brand.properties   # properties exposed by the UI for customization purposes
brand.less         # style vars your theme overrides and custom style rules your theme adds

In the Git repo, look at /ui-modules/branding/monochrome/brand.{properties,less} for a minimal example, or /ui-modules/branding/brand.{properties,less} for a complete list.

If you wish to refer to your own resources such as images or HTML files, they can be in under this directory and referenced with the prefix brand/. For example if you have acme-logo.png in this folder, you might want to set product.logo.img=brand/acme-logo.png. (The UI code will then use your logo in various places.)

Other tips:

  • UI shared content (from the folder /ui-modules/shared/) and be referenced with the prefix brooklyn-shared/
  • You can supply your own partials (HTML fragments) in some properties, and in these you can refer to properties you've set under the brand namespace; for example the logo above is used as follows: <img class="logo" src="${require('!!file-loader!<%= brand.product.logo.img %>')}">

Reskinning

Requirements

To build the UI you will need the following installed on your build machine:

  • java
  • maven (please note, you will need version 3.5.2 or later)
  • git
  • bzip2
  • libpng-devel
  • automake
  • autoconf
  • libtool
  • dpkg
  • pkgconfig
  • nasm
  • gcc

Dev Build

For test purposes, you can build individual UI projects under /ui-modules/ in dev mode as described in the README in those directories. To apply a custom brand, set the environment variable BROOKLYN_UI_BRAND_DIR to point at the absolute path of the folder where your brand.{properties,less} files are. For example to see what App Inspector looks like using the theme in monochrome, go to that project dir and run:

BROOKLYN_UI_BRAND_DIR=/path/to/brooklyn-ui/ui-modules/branding/monochrome/ make dev

Notes:

  • Consult the README.md in each dir for more info. Typically the dev build expects the Brooklyn REST API to be running on localhost:8081.
  • Although the monochrome example is located under ui-modules, it isn't used; it's intended as an example.
  • Some changes may be picked up automatically but many might require a restart.

Prod Build

The production build uses Maven. Go to the /ui-modules/ directory and run:

mvn -Dbrooklyn.ui.brand.dir=/absolute/path/to/branding-dir clean install

The "/absolute/path/to/branding-dir" is the folder containing brand.properties and brand.less created above.

Please Note, the version of the bundles built should differ from the versions installed into Brooklyn to make them easier to identify and to prevent Karaf from ignoring them as duplicates.
Typically this is done by appending a custom qualifier. The simplest way to do this is to add -Dbrooklyn.ui.version=${brooklyn.version}-custom as part of the build, on the command line (quoting to avoid bash variable expansion) or in a .mvn/maven.config file. You can also use the change-version.sh script from https://github.com/apache/brooklyn-dist/tree/master/release/ : e.g. change-version.sh BROOKLYN <version>.custom <version>.your_company.1, follwed by a rebuild.

The build will create a KAR archive in features/target/*.kar. This file can be copied to your Brooklyn install's deploy/ directory prior to launching it, and your custom skin will automatically be deployed. A ZIP or cloud/container image of Brooklyn can then be created (with this KAR archive in deploy/) to make a redistributable that can be installed on other machines.

Embedding into a larger build project

In addition to the .mvn/maven.config suggestion above, defining the brand dir and the version qualifier, you may wish also to:

  • have the larger project include a symlink to the brooklyn-ui and an aggregator project which builds the module brooklyn-ui/ui-modules with the maven defines as noted above (note that these system properties and env vars are the only way to pass data to aggregated maven modules where the parent hierarchy is different)

  • have the larger project include a "precheck" module which uses the maven enforcer to check that variables are set (to prevent builds that don't have your branding and qualifier)

  • set -Dbrooklyn.ui.modularity.version=${brooklyn.version} to use the standard Brooklyn modularity JARs (only the UI modules need rebuilding)

  • set -Dbuild.version=X.X.X and -Dbuild.name=Acme to have that information reflected in selected pages of the UI (such as the "About" page). This is in addition to defining custom branding and a custom qualifier on the Brooklyn version.