docs/skinning.md - brooklyn-ui - Git at Google

 # 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.
 -->
	# 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.
	-->