tubby
    TypeScript icon, indicating that this package has built-in type declarations

    0.3.3 • Public • Published

    tubby — youtube playlist search

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

    1. 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
    2. 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
    3. 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"

    4. 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"))
    5. 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> 
    6. 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">

    tubby is open source and contributions are welcome!

    please consider opening an issue or contributing pull requests :)

    Install

    npm i tubby

    DownloadsWeekly Downloads

    4

    Version

    0.3.3

    License

    ISC

    Unpacked Size

    149 kB

    Total Files

    124

    Last publish

    Collaborators

    • chasemoskal