Tubby NPM | npm.io

`tubby` — youtube playlist search

⚡ demo: chasemoskal.com/tubby
web component to display a youtube playlist with a search bar

using the `<tubby-youtube-explorer>` component on your webpage

first, you need access to the youtube api, and have your api key ready
- login with the google developer console, and get yourself a youtube api key
- you have to whitelist your domains with that api key
- you can have an api key that allows 'localhost' for testing

install tubby on your page

include the following snippet on your page

<script type="importmap-shim">
  {
    "imports": {
      "lit-html/": "https://unpkg.com/lit-html@1.1.0/",
      "lit-html": "https://unpkg.com/lit-html@1.1.0/lit-html.js",
      "lit-element/": "https://unpkg.com/lit-element@2.1.0/",
      "lit-element": "https://unpkg.com/lit-element@2.1.0/lit-element.js",
      "tubby/": "https://unpkg.com/tubby@0.3.0-dev.4/",
      "tubby": "https://unpkg.com/tubby@0.3.0-dev.4/dist/index.js"
    }
  }
</script>
<script type="module-shim">
  import "tubby/dist/register-all.js"
</script>
<script src="https://unpkg.com/es-module-shims@0.2.3/dist/es-module-shims.js"></script>

here's what's going on in this snippet

import maps
- we provide an import map which locates tubby and its dependencies
- of course, for the import map, we're using guy bedford's awesome polyfill: es-module-shims
- if you're from the future, you won't need the -shim's
register the web components
- we run import "tubby/dist/register-all.js" to register the <tubby-youtube-explorer> component

place the explorer html on your page
```
<tubby-youtube-explorer
  search
  max-description-length="360"
  api-key="AIzaSyDeHpB9W14feQs8myoWgFAZOCrDeKMLRwE"
  playlist-id="UUL_f53ZEJxp8TtlOkHwMV9Q"
  canned="dist-demo/canned-videos.json"
  >
</tubby-youtube-explorer>
```
the youtube explorer fetches the specified youtube playlist, and displays video thumbnails in a grid formation, and optionally has a searchbar for filtering the video selection
youtube's api limits us to 50 videos at a time, so tubby does the hard work and requests every video sequentially, using back-to-back calls until it finds every video in the playlist
tubby has a simple dev-time caching mechanism i call "canning videos"
know how to configure the explorer for your use-case
all of tubby's configurable properties are optional, but you probably want to use a combination that loads some videos
- ⚓ string attributes [api-key] and [playlist-id]
  tubby will fetch all the videos in that playlist
- ⚓ string attributes [api-key] and [channel-id]
  tubby will make an extra round trip to find the playlist called "uploads".
  it is faster to provide the [playlist-id] attribute instead
- ⚓ string attribute [canned] url
  tubby will fetch these cached videos.
  if a playlist is also being fetched, the canned videos will provide a headstart that can prevent many round-trips and greatly improve the loading time.
  more on canning videos later in the readme
- ⚓ boolean attribute [search]
  tubby will display a search bar that the user can use to narrow the video listing
- ⚓ number attribute [max-description-length]
  character number limit for video descriptions
optional javascript stuff
```
// we can create the explorer programmatically
const explorer = document.createElement("tubby-youtube-explorer")
document.body.appendChild(explorer)

// we can set the attributes as properties
explorer["search"] = true
explorer["max-description-length"] = 360
explorer["api-key"] = "AIzaSyDeHpB9W14feQs8myoWgFAZOCrDeKMLRwE" 
explorer["playlist-id"] = "UUL_f53ZEJxp8TtlOkHwMV9Q"
explorer["canned"] = "dist-demo/canned-videos.json"

// the explorer supports these callbacks
explorer.onReady = () => console.log(`tubby loaded ${explorer.videos.length} videos`)
explorer.onError = error => console.warn(error)

// in addition to the two callbacks, there are matching custom events
explorer.addEventListener("ready", () => console.info("ready"))
explorer.addEventListener("error", () => console.info("error"))
```

know how to style the explorer

<style>
  tubby-video-explorer {
    --focus-outline: 2px solid #0ef;
    --tubby-search-focus-outline-offset: -4px;
    --tubby-pending-bg: rgba(0,0,0, 0.2);
    --tubby-error-bg: rgba(128,0,0, 0.2);
    --tubby-pending-color: white;
    --tubby-error-color: yellow;
    --tubby-search-icon-color: rgba(0,0,0, 0.5);
    --tubby-results-blink-color: rgba(255,255,255, 0.5);
    --tubby-grid-bg: rgba(0,0,0, 0.2);
    --tubby-video-color: white;
    --tubby-video-bg: linear-gradient(to bottom right,
      rgba(25,25,25, 0.95) 32%,
      rgba(25,25,25, 0.6)
    );
  }
</style>

canning videos with tubby's tubby-download commandline tool
you can give tubby a headstart (greatly reducing load times for large playlists), by using the tubby-download cli to generate a cache of "canned" videos in a json file, here's how
- npm install tubby
  install tubby into your npm package
- tubby-download --api-key=AIzaSyDeHpB9W14feQs8myoWgFAZOCrDeKMLRwE --playlist-id=UUL_f53ZEJxp8TtlOkHwMV9Q > dist/canned-videos.json
  call the tubby binary in a package.json script, supply the api-key and playlist-id, and specify where tubby should write the canned videos json file
- then you just provide the [canned] attribute like so: <tubby-youtube-explorer canned="dist/canned-videos.json">