Skip to content

Latest commit

 

History

History
249 lines (176 loc) · 8.12 KB

BRANDING.adoc

File metadata and controls

249 lines (176 loc) · 8.12 KB
Raw

Branding

Outline

The 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

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

webadmin_css

Css to inject into web admin (optional).

welcome_css

Css for the welcome page (optional).

messages

Standard java message bundle (optional). Comma-delimited list.

resources

The file that defines cascading resources. These are static resources (favicon, images, PDFs, etc.) that exist outside of CSS, but we still want to cascade them (optional).

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 in the constant org.ovirt.engine.core.branding.BrandingManager.CURRENT_BRANDING_VERSION, is 2.

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 distinct modules:

  • Web Admin (GWT)

  • Common widgets (GWT)

  • welcome page

  • Dashboard (React)

  • VM Portal (React)

  • (optional) various UI plugins

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:

branding.properties

This is the main properties file defining the branding properties.

web_admin.css

The web admin style sheet file.

welcome_style.css

The styles associated with the welcome page.

welcome_page.template

An HTML formatted template that gets inserted into the welcome page.

messages.properties

A java message bundle in many different locales. Only strings to be localized should go in here.

external_messages.properties

A second java message bundle, used for non-translatable strings (like URLs).

resources.properties

Contains the locations of cascading resources such as the brand’s favicon.

Note that most images are background images instead of image tags so we can use style sheets to replace them. However, branding does include a servlet to serve branded images (and other static resources) outside of CSS in a cascading manner.

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.

Cascading resources

These are images, PDFs, etc. that exist in multiple brands and are cascaded similarly to how CSS cascades. This allows us to use a cascading mechanism for branding outside of CSS, for things like favicon.ico.

If the same resource key exists in a higher brand, the higher brand "wins" and its copy of the resource gets served.

All cascading resources are defined in resources.properties. For each resource, specify a file path and optionally a contentType.

Example:

favicon.file=images/favicon.ico
favicon.contentType=image/x-icon

The BrandingCascadingResourceServlet that serves these resources is mapped to /ovirt-engine-theme-resource for the root app, /theme-resource for WebAdmin. To reference a cascaded resource in the root ovirt-engine.jsp, use ${pageContext.request.contextPath}/ovirt-engine-theme-resource/<resource> where <resource> is the key of the resource in resources.properties. To reference a cascaded resource in the WebAdmin GWT host page, use ${pageContext.request.contextPath}/theme-resource/<resource> where <resource> is the key of the resource in resources.properties.

Examples:

In WebAdmin:

<link rel="shortcut icon" href="${pageContext.request.contextPath}/theme-resource/favicon" type="image/x-icon" />

In root app:

<link rel="shortcut icon" href="${pageContext.request.contextPath}/ovirt-engine-theme-resource/favicon" type="image/x-icon" />

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>

If you want to completely replace any previous templates you can add a new key to the branding.properties file called welcome_replace with a value of true. This will cause the template engine to wipe out the template generated by processing previous theme, and complete replace it with yours. Default behaviour is to append your template to the end of the previous template(s). This flag allows you to override that behaviour and just use your template. Any themes processed after yours will default back to append unless they specify the flag as well.

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 add a new branded message to the application:

  1. Add a property to messages.properties or external_messages.properties in the form of:

    obrand.webadmin.my_new_message=BrandX Message
    Note
    		 Use messages.properties for any messages that will need to be translated into other languages. Use external_messages.properties for anything else, like URLs.

  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.

  4. 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();

  5. If the message will be exposed to webadmin, add an addFallback() call in webadmin’s copy of ApplicationDynamicMessages.java. Use existing calls as examples.

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.