Each JMP platform generates a unique display, but there are common features and common objects in the report layout. The most familiar feature in a JMP report is the outline box. Most JMP users have probably edited an outline box title or toggled the button to show or hide the graphs and analyses belonging to that outline box.
The next step is to learn the JSL equivalents of these user interface tasks, like changing the outline box title or toggling the disclosure icon ◢.
There are two specific skills required to edit the Report Layer. One is using the valid JSL messages and syntax appropriate for the targeted display feature. The other is finding the address of the feature to be changed. We call this last skill navigation.
Show Tree Structure
Navigation almost always begins with a map. Run the following script to generate a report. Then, right-click on the disclosure icon ◢ located left of the outline box titled “Oneway Analysis of height By sex.” Select Edit ► Show Tree Structure. (See Figure 6.5.)
bigclass_dt = Open( "$SAMPLE_DATA/Big Class.jmp" );
bigclass_ht_onew = bigclass_dt << Oneway(
Y( :height ), X( :sex ), Ignore Platform Preferences( 1 ),
Box Plots( 1 ), Means and Std Dev( 1 ), X Axis Proportional( 0 ),
Mean Error Bars( 0 ), Std Dev Lines( 0 )
);
Figure 6.5 Edit Menu—Show Tree Structure: (L) Entire Report (R) Y-Axis
The tree structure is shown in a new window. It is a nested, hierarchical list (yes, a list) of outline boxes, where each outline box represents a JMP display box used in the report. Because the top-most reveal button was selected, the tree structure for the entire report is shown. You need to scroll down to see the full tree structure. Figure 6.6 (L) displays this tree structure after right-clicking on the top reveal button, selecting Close All Below, and then selectively opening a few items.
Figure 6.6 Tree Structure: Linked Report with FrameBox(1) Highlighted
 |  |
Line up the tree structure window and the one-way report. Hover your mouse on the reveal button for FrameBox(1) and see the corresponding display highlighted in the one-way report. See Figure 6.6 (R). Note the list of IfBox( ) items in the tree. Hover on each reveal icon. IfBox(1) contains the outline for the graph portion of the display. IfBox(4) corresponds to the Means and Std Deviations table. The IfBox container displays or hides its contents based upon the object options: if the Boolean option is specified, display; if not, hide.
Each disclosure icon in the report window has the same user interface. This enables the user to show the tree structure for a smaller portion of the report window. Figure 6.5 (R) shows that right-clicking on a report window feature like the Y-axis displays a menu (Edit ► Show Tree Structure). In other words, the tree structure can be requested for more than outline boxes.
Close the tree structure for the entire report. Right-click on the reveal button to the left of the outline box titled “Means and Std Deviations” and create the tree structure. Repeat the same steps, but this time hold down the SHIFT key while selecting Show Tree Structure. See Figure 6.7.
Figure 6.7 Oneway Analysis Means and Std Deviations Tree Structure – Interactive Default Format (L) Classic Format (R)
 |  |
Both tree structure formats display the objects used to arrange the output. Each object has the word “box” in its name (for example, OutlineBox, TableBox, StringColBox, and NumberColBox). For both formats, the arrangement of the objects is a nested, hierarchical structure. The interactive default tree structure (L) is reminiscent of an outline. The classic format (R) is reminiscent of an organizational (org) chart.
The interactive highlighting of the default tree structure is useful to match the report to its component display boxes. However, it is long and it can be difficult to discern the basic structure until strategically selected disclosure icons are closed. Using the classic format tree structure can make it easier to see the relationships of objects in the report. For example, the relationship of NumberColBox(6) to TableBox(1) is immediate in this org chart like display.
Both formats are informative. Sometimes we look at both. For either format, the tree structure for a portion of the report will be easier to read than the tree structure for the entire report.
Reference the Report Layer
A change to the Analysis Layer requires that a valid message be sent to the platform object or the reference object for that platform. For the current example, the platform is Oneway, and the handle to it is the variable reference bigclass_ht_onew.
//Message to the Analysis Layer
bigclass_ht_onew << Points Jittered(1);
Similarly, to change the display objects, a valid message must be sent to the Report Layer. The two ways to assign a variable reference to the Report Layer are the following:
//These two lines assign a variable name to the report,
//either syntax is acceptable
rpt_bc_ht_onew = Report( bigclass_ht_onew );
rpt_bc_ht_onew = bigclass_ht_onew << Report;
To change a display feature, the valid message must be sent to the display object’s address. The Report message (or function) returns an address for the targeted display object. For both of the previous examples, rpt_bc_ht_onew stores the address for the Oneway Analysis display, the Oneway report layer. Review the outline box messages shown in Figure 6.5 (L). Using the report address, the nesting and addresses of the boxes seen in the tree structure, this next set of statements should be apparent:
bigclass_ht_onew << Bring Window to Front;
//line up this script and this window, run 1 line at a time
rpt_bc_ht_onew[OutlineBox(1)] << Close;
rpt_bc_ht_onew[OutlineBox(1)] << Open All Below;
rpt_bc_ht_onew[OutlineBox(1)] << Close(1);
rpt_bc_ht_onew[OutlineBox(1)] << Close(0);Each display object (OutlineBox, TableBox, StringColBox) belongs to a broader classification called display box. The name OutlineBox (or NumberColBox, etc.) is an object’s class name. A critical skill to learn is traversing the tree structure, which is discussed in the section “Navigate a Report” in this chapter.
JMP makes it easy to find valid messages for most display box objects. From the JMP Scripting Index, select Display Box ► OutlineBox. First, notice the messages that are common with the list of menu options shown in Figure 6.5. Find the message Close. Its description states that this message has a Boolean argument. Look at the sample scripts for Get Title and Set Title, and run the following JSL statement:
rpt_bc_ht_onew[OutlineBox(1)] << Set Title("Limit Mousing via JSL");Congratulations! You’ve just learned the JSL equivalents to reveal or hide, and to change the title of an outline box.
We offer one more useful skill before leaving this section: the ability to select and deselect parts of the Report Layer using the messages Select and Deselect. These two messages are available for every type of display box and can be used to highlight a portion of the display. Here we use these two messages to test whether the address for a display box is correct before changing the display box. Here is a snippet from 6_ReportLayer.jsl with scripted delays to see the selection process:
rpt_bc_ht_onew[TableBox(1)] << Select;
wait(2);
rpt_bc_ht_onew[TableBox(1)] << Deselect;
rpt_bc_ht_onew[TableBox(1)][NumberColBox("Std Dev")] << Select;
wait(2);
rpt_bc_ht_onew[TableBox(1)][NumberColBox("Std Dev")] << Deselect;
The last pair of Select and Deselect statements is a preview of report navigation, which is described in the section “Navigate a Report.” The location of the display box to be selected can be found by starting at the top of the report, and then moving down to TableBox(1). Within the TableBox(1) subordinates, you will find the NumberColBox labeled Std Dev.
Generating a report and finding valid messages for display box objects is straightforward: use the Scripting Index for Display Box. Navigating a simple report can be straightforward as well. But, there is more to learn, and navigation can get tricky when the report is more complex or when the analysis involves many Y, X, and By columns. The next section, “Display Box Scripting,” recommends a reading list to tackle the long list of display boxes and their messages.
The content of this blog was condensed from an excerpt of our book, JSL Companion: Applications of the JMP® Scripting Language, Second Edition, where you will find more techniques and examples of working with the JMP scripting language.