This PR reverts API changes introduced in version 3.0.0 of Pillarbox (as well as a minor subsequent change introduced in 4.0.0).
We attempted to make it easier to implement playlist view models based on business model objects by adding a source parameter to PlayerItem. Usage revealed that this does not make the task any easier than it was:
If the business model object list is updated (not a reshuffle but new additions to existing objects) then some sync code is still required to avoid recreating items unnecessarily.
If we wanted to avoid this issue we would need to make Player generic with a constraint on type (e.g. Hashable or Identifiable). But this would make Player far less ergonomic to use in the general case just for the sake of better handling business model objects (generics would leak basically everywhere).
If we wanted to implement the business model / player item relationship outside Player, e.g. in some playlist management object, we would be facing another issue: Items could still be added directly to a player without going through the playlist management object, leading to undefined behavior (in general data we would like to have associated with a PlayerItem would be missing). Such an API would not be ergonomic.
For this reason we reverted most of recent changes made to support sources at the PlayerItem level. Some good changes, e.g. a more item-based API (instead of sometimes being index-based) and demo simplifications (template removal, mostly) have been retained.
This means apps will be responsible of implementing playlist view models involving business model objects, which was still required with Pillarbox 3.0.0 anyway. To make it easier to sync with current player item updates this PR also makes currentItem a published property.
Changes made
Remove source parameter from API and documentation.
Remove Playlist.
Make currentItem a published property for easy subscription to changes. The behavior of the associated setter has been improved (replacements are now supported and the player will skip to the default position when setting the current item onto itself).
Make PlayerItem equatable instead of hashable, as was the case in Pillarbox 2.0.0.
Restore media - item sync code in demo playlist view model.
Checklist
[x] APIs have been properly documented (if relevant).
[x] The documentation has been updated (if relevant).
[x] New unit tests have been written (if relevant).
Description
This PR reverts API changes introduced in version 3.0.0 of Pillarbox (as well as a minor subsequent change introduced in 4.0.0).
We attempted to make it easier to implement playlist view models based on business model objects by adding a
sourceparameter toPlayerItem. Usage revealed that this does not make the task any easier than it was:Playergeneric with a constraint on type (e.g.HashableorIdentifiable). But this would makePlayerfar less ergonomic to use in the general case just for the sake of better handling business model objects (generics would leak basically everywhere).Player, e.g. in some playlist management object, we would be facing another issue: Items could still be added directly to a player without going through the playlist management object, leading to undefined behavior (in general data we would like to have associated with aPlayerItemwould be missing). Such an API would not be ergonomic.For this reason we reverted most of recent changes made to support sources at the
PlayerItemlevel. Some good changes, e.g. a more item-based API (instead of sometimes being index-based) and demo simplifications (template removal, mostly) have been retained.This means apps will be responsible of implementing playlist view models involving business model objects, which was still required with Pillarbox 3.0.0 anyway. To make it easier to sync with current player item updates this PR also makes
currentItema published property.Changes made
sourceparameter from API and documentation.Playlist.currentItema published property for easy subscription to changes. The behavior of the associated setter has been improved (replacements are now supported and the player will skip to the default position when setting the current item onto itself).PlayerItemequatable instead of hashable, as was the case in Pillarbox 2.0.0.Checklist