rPath Appliance Platform Agent:Modifying raa-branding

From rPath Wiki

The package raa-branding controls the default branding for rPath Appliance Platform Agent, providing its default "look and feel" branded with rPath logos and information. This package installs the files related to branding in /usr/share/conary/web-common/apps/raa on the appliance.

rPath recommends that appliance developers use the guidelines provided in rPath Appliance Platform Agent:Branding to add customizations in custom configuration and directories instead of modifying the raa-branding package itself.

When appliance developers want a deeper level of branding customization, they can use the following sections as a guide.

Shadow and Check Out raa-branding

Shadow raa-branding to the development label matching your appliance development. Shadow from the same label from which your appliance includes the appliance agent.

The following command shadows raa-branding for rBuilder Online project example:

$> cvc shadow example.rpath.org@corp:devel raa-branding:source=raa.rpath.org@rpath:raa-2

Check out the shadow to examine the package and modify its contents as with adapting packages for an appliance. The following command checks out the package for project example in the corresponding context of the project's build environment:

$> cvc co raa-branding

Unpack and Examine the Source Tarball

Change to the package directory to list its contents. Verify the file raa-branding.tar.bz2 is listed. If this tarball file is missing, download it by cooking the recipe with the --download option:

$> cvc cook --download raa-branding.recipe

The download option places the tarball in the look-aside cache directory created when configuring the build environment. Move it to the current directory, such as in the following command:

$> mv ../../cache/raa-branding/download.rpath.com/raa/raa-branding-2.0.3.tar.bz2 .
$> ls
CONARY  raa-branding-2.0.3.tar.bz2  raa-branding.recipe

The upstream version (shown as 1.0.4 in the example) will vary depending on the version of rAP you are including. Unless otherwise specified, this will be the latest available version.

Unpack the tarball and change to the resulting raa-branding-<upstream_version> directory:

$> tar jxf raa-branding-2.0.3.tar.bz2 
$> cd raa-branding-2.0.3
$> ls
docs      MANIFEST.in  raa_branding.egg-info  README.branding
LICENSE   PKG-INFO     raaplugins             setup.cfg
Makefile  raa          README

Note the following contents of the source tarball:

Modify the Branding Files

Modify the files in the source tarball for raa-branding using the following sections as a reference.

Templates for Content Layout

rPath Appliance Platform Agent uses kid templates for content layout and presentation.

See the Templates page for information about the appliance agent templates.

Static Files for Images and Styles

Images, CSS files, HTML, and JavaScript used in branding rAP are located in a subdirectory of raa/content corresponding to the content type: css, html, images, javascript. Add and replace files appropriate to a new branding scheme to the appropriate locations in this directory.

Logos for an appliance correspond to the following rAP images:

• raa/content/images/corplogo.png : The organization logo with transparent background
• raa/content/images/corplogo_notrans.png : The organization logo
• raa/content/images/prodlogo.png : The project or product logo

Examine the contents of any file to learn more about the existing files of each type. Some examples include:

• raa/content/javascript/date-picker.js: The default JavaScript date picker
• raa/content/html/404.html: The default 404 error HTML page

Documentation

The default documentation set provided with rPath Appliance Platform is comprised of DocBook XML source files which are organized around usage explanation for the standard rPath Appliance Platform plugins. These files are located in the docs/userguide directory. The following table describes its existing content:

Add appliance documentation as desired to supplement the existing user guide material, or replace the existing material with custom content which allows the rPath Appliance Platform to use context-sensitive on-line help.

Additional Considerations

Some additional considerations for rPath Appliance Platform branding are:

• Do not modify the html id="" attributes, even if you have to modify JavaScript code.
• If you radically alter the page layout, you may have to modify some of the JavaScript code.

Test Changes

If you want to test changes actively while making modifications, ensuring each change renders correctly in the web interface, copy the modifications to the corresponding deployed location on a test system. If you are developing plugins, you can also test the changes alongside the plugin changes.

Repackage the Modifications

After you have made the changes to rAP web interface to incorporate your project's branding, recreate the source tarball and commit the changes to the shadowed raa-branding package.

Recreate the Source Tarball

Remove the existing tarball, then recreate the tarball from the modified directory:

>$ rm raa-branding-2.0.3.tar.bz2
>$ tar jcvf raa-branding-2.0.3.tar.bz2 raa-branding-2.0.3/

Modify the Package Recipe

Because the package recipe obtains the source tarball from a consistent location associated with the current version of the rPath Appliance Platform, modify the package recipe to use the new source tarball. In a text editor, open raa-branding.recipe and change the r.addArchive line to remove ftp://download.rpath.com/raa/ before the archive name code. The line should then read:

r.addArchive('%(name)s-%(version)s.tar.bz2')

Save and close the recipe file, then cook the recipe to ensure a successful cook before committing the changes to the project repository:

$> cvc cook raa-branding.recipe

Commit and Cook raa-branding

Use cvc add to add the modified source tarball to the items to be committed to the project repository, such as in the following command:

$> cvc add raa-branding-2.0.3.tar.bz2

Commit the modified source tarball and recipe to the project repository, and cook the raa-branding package:

$> cvc ci
$> cvc cook raa-branding

Verify the changeset is committed to the repository at the end of the cook, and verify the availability of the package:

$> conary rq raa-branding --full-versions
raa-branding=/raa.rpath.org@rpath:raa-2//example.rpath.org@corp:devel/2.0.3-1.0.1-1

Incorporate in an Appliance

The group recipe used to define the appliance includes either the [[rPath Appliance Platform Agent:Include with an Appliance|the rPath Appliance Platform packages]] or group-raa.

If the packages are specified separately, the recipe should have the following line to include raa-branding:

r.add('raa-branding')

If the custom raa-branding package is on a different label than the appliance group, specify the version string information appropriately in the r.add.

If group-raa is specified, be sure the method used is r.addAll:

r.addAll('group-raa')

Then, add the following line to the group recipe to replace the raa-branding pulled in by the group with the custom raa-branding (use the appropriate label in place of the example label shown):

r.replace('raa-branding', 'example.rpath.org@corp:devel')

Recook the appliance group to incorporate the new raa-branding package, even if recipe modifications were not necessary.