Branding NBIA Classic

The NBIA Classic application is currently in production, primarily to provide administrative tools. The NBIA Client is the new search interface for NBIA and is also in production.

To brand the NBIA Classic application, the developer will need to download the code from GitHub https://github.com/CBIIT/national-biomedical-image-archive and build the application using the ant target build:all.  You will need to have the following required software:

Branding in NBIA is accomplished by editing and or replacing the objects in the branding folders found in /software/common/resources/branding. The nbia folder contained within is the default branding for NBIA. The subfolder called images contains the customizable images for the application; they include:

To use your own images, simply replace the image while keeping the same name as the original one in your new folder; the build will update it accordingly. At the base level of the folder are the XHTML/properties files that allow customization. Those files are listed in the following table.

Building a Branded Version

To create and build a branded version copy the example nbia folder to a new folder. As an example, assume the copied folder is "ncia" and you plan to make a version named "NCIA". Copy and name the folder and edit accordingly. Note the ncia_messages.properties contains much of the applications textual information and branding.properties contains the application names. Once you have edited the files, edit the install.properties and the defaultAHP3.properties files in the /software/build directory. Specify the branding properties. An example for naming an application "NCIA" follows.

##############################################
### New Branding Properties ###
##############################################
branding.appname=NCIA
branding.folder=ncia

Once that is complete, execute the build:all ant target and the new war files in the directory (nbia-source-directory)/software/target/dist/exploded/nbia-wars/ will be properly branded. Replace the war files in tomcat\webapps with the branded ones, delete the nbia-api, ncia, and nbia-download and restart tomcat.

For the JNLP Download Manager to work correctly, a Java signing certificate must be used to sign the jar files used by Download Manager. If you do not have a signing certificate you can pull the following jar files from the NBIA install files ncia.war: ncia.war\NBIADownloadManager.jar and the folder ncia.war\download-mgr-dependencies and replace the files in your generated ncia.war.

XHTML/Facelets Basics

For all of the XHTML files that can be specified through the branding process, they MUST start with:

<ui:composition xmlns:ui="http://java.sun.com/jsf/facelets">

and they MUST finish up with:

</ui:composition>

Within the composition, almost any XHTML can be specified. 

Entities

The one exception to watch out for are entities such as non-breaking spaces. Including these directly will cause the rendering of the page to fail, and users will see a big mess in their browser. In other words   will break rendering. Instead, the entity must be enclosed in a "verbatim" tag. Please note that another namespace is defined in the composition tag (in red below).

<ui:composition xmlns:ui="http://java.sun.com/jsf/facelets"
                xmlns:f="http://java.sun.com/jsf/core">
  <f:verbatim>&amp;nbsp;</f:verbatim>
</ui:composition>

Quick Links XHTML

The Quick Links XHTML is imported into the scope of an XHTML table. Any XHTML specified here should be wrapped in a <tr> and at least one <td> element.
For an example see: https://github.com/CBIIT/national-biomedical-image-archive/blob/master/software/common/resources/branding/niams/quickLinks.xhtml

Other XHTML

There are no restrictions on XHTML for the welcome title/text or the footer.

Branding the NBIA Client

The NBIA Client is the new search interface for NBIA. Both the NBIA Client and the NBIA Classic interfaces are currently in production.

Branding files for the NBIA Client are in directories within the assets/brand directory. Each subdirectory represents one brand. Which brand directory to be used is determined by the content of the text file assets/brand/currentBrand, it should contain the name of a directory within assets/brand.

If there is no assets/brand/currentBrand file, or its contents don't point to a valid directory, the default brand "nbia" will be used.

If there are any files missing from the brand directory named in assets/brand/currentBrand, the file from the default directory will be used.

If you only want to change one aspect of a brand, only include that file. The default directory versions will be used for the others.

You can brand the following files.

The customMenu.json is an array, with each top-level object representing one top-level menu item, as follows.

Example of Branded Properties

[
    {
        "entryTitle": "Home",
        "menuData": {
            "target": "https://www.cancerimagingarchive.net"
        }
    },
    {
        "entryTitle": "News",
        "menuData": {
            "target": "https://www.cancerimagingarchive.net/news/"
        }
    },
    {
        "entryTitle": "About Us",
        "menuDataDropdown": [
            {
                "menuText": "About The Cancer Imaging Archive (TCIA)",
                "target": "https://www.cancerimagingarchive.net/about-the-cancer-imaging-archive-tcia"
            },
            {
                "menuText": "About the Cancer Imaging Program (CIP)",
                "target": "https://www.cancerimagingarchive.net/about-the-cancer-imaging-program-cip/"
            },
            {
                "menuText": "About the University of Arkansas for Medical Sciences (UAMS)",
                "target": "https://www.cancerimagingarchive.net/about-the-university-of-arkansas-for-medical-sciences-uams/"
            }
        ]
    },
...