DK YouTube Viewer Docs

Welcome to the DK YouTube Viewer Docs page. Instructions for configuring your channel and displaying its videos on your site can be found here.
If an answer cannot be found in the docs or a new feature or setting request is needed, please email me.

Getting Started

DK YouTube Viewer displays a channel's uploads with a featured YouTube player and a grid of video thumbnails. It requires WordPress 6.0 or later, PHP 8.0 or later, and an installed and activated DK Base Plugin.

  1. Install and activate DK YouTube Viewer through DK Plugins.
  2. Open DK Plugins → YouTube Viewer.
  3. Enter your YouTube API Key for YouTube Data API v3.
  4. Enter your Default Channel ID. Use the channel ID (usually beginning with UC), rather than a channel URL, handle, or playlist ID.
  5. Set a positive Default Batch Size and click Save Changes.
  6. Add [dk_youtube_featured_playlist] to a WordPress Shortcode block on the page where you want the viewer, then view that page.

Settings

  • YouTube API Key: Required to retrieve channel uploads. The key is saved in the plugin settings and used by the WordPress server for YouTube Data API requests.
  • Default Channel ID: Used whenever the shortcode omits channel_id. You may leave this blank if every shortcode supplies its own channel ID.
  • Default Max Videos: Defaults to 999. This setting and the max shortcode attribute limit the videos displayed (minimum 1). The cached channel playlist remains shared, so one viewer’s limit does not truncate another viewer. Retrieval stops when the uploads playlist ends or the pagination safety limit is reached.
  • Default Batch Size: Defaults to 10. Controls how many thumbnails are revealed at a time. Use a whole number of at least 1.

Shortcode Examples

Use your saved channel and batch settings:

[dk_youtube_featured_playlist]

Show another channel without changing the default. Replace the example ID with the actual channel ID:

[dk_youtube_featured_playlist channel_id="UC_REPLACE_WITH_YOUR_CHANNEL_ID"]

Reveal six thumbnails at a time for this viewer:

[dk_youtube_featured_playlist channel_id="UC_REPLACE_WITH_YOUR_CHANNEL_ID" batch="6"]

The supported attributes are channel_id, batch, and max. Omitted attributes use the saved settings. The API key is configured in settings; it is not a shortcode attribute. The viewer uses the channel's uploads playlist; there is no setting for selecting a separate YouTube playlist.

Using the Viewer

The first video returned from the channel's uploads playlist appears in the featured player. Click a thumbnail to switch the player to that video; the page scrolls back to the player. The selected thumbnail stays in color and displays a red indicator. Other thumbnails change from grayscale to color on hover.

More thumbnails appear in batches as you scroll near the bottom of the viewer. This reveals videos already retrieved with the page; it does not request another set of videos from YouTube. The player and thumbnail grid adjust to the available screen width.

Updates and Caching

The plugin caches a nonempty uploads list separately for each channel. The cache expiration is calculated as the next Tuesday at 12:05 p.m. in the America/Denver time zone, with a minimum lifetime of five minutes. After the cache expires, the next page request retrieves the uploads again; there is no background refresh job.

New uploads may therefore take time to appear. Saving settings does not clear an existing channel cache. If your site also caches whole pages, those pages may need to refresh before visitors see the updated list. Empty results are not cached by the plugin.

Troubleshooting

  • No channel ID provided. Save a Default Channel ID or supply channel_id in the shortcode.
  • No YouTube API Key provided. Enter your YouTube Data API v3 key in the plugin settings and save.
  • Failed to load channel. WordPress could not complete the channel request. Check the server's outbound HTTPS connection to Google's API.
  • Uploads playlist not found. Check that you supplied a channel ID, then check the API key and API access.
  • No videos found. Confirm that the channel has available uploads and that the API key can access YouTube Data API v3. Check API restrictions, quota, and server logs for request errors.
  • Player appears but thumbnails do not. Use a positive batch size and check that the plugin's stylesheet and JavaScript load successfully. If your site uses script optimization or caching, refresh those assets after updating the plugin.
  • A video will not play. Check the video on YouTube. Removed, private, or embedding-restricted videos may be unavailable in the embedded player.
  • New uploads are missing. Allow the channel cache to expire and check any page cache. For a large channel, the pagination safety limit may also prevent the entire upload history from being retrieved.