We’ve been working hard to clean up the user interaction this cycle. Towards that end we landed some work a few weeks ago to clean up the column picker for libraries and playlists. You may have noticed in our current nightly builds that you have a slimmed down context menu instead of the old column picker button. In order to get that sleek look, yet still have the flexibilty to define and show custom properties, we needed to change the underlying use of the userViewable parameter. Just yesterday we landed the corresponding fix to address those changes for properties created by the Webpage API. Follow the jump to find out, in mind numbing detail, what that fix was and what it means if you’re using the Webpage API on your site.

First of all, the changes that landed a few weeks ago (changesets 11147, 11149, 11113, 11126),  modified the internal usage of userViewable. Previously this parameter indicated if the property was available to be added as a user-viewable column in playlists. This has now changed to indicate whether or not the property is available globally application-wide. If the property is:

• true, the property will show up in all column pickers for all libraries and playlists.
• false, the property can still be added as a column to a playlist, but can only be done so programmatically ( as opposed to the end user being able to select it from the column picker ).

At the same time we modified the column picker code to check the defaultColumnSpec and add those properties to the column picker, even if they aren’t currently shown to the user (this is important a little later).

Secondly, let’s cover the change that landed last night in the Webpage API. In all the different methods that create properties (e.g. createTextProperty()) there is a parameter hidden that maps inversely, behind the scenes, to userViewable. That parameter defaults to false. Having a default that meant the created property would be visible to all playlists didn’t seem like the right design. We decided to invert the parameter such that the hidden parameter is now userViewable.

How does this impact existing website that use the Webpage API? Without modification to their calls website will see:

• any properties created as hidden will now show up in all column pickers.
• properties created as not hidden will no longer appear in the column picker by default ( without calls to appendColumn() or insertColumBefore() ).

What should a site do to remedy the situation?

• For properties that should be hidden (e.g. urls to internal locations, site specific item IDs) use either the default argument, or pass false as the argument.

  songbird.createTextProperty( "http://example.com/hidden/foo", // name
                               "Foobar",                        // display name
                               false,                           // readonly
                               false,                           // viewable (used to be hidden)
                               0 );                             // nullSort
  songbird.createTextProperty( "http://example.com/hidden/bar", // name
                               "Foobaz" );                      // display name

• For properties that should be available across ALL playlists, libraries, set userViewable to true e.g. Creative Commons License

  songbird.createImageProperty( "http://example.com/global/CCL", // name
                                "CC License",                    // display name
                                true,                            // readonly
                                true,                            // viewable (used to be hidden)
                                0 );                             // nullSort

• For properties that should be available to the playlists for your particular site there are 2 options.
  • set the argument userViewable to false and then call append/insert

    songbird.createButtonProperty( "http://example.com/private/buyme", // name
                                   "Buy This Track",                   // display name
                                   true,                               // readonly
                                   false,                              // viewable (used to be hidden)
                                   0 );                                // nullSort
    songbird.webPlaylist.insertColumnBefore( "http://example.com/private/buyme",
                                             "http://songbirdnest.com/data/1.0#artistName",
                                             "100" );

  • set the parameter userViewable to false and set the defaultColumnSpec property to include your property ( recommended ).

    songbird.createButtonProperty( "http://example.com/private/buyme", // name
                                   "Buy This Track",                   // display name
                                   true,                               // readonly
                                   false,                              // viewable (used to be hidden)
                                   0 );                                // nullSort
    mylist.setProperty( "http://songbirdnest.com/data/1.0#defaultColumnSpec",
                        "http://songbirdnest.com/data/1.0#ordinal " +
                        "http://songbirdnest.com/data/1.0#trackName " +
                        "http://songbirdnest.com/data/1.0#artistName " +
                        "http://songbirdnest.com/data/1.0#duration " +
                        "http://example.com/private/buyme");
    songbird.webPlaylist.mediaList = mylist;

There are 2 reasons I suggest setting the defaultColumnSpec. There is currently a bug that will affect resizers in some cases when appending or inserting hidden properties programmatically (bug 13146). Using the defaultColumnSpec on the medialist will avoid this problem. Secondly, by using the defaultColumnSpec your properties will automatically show up in the column picker and if de-selected by the user will remain there. If you only add your hidden property programmatically and the user deselects it from the column picker and forces a refresh of the playlist (possibly by as little as re-sorting the list) your column would no longer appear in the picker.