App Header

Deprecation Warning! The content below is only applicable for use within deprecated 1.x versions of CA Agile Central's App SDK. Use of the component(s) and/or code on this page is not supported. To develop custom apps within our current environments, please see App SDK 2.0 documentation.

The App Header provides a consistently styled banner for apps and exposes common items like a title, page tools, and help.
Apps built using the SDK are automatically decorated with the component.

app header

The App Header is comprised of five items:

  • AppBadge
  • AppTitle
  • AppMessage
  • PageTools
  • Help

AppBadge

AppBadge displays information about the author of an app. It is automatically added to the App Header and configured based on the vendor of the AppInfo object returned from rally.sdk.util.Context.getAppInfo().

There are currently four types of badges:

Icon Type Hover Text Description
customer Customer Created by Customer: [customer] An app created by a CA Agile Central customer.
partner Partner Created by Partner: [partner] An app created by a CA Agile Central Software partner.
rally CA Agile Central Created by CA Agile Central An app created by CA Agile Central Software.
labs CA Agile Central Labs Created by CA Agile Central Labs An experimental app created by CA Agile Central Software.

AppTitle

AppTitle displays the title of an app in a consistent look and feel. It is automatically added to the App Header and configured based on the title of the AppInfo object returned from rally.sdk.util.Context.getAppInfo().

AppMessage

AppMessage displays a custom message flare centered in the header. Info (green), Warning (yellow) and Error (red) messages are supported.

PageTools

PageTools displays a page tools drop-down. It is automatically added to the App Header and configured with one built-in action: Print. The page tools drop-down is hidden by default.

Help

Help displays a clickable help icon. It is automatically added to the App Header and is hidden by default.

Usage

An instance of rally.sdk.ui.Header is automatically instantiated and displayed at the top of an app's body element on load when the App SDK javascript is included:

<script type="text/javascript" src="/apps/[version]/sdk.js"></script>

A reference to this single instance is exposed as rally.sdk.ui.AppHeader.

var header = rally.sdk.ui.AppHeader;

Methods

Method Name Parameters Description Example
addPageTool pageTool Add the specified page tool to the page tools menu.
The page tools component will automatically display.
The following built-in tools are available:

rally.sdk.ui.PageTools.BuiltIn.Print

rally.sdk.ui.PageTools.BuiltIn.OpenInNewWindow
header.addPageTool({
   key:"helloWorld",
   label: "Hello World!",
   onClick: function() {
     alert("Hello World!");
   } });
getPageTools - Get the array of items currently contained in the page tools menu. By default, this will contain one item: Print. header.getPageTools();
removePageTool pageTool Remove the specified page tool from the menu. The parameter may be either the key which it was originally added or the page tool object itself. header.removePageTool("helloWorld");
setHelpTopic helpTopic Set the help topic path in CA Agile Central's help system. The help component will automatically display. header.setHelpTopic("/display/mshtk/App+SDK");
setHelpUrl helpUrl Set the full help url. The help component will automatically display. This is useful for documenting customer-developed apps. header.setHelpUrl("http://www.acme.com/help");
showMessage type, message Display the specified message in the center of the app header. header.showMessage("error", "Oops!");
showPageTools visible Show or hide the page tools component. header.showPageTools(true);
display element Display the header in the specified element. Called automatically on app load. header.display(document.body);
destroy - Recursively destroy all child components and completely remove the header from its container. header.destroy();
addComponent component Add the specified component to the header.
The component should contain a key property to identify it and specify display and destroy methods to add or remove it.
header.addComponent({
   key:"myComponent",
   display: function(element) {
    //Add to element
   }
   destroy: function() {
    //Clean up and remove
   }
});
getComponents - Returns an object containing all components accessible by the key with which each was added. var myComponent = header.getComponents()["myComponent"];
getComponent - Get a specific component by the key with which it was added. var myComponent = header.getComponent("myComponent");
getBadge - Get the Badge component. var badge = header.getBadge();
getHelp - Get the Help component. var badge = header.getHelp();
getPageTools - Get the Page Tools component. var badge = header.getPageTools();
getTitle - Get the Title component. var badge = header.getTitle();
removeComponent component Remove the specified component from the header. The parameter may be either the key which which it was originally added or the component object itself. header.removeComponent("myComponent");
showHelp visible Show or hide the help component. This method internally calls getHelp().show(); header.showHelp(true);

Example

Copy and paste the following into a CA Agile Central Custom app page.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
    <title>App Header Example</title>
    <meta name="Name" content="App Example: App Header" />
    <meta name="Version" content="2010.4" />
    <meta name="Vendor" content="CA Agile Central Software" />

    <script type="text/javascript" src="/apps/1.26/sdk.js"></script>

    <script type="text/javascript">

       function updateAppHeader() {

          var helloWorldPageTool = function() {
             alert("Hello world!");
          };

          rally.sdk.ui.AppHeader.addPageTool({
             key:"helloWorld",
             label: "Hello World!",
             onClick: helloWorldPageTool
          });

          rally.sdk.ui.AppHeader.setHelpUrl("https://rally1.rallydev.com/slm");

          rally.sdk.ui.AppHeader.showMessage("error", "Oops!");
       }

       rally.addOnLoad(updateAppHeader);
    </script>
</head>
<body>
    <div>My App Goes Here</div>
</body>
</html>