I was trying to wrap up a major project last week, and I wasn’t able to get my weekly post out. It’s really a rare thing when that happens, but I’m back on track this week. I will continue using the Spotfire IronPython Quick Reference to learn the Spotfire API. This week, we will learn how to use for loops in IronPython. For loops are used to iterate over a sequence. In our Spotfire IronPython example, we’ll iterate over the pages in a Spotfire DXP and the visuals on the pages.
Here is the code snippet we are working with. It looks at each page title in a Spotfire DXP and each visual title on a page. If the page name says “Exclude”, the page is skipped. If the visual title says “Nope”, the visual is skipped. For all other pages and visuals, it will hide the title on the visual.
Note, you can’t have multiple pages with the same name, so this code would only be able to exclude one page.
My DXP contained 2 pages. One was named “Exclude” and the other “Page(3)”. See screenshots below.
Before The Script
After Running the Script
Now that you understand what the code is doing, let’s talk about the IronPython syntax.
The Syntax of For Loops
Now, as previously mentioned, a for loop is used for iterating over a sequence like a list, dictionary, or string. The W3Schools examples below do an excellent job of demonstrating.
In this first example, they have created an object called “fruits” that is a concatenated list. “For x in fruits” iterates over each element in the list. The code is simply printing each element.
In the second example, the code is iterating over every letter in the string “banana” and printing each letter.
Note that “x” is also an object and can be anything you want it to be. Now that you understand the basic concept of for loops, let’s talk about how it works with the Spotfire API.
When I first started trying to write IronPython, I could easily test and understand that “page” was a developer created object. I didn’t understand that other parts of the syntax or API referenced a collection, like pages in a document or visualizations on a page. There are clues in the API. The screenshot below shows the properties of the Document class. As you can see, some of them are plural and described as a collection or multiple elements.
More specifically, Document.Pages is returning a collection of pages. “page” refers to one of the things in the collection. In the code, we iterate over the collection using the for loop. “page” is identifying an individual page in the collection when iterating. To access any of the properties we use “page.Visuals” or “page.Title”.
Next, let’s look each piece of the API referenced by the code.
To keep everything clean, let’s delineate between objects and API references. Note, this developer wrote objects in lower case to distinguish them from the API references, which is good practice.
- API References
- Pages (property of Document class)
- Visuals (property of Page class)
- Title (property of Pages and Visuals class)
- ShowTitle (property of Visuals class)
“Document”, “Page”, and “Visual” are all classes in the Spotfire.Dxp.Application namespace.
The descriptions for the Page and Visual classes are shorter. Make sure not to confuse the Page class with the Pages property of the Document class.
Properties of a Class
If you click on each class (Document, Page or Visual), it will take you to a list of properties for the class.
Document Class Properties
Our code snippet references the Pages property of the Document class (“Document.Pages”), as shown below.
Page & Visual Class Properties
Both the Page and Visual class have a “Title” property used in the code snippet. The Visual class’ “Show Title” property is also used to turn off the title in each visualization (“visual.ShowTitle = False”).
To wrap up this post, let’s summarize what the code does.
Line 1 starts a for loop. The code loops thru each page in the document by referencing the Document class and it's Pages property.
Line 2 looks at the title of each page using the Title property of the Page class. If the title is "Exclude", it ignores it.
In Line 3, if the title is not "Exclude", another for loop starts that looks at each visual in a page by referencing the Page class property Visuals.
Line 4 specifies that if the visual title is "Nope", it is ignored.
Line 5 says to hide the title using the Visual class property ShowTitle if the title is not "Nope".
Now, you may notice that when referencing the Document class property, the code syntax is “Document.Pages”. However, when referencing the Visual or Page class properties, the class is not referenced. I’m not entirely clear on this. I think it is because you are already in the document and a page or a visual is part of the document. If anyone can articulate this, please leave a comment.
That wraps up this IronPython post. Hopefully, you now understand how to use for loops in IronPython, include a more in-depth knowledge of the Spotfire API. More to come next week!
Content created with Spotfire version 10.2.
If You Liked This…
If you enjoyed this post, check out any of the following posts….