Business Intelligence Tools / Developers Corner

Learn IronPython for Spotfire…Navigating the API

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.

Code

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.

Location of namespace.
More specific namespace.

 

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.

Here’s where to find the classes in the namespace.

Line 7 

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

Line 9 myFilter = myPanel.TableGroups[4].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

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

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

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

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

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
  • 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

Conclusion

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.

Spotfire Version

Content created with Spotfire 7.12.

10 thoughts on “Learn IronPython for Spotfire…Navigating the API

  1. Pingback: Learn IronPython for Spotfire...One Code Snippet At A Time - Data Shop Talk

  2. Atheer Al Attar Reply

    Thanks, I was trying to print out the value of a property but still getting

    this was my code

    import Spotfire.Dxp.Application.Filters as filters
    import Spotfire.Dxp.Application.Filters.CheckBoxFilter as chkBox
    import Spotfire.Dxp.Application.Filters.FilterTypeIdentifiers as fti
    import Spotfire.Dxp.Application.Document as doc
    import Spotfire.Dxp.Application.Page as pg
    print ((pg.Title))

    • Julie Sebby Post authorReply

      Was there more to the comment…you are still getting….??? I’ll put this code in a DXP and see what I get.

    • Julie Sebby Post authorReply

      I ran this…(added Document.ActivePageReference.Title) and it printed page title of the active page.

      import Spotfire.Dxp.Application.Filters as filters
      import Spotfire.Dxp.Application.Filters.CheckBoxFilter as chkBox
      import Spotfire.Dxp.Application.Filters.FilterTypeIdentifiers as fti
      import Spotfire.Dxp.Application.Document as doc
      import Spotfire.Dxp.Application.Page as pg
      myTitle = Document.ActivePageReference.Title
      print ((myTitle))

      • Atheer Al Attar Reply

        Sorry, the complete comment was “I get ”

        Anyways, the main confusion I always get frustrated when dealing with IP API is that here is more than path to access a property and not all of them are correct and you addressed that in your post. I was trying to access the Page title through the path Spotfire.Dxp.Application.Page.Title and that’s where I am getting .

  3. Pingback: Learning IronPython for Spotfire...How the Code Works • The Analytics Corner

  4. Vara Reply

    Great Posts on Iron Python, Even I have the same thoughts of spending more time and gain in-depth knowledge, was finding ways to start.. your posts help me a lot.. Thank you for sharing.. Hope to see more posts..

Leave a Reply

Your email address will not be published. Required fields are marked *