Overlays

The best-practice behavior for a view is to indicate when a scenario is executing, or when results are not available to be displayed.

The API provides built in overlay functionality for these two cases.

The Execution Overlay will hide the entire view's contents and instead show a spinner and a message. This will happen whenever one or more scenarios that are in use by the view are in some execution state (queued, paused, executing, and so forth).

A view considers a scenario to be in use if there is a ScenarioObserver registered against it. So the following example considers scenarios 0 and 1 as in use and will show the execution overlay if either of them are being executed:

var view = insight.getView();
view.withScenarios(0,1);

You can customize the look of the execution overlay using the CSS rule .execution-overlay. You can also make use of the following class that is added to the body when the overlay is activated, scenario-executing.

The No-Results Overlay is used mark areas of a view are dependent on result data. If the results are not available for a marked up area, then the area will be hidden and in its place will be an overlay saying no results available. The view will watch the state of each scenario and manage the visibility of the overlays but it is up to you to mark up areas of the page to show they are interested in result data and optionally specify which scenarios to watch.

To mark an area as dependent on results do the following:

<div class="if-results-available" style="display: none;"> 
	<!-- content -->
</div>

This will hide the content of the div whenever any scenario in the selection is executing. If you need to limit the scenarios that are watched for a particular area on the page, you can add the following optional attribute:

<div class="if-results-available" data-scenario="0" 
	style="display: none;">

This will only hide the contents of the area if the first scenario in the selection is executing. You can specify multiple, comma-separated, scenarios in the data-scenario attribute:

<div class="if-results-available" data-scenario="0,1,3" 
	style="display: none;">

In a similar way, you can configure an overlay to be shown whenever a scenario has no input data:

<div class="if-scenario-loaded" data-scenario="0" style="display: none;">

You can customize the style of the overlays using the CSS rules .no-results-overlay and .scenario-not-loaded-overlay.

The overlays are enabled by default but will only start taking effect when you have started the view:

var view = insight.getView();
view.start();

There are some basic configuration parameters available for the overlays. They allow you to enable/disable the overlays and change the messages presented to the end-user. Pass the options in to the View.configure() method, for example here are the defaults:

var view = insight.getView();
view.configure({
      noResultsOverlay: true, 
      noResultsMessage: 'no results available', 
      notLoadedOverlay: true, 
      notLoadedMessage: 'scenario not loaded', 
      executionOverlay: true,
      executionOverlayMessage: 'Please wait...'
});

Contents

Index

Glossary

Search Results

Overlays