Integrating with Earthdata Tophat2

Tophat2 is a JavaScript widget that adds the NASA Earthdata DAAC navigation and optionally Status App updates and the Feedback Module to your site or application.

Tophat default_navn

Getting Started

To use Tophat2, include the Tophat2 JavaScript file from the Earthdata CDN on an HTML page with optional attributes.

Example configuration:

<script src="https://cdn.earthdata.nasa.gov/tophat2/tophat2.js" 
        id="earthdata-tophat-script"></script>

The CDN paths from which Tophat2 is distributed are as follows:

Operations (OPS) is at https://cdn.earthdata.nasa.gov/tophat2/tophat2.js. The OPS path is the endpoint for production-ready sites.
User Acceptance Testing (UAT) is at https://cdn.uat.earthdata.nasa.gov/tophat2/tophat2.js. It is advisable that UAT is used for testing the integration of a site with tophat2.

NB: The System Integraiton Test (SIT) instance of Tophat2 should neither be used for testing nor production-ready sites as it is prone to frequent and unannounced changes.

Configuration Parameters

Configurations parameters are set by specifying the value for that parameter directly in the script tag as an attribute, e.g., <script data-show-fbm='true'>.

List of all configuration parameters:

Option	Purpose	Options	Default Value	Required?
data-show-fbm	Show/hide Feedback Module	true,false	false	No
data-show-status	Show/hide Status Messages	true,false	false	No
data-current-daac	The name of the DAAC on which Tophat is being displayed, if applicable.	*	n/a	No
data-status-polling-interval	How often to poll the Status API, in minutes. Only applies if data-show-status is "true". Set to 0 if polling once on page load/refresh is sufficient. Otherwise, minimum value allowed is 10 minutes.	Integer	0	No
data-status-api-url	Overrides the default location from which notifications are retrieved for the current environment.	String	**	No
data-fbm-subject-line	Sets the Feedback Module Subject line.	String	The default subject will show up if this configuration is not included.	No
data-use-fontawesome	Overrides the usage of Font Awesome. If your site or application already uses this, you can disable Tophat2's import of it.	true, false	true	No
data-width	Allows setting a default width of TopHat content. Black background will still be full width.	Any value above 800 (no px needed)	n/a	No
data-layout	Sticky functionality for TopHat. TopHat will always be positioned at the top of the page.	Fixed	n/a	No
data-element-id	The optional element ID where Tophat2 will be created instead of being added as the first element after the `<body>`.	The target element ID	n/a	No
data-classes	Additional CSS classes to pass to the `.th-wrapper` element for adjusting or overriding styles (such as when using a responsive layout framework)	A list of CSS separated by spaces	n/a	No
data-show-outage-banner="true"	Show outage banners. If set to `true`, a prominent banner will be displayed under the main Tophat2 element for outage message that meet certain criteria.	true,false	false	No

* - The abbreviated DAAC name should be set here. For example the Alaska Satellite Facility DAAC (abbreviated as "ASF DAAC") would be set using data-current-daac="ASF DAAC". If this is set, the DAAC menu will display Other DAACs and the current DAAC will be highlighted. If this is not set, the DAAC menu will display Find a DAAC.

** - Default values for data-status-api-url are the following endpoints for each environment:

OPS: https://status.earthdata.nasa.gov/api/v1/notifications
UAT: https://status.uat.earthdata.nasa.gov/api/v1/notifications

Using Tophat2 With Feedback Module (optional)

Tophat with FBM

Tophat2 may optionally be configured to trigger the display of the Feedback Module (FBM) dialog as long FBM is already integrated with the site as described in the integration documentation here.

Once the FBM is configured, Tophat2's FBM button may be enabled by setting data-show-fbm="true" in the script tag. This displays the FBM button in Tophat2. The button, when clicked, will display the FBM dialog. You can also customize the Feedback message subject line by setting data-fbm-subject-line to any string.

If Feedback Module has already been set up and initialized for your application or site, you may want to change the initialization so that the side-loaded icon does not appear (see example below).

Example configuration:

 <script>
 // This prevents the FBM flyout banner from appearing on the side of the page.
feedback.init({showIcon: false});
</script>

<script src="https://cdn.earthdata.nasa.gov/tophat2/tophat2.js" 
        id="earthdata-tophat-script" 
        data-show-fbm="true" 
        data-fbm-subject-line="Help with my app"></script>

Using Tophat2 With Status App (optional)

Tophat with Status App and FBM

Tophat2 may optionally be configured to show status messages for the domain into which it is installed. This functionality requires the registration of a client application with the Earthdata Status App as described here.

Once the Status App registration is complete, Tophat2 notifications are enabled by setting the parameters as follows:

data-show-status to true
data-status-api-url to an endpoint that overrides the default Status App API endpoint (optional, useful only for testing)
data-status-polling-interval to an integer value indicating the interval in minutes between polling. If not set, polling only occurs on page load/refresh as was the case with the banner widget previously used by StatusApp. Otherwise, the minimum value is 10 minutes.

Example configuration:

<!-- In this example, we are overriding the API endpoint. -->
<script src="https://cdn.earthdata.nasa.gov/tophat2/tophat2.js"
        id="earthdata-tophat-script"
        data-show-status="true"
        data-status-api-url="https://status.uat.earthdata.nasa.gov/api/v1/notifications"
        data-status-polling-interval="10">
</script>

Attaching Tophat2 to a Custom Page Element

By default, Tophat2 is created as the first element after the <body> tag. If your site needs Tophat2 to be placed in a different element, such as in a specifc <div>, use the data-element-id attribute to specify the ID of the target element. It is recommended to give this element an id of something like "custom-tophat2-element" to avoid confusion. An id of "earthdata-tophat2" should not be used, as this is assigned to the Tophat2 widget itself and will prevent Tophat2 from rendering.

Example configuration:


<div id="custom-tophat2-element">
  <!-- Tophat2 will go here -->
</div>

<script src="https://cdn.earthdata.nasa.gov/tophat2/tophat2.js"
        id="earthdata-tophat-script"        
        data-element-id="custom-tophat2-element">
</script>

Outage Banners

Tophat2 can optionally display important outage notifications as a prominent banner. To enable this feature, data-show-outage-banner="true" must be added as an attribute to the Tophat2 script tag.

Example configuration:

<script src="https://cdn.earthdata.nasa.gov/tophat2/tophat2.js"
        id="earthdata-tophat-script"    
        data-show-outage-banner="true">
</script>

How To Display an Outage Banner

When posting notifications in Status App:
- Notifications must be of the type "Outage"
- The outage notification with no start/end time or the earliest start time will be shown as the banner
- Outage notifications posted via trusted partner will not be displayed as a banner. For example, if an outage is posted to EDSC and additionally to DAAC A as a trusted partner, the banner will only be displayed in EDSC (the outage message will still be displayed in the bell on the DAAC A site)

How Outage Banners Work

When a page is first loaded or when the user navigates througout the site, only an outage message for that site will be shown as a banner; no other messages will be displayed as a banner
Clicking on the "Dismiss" link within this banner message will prevent further automatic display of the banner in the current session (the banner will be shown again if a new window or tab is opened for that site/application).
Clicking on the body of the page, the bell, the outage message or any other area beside the "Dismiss" link will only close the outage banner temporarily, and subsequent page reloads or navigation will still result in automatic display of the banner until the user clicks the "Dismiss" link.
When the user clicks the bell to see all notifications, the outage banner will continue to be visible as the top-most message. The "Dismiss" link will not be present within the banner message when opened this way.
Outage messages from trusted applications stay in the status bell
When there are multiple outage messages:
- IMPORTANT: It is not recommended to have more than one outage message. Instead, consider combining if messages are important.
- If there is an outage message with no start time, then that will be the message shown.
- If there are multiple outage messages without a start time, the one with the earliest creation time will be the one shown.
- If all outage messages have a start time, then the one with the earliest start time will be shown as the banner

Troubleshooting

Conflicts with Font Awesome

Tophat2 uses Font Awesome for some features. If your site or application already uses this, there is a possibility that it could cause conflicts. To fix this, you can turn off Tophat2's import of FontAwesome by setting data-use-fontawesome to "false". By default, Tophat2 will always import Font Awesome and it is not necessary to include this configuration parameter in the script tag unless you want to disable this.

Preventing Page Jumps

Though not required, in order to prevent the page from jumping down after the content loads, it is recommended to place a <div> with the id set to "earthdata-tophat" as the first element in the page immediately after the <body> tag, e.g.:

<body>
  <div id="earthdata-tophat2" style="height: 32px;"></div>
</body>