| # 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. |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |