1. Introduction

TubePress is a PHP library that displays beautiful YouTube video galleries in your web site. It's highly configurable and easy to use. Check out a demo gallery here.

There are two different TubePress packages available:

1. A WordPress plugin (free!)
2. TubePress Pro - A stand-alone library for use anywhere that supports PHP (only $10)

Both packages are released under the GPLv3. TubePress was created, is developed and maintained by Eric D. Hough

2. Download

2.1 Latest stable release

2.2 Subversion

2.2.1 From the command line

1. Change directories to wp-content/plugins
2. Make sure you've removed any existing installs of TubePress from this directory
3. Execute

   svn checkout http://tubepress.googlecode.com/svn/trunk/ tubepress

1. Change directories to wp-content/plugins/tubepress
2. Execute

   svn update

2.2.2 Using FTP

1. Use any SVN client to browse to http://tubepress.googlecode.com/svn/trunk/
2. Checkout the trunk directory to a local directory called tubepress
3. Upload the tubepress directory you just created to your WordPress installation at wp-content/plugins

2.3 Nightly Builds

3. WordPress Plugin

3.1 Quick Start

TubePress can be installed and activated just like any other WordPress plugin. See the WordPress docs on plugin management for more information.

1. Download the plugin from http://tubepress.org/download
2. Unzip into your plugins directory (wp-content/plugins)
3. Activate TubePress from Site Admin > Plugins
4. Configure from Site Admin > Settings > TubePress
5. Type

   [tubepress]
   

   in a post or a page where you'd like to insert your gallery (this is actually the simplest form of a TubePress shortcode). See the image below for an example.

This will result in something like the following…

3.2 Multiple galleries

The options in Settings > TubePress are the global options for TubePress. The real power of the plugin lies in the ability to put multiple galleries on multiple pages. You can do this by using TubePress shortcodes on your posts/pages.

For example, say on one page I want to display a gallery of videos that are tagged with "football". On this page, I would type

[tubepress mode='tag', tagValue='football']

on the page where I want the gallery to show up. And say on another page I want to display a gallery with the default (global) options that were set in Settings > TubePress. On this page I would type

[tubepress]

where I wanted the gallery to show up. You can follow this procedure for unlimited galleries on unlimited posts/pages. Just use any TubePress shortcode to control the gallery content. Get creative!

3.3 Upgrading

Upgrading is usually just a matter of copying the latest version of TubePress over your existing installation. However, if you want to be sure there are no problems, follow these directions in order.

1. Remove your existing TubePress install directory (wp-content/plugins/tubepress)
2. Unzip the latest version of TubePress into (wp-content/plugins)
3. Visit Site Admin > Settings > TubePress once initialize your options

3.4 Sidebar Widget

The TubePress plugin comes with widget functionality, which allows you to place a customizable list of videos in your blog's sidebar. Here's an example of the widget's output:

There are no separate installation instructions; if you've installed and enabled the TubePress plugin then you're done. Please see the WordPress widget documentation for general info on how to enable and disable widgets.

This is what the TubePress widget control looks like:

In the "Title" section of the widget control, enter the text you'd like for the sidebar's header.

To customize which videos show up in your sidebar, just use a TubePress shortcode. Please note that by default, the TubePress widget will use the following shortcode:

[tubepress resultsPerPage='3', views='false', description='true', descriptionLimit='50', playerLocation='popup', thumbHeight='105', thumbWidth='135']

Of course, like any TubePress shortcode, you can override any setting you like.

3.5 Initialize your options

http://myblog.com

http://myblog.com/wp-content/plugins/tubepress/env/WordPress/functions/db_nuke.php

4. TubePress Pro

4.1 Plain PHP

1. Download
   After you purchase TubePress Pro, check your email that you've registered with PayPal. You'll find an email, from tubepress.org, that contains your download link. When you click on this link, your web browser will prompt you to download (or open) a zip file containing TubePress Pro. Click "Save file" and download the zip file to somewhere easy to find, like your desktop. As of this writing, the name of the zip file is tubepress_pro_1_7_0.zip.
   
   
2. Unzip
   Unzip the file you just downloaded (tubepress_pro_1_7_0.zip). It will expand into a directory named tubepress_pro_1_7_0.
   
   
3. Upload
   This entire directory that you unzipped must be uploaded to your web server in a place that's web accessible. In this example, my webserver has a URL of http://myblog.com and a document root of /var/www/html, so I'll need to upload the entire tubepress_pro_1_7_0 directory to anywhere inside /var/www/html on myblog.com. For this example, I'll just upload the directory to the /var/www/html directory.
   
   Now my TubePress installation is web accessible at http://myblog.com/tubepress_pro_1_7_0 and on the server's filesystem at /var/www/html/tubepress_pro_1_7_0.
   
   
4. Verify upload
   It's a good idea to make sure that the directory you just uploaded is actually readable by your web server. Try navigating to http://myblog.com/tubepress_pro_1_7_0/env/standalone/tubepress-standalone.php. You should get a blank white screen with no errors.
   
   
5. Create gallery page
   I want to create a gallery in /var/www/html/index.php. Below are the contents of index.php. It's an extremely simple PHP file with four steps added to include a TubePress gallery. We'll go the steps one-by-one.

   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   <?php 
   
   /* STEP 1: Enter the web-accessible URL of your TubePress installation */
   $tubepress_base_url = "http://myblog.com/tubepress_pro_1_7_0";
   
   /* STEP 2: Include the TubePress stand-alone library file (tubepress-standalone.php) */
   require_once "tubepress_pro_1_7_0/env/standalone/tubepress-standalone.php";
   ?>
   
   <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
           <head>
                   <title>TubePress Standalone Example</title>
                   <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
                   
                   <!-- STEP 3: Include this statement inside the HEAD of your HTML document -->
                   <?php print tubepressHeadElements(); ?>
       </head>
       <body>
                   <div style="width:500px">
   
                           <!-- STEP 4: Call "tubepressGallery" anywhere you like -->
                           <?php print tubepressGallery("resultsPerPage='3'"); ?>
   
                   </div>
           </body>
   </html>
   

   Step 1:
   Set the tubepress_base_url variable to the web URL of your TubePress Pro installation. In this example, it's http://myblog.com/tubepress_pro_1_7_0.
   
   Step 2:
   Include the TubePress Pro library file, tubepress-standalone.php. This file is located right inside your TubePress Pro installation directory, so in this example it's found at tubepress_pro_1_7_0/env/standalone/tubepress-standalone.php
   
   Step 3:
   In the head of your PHP file, execute print tubepressHeadElements(); one time. This will include TubePress's CSS and JavaScript files.
   
   Step 4:
   Anywhere you want a gallery, just execute print tubepressGallery("resultsPerPage='3'"); Note that you can put any TubePress shortcode syntax as a parameter to this function call. Note that you can leave out the opening and closing brackets of the shortcode (along with the "tubepress" word) if you like.
   
   
6. Result
   Here's the resulting output of the example: http://tubepress.org/pro_demo

4.2 Outside the WordPress loop

1. Include the tubepress-standalone.php file to load up the TubePress Pro libraries
2. Anywhere you'd like a video gallery, type

   print tubepressGallery("resultsPerPage='3'");

   As the argument to this function, you can include any shortcode you'd like (with or without the square brackets).

<?php

        require_once "tubepress/env/standalone/tubepress-standalone.php";

        get_header();

        print tubepressGallery("resultsPerPage='3'");
        
        if (have_posts()) :
           while (have_posts()) :
              the_post();
              the_content();
           endwhile;
        endif;
        get_sidebar();
        get_footer(); 
?>

5. TubePress Shortcodes

TubePress shortcodes are small snippets of text that allow you to easily control the content, style, and behavior of TubePress galleries. There are very similar to WordPress shortcodes, with some minor syntax differences.

TubePress will replace any TubePress shortcodes with a video gallery. Each gallery can be configured completely independently from the others, based on the content of the shortcode.

The simplest shortcode is

[tubepress]

name='value'

So for instance, say I wanted a gallery with

• my favorite videos
• 10 videos per page
• the description included under each thumbnail
• that plays videos using lightWindow

[tubepress mode='favorites', favoritesValue='3hough', resultsPerPage='10', description='true', playerLocation='lightwindow']

5.1 Gallery Options

These settings control which group of videos the gallery will display.

5.1.1 Gallery Descriptions

[tubepress mode='favorites', favoritesValue='3hough']

[tubepress mode='playlist', playlistValue='6813408AE8D50E6F']

[tubepress mode='tag', tagValue='barack obama john mccain']

[tubepress mode='user', userValue='3hough']

5.2 Video Display Options

These settings control the overall viewing experience for the user

5.2.1 Video Players

5.2.2 Video sort order

• Favorites
  A gallery of a user's favorite videos will always be sorted in the order that the videos were favorited.
  
  
• Playlist
  A playlist gallery will always be sorted in the order that the videos appear in the playlist
  
  

5.3 Embedded Player Options

These settings apply to the embedded Flash player from YouTube

5.4 Video Meta Display

These settings control what information gets printed out below each video thumbnail

5.5 Advanced Options

Various features that casual users will not likely need/want to adjust

6. Troubleshooting

6.1 Enable debug mode

This mode will print out tons of debugging information. To use it, you just need to add tubepress_debug=true to the URL string (in your browser's address bar). For instance, if the TubePress page you're trying to debug has an address of

http://ehough.com/?page_id=19

http://ehough.com/?page_id=19&tubepress_debug=true

6.2 YouTube Connection Test

6.2 Discussion Forum

Still can't solve your issue? Try searching or posting in the TubePress discussion forum, hosted by Google Groups. You'll need a Google account to post.

6.3 Open a trouble ticket

If you can't find a solution to your problem in the discussion forum, someone may have already submitted a trouble ticket. The current list of tickets can be found at http://code.google.com/p/tubepress/issues/list. Please feel free to submit a trouble ticket. Note that you'll need a Google account.

7. Contributing

7.1 Submit a patch

1. Checkout the trunk version of TubePress (see section 2.2)
2. Generate your patch against it
3. Submit your patch as an attachment to a new issue report at http://code.google.com/p/tubepress/issues/list

7.2 I18N

As of version 1.6.5, TubePress can be translated into any language using the gettext framework. To submit a translation...

1. Translate the words/phrases in this file from English to your native language
2. Attach the translated file as an attachment to a new issue. Please be sure to note your two-digit country code and your two-digit language code.

You will, of course, receive full credit for your contribution to an open source project! If you're interested in the gory details of how it works, I highly recommend reading WordPress's excellent i18n documentation.

7.3 Donate

TubePress is an open source project. I've spent many long nights working on this project. If you enjoy the software, please consider a donation. No amount is too small. Thanks!