Chapter 6: The Dashboard and Application Builders

Overview

Combine Windows, the Dashboard Builder, and the Application Builder

Combine Windows

Dashboard Builder

Application Builder

Summary

 

There are tools built into JMP software that can accelerate your progress when creating reports, dashboards, and applications.  In this chapter, we discuss the following:

●        building reports and dashboards using the interactive method, Combine Windows

●        creating custom dashboards using the Dashboard Builder

●        using the features of the Application Builder for application development

If you love building complicated custom windows and reports from scratch, that’s fine. However, JMP provides you with some much easier options through the Application Builder and its related platforms.

There are three major features of the Application Builder suite of tools: 

●        Combine Windows is a feature that enables the user to combine reports and tables seen on the screen into one report, which can then be used as a combination report or dashboard as is, or edited in the Application Builder with the click of a button. The report generated is sometimes called an instant application because it is so easy to create.  The Combine Windows feature is a great way to build a simple report or dashboard, or to initiate the report building and customization process using the Dashboard Builder or Application Builder later.

●        The Dashboard Builder is a specialized form of the Application Builder with which you create your own dashboard  by combining windows and reports from the JMP desktop or using a series of templates.  The Dashboard Builder requires no scripting.

●        The Application Builder is a platform in JMP that provides an interface to easily combine reports and windows by clicking, dragging, and dropping reports and dependent data tables within a console.  This feature was initially conceived and developed to ease the complexity of building custom JSL applications from scratch.

All these software features enable you to develop a report, dashboard, or application with an underlying script that can be used to re-create it.  Scripting the display boxes in a custom window can be a very tedious and iterative process. In contrast, using Combine Windows, the Dashboard Builder, or the Application Builder makes the task so much easier.  The following sections provide more details about each of the three time-saving features.

Using the Combine Windows feature is the easiest way to combine reports and data table windows generated by JMP. 

Keep in mind that JMP will attempt to combine the windows in exactly the same configuration as you see on the screen. So to save yourself trouble later, be sure to align the windows as you want to see them in the final combined report.

In this example, we show how to combine two reports into one window:

1.       Arrange the reports in the configuration that you want to show in the report (see Figure 6.1).  JMP will do its best to keep the configuration as shown on the desktop.

Figure 6.1 Arrange Windows

2.       Place a check in each window box for those selected for the combined report.

Figure 6.2 Check Boxes for Windows

3.      Click the black arrow of one of the windows and select Combine Windows from the drop-down menu.

Figure 6.3 Select Combine Windows Option

 

4.       In the resulting dialog, enter a title for your combined report, and then click OK.

Figure 6.4 Combine Windows Dialog

5.       The combined report is created.

Figure 6.5 Report from Combining Windows

 

 

6.       If you want to save a script of the report or edit the report in the Dashboard Builder or Application Builder, click the red triangle in the upper left corner of the report to display the menu with options. 

Figure 6.6 Option for Editing

Using Combine Windows is one way to create a dashboard or instant application.  Keep in mind that the dashboard or application is dependent on the columns in the data table used for its construction.  Using a different table when invoking the dashboard or script will likely result in errors.

Next, we will show you another way to build a dashboard.

The Dashboard Builder makes it easy to build a dashboard from your open reports and tables.  The interface offers several templates to choose from, and all you have to do is drag and drop into the configuration that you selected.  No scripting is needed.

Open the Dashboard Builder by selecting File ► New ► Dashboard.  The interface that opens offers Custom Templates where you can save templates that you create, Templates in multiple configurations that JMP provides, and Samples where you can explore ready-built dashboards.

Figure 6.7 The Dashboard Builder Template Gallery

An example is the best way to show how it works.  Using weather data from various stations around the US, we will we create a graph of the stations to use as a filter on another graph that shows temperature highs, lows, and means over time for the stations. The Filter + 1 Dashboard template is the best option for our purposes.

1.       Open the sample data table, Weekly Weather Data.jmp, from the sample data directory.

2.       Execute the script named Weather Station Locations, which is embedded in the data table.

 

Figure 6.8  Run Weather Station Locations Script

Figure 6.9 Weather Station Locations Graph

3.       Create a graph showing the temperature highs, lows, and averages using Graph Builder:

a.   Open Graph Builder by selecting Graph ► Graph Builder.

b.   Drag and drop the DATE variable onto the X axis.

c.   Select TMIN, TMAX, and TAVG, and then drag them all and drop onto the Y axis.

d.   Click the Done button.

Figure 6.10 Temperature Graph

4.       Open the Dashboard Builder (File ► New ► Dashboard), and then click the Filter + 1 Dashboard template.

5.       On the left, under Sources, are the two graphs created earlier.  On the right is the grid that holds the chosen template.

Figure 6.11  Dashboard Builder Main Window

6.       Drag and drop the graph with the US map with the weather station locations into the left box of the template, which contains the filter symbol.  Then drag and drop the temperature graph into the box on the right side of the template.  The plots should snap into place.

Figure 6.12 Dashboard Builder with Graphs in Place

7.       Launch the dashboard by clicking the red triangle icon and selecting Run Dashboard (for more information about the red triangle menu items, see the topic in the Application Builder section that follows).  Another option is to click the Run Script button in the toolbar menu to launch the dashboard (see Figure 6.34).

Figure 6.13 Run Dashboard

 

The dashboard appears in a new window.  Click any of the station dots in the US Map graph to filter the temperature graph.

Figure 6.14 Weather Dashboard

8.       To create a copy of the dashboard script, click the upper left red triangle and select Save Script from the menu.

Figure 6.15 Save the Dashboard Script

There are multiple options for saving a script of your dashboard.  A script can be saved to the data table, a journal, a script window, or an add-in.  If you think you might use the dashboard as the starting point for other dashboards in the future, save it as a template.  Your custom template scripts are listed when you open a new dashboard or application (File► New ► Dashboard, or File ► New ► Application).

9.       You have three options when saving your dashboard as a file from the File ► Save As menu: 

a.   A JMP Source File (.jmpappsource):  When you have your application saved as this file type and then open it, the dashboard opens in the Dashboard Builder, where you can continue to build your dashboard. 

 

b.   A JMP Application File (.jmpapp): When you have your application saved as this file type and then open it, the dashboard opens as the dashboard application.  Consider this file for the finished product.

c.   A JMP Script: This last option saves your dashboard as a script.  After opening the script file, you can execute the script to bring up the dashboard in the Dashboard Builder.

Figure 6.16 File Type Options When Saving a Dashboard

For more information about using the Dashboard Builder, please see the “Display Trees” chapter in the Scripting Guide (Help ► Books ► Scripting Guide).

If you are looking to build an application that is more complex than a dashboard or instant application, use the feature-rich Application Builder.  Scripting an application from scratch can be very tedious, especially when trying to arrange and space display boxes to look good.  The Application Builder makes the task a snap.

The interface for the Application Builder is much like the Dashboard Builder, but there are many more options.  Whereas the Dashboard Builder shows a few display boxes or containers for dragging and dropping into the workspace, the Application Builder offers more than a dozen.  Also, a  couple of important features of the Application Builder are the modules and the script windows for each.  You will not see these in the Dashboard Builder interface. 

Application Builder Interface

A good place to start is to open the platform and take a tour of the features.

First, open the sample data table, Big Class.jmp, and then run the table scripts for Distribution and Bivariate.  These two reports will be used in the example.

 

To create a new instance of the Application Builder, select File► New ► Application:

Figure 6.17 Open the Application Builder

The first window that opens offers a gallery of options:

1.       Custom templates (optional):  If you save your application as a template after you build it, an icon is saved to this area.  You will not see this heading unless you have purposefully saved your dashboard or application as a template previously.

2.       Templates: These are the built-in templates that come with JMP.  All of these templates, except one, open in the Dashboard Builder, which is a streamlined version of the Application Builder.  The Blank Application template opens in the Application Builder.

3.       Samples:  JMP offers several sample applications.  Choose one to see how a particular application was built or scripted, and execute it to observe how it works.  If you learn best by looking at examples, be sure to open these sample applications and explore how they were implemented.

Figure 6.18 The Template Gallery

Click the icon for the Blank Application to view the Application Builder interface.

Figure 6.19 Blank Application

After you click the Blank Application icon, the builder opens.  Here is where all your tools are laid out to create your application. Notice how the window is divided into three main panels: Sources, the workspace, and Objects/Properties.

Figure 6.20 The Three Panels of the Application Builder Window

Sources Panel

The Sources panel ❶ displays the potential building blocks of your application.  It shows what you can drag and drop into the workspace ❷.  The Objects and Properties panels ❸, which provide information about object placement and object properties, respectively, will be examined a bit later. All reports that are open in JMP are displayed as thumbnails under the heading Reports.  In Figure 6.20, two reports, Bivariate and Distribution, are open in JMP and are displayed under the Reports heading.  Any report shown can be used in your application.  However, keep in mind that custom windows cannot be used in the Application Builder and are not shown in the report list.

Under the Data Table heading, there are four boxes related to data tables.  Use the first one to drag and drop a copy of the current data table into the workspace.  The other three boxes facilitate filtering, including hierarchical filtering in an application.

The Containers section displays choices of display boxes that hold or contain other objects, which are essential in establishing the configuration of elements in your application.  The other categories of sources are Spacers, Display, Tables, Buttons, and Input.  The list is long, so be sure to scroll down the entire Sources panel to view all the choices available.

Right-click any box in the Sources panel, and then click Scripting Help to open the Scripting Index, which displays information about that particular object.

Workspace Panel

The workspace panel is where you can get creative and design your application.  Roll up your sleeves and start dragging and dropping containers, reports, data tables, and more into the workspace to build your application.

But first, look at the tabs at the top of the workspace.  You will see the first tab is named Scripts and the second is Module1.

Module: A module is a container for objects in your application.  You can have more than one module.  To add modules, click the Add Module icon to the right of the Module tab or tabs.  The default names are Module1, Module2, and so on, but you can edit the names to specify something more meaningful, depending on the purpose of the application you are building.  Clicking on the different Module tabs exposes the workspace for each.  Each module can represent a window for your application, and each module creates a separate namespace.  The variables in each module namespace are not visible to other module namespaces. It is a great way to compartmentalize an application and prevent collisions of variables. 

Scripts: If your application is not as simple as a dashboard, scripting behind the scenes might be required.  If you click the tab named Scripts, you will see a Namespace drop-down menu where you can select the script for each module or for the application level. 

Figure 6.21 Namespace Drop-down Menu

Select each and notice how each Script tab window contains helpful comments to get you started. 

Figure 6.22 Script Tab Window

Each  module script displays a rudimentary OnModuleLoad function and also a command to create an instance of the module. 

Figure 6.23 Built-In OnModuleLoad Function

To view a good example showing passing parameters using the OnModuleLoad function, open the Graph Launcher application from the Sample Applications Directory, select the Scripts tab, and examine the LaunchModule and Graph Module scripts.

Click Application in the Namespace drop-down menu.

Figure 6.24 Application Script

It is helpful to understand the hierarchy of the application and module scripts. Each module has its own namespace, and the application namespace encompasses all the modules. If you declare a variable at the application level, it is global or visible to all module namespaces. In the Figure 6.25 schematic, the variable x is declared and initialized at the application level. Therefore, x is global to all three modules.

Figure 6.25  The Application Namespace

The Method menu offers a way to skip down to a variable declaration, function, or expression. This is especially useful if the module script is long.  In Figure 6.26, the module named LaunchModule shows five declarations, and by using the Method drop-down menu, you can easily get to the script area of one of the listed declarations by selecting the name.

Figure 6.26 Method Menu

Objects and Properties Panels

The third area of the Application Builder window, on the far right, consists of two sections:  the Objects panel and the Properties panel.  The Objects panel displays the contents of the application, including the objects of each module that you have placed into the workspace.  What you see is a hierarchy or tree structure.  This gives you a visual representation of the relationships of the objects to each other.  By clicking on the gray disclosure triangles, you can fully expand the tree, as Figure 6.27 shows.

Figure 6.27 Objects Tree

You can right-click any object in the tree structure to bring up a context menu where you can choose an action:

Menu Item	Action
Move to Corner	Moves the selected item to upper left corner of the workspace.
Align	Provides options to move the item left, center, right, top, middle, and bottom.
Change Container	Swaps out the selected item for a container of your choosing.
Add Container	Wraps the selected item in container of your choosing.
Use as Selection Filter	Specifies to use the selected report as a filter for other reports in the window.
Scripting Help	Brings up explanatory information about the selected item.
Module	Shows options for adding and deleting modules.
Edit Platform Script	Opens a script window where you can edit the selected platform script.
Copy	Copies the selected item to the clipboard.
Cut	Copies the selected item to the clipboard and deletes it.
Paste	Pastes the selection from the clipboard.
Delete	Deletes the selected item.

 

Figure 6.28  Objects Tree Context Menu

This context menu is also available when you right-click a selected item in the workspace.

If you select an object in the Objects panel or workspace, the properties of the object are shown in the Properties panel.

Figure 6.29 Properties Panel

The Properties panel is where you can change the variable name for the object from the given default, view and edit positioning information regarding the object, specify properties or characteristics for the object in the Edit area, and change box limitations in the Display Box area. 

If you click a module in the Objects tree, you can see in its Properties panel several properties, including those for name, title, and windows resizing.

Figure 6.30 Select Module to Show Properties

 

Here are two important properties to note:

1.       Module Type: Here is where you can choose from one of six types of displays for this module, as shown in Figure 6.31:

Figure 6.31 Module Type

 

For example, if your module’s function is to query the user, consider specifying the module type as Dialog.  The sample application Data Table Application.jmpappsource shows an example of a Dialog module type. If a window menu is needed, specify Dialog with Menu.

Another option is Modal Dialog, which is much like the modal New Window function.  However, there are differences, as the Modal Dialog module type has some special characteristics in the context of the Application Builder.  Consult the “Creating Applications” chapter in the Scripting Guide for more information about this topic.

If you need a platform-type launcher that generates a report, use a Launcher module type, paired with a Report module type.  The sample application Launcher Report.jmpappsource provides an example of casting data table columns into roles in the Launcher module, and then the Report module creates the graph.

2.       Auto Launch:  This setting determines whether the module instance is automatically executed when the application is invoked (selected), or if the module instance is conditionally executed by scripting action (unselected). 

For example, if you have a Launcher and Report module combo, the Launcher module will be set to automatically launch (Auto Launch is selected) when the application is run.  The Report module will not be selected to automatically launch, because its instance should not occur until the Launcher module conditionally calls it.

Figure 6.32 Auto Launch

The Application Red Triangle Menu

The red triangle menu for the Application Builder offers the option to run the application so that you can see whether it works as you wish, or to use the debugger to investigate issues.  You can also modify the design area grid and panels from this menu.  The following table itemizes and briefly explains the menu items:

Menu Item	Action
Run Application	Executes the application program.
Debug Application	Executes the application in debugger mode.
Start Over	Closes the current window and returns to the template window for the selection.
Snap to Grid	Restricts the design area grid to 10 x 10. *
Show Grid	Shows a grid in the design area. *
Show Properties	Exposes the Objects and Properties panels. *
Auto Scroll	Scrolls the workspace design area if a box is dragged to the bottom of the screen. *
Dashboard Mode	Arranges a report within the window and decreases the options shown. **
Source Panel	Offers options to Show Sources and Group by Category.
Save Script	Saves the application script to a specified destination.

*On by default but can be toggled off from the menu.

**Off by default when using the Application Builder.

The options for saving a script of your application are the same as with the dashboard.  A script can be saved to the data table, a journal, a script window, or an add-in.  If you think you might use the application as the starting point for future applications, save it as a template to decrease your development work.  Your custom template scripts are listed when you open a new dashboard or application (File ► New ► Dashboard, or File ► New ► Application).

Figure 6.33 Red Triangle Menu and Save Script Options

Using the Toolbar, Saving Applications, and Accessing Sample Applications

The toolbar at the top of the Application Builder has many features to make building your application easier with the click of a button.  You can hold your mouse pointer over each icon to display its role.  Keep in mind that one or more objects must be selected in the workspace for most of the buttons to be active.  Clicking in the Objects or Properties panel dims all buttons except Open and Save.

Figure 6.34 The Application Builder Toolbar

On the far left are the Open and Save icons ❶, for opening and saving other applications or saving the current application.

Just to the right are the Cut, Copy, and Paste icons ❷, which are used to perform these actions on components of your workspaces.

Next are the script-related buttons ❸. Use the Run Script button to execute your application script or a portion thereof. Use the other button, Debug Script, to start the JMP Debugger if you have encountered issues and need a little help determining where the problem lies.

Although you can add or delete modules from the workspace tabs, another option is to use the toolbar buttons for those actions ❹.

When you are working with lots of display boxes, it is nice to have an easy method for aligning them, and here are the buttons that will take the guesswork out of that task.  You can align left, right, center, horizontal, and vertical ❺.

The toolbar also offers buttons for adding thirteen different containers ❻.  Hold your mouse pointer over any container if you are unsure which container it might be.  Select an object or objects in your workspace to highlight, and then click the container button of choice to wrap the selected object or objects in that chosen container.

The last button in the toolbar is the Peel button ❼, which is so handy if you have added a container and then have second thoughts about it.  If you need to remove a container, select it in the workspace or Objects tree, and then click the Peel button to delete it. 

Saving Your Application as a File

You have the same three options when saving your application as a file from the File ► Save As menu as you do when saving a dashboard. You can save the file as a JMP Source File (.jmpappsource),  a JMP Application File (.jmpapp), or a JMP Script (.jsl). For more details, see step 9 in the “Dashboard Builder” topic in this chapter.

Figure 6.35 File Type Options When Saving an Application

This is just a brief introduction and exploration of  the Application Builder.  For more comprehensive information, please visit the “Creating Applications” section of the Scripting Guide (Help ►Books ►Scripting Guide). 

As mentioned earlier, you can access example applications when opening a new blank application, but these examples can also be found in the Sample Applications Directory. To access the examples, select  Help ► Sample Data, and then click Open the Sample Applications Directory.

Figure 6.36 Opening the Sample Applications Directory

This brief exploration of the Application Builder suite of tools has shown you how these platforms can be used when creating reports, dashboards, and applications. By clicking, dragging, and dropping, sometimes with little or no scripting, you can save time and effort. 

Next, we will discuss some advanced scripting concepts to help you understand the scripting language.