Referencing Visualizations

Before you can perform any operation on a specific visualization, such as changing it’s title, you must set a reference to this visualization in your script. This can be accomplished in a couple ways, each of which may be needed in different scenarios.

Adding a Visualization as a Script Parameter

This is the easiest method if you know which specific visualization or set of visualizations your script will always operate on. However, there is one detail of this method that can cause confusion which I highlight at the end of this section.

In the Edit Script dialog box, click the Add… button, then name the script parameter, choose Visualization as the type, then in the Select visualization: dropdown, select the visualization to reference.

There is one slightly confusing aspect of this method, however. Selecting a visualization as a script parameter when editing the script only sets that reference as a debug value - it will only be used when you click the Run Script button in the Edit Script dialog box.

When you are ready to actually execute this same script elsewhere, such as by clicking a button in a text area or by selecting a script to run each time a document property’s value changes, you will again need to select a specific visualization for each visualization script parameter used in your IronPython script.

This may seem redundant at first glance, but it becomes very useful in situations where you want to run the same script against different visualizations in different situations. For example, you could write a single script for toggling the legend on a visualization, and then execute this same script from four different buttons in your workbook. Each of these buttons could toggle the legend for a different visualization simply by selecting that visualization as the script parameter input in each button’s Action Control dialog box.

Referencing a Visualization Using Nested For Loops

In many scenarios (perhaps most), hard-coding a visualization reference by adding it as a script parameter just won’t work. You will instead need to find a way to select one or more visualizations programmatically based on some logic in your IronPython script.

In a contrived example, let’s say you want to hide the title for all visualizations on all pages except the page titled “Exclude”, and excluding any visualizations titled “Nope”. This can be be done with nested for loops as shown below:

for page in Document.Pages:  #Loop through every page
    if page.Title <> 'Exclude':  #End the iteration if page titled 'Exclude'
        for visual in page.Visuals:  #On this page, loop through every visual
            if visual.Title <> 'Nope':  #End the iteration if visual titled 'Nope'
                
                #The two conditions above were satisfied, so hide the title
                visual.ShowTitle = False

Of course, many more useful things can be accomplished using this technique. You can use any property or condition of the pages or the titles to narrow down to only the visualizations you want to operate on. You could work with visuals only on the first three pages, the odd numbered ones, or even only those with at least one bar chart. You could also select visuals only of a certain type or based on some low level visualization property such as only those with labels shown or a reversed y-axis.