Add updatePlaylist method, docs and tests.

docs/configuration/playlists.md

@@ -154,3 +154,8 @@ The `key` parameter is the key of the playlist such as `ancient_astronauts` up a
 The `data` is any of the meta data that works for the playlist. Anything you want to pass as meta data for the playlist can be passed in a JSON object.
 
 the `songs` is an array of song objects for your playlist. These songs will only get added to the new playlist. Each one of these can be either an index of the song in the songs array, or an entirely new song object that only gets added to the playlist.
+
+
+## Updating an existing playlist
+
+If you want to update an existing (possibly even active) playlist completely, without interrupting the state, you can use the `Amplitude.updatePlaylist( key, data, songs, active_index )` method. This takes the same parameters as the `addPlaylist` method, as well as an integer that can be used to indicate which song is currently playing.

docs/functions/README.md

@@ -493,6 +493,15 @@ The second argument is all of the data describing the playlist such as `name`, `
 
 Finally, the third argument is an array of song objects. These are the songs that will be added to the playlist.
 
+## Update Playlist
+
+This method allows you to update an existing playlist in AmplitudeJS. To do this, you need a unique key for your playlist, the data describing your playlist such as `title`, `author`, etc., an array of song objects for your playlist and optionally the index of the song that should be marked as active (currently playing).
+This is required when mass-updating the playlist when reordering with drag&drop, for example.
+
+```javascript
+Amplitude.updatePlaylist( key, data, songs, active_index );
+```
+
 ## Register Visualization
 
 The other way to register a visualization is through the public `Amplitude.registerVisualization( visualization, preferences )` method. The first parameter being the object included with the visualization file and the second parameter being a JSON object containing any of the parameters needed to overwrite defaults provided by the visualization.

src/index.js

@@ -664,7 +664,37 @@ let Amplitude = (function() {
 
       return config.playlists[key];
     } else {
-      Debug.writeMessage("A playlist already exists with that key!");
+      Debug.writeMessage("A playlist already exists with that key, try updating instead!");
+      return null;
+    }
+  }
+
+  /**
+   * Update an existing playlist.
+   *
+   * @param {string} key            - The key of the playlist we are adding.
+   * @param {object} data           - The data relating to the playlist
+   * @param {array} songs           - The songs to add to the playlist
+   * @param {int|null} active_index - The active song in the updated list
+   */
+  function updatePlaylist(key, data, songs, active_index=null) {
+    /*
+      Ensures the playlist is defined.
+    */
+    if (config.playlists[key] !== undefined) {
+      /*
+        Recreate the playlist object.
+      */
+      config.playlists[key] = undefined;
+      this.addPlaylist(key, data, songs);
+
+      if (active_index !== null) {
+        config.playlists[key].active_index = active_index;
+      }
+
+      return config.playlists[key];
+    } else {
+      Debug.writeMessage("No playlist exists with that key.");
       return null;
     }
   }
@@ -1401,6 +1431,7 @@ let Amplitude = (function() {
     getDelay: getDelay,
     getPlayerState: getPlayerState,
     addPlaylist: addPlaylist,
+    updatePlaylist: updatePlaylist,
     registerVisualization: registerVisualization,
     setPlaylistVisualization: setPlaylistVisualization,
     setSongVisualization: setSongVisualization,

tests/index.test.js

@@ -287,6 +287,37 @@ test("AmplitudeJS can not add a playlist that already exists", () => {
   expect(newPlaylist).toBeNull();
 });
 
+/**
+ * Ensure we can update an existing playlist in AmplitudeJS.
+ */
+test("Amplitude can update a playlist that already exists", () => {
+  let song = {
+    artist: "Emancipator",
+    name: "Test New Song",
+    album: "Test New Album"
+  };
+
+  let data = {
+    foo: "bar"
+  };
+
+  let existingPlaylist = Amplitude.addPlaylist("existing_playlist",[data], [song]);
+  let updatedPlaylist = Amplitude.updatePlaylist("existing_playlist",[data, data], [song, song], 1);
+
+  expect(updatedPlaylist).toBeDefined();
+  expect(config.playlists["test_playlist"].songs.length).toBe(2);
+  expect(config.playlists["test_playlist"].songs.active_index).toBe(1);
+});
+
+/**
+ * Ensure we can't update a playlist that doesn't exist.
+ */
+test("Amplitude can not update a playlist that doesn't exists", () => {
+  let newPlaylist = Amplitude.updatePlaylist("FooBar123456", [{}], [{}]);
+
+  expect(newPlaylist).toBeNull();
+});
+
 /**
  * Ensures we can remove a song from the song array.
  */