Welcome to my second IronPython post this week. If you missed the first one, start here. The first post introduced the code and provided information on how to modify it for other use cases. This post builds on that by focusing on navigating the Spotfire API reference. The next post will then explain how and why the code is written. A screenshot of the code is shown below, and then we’ll dive into the API.
This code is grabbing a particular filter in the filter panel (a checkbox filter) and unchecking all the boxes.
Walking Thru the API
I am going to walk thru the API one reference at a time. Note, I am NOT going to explain exactly what the code is doing (yet). This section will show you where to find the API references, which in turn will show you how to navigate the API. The next post will explain what the code is doing and why.
Lines 1, 3, 5
Lines 1, 3, and 5 import namespaces and classes from the Spotfire.Dxp.Application.Filters namespace.
Line 1 import Spotfire.Dxp.Application.Filters as filters
Line 1 imports the Spotfire.Dxp.Application.Filters namespace. If you are in the API reference, this namespace is 8 lines down at the highest level of the hierarchy. It is also mentioned/linked in the Spotfire.Dxp.Application namespace as shown below. As you can see in the API reference, this namespace works with filters and filtering schemes in the filter panel. That is exactly what we are doing – modifying a filter.
Line 3 import Spotfire.Dxp.Application.Filters.CheckBoxFilter Line 5 from Spotfire.Dxp.Application.Filters import FilterTypeIdentifiers
Lines 3 and 5 import CheckBoxFilter and FilterTypeIdentifiers, which are classes in Spotfire.Dxp.Application.Filters namespace. Once the class has been added, the developer can reference a class’ properties, methods, fields, etc.
Line 7 myPanel = Document.ActivePageReference.FilterPanel
Line 7 references the Document class, which is a class in the Spotfire.Dxp.Application namespace. The developer didn’t import this namespace because Spotfire imports most of it by default. ActivePageReference is a property of the Document class. Now, the ActivePageReference gets or sets the currently active Page. If you are in the API reference and click on Page as circled below, you’ll see this then takes you to the Page class, where Filter Panel is a property.
Line 9 myFilter = myPanel.TableGroups.GetFilter("BudgetNode")
Line 7 essentially ends in the Filter Panel. Then, Line 9 calls the TableGroups property, which is in the FilterPanel class under the Spotfire.Dxp.Application.Filters namespace. The code also uses the GetFilter method from the FilterGroup class.
Line 11 myFilter.FilterReference.TypeId = FilterTypeIdentifiers.CheckBoxFilter
Line 11 references a lot of the API, and this one was a bit confusing at first because I didn’t understand how to move from the filter panel to the actual filter. TIBCO support helped by showing me this flow chart. In order to access filters in the filter panel, you must use the TableGroup, even if there is only one table in your DXP. TableGroup is the path to the FilterHandle, which accesses the filter.
Now, when I was working thru the API, I saw references to the FilterSubGroup, and I wasn’t sure if it was referring to creating a subgroup in the filter panel (select filter in filter panel, right-click, New group) or if it was a different API reference. Groups in the filter panel would be accessed via TableGroup.SubGroups, but they don’t have to be there.
So, line 11 hits three different classes and multiple properties. First, it references the FilterReference property in the FilterHandle class. If you go to the FilterHandle class, you will find the FilterReference property in the API. This gets the Filter that fits this FilterHandle reference. If you click on Filter (as circled below), it takes you to the Filter class. Then the code uses the TypeId property in the Filter class. That value should equal the CheckBoxFilter field from the FilterTypeIdentifers class.
Line 13 checkBoxFilter = myFilter.FilterReference.As[filters.CheckBoxFilter]()
Line 13 is just as busy as Line 11. It hits the FilterReference property in the FilterHandle class. That connects with the As method from the Filter class. Remeber, Line 1 created the filters object, which was equal to the Spotfire.Dxp.Application.Filters namespace, so filters.CheckBoxFilter = Spotfire.Dxp.ApplicationFilters.CheckBoxFilter, which is a reference to the CheckBoxFilter class.
Line 15 checkBoxFilter.IncludeEmpty = False
This line uses the IncludeEmpty property, which is in the CheckBoxFilter class. Can you find this on your own in the API?
Line 17 for value in checkBoxFilter.Values:
Here, the code references the Values property of the CheckBoxFilter class. What about this one? Can you find it on your own in the API?
Line 19 checkBoxFilter.Uncheck(value)
Line 19 uses the Uncheck method of the CheckBoxFilter class. Although, note that in this line, checkBoxFilter is an object, not a reference to the class.
Now you know where all of the API references came from! Before wrapping up, I want to mention that I had to search the API quite a bit. Now, searching would be easy if the API named all of the properties, methods, fields, classes, etc uniquely. If my search returned an API result, I would know it is the right reference because there is only one. Unfortunately, the API is not written that way. Classes are distinctly named, but other pieces of syntax can have duplicates. For example, Title is a property of Page, Panel, MapChart, and all other visualization types represented as classes. Keep that in mind as you are exploring (and checking my work).
Summary of API References
If you want to walk thru everything again, here is a summary of the namespaces, classes, properties, methods, and fields used in this code.
- Spotfire.Dxp.Application namespace
- Document class
- ActivePageReference property
- Page class
- FilterPanel property
- Document class
- Spotfire.Dxp.Application.Filters namespace
- CheckBoxFilter class
- IncludeEmpty property
- Values property
- Uncheck method
- Filter class
- TypeId property
- As method
- FilterGroup class
- GetFilter method
- FilterHandle class
- FilterReference property
- FilterPanel class
- TableGroups property
- FilterTypeIdentifiers class
- CheckBoxFilter field
- CheckBoxFilter class
Unfortunately, there’s a whole lot I haven’t addressed yet. For example, what if you don’t know the difference between a namespace, property or class? Don’t worry, I’ll get there in a future post. What if you don’t understand why each piece of the API was called. I’ll get there too. This learning process is a long game. The next post explains how the code is written.
Content created with Spotfire 7.12.
Guest Spotfire blogger residing in Whitefish, MT. Working for SM Energy’s Advanced Analytics and Emerging Technology team!