Preview Mode
Preview Mode allows you to check the narrative generated by your project as you develop it. You can preview the entire narrative or selected fragments, which makes Preview Mode a valuable tool for checking your progress and identifying errors.
We have organized the topics into these sections:
Previewing the current script
To access Preview Mode, click the Preview button in the top right of the screen. If you do this while in the Compose view, Studio shows the output for the current script — that is, the one you've selected in the script panel.
You can access Preview Mode from outside the Compose view. Please note, however, that clicking Preview in the other views — for example, the Settings view — always previews the Main script. To preview any other script, you must select it while in the Compose view.
Tip
The Alt + p keyboard shortcut (Windows) also opens Preview Mode. Use Ctrl + ⌘ + p on a Mac.
Please see User Menu > Hot keys for a full list of keyboard shortcuts.
Previewing projects with a focus row
"Describe Each Row" and "Describe Row in Context" projects generate a separate narrative for each table row. Therefore, for these projects, the preview window includes extra buttons for navigating between narratives.
As shown above, you can navigate using the First, Prev, Next, and Last buttons. In addition, you can enter a specific row number. Note that the window also shows the data for the focus row, thereby allowing you to check for narrative accuracy.
Tip
You can also navigate using the left-arrow and right-arrow keys on your keyboard.
Previewing the Main script
When building or revising your project, you may need to check how changes to a subscript affect the narrative returned by the Main script. This task is made easier by the Preview Main option, which previews the Main script regardless of what script you're working in.
In the above example, the user fixes a problem with the Main narrative by making changes in the Performance script. Clicking the Preview Main button allows the user to check the changes without having to select the Main script first.
Tip
The Alt + m keyboard shortcut (Windows) also previews the Main script. Use Ctrl + ⌘ + m on a Mac.
Previewing selected content
To preview a specific portion of a script, select the content using click and drag before clicking Preview.
Be careful when previewing selected portions of a script containing script variables — i.e. user-created variables defined in the script. Errors may occur if you don't also include the ATL code defining the variables.
In the above example, clicking Preview would return a "variable not defined" error. This is because the selected ATL block (highlighted grey) uses the Q2results variable, which is defined in a non-selected part of the script.
To preview the output for the selected block (highlighted grey), you would need to re-do the selection to include the ATL defining the Q2results variable. This would mean selecting the entire ATL block at the top of the script, not just the line defining the variable.
Tip
You can avoid this problem by defining variables in the project's Variables view instead.
Error messages
Preview Mode helps you to debug your projects. When you preview a script that includes errors, the window splits in two, displaying the generated narrative text on the left side and a list of warning messages on the right. For example:
Note that the warning message provides the name of the script where the error resides, describes the error, and proposes a fix. In this case, there's a syntax error — a missing closing round bracket — in the SalesAgainstTarget script.
Important
Since the problem is a minor syntax error, Studio is still able to generate the intended narrative. This doesn't mean you can ignore the error. You must remove all syntax errors before you can publish the project.
The inclusion of the script name in the warning message is helpful because sometimes the error resides in a script other than the one you're previewing. This is shown in the example below:
Notice how Preview Mode identifies two major errors — one in the SalesAgainstTarget script, the other in SalesComparisonByQuarter — when the user first previews the Main script. This is because the Main script includes calls to those scripts in which the errors reside. The user fixes the errors and then uses the Preview Main option to confirm the effectiveness of each change.
Look again at the warning message from the last example:
Since these are major errors rather than minor syntax errors, Studio is unable to produce the intended narrative in full. Instead, it shows some narrative text along with the ATL blocks in which the errors reside. You can use this to find each error's location in the relevant script.
Console log
The Console log area appears when your project includes calls to the consolePrint function.
If a call to consolePrint executes when you preview, the resulting log entry appears in the area.
The log entries are for debugging purposes only and do NOT appear in the output narrative.
Also, you CANNOT see the log entries when you run the project in an external environment such as Studio Runner.
Important
If your project has calls to consolePrint but none execute when you preview — perhaps because they are in non-called scripts — the Console log appears but is empty.
Copying console log entries
When populated, the Console log area reduces the space available for the narrative preview. If working on a small screen, this may make the narrative preview difficult to read. If so, one option is to click the Copy to clipboard button, paste the content into another application (e.g. Word or Notepad++), and collapse the console log by clicking the arrow.
