7. TubePress Shortcodes

TubePress shortcodes are small snippets of text that allow you to easily and completely control the content, style, and behavior of TubePress galleries. They are invoked slightly differently in the WordPress plugin and in TubePress Pro, but the actual shortcodes themselves are identical.

In TubePress terminology, a shortcode is a collection of name-value pairs (a.k.a. "attributes") that follow the pattern optionName=optionValue, where optionValue is wrapped with single or double quotes (e.g. foo="bar"). Each valid shortcode attribute is defined in Section 7.3, “TubePress Shortcode Reference”.

7.1 WordPress

TubePress shortcodes are very similar to WordPress shortcodes, but with minor syntax differences. TubePress will replace any TubePress shortcode it finds in a post or page 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]

In a post or a page, TubePress will replace this shortcode with a video gallery defined by the default settings. You can override each TubePress setting by providing any of the shortcode attributes found in Section 7.3, “TubePress Shortcode Reference”.

7.2 Standalone PHP

In TubePress Pro, you can provide shortcode attributes found in Section 7.3, “TubePress Shortcode Reference” to the tubepressGallery function to completely control the behavior of your galleries. e.g. 

print tubepressGallery("ajaxPagination='true' author='false'");

Each gallery can be configured completely independently from the others, based on the content of the shortcode.

7.3 TubePress Shortcode Reference

7.3.1 Gallery Content

These shortcodes determine which videos will populate the gallery

Table 7.1. Gallery Content Shortcodes

Mode NameDescriptionNotesExample
favorites and favoritesValue"Favorite" videos of a YouTube user. The YouTube user is defined by the value you supply to the favoritesValue attribute.Limited to 50 videos[tubepress mode="favorites" favoritesValue="3hough"]
recently_featured The lastest "featured" videos on YouTube's homepage [tubepress mode="recently_featured"]
most_discussedThe most-commented videos on YouTube [tubepress mode="most_discussed"]
most_linkedYouTube videos with the most links [tubepress mode="most_linked"]
most_recentYouTube videos most recently uploaded to YouTube [tubepress mode="most_recent"]
most_respondedYouTube videos with the most video responses [tubepress mode="most_responded"]
playlist and playlistValueVideos from a YouTube playlist. The playlist is defined by the value you supply to the playlistValue attribute.

  • Limited to 200 videos

  • Only public playlists can be shown with TubePress.

  • Videos will appear in the order in which they were added to the playlist.

 [tubepress mode="playlist" playlistValue="6813408AE8D50E6F"]
mobileYouTube videos suitable for mobile devices [tubepress mode="mobile"]
tag and tagValueYouTube videos matching a search term. The search term is defined by the value you supply to the tagValue attribute. Limited to approximately 1000 videos[tubepress mode="tag" tagValue="barack obama john mccain"]
user and userValueYouTube videos uploaded by a specific YouTube user. The YouTube user is defined by the value you supply to the userValue attribute. Limited to approximately 1000 videos[tubepress mode="user" userValue="3hough"]

7.3.2 Single video embedding

Table 7.2. Single video shortcodes

SettingDescriptionNotesExample
videoThe ID of the video to embed [tubepress video="J51kfduN5aA"]

7.3.3 Display Options

These settings control the overall appearance of the gallery

Table 7.3. Display Options

SettingDescriptionValid Value(s)Example
ajaxPaginationTubePress Pro only. Use AJAX to paginate galleries asynchronously.

  • true

  • false

[tubepress ajaxPagination="true"]
descriptionLimitLimit the length of video descriptions to a certain number of characters. This can help prevent video descriptions from overflowing onto other thumbnails. Any positive integer[tubepress descriptionLimit="50"]
paginationAboveIf resultsPerPage is less than the total number of videos in the gallery, setting this value to true will display pagination links above the gallery thumbnails

  • true

  • false

[tubepress paginationAbove="true"]
paginationBelowIf resultsPerPage is less than the total number of videos in the gallery, setting this value to true will display pagination links below the gallery thumbnails

  • true

  • false

[tubepress paginationBelow="true"]
relativeDatesDisplay yesterday instead of November 3, 2009, for instance.

  • true

  • false

[tubepress relativeDates="true"]
resultsPerPageHow many video thumbnails to display on a single pageAny integer x such that 0 < x <= 50[tubepress resultsPerPage="30"]
templateCustom templateName of a readable file located in ui/gallery/html_templates (for galleries) or ui/single_video/html_templates (for single videos). These are the only permissible locations for custom templates.[tubepress template="custom_template.tpl.html"]
thumbHeightVertical size (in px) of thumbnailsAny integer x such that 0 < x <= 90[tubepress thumbHeight="45"]
thumbWidthHorizontal size (in px) of thumbnailsAny integer x such that 0 < x <= 120[tubepress thumbWidth="60"]

7.3.4 Player Locations

In TubePress terminology, a "player location" defines where the embedded video player will appear after the user clicks a thumbnail to play a video. TubePress offers several different options, each of which can be activated by supplying the desired value to the playerLocation shortcode attribute.

Table 7.4. Player Locations

playerLocation ValueDescriptionExample
fancyboxTubePress Pro only. Plays videos using FancyBox[tubepress playerLocation="fancybox"]
jqmodalPlays videos using jqModal[tubepress playerLocation="jqModal"]
normal

Plays videos in an embedded Flash player above the video thumbnails. If you'd like the page to load with a specific video at the top of the gallery, just add the video's ID to the address of you gallery as the tubepress_video parameter.

For instance, given a gallery with a URL of http://mygallery.com, navigating to http://mygallery.com?tubepress_video=CNo7Hm0IOag would start the gallery with the video with ID CNo7Hm0IOag in the embedded player.

[tubepress playerLocation="normal"]
popupPlays videos in an HTML popup window[tubepress playerLocation="popup"]
shadowboxPlays videos using ShadowBox[tubepress playerLocation="shadowbox"]
staticBehaves exactly the same as the normal player, but each thumbnail click will trigger a page refresh. This can be useful if you want to increase page loads for advertising purposes. It also makes it clearer to your users on how they can share links to individual videos.[tubepress playerLocation="static"]
tinyboxTubePress Pro only. Plays videos using TinyBox[tubepress playerLocation="tinybox"]
youtube Redirects to the video's original YouTube page [tubepress playerLocation="youtube"]

7.3.5 Video Sort Order

The sorting capabilities of TubePress are limited by the providers of the videos (e.g. YouTube). Sorting functionality can be quirky, and there are some limitations. Below are the shortcodes, all based on the orderBy attribute, that control the video sort order.

Table 7.5. Video Sort Order

orderBy ValueDescriptionNotesExample
published Show videos in the order they were published YouTube galleries will show more-recent videos first[tubepress orderBy="published"]
viewCount Shows videos in order of how many times they've been viewed YouTube galleries will show more-viewed videos first[tubepress orderBy="viewCount"]
rating Shows videos in order of their rating YouTube galleries will show higher-rated videos first[tubepress orderBy="rating"]
relevance Shows videos in order of relevance Only applies to YouTube tag galleries[tubepress orderBy="relevance"]
random Shuffles videos for a given gallery page Will only randomize the order for a single gallery page. e.g. If you have a gallery with a total of 500 videos, with 20 videos per page, only 20 videos at a time will be shuffled. This is a restriction on YouTube's end.[tubepress orderBy="random"]

Note

Please note that these galleries can't be sorted

  • A gallery of a user's favorite videos (mode="favorites") will always be sorted in the order that the videos were favorited.

  • A playlist gallery (mode="playlist") will always be sorted in the order that the videos appear in the playlist

7.4 Embedded Player

These shortcodes control the appearance and behavior the embedded Flash player.

Table 7.6. Embedded Player Shortcodes

SettingDescriptionValid ValuesExample
autoplayStart video playback without user intervention

  • true

  • false

[tubepress autoplay="true"]
borderFrame embedded player

  • true

  • false

[tubepress border="true"]
embeddedHeightVertical size (in px) of embedded playerAny positive integer[tubepress embeddedHeight="true"]
embeddedWidthHorizontal size (in px) of embedded playerAny positive integer[tubepress embeddedWidth="true"]
fullscreenAllow fullscreen playback

  • true

  • false

[tubepress fullscreen="true"]
genieDisplay "genie" menu during video playback

  • true

  • false

[tubepress genie="true"]
hdDisplay high definition videos

  • true

  • false

[tubepress hd="true"]
loopRepeat videos without user intervention

  • true

  • false

[tubepress loop="true"]
playerColorPrimary and secondary colors of embedded playerTwo HTML color values in hex, combined with a single forward slash[tubepress playerColor="0xffaabb/0xaa2233"]
playerImplementationChoose vendor of embedded Flash player. Current choices are the standard YouTube player, or the JW FLV Media Player from LongTail.

  • youtube

  • longtail

[tubepress playerImplementation="longtail"]
showInfoDisplay title and rating before playback

  • true

  • false

[tubepress showInfo="true"]
showRelatedDisplay related videos after playback

  • true

  • false

[tubepress showRelated="true"]

7.5 Video Meta Display

These shortcodes control what information is displayed below each video thumbnail.

Table 7.7. Video Meta Display

SettingDescriptionValid ValuesExample
authorDisplay video author

  • true

  • false

[tubepress author="true"]
categoryDisplay video category

  • true

  • false

[tubepress category="false"]
descriptionDisplay video description

  • true

  • false

[tubepress description="false"]
idDisplay video ID

  • true

  • false

[tubepress id="true"]
lengthDisplay video run time

  • true

  • false

[tubepress length="false"]
ratingDisplay average video rating

  • true

  • false

[tubepress rating="true"]
ratingsDisplay video rating count

  • true

  • false

[tubepress ratings="true"]
tagsDisplay video keywords

  • true

  • false

[tubepress tags="false"]
titleDisplay video title

  • true

  • false

[tubepress title="true"]
uploadedDisplay video upload timestamp

  • true

  • false

[tubepress uploaded="false"]
urlDisplay video URL on YouTube

  • true

  • false

[tubepress url="false"]
viewsDisplay video view count

  • true

  • false

[tubepress views="true"]

7.6 Video Feed

These shortcodes control how TubePress interacts with content providers (e.g. YouTube)

Table 7.8. Video Feed Shortcodes

SettingDescriptionValid ValuesExample
cacheEnabled Use a file-based cache to store responses from provider

  • true

  • false

[tubepress cacheEnabled="false"]
clientKey The YouTube Client Key when interacting with YouTube Any valid YouTube Client Key[tubepress clientKey="33AEF33BBC344"]
developerKey The YouTube Developer Key when interacting with YouTube Any valid YouTube Developer Key[tubepress developerKey="33AEF33BBC344"]
embeddableOnly Only retrieve videos that can be embedded in other sites

  • true

  • false

[tubepress embeddableOnly="true"]
filter_racy Retrieve videos that may be unsuitable for minors

  • true

  • false

[tubepress filter_racy="true"]
resultCountCapMaximum total videos to retrieveAny integer x such that x >= 0This can help to reduce the number of pages in your gallery. Set to "0" to remove any limit.

7.7 Advanced

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

Table 7.9. Advanced Shortcodes

SettingDescriptionValid ValuesExample
dateFormatFormatting of date information for videos. See http://us.php.net/date for examplesAny valid string as defined by http://php.net/date[tubepress dateFormat="l jS \of F Y h:i:s A"]
debugging_enabledEnable ability to perform remote debugging

  • true

  • false

[tubepress debugging_enabled="false"]
randomize_thumbnailsRandomize thumbnail selection for each video (each video comes with several thumbnails)

  • true

  • false

[tubepress randomize_thumbnails="false"]

Prev   Next
6. Customizing Home 8. TubePress in Your Language