Show TOC

Enabling Application BrandingLocate this document in the navigation structure

Use

The Web Resource Repository Branding API enables portal applications to expose their style resources, such as .css files or images, so that they can be customized by an administrator and adapted to different portal themes.

Branding resources are imported into the Application Branding folder in the Web Resource Repository. For each application that exposes branding resources, a dedicated folder is created that contains the application's branding resources.

The Branding API provides two main interfaces:

  • IBrandingImporter is used for importing application resources into the Application Branding folder

  • IBrandingLoader is used for loading branding resources by portal applications at runtime, according to the active portal theme

These interfaces are contained in the com.sap.portal.resource.repository.branding package.

The following examples illustrate how to use the API, as well as provide some implementation guidelines.

Importing Branding Resources

A portal application can import its style resources into the Application Branding so that they can be customized by portal administrators.

To do so, perform the following steps:

  1. Create a themes folder in your portal application's dist folder.

  2. Create a default folder in the themes folder.

  3. Place the resource that should be exposed in the Application Branding in the default folder.

    Note

    • The content of the default folder is used for all portal themes. If you want to provide theme-specific style resources for your application, create a folder with the specific theme ID under the themes folder and place the theme-specific resource in this folder.

    • There are no restrictions on the structure of the default folder; you can create any number of separate folders for resource files, as required.

    • The folder and resource file names may only include alphanumeric characters and the following special characters: _-.~() . Spaces and other special characters are not allowed.

  4. Start a resource import process as follows:

    Sample Code 
                            
//Getting an IBrandingImporter instance
IBrandingService brandingService = (IBrandingService) PortalRuntime
        .getRuntimeResources().getService(IBrandingService.KEY);
IBrandingImporter brandingImporter = brandingService.getBrandingImporter();

//Importing the branding resources
//you can get the application name from the portal service or component context
brandingImporter.importIfModified(namespace, mm_serviceContext.getApplicationName());
Note

  • You can also use the importIfModified method without the namespace parameter.

  • Although you can start an import process from your portal component code, we recommend that you do this during the initialization of a portal service, which is configured to start automatically. This way, the resources are imported before a portal component of your application is launched for the first time.

  • The branding infrastructure automatically detects changes to branding resources. If no resources have been changed, the importIfModified() method does nothing. If any resources have been changed, a new folder is created under the application branding context in the Web Resource Repository containing the resources.

  • The resource path used for loading branding resources is the path to the requested resource file relative to the themes/default folder in the application. For example, when loading the resource file located in <portal project root>>/dist/themes/default/my_resources/main.css , use the relative path /my_resources/main.css .

Loading Branding Resources

Branding resources that were imported into the Web Resource Repository can be accessed at runtime either by using their URIs or by including them in portal responses. This ensures that the most recent version of the branding resources is used. If any theme-specific resources are available for the current theme, these resources are used.

The following example illustrates how to load branding resources in a portal component implementation:

Sample Code 
                  //Creating a branding loader instance
IBrandingService brandingService = (IBrandingService) PortalRuntime
        .getRuntimeResources().getService(IBrandingService.KEY);
IBrandingLoader brandingLoader = brandingService.createBrandingLoader(
                        namespace, request.getComponentContext().getApplicationName(), request);

//Including a CSS in the response 
brandingLoader.includeResource("/my_resources/main.css", request, response);

//Using the resource URI
URI resourceURI = brandingLoader.getResourceURI("/my_resources/logo.png");
response.getWriter().write("<image src=\"" + resourceURI + "\"/>");
Note

You can load branding resources from other applications by passing the required application name when creating an instance of IBrandingLoader.

If you want your responses to be cached, be sure to set the caching headers after including the branding resources.

More Information