Fix Multiple Player in one site #21

APIv2-3_Reference.md

@@ -0,0 +1,185 @@
+#APIv2 to APIv3 Reference Notes
+
+Notes to reference for the conversion for a better understanding on what has changed for myself and others.
+
+## Youtube-TV Elements Chart
+
+Currently used elements in `ytv.js` and their new APIv3 counterparts.
+
+#### User (channel) Playlists
+
+playlists = | res.feed.entry
+----------- | --------------
+ | **res.feed.items**
+
+`playlists[i]`
+
+Element | Old Value | New Value
+------- | --------- | ---------
+title | .title.$t | .snippet.title
+plid | .yt$playlistId.$t | .id
+thumb | .media$group.media$thumbnail[1].url | .snippet.thumbnails.medium.url
+
+#### User (channel) Info
+
+user = | userInfo.entry
+------ | -------------- 
+ | **userInfo.items[0]**
+
+Element | Old Value | New Value
+------- | --------- | ---------
+title | .title.$t | .snippet.title
+url | .yt$username.$t | .id
+thumb | .media$thumbnail.url | .snippet.thumbnails.default.url
+summary | .summary.$t | .snippet.description
+subscribers | .yt$statistics.subscriberCount | .statistics.subscriberCount
+views | .yt$statistics.totalUploadViews | .statistics.viewCount
+**`NEW`** | - | -
+uploads | n/a | .contentDetails.relatedPlaylists.uploads
+
+To support newer accounts by using channel ID instead of user ID.  
+**Old:** `url: local+'//youtube.com/user/'+userInfo.entry.yt$username.$t`  
+**New:** `url: 'https://youtube.com/channel/'+userInfo.id`
+
+#### `NEW` Playlist Videos
+
+playlistVideos = | n/a
+---------------- | ---
+ | **res.feed.items**
+
+`plistlistVideos[i]`
+
+Element | Old Value | New Value
+------- | --------- | ---------
+slug | n/a | .contentDetails.videoId
+
+#### Video Info
+
+videos = | data.feed.entry
+-------- | --------------- 
+ | **data.feed.items**
+
+`videos[i]`
+
+Element | Old Value | New Value
+------- | --------- | ---------
+title | .title.$t | .snippet.title
+*slug | .media$group.yt$videoid.$t | .id
+link | .link[0].href | n/a *use slug
+published | .published.$t | .snippet.publishedAt
+rating | .yt$rating | n/a *see statistics
+stats | .yt$statistics | .statistics
+duration | ( .media$group.yt$duration.seconds) | .contentDetails.duration
+thumb | .media$group.media$thumbnail[1].url | .snippet.thumbnails.medium.url
+**`NEW`** | - | -
+embed | n/a | .status.embeddable
+
+## Updated URLs
+#### base 
+
+base = | `local+'//gdata.youtube.com/'` 
+------ | ----------------------------
+ | **`'https://www.googleapis.com/youtube/v3/'`**
+
+* *https required for APIv3*
+
+#### userInfo
+```
+Before:  
+utils.endpoints.base+'feeds/api/users/'+settings.user+'?v=2&alt=json';
+After:  
+utils.endpoints.base+'channels?'+settings.cid+'&key='+apiKey+'&part=snippet,contentDetails,statistics';
+```
+**Required in Build**
+```javascript
+if (settings.channelId){
+    settings.cid = 'id='+settings.channelId;
+} else if(settings.user){
+    settings.cid = 'forUsername='+settings.user;
+}
+```
+
+#### userVids
+```
+Before:  
+utils.endpoints.base+'feeds/api/users/'+settings.user+'/uploads/?v=2&alt=json&format=5&max-results=50';
+After:  n/a pulled playlistId pulled from userInfo
+```
+**Replaced with:**
+```javascript
+userUploads: function(userInfo){
+    if (userInfo && userInfo.items){
+        settings.playlist = userInfo.items[0].contentDetails.relatedPlaylists.uploads;
+        utils.ajax.get( utils.endpoints.playlistVids(), prepare.compileVideos );
+    }
+}
+```
+
+#### userPlaylists
+```
+Before:  
+utils.endpoints.base+'feeds/api/users/'+settings.user+'/playlists/?v=2&alt=json&format=5&max-results=50';
+After:  
+utils.endpoints.base+'playlists?channelId='+settings.channelId+'&key='+apiKey+'&maxResults=50&part=snippet';
+```
+
+#### playlistVids
+```
+Before:  
+utils.endpoints.base+'feeds/api/playlists/'+(settings.playlist)+'?v=2&alt=json&format=5&max-results=50';
+After:  
+utils.endpoints.base+'playlistItems?playlistId='+settings.playlist+'&key='+apiKey+'&maxResults=50&part=contentDetails';
+```
+
+#### `NEW` playlistInfo
+`utils.endpoints.base+'playlists?id='+settings.playlist+'&key='+apiKey+'&maxResults=50&part=snippet';`
+```javascript
+selectedPlaylist: function(playlistInfo){
+    if (playlistInfo && playlistInfo.items) {
+        settings.currentPlaylist = playlistInfo.items[0].snippet.title;
+        utils.ajax.get( utils.endpoints.playlistVids(), prepare.compileVideos );
+    }
+}
+```
+
+#### `NEW` videoInfo  
+`utils.endpoints.base+'videos?id='+settings.videoString+'&key='+apiKey+'&maxResults=50&part=snippet,contentDetails,status,statistics';`
+```javascript
+compileVideos: function(res){
+    if (res && res.items){
+        var playlists = res.items,
+        i;
+        settings.videoString = '';
+        for(i=0; i<playlists.length; i++){
+            settings.videoString += playlists[i].contentDetails.videoId;
+            if (i<playlists.length-1){ settings.videoString += ',';}
+        }
+        utils.ajax.get( utils.endpoints.videoInfo(), prepare.compileList );
+    }
+}
+```
+
+### Parsing the new time format - Reference
+```javascript
+function parseDuration(duration) {
+    var matches = video.duration.match(/[0-9]+[HMS]/g);
+    var h = 0, m = 0, s = 0, time = '';
+
+    matches.forEach(function (part) {
+        var unit = part.charAt(part.length-1);
+        var amount = parseInt(part.slice(0,-1));
+
+        switch (unit) {
+            case 'H': h = (amount > 9 ? '' + amount : '0' + amount); break;
+            case 'M': m = (amount > 9 ? '' + amount : '0' + amount); break;
+            case 'S': s = (amount > 9 ? '' + amount : '0' + amount); break;
+            default: // ??? profit
+        }
+    });
+    if (h){ time += h+':';}
+    if (m){ time += m+':';} else { time += '00:';}
+    if (s){ time += s;} else { time += '00';}
+
+    return time;
+}
+```

README.md

@@ -1,11 +1,8 @@
 # YoutubeTV
+**NOW with API Version 3 Support!!**  
 A small, slick, library independent YouTube User/Playlist player
 
-<img src="http://i.imgur.com/BTYZ5ur.png">
-
-<a href="https://twitter.com/intent/tweet?hashtags=youtubetv&via=jakiestfu&url=https%3A%2F%2Fgithub.com%2Fjakiestfu%2FYoutube-TV%2F&text=Youtube%20TV%3A%20A%20small%2C%20slick%2C%20library%20independent%20YouTube%20User%2FPlaylist%20player"><img src="http://jakiestfu.github.io/Youtube-TV/static/twit.png" target="_blank"></a>
-<a href="https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fgithub.com%2Fjakiestfu%2FYoutube-TV%2F"><img src="http://jakiestfu.github.io/Youtube-TV/static/fb.png" target="_blank"></a>
-
+<img src="./demos/assets/images/default.png">
 
 ## Features
 * Library Independent
@@ -15,16 +12,35 @@ A small, slick, library independent YouTube User/Playlist player
 * Supports Playlists and Users
 * jQuery Support
 * Module Support
+* Responsive Support
+* Alternative color scheme
 
 ## Demos
-* [Default Player Options](http://jakiestfu.github.io/Youtube-TV/demos/default.html)
-* [Chromeless Player](http://jakiestfu.github.io/Youtube-TV/demos/chromeless.html)
-* [Playlist Support](http://jakiestfu.github.io/Youtube-TV/demos/playlists.html)
-* [Full Screen Player](http://jakiestfu.github.io/Youtube-TV/demos/fullscreen.html) (Good for a .tv website?)
-* [jQuery Support](http://jakiestfu.github.io/Youtube-TV/demos/jquery.html)
+* [Default Player Options](http://giorgio003.github.io/Youtube-TV/demos/default.html)
+* [Chromeless Player](http://giorgio003.github.io/Youtube-TV/demos/chromeless.html)
+* [Playlist Support](http://giorgio003.github.io/Youtube-TV/demos/playlists.html)
+* [Full Screen Player](http://giorgio003.github.io/Youtube-TV/demos/fullscreen.html) (Good for a .tv website?)
+* [jQuery Support](http://giorgio003.github.io/Youtube-TV/demos/jquery.html)
+* [Responsive Support](http://giorgio003.github.io/Youtube-TV/demos/responsive.html)
+* [Multiple Players](http://giorgio003.github.io/Youtube-TV/demos/multiplayer.html)
+
+## Obtaining Youtube API Key
+
+As part of the update to [Youtube's API version 3](https://developers.google.com/youtube/v3/), it is required to obtain an API Key from [Google's Developer Console](https://console.developers.google.com/).
+
+To obtain your API Key you can follow this guide using steps 1 to 3.
+[https://developers.google.com/youtube/v3/getting-started](https://developers.google.com/youtube/v3/getting-started)
+
+Then:
+4. under APIs & auth > Credentials > Create new Key > (Select) Browser Key
+5. (Recommended) Set any referrers to your domain to prevent unauthorized use of your key.
+6. (Optional) Additionally disabling any other unused APIs that are enabled.
 
 ## Installation
 
+After obtaining your API Key, fill it in `ytv.js` near the top via this line:  
+`var apiKey = 'YOUR_API_KEY_HERE';`
+
 Include both the `ytv.css` and `ytv.js` in your HTML file and you are good to go.
 
 ```html
@@ -35,20 +51,58 @@ Include both the `ytv.css` and `ytv.js` in your HTML file and you are good to go
 ## Usage
 
 After your page has loaded, you may call the script like so:
-
+```html
+<div id="YourPlayerID"></div>
+```
 ```javascript
-var controller = new YTV(element, {
-	user: 'YoutubeUsername'
+document.addEventListener("DOMContentLoaded", function(event) {
+    var controller = new YTV('YourPlayerID', {
+	   user: 'YoutubeUsername'
+    });
 });
 ```
+**Technical Note:** Above `DOMContentLoaded` is preferred for speed on modern browsers (additionally works down to IE9). However the demos are mostly using `window.onload` which is a slower option but compatible with older browsers (IE8 or older). Good examples of this difference can be found [here (microsoft.com)](http://ie.microsoft.com/Testdrive/HTML5/DOMContentLoaded/Default.html) and [here (jspref.com)](http://jsperf.com/onload-vs-domcontentloaded/3)
+
+**`Note:`** If you are using a newer YouTube channel you may have a **Channel ID** which may look similar to this: `UCXXXXXXXXXXXXXXXXXXXXXX`
+If so, use `channelId: 'UCXXXXXXXXXXXXXXXXXXXXXX'` to replace user!
+
+#### User vs Channel ID
+By visiting the intended channel's Youtube home page. The URL should look like one of the following.
+##### User ID `user: ''`
+<img src="./demos/assets/images/user.png">
+
+##### Channel ID `channelId: ''`
+<img src="./demos/assets/images/channelid.png">
+
+#### Additional Options
+
+Additional options you may wish to add to get started.
+
+In addition to `user` and `channelId` you can also use `playlist` ID's which can also replace `user` and `channelId` or work along side them.
+`playlist: 'PLAYLIST_ID_HERE'` 
+To chain multiple playlists together, separate them by comma's. Example:
+`playlist: 'PLAYLIST_ID1,PLAYLIST_ID2,PLAYLIST_ID3'`
+
+Add this to enable the responsive Youtube-TV player allowing the player to adjust from desktop resolution all the way to mobile devices.
+`responsive: true`
+
+Accent colour will appear beside the active video in the list. This will accept any CSS value from `#FFF` to `orange`.
+`accent: '#008D54'`
+
+If you prefer the `light` theme over the dark, add these 2 options (or mix 'n match if desired).
+`playerTheme: 'light'`
+`listTheme: 'light'`
+
+**Don't forget comma's between each option!**
 
 `YTV` accepts two parameters. The first is a string of the element ID you want to use as the player, OR it may the element itself. The second parameter is an object of options defined below:
 
-## Settings and Defaults
+## Settings, Defaults and Details
 ```javascript
 settings = {
     element: null,
     user: null,
+    channelId: null,
     playlist: '',
     fullscreen: false,
     accent: '#fff',
@@ -57,6 +111,13 @@ settings = {
     autoplay: false,
     chainVideos: true,
     browsePlaylists: false,
+    playerTheme: 'dark',
+    listTheme: 'dark',
+    responsive: false,
+    playId:'',
+    sortList: false,
+    reverseList: false,
+    shuffleList: false,
     wmode: 'opaque',
     events: {
         videoReady: function(){},
@@ -67,18 +128,36 @@ settings = {
 
 * `element`: The element or element ID to apply the YouTube TV Player to
 * `user`: (String) The Username of the YouTube user you want to display videos from
-* `playlist`: (String) The Playlist ID you would like to load (Overrides `user`)
+* `channelId`: (String) The Channel ID of the YouTube channel you want to display videos from (for newer accounts)
+* `playlist`: (String) The Playlist ID(s) you would like to load separated by comma's (Overrides `user`)
 * `browsePlaylists`: (Boolean) If `true` and the specified `user` has YouTube playlists, they will be accessible in the player by clicking the users Username
 * `fullscreen`: (Boolean) If `true`, the player will take up all the available space on the users browser screen
 * `accent`: (String) A CSS color string to apply to the accents of the player
 * `controls`: (Boolean) If `false`, the normal YouTube controls will be hidden.
 * `annotations`: (Boolean) If `false`, the annotations from the YouTube video will be hidden
 * `autoplay`: (Boolean) If `true`, the first video in the list will automatically play once the player has loaded
 * `chainVideos`: (Boolean) If `true`, the next video in que will automatically play after the current video has completed
+* `playerTheme`: (String) Sets the youtube player theme. Default is `dark` with an alterative `light` color scheme.
+* `listTheme`: (String) Sets the playlist theme. Default is `dark` with a `light` theme to match the alternative player theme.
+* `responsive`: (Boolean) If `true`, it enables a responsive design to support various resolutions including mobile devices. Default currently `false`.
+* `playId`: (String) On load this option will allow you to select the first video to play/display. Enter the id of the video you want to display. (ie. `.../watch?v=VIDEOID` to `playId: 'VIDEOID'`).
+* `sortList`: (Boolean) If `true`, this option will sort the video list by date uploaded.
+* `reverseList`: (Boolean) If `true`, this option will reverse order of the videos. (Can be combined with other sorting option to reverse after sorting).
+* `shuffleList`: (Boolean) If `true`, this option will shuffle the video list. (Useful for music playlists).
 * `wmode`: (String) Sets the Window Mode property for transparency, layering, and positioning in the browser. Values can be: `window` - movie plays in its own rectangular window on a web page. `opaque` - the movie hides everything on the page behind it. `transparent` - the background of the HTML page shows through all transparent portions of the movie, this may slow animation performance.
 * `events`: The respective events will fire when key actions in the player have been called
 
 
+## Responsive Design
+Youtube-TV can now adapt to various changes in resolution based on it's parent canvas/container. Currently set to `max-width:992px` to match Bootstrap's responsive transitions, but can be modified to match any other responsive boilerplate.
+
+#### Playlist beside
+*(image resized on github don't be fooled >_<)*
+<img src="./demos/assets/images/responsive1.png">
+#### Playlist on bottom
+*Better for mobile devices*
+<img src="./demos/assets/images/responsive2.png">
+
 ## Public Methods
 
 ### `destroy`
@@ -117,16 +196,11 @@ YTV may be used as a jQuery plugin in the following fashion:
 $('#frame').ytv({opts});
 ```
 
-<img src="http://i.imgur.com/pHPB5wS.png">
+<img src="./demos/assets/images/playlists.png">
 
 ## Licensing
 **MIT Licensing**
 <p>Copyright (c) 2013 Jacob Kelley</p>
 <p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p>
 <p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>
 <p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
-
-
-## Share Meh!
-<a href="https://twitter.com/intent/tweet?hashtags=youtubetv&via=jakiestfu&url=https%3A%2F%2Fgithub.com%2Fjakiestfu%2FYoutube-TV%2F&text=Youtube%20TV%3A%20A%20small%2C%20slick%2C%20library%20independent%20YouTube%20User%2FPlaylist%20player"><img src="http://jakiestfu.github.io/Youtube-TV/static/twit.png" target="_blank"></a>
-<a href="https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fgithub.com%2Fjakiestfu%2FYoutube-TV%2F"><img src="http://jakiestfu.github.io/Youtube-TV/static/fb.png" target="_blank"></a>