ovirt-engine Branding
=====================

OUTLINE
-------

ovirt-engine supports pluggable branding that may effect the user interface
themes and selected strings. There may be several branding packages
installed in specific order, each package overrides the previous ones
for the resources it defines.

PACKAGE FORMAT
--------------

branding.properties
    This is the main properties file that defines where the branding
    resources can be found. Resources are relative to branding.properties.

    user_portal_css - Css to inject into user portal (required, can be empty).
    web_admin_css - Css to inject into web admin (required, can be empty).
    welcome_css - Css for the welcome page (required, can be empty).
    messages - Standard java message bundle (required).
    version - The version of the branding in the package. Only versions
      that match the one defined in the engine will be loaded (required,
      theme will not load without it).

The current branding version as defined by engine is 1.

CSS INJECTION
-------------

CSS are injected in the same order of how the branding packages are declared,
this way the last css's styles are defined in the correct order.

The oVirt UI is broken up into four distinct modules at this point.
 * User Portal
 * Web Admin
 * Common widgets
 * welcome page

Each of those modules contain some widgets that we can style using CSS
clases. Refer to EXAMPLE to see a listing of available classes categorized
by what widget is being styled.

EXAMPLE
-------

If you look in packaging/branding/ovirt.brand you will see a functional
example branding theme which just happens to be the default oVirt theme.
You will notice the following files:

1. branding.properties, This is the main properties file defining
   the branding properties.
2. user_portal.css, The user portal style sheet file.
3. web_admin.css, The web admin style sheet file.
4. welcome_style.css, The styles associated with the welcome page.
5. welcome_page.template, An HTML formatted template that gets inserted
   into the welcome page.
5. messages.properties, A java message bundle in many different locales.

Note that images are background images instead of image tags so we can use
style sheets to replace them.

As you can see the example branding theme references images from the images
directory. There is no rule that images have to exist in an images directory
but we highly suggest you organize your images in some way to make it easier
to maintain them.

WELCOME PAGE TEMPLATE
---------------------
The welcome page template is in HTML format with some minor differences. As
the template is inserted in the welcome page, there is no need for html, head,
or body tags.

Adding a # at the front of any line will mark it comment and it won't end up
in the output inserted into the welcome page.

The template can contain place holder elements which will be replaced by
localized messages based on the place holder strings. Each place holder string
is prefixed with obrand.welcome

For instance in welcome_page.template:
<a href="/someplace">{section_key}</a>
And in messages.properties:
obrand.welcome.section_key=Message

The output will be:
<a href="/someplace">Message</a>

There is a special place holder called {userLocale} which will be replaced with
the currently selected locale of the user. For instance if the current locale
is fr_FR and you have the following in your template:
<a href="/{userLocale}/documentation">Documentation</a>

The output will be:
<a href="/fr_FR/documenation">Documenation</a>

INSTALLATION
------------

Branding packages location is ${engine_syconfdir}/branding/*.brand. Usually
located at /etc/ovirt-engine/branding, within each package resides in its
own directory.

The branding directory is treated as a standard conf.d, in which directories
are sorted by name, each package is read by order and overrides
the previous ones.

MAINTENANCE - CSS
-----------------

To expose CSS class defined in ui.xml template via <ui:style> element:
1. rename the given class to use obrand_ prefix and mark it as @external,
   for example: @external obrand_myClass; .obrand_myClass { ..cssRules.. }
2. move CSS rules out of ui.xml template into corresponding CSS file under
   packaging/branding/ovirt.brand directory
3. when styling <g:Image> or other widgets that work with ImageResource,
   specify url="clear.cache.gif" to avoid broken images

MAINTENANCE - ADDING A BRANDED MESSAGE
--------------------------------------

All branded messages feed into the application via the host page and then via the
ApplicationDynamicMessages classes. To added a new branded message to the application:

1. add a property to messages.properties in the form of
    obrand.webadmin.my_new_message=BrandX Message
    obrand.userportal.my_new_message=BrandX Message
  You'll need to add one for both webadmin and userportal if you want the message
  exposed to both applications.
2. in DynamicMessages.java, add a key to the DynamicMessageKey enum for your property.
3. in DynamicMessages.java, add a getter for your property. Use the existing getters
  as examples.
4a. If the message will be exposed to webadmin, add a constant to the webadmin copy
  of ApplicationConstants.java. This will be used as a fallback if the branding files
  are missing. Example:
    @DefaultStringValue("BrandX Message")
    String myNewMessage();
4b. If the message will be exposed to webadmin, repeat 4a for userportal's copy of
  ApplicationConstants.java.
5a. If the message will be exposed to webadmin, add an addFallback() call in webadmin's
  copy of ApplicationDynamicMessages.java. Use existing calls as examples.
5b. If the message will be exposed to webadmin, repeat 5a for userportal's copy of
  ApplicationDynamicMessages.java.

You can now use an injected ApplicationDynamicMessages to access the branded messages.
Example:
  Anchor x = new Anchor(dynamicMessages.myNewMessage());
See HeaderView.java for a real-world example.

