Appendix: TubePress Shortcode Reference

Shortcodes are small snippets of text that give you complete control over TubePress. More specifically, a shortcode is a collection of space-separated name-value pairs (a.k.a. "attributes") that roughly follow the pattern [tubepress optionName="optionValue"].

Examples of valid shortcode syntax

[tubepress name = "value"]
[tubepress name = 'value']
[tubepress name='value']
[tubepress name="value"]
[tubepress name = '"some text" more stuff']
[tubepress name = "'some text' more stuff"]

Examples of invalid shortcode syntax

[tubepress name = 'value"]
[tubepress name = value]
[tubepress name = '"some text more stuff']

Thumbnail Gallery Content

These shortcodes control the content of thumbnail galleries.

Mode name	Description	Notes	Example
`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_discussed`	The most-commented videos on YouTube		`[tubepress mode="most_discussed"]`
`most_recent`	Videos most recently added to YouTube		`[tubepress mode="most_recent"]`
`most_responded`	YouTube videos with the most video responses		`[tubepress mode="most_responded"]`
`most_viewed`	YouTube videos with the most views		`[tubepress mode="most_viewed"]`
`playlist` and `playlistValue`	Videos 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"]`
`tag` and `tagValue`	YouTube videos matching a search term. Supply space-separated search terms to the `tagValue` attribute. To search for an exact phrase, enclose the phrase in double quotes. Use the pipe character (`\|`) to indicate a boolean OR, and the minus character (`-`) to exclude a term.	Limited to approximately 1000 videos	`[tubepress mode="tag" tagValue='"pittsburgh steelers" -highlights playoffs\|superbowl']`
`top_rated`	Videos with the highest ratings.		`[tubepress mode="top_rated"]`
`user` and `userValue`	YouTube 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"]`
`youtubeTopFavorites`	YouTube videos most often added as favorites		`[tubepress mode="youtubeTopFavorites"]`
`vimeoUploadedBy` and `vimeoUploadedByValue`	Videos uploaded by the given Vimeo user. The Vimeo user is defined by the value you supply to the `vimeoUploadedByValue` attribute.		`[tubepress mode="vimeoUploadedBy" vimeoUploadedByValue="mattkaar"]`
`vimeoLikes` and `vimeoLikesValue`	Videos "liked" by the given Vimeo user. The Vimeo user is defined by the value you supply to the `vimeoLikesValue` attribute.		`[tubepress mode="vimeoLikes" vimeoLikesValue="coiffier"]`
`vimeoAppearsIn` and `vimeoAppearsInValue`	Videos in which the given Vimeo user appears. The Vimeo user is defined by the value you supply to the `vimeoAppearsInValue` attribute.		`[tubepress mode="vimeoAppearsIn" vimeoAppearsInValue="royksopp"]`
`vimeoSearch` and `vimeoSearchValue`	Vimeo videos matching a search term. Supply space-separated search terms to the `vimeoSearchValue` attribute. To search for an exact phrase, enclose the phrase in double quotes. Use the minus character (`-`) to exclude a term.		`[tubepress mode="vimeoSearch" vimeoSearchValue='"celebrity gossip" -snooky']`
`vimeoCreditedTo` and `vimeoCreditedToValue`	Vimeo videos in which the given user uploaded and/or appears. The Vimeo user is defined by the value you supply to the `vimeoCreditedToValue` attribute.		`[tubepress mode="vimeoCreditedTo" vimeoCreditedToValue="patricklawler"]`
`vimeoChannel` and `vimeoChannelValue`	Vimeo videos in the given channel. The channel is defined by the value you supply to the `vimeoChannelValue` attribute.		`[tubepress mode="vimeoChannel" vimeoChannelValue="splitscreenstuff"]`
`vimeoAlbum` and `vimeoAlbumValue`	Vimeo videos in the given album. The album is defined by the value you supply to the `vimeoAlbumValue` attribute.		`[tubepress mode="vimeoAlbum" vimeoAlbumValue="140484"]`
`vimeoGroup` and `vimeoGroupValue`	Vimeo videos in the given group. The group is defined by the value you supply to the `vimeoGroupValue` attribute.		`[tubepress mode="vimeoGroup" vimeoGroupValue="hdxs"]`

Single-Video Embeds

Setting	Description	Example	Provider
video	The ID of the video to embed	`[tubepress video="J51kfduN5aA"]`

Thumbnail Gallery Appearance

These settings control details on how your thumbnail galleries are displayed.

Setting	Description	Valid values	Example
`ajaxPagination`	TubePress Pro only. Use AJAX to paginate galleries asynchronously.	`true` or `false`	`[tubepress ajaxPagination="true"]`
`descriptionLimit`	Limit 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"]`
`hqThumbs`	TubePress Pro only. High quality thumbnails.	`true` or `false`	`[tubepress hqThumbs="true"]`
`paginationAbove`	If `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` or `false`	`[tubepress paginationAbove="true"]`
`paginationBelow`	If `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` or `false`	`[tubepress paginationBelow="true"]`
`randomize_thumbnails`	Randomize thumbnail selection for each video (each video comes with several thumbnails)	`true` or `false`	`[tubepress randomize_thumbnails="false"]`
`relativeDates`	Display `yesterday` instead of `November 3, 2009`, for instance.	`true` or `false`	`[tubepress relativeDates="true"]`
`resultsPerPage`	How many video thumbnails to display on a single page	Any positive integer less than 50	`[tubepress resultsPerPage="30"]`
`theme`	TubePress theme to use for this gallery		`[tubepress template="custom_template.tpl.html"]`
`thumbHeight`	Vertical size (in px) of thumbnails	Any positive integer	`[tubepress thumbHeight="45"]`
`thumbWidth`	Horizontal size (in px) of thumbnails	Any positive integer	`[tubepress thumbWidth="60"]`

Embedded 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.

`playerLocation` value	Description	Example
`fancybox`	TubePress Pro only. Plays videos using FancyBox	`[tubepress playerLocation="fancybox"]`
`jqmodal`	Plays 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"]`
`popup`	Plays videos in an HTML popup window	`[tubepress playerLocation="popup"]`
`shadowbox`	Plays videos using ShadowBox	`[tubepress playerLocation="shadowbox"]`
`solo`	After clicking a thumbnail, the entire page will refresh. The gallery will be replaced with a single video embed of the selected video, along with all meta information. The user must user their browser's "back" button to return to the gallery.	`[tubepress playerLocation="solo"]`
`static`	Behaves 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"]`
`tinybox`	TubePress Pro only. Plays videos using TinyBox	`[tubepress playerLocation="tinybox"]`
`vimeo`	Redirects to the video's original Vimeo page.	`[tubepress playerLocation="vimeo"]`
`youtube`	Redirects to the video's original YouTube page.	`[tubepress playerLocation="youtube"]`

Thumbnail Gallery Sort Order

The sorting capabilities of TubePress are limited by the providers of the videos (e.g. YouTube or Vimeo). 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.

`orderBy` value	Description	Notes	Example
`published`	Show videos in the order they were published	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. Does not apply to YouTube playlists.	`[tubepress orderBy="viewCount"]`
`rating`	Shows videos in order of their rating	YouTube galleries will show higher-rated videos first. Does not apply to YouTube playlists.	`[tubepress orderBy="rating"]`
`relevance`	Shows videos in order of relevance	Only applies to YouTube `tag` and Vimeo `search` galleries	`[tubepress orderBy="relevance"]`
`random`	Shuffles videos	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. For Vimeo, only applies to `vimeoGroup` galleries.	`[tubepress orderBy="random"]`
`position`	Shows videos in the order they were added to a playlist	Only applies to YouTube `playlist` galleries	`[tubepress orderBy="position"]`
`commentCount`	Shows videos in order of comment count	For YouTube, only applies to `playlist` galleries. Shows most-commented to least-commented.	`[tubepress orderBy="commentCount"]`
`duration`	Shows videos in order of length	Only applies to YouTube `playlist` galleries. Shows longest videos first.	`[tubepress orderBy="duration"]`
`title`	Shows videos in alphabetical order by title	Only applies to YouTube `playlist` galleries.	`[tubepress orderBy="title"]`
`newest`	Shows video in they order they were published. Newest first.		`[tubepress orderBy="newest"]`
`oldest`	Shows video in they order they were published. Oldest first.		`[tubepress orderBy="oldest"]`

The following galleries can't be sorted

A YouTube gallery of a user's favorite videos (mode="favorites") will always be sorted in the order that the videos were favorited.
A YouTube playlist gallery (mode="playlist") will always be sorted in the order that the videos appear in the playlist
Vimeo album galleries (mode="vimeoAlbum")
Vimeo channel galleries (mode="vimeoChannel")

Embedded Video Player Shortcodes

These shortcodes control the appearance and behavior the actual video player (Flash, HTML5, etc).

Setting	Description	Valid values	Examples
`autoplay`	Start video playback without user intervention	`true` or `false`	`[tubepress autoplay="true"]`
`embeddedHeight`	Vertical size (in px) of embedded player	Any positive integer	`[tubepress embeddedHeight="480"]`
`embeddedWidth`	Horizontal size (in px) of embedded player	Any positive integer	`[tubepress embeddedWidth="640"]`
`fullscreen`	Allow fullscreen playback	`true` or `false`	`[tubepress fullscreen="true"]`
`hd`	Display high definition videos	`true` or `false`	`[tubepress hd="true"]`
`loop`	Repeat videos without user intervention	`true` or `false`	`[tubepress loop="true"]`
`playerColor`	Primary color of embedded player	Six hexadecimal digits, representing a valid HTML color code	`[tubepress playerColor="ffaabb"]`
`playerHighlight`	Highlight color of embedded player	Six hexadecimal digits, representing a valid HTML color code	`[tubepress playerColor="aa2233"]`
`playerImplementation`	Choose vendor of embedded Flash player. Choose from the provider implementation (YouTube, Vimeo, etc), or the JW FLV Media Player from LongTail (for YouTube only).	`youtube` or `longtail`	`[tubepress playerImplementation="longtail"]`
`showInfo`	Display title and rating before playback	`true` or `false`	`[tubepress showInfo="true"]`
`showRelated`	Display related videos after playback	`true` or `false`	`[tubepress showRelated="true"]`

Video Meta Display

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

Setting	Description	Valid values	Example
`author`	Display video author	`true` or `false`	`[tubepress author="true"]`
`category`	Display video category	`true` or `false`	`[tubepress category="false"]`
`description`	Display video description	`true` or `false`	`[tubepress description="false"]`
`id`	Display video ID	`true` or `false`	`[tubepress id="true"]`
`length`	Display video run time	`true` or `false`	`[tubepress length="false"]`
`likes`	Display Vimeo "likes" count	`true` or `false`	`[tubepress likes="true"]`
`rating`	Display average video rating	`true` or `false`	`[tubepress rating="true"]`
`ratings`	Display video rating count	`true` or `false`	`[tubepress ratings="true"]`
`tags`	Display video keywords	`true` or `false`	`[tubepress tags="false"]`
`title`	Display video title	`true` or `false`	`[tubepress title="true"]`
`uploaded`	Display video upload timestamp	`true` or `false`	`[tubepress uploaded="false"]`
`url`	Display video URL on YouTube	`true` or `false`	`[tubepress url="false"]`
`views`	Display video view count	`true` or `false`	`[tubepress views="true"]`

Video Feed Provider

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

Setting	Description	Valid values	Example
`cacheEnabled`	Use a file-based cache to store responses from provider	`true` or `false`	`[tubepress cacheEnabled="false"]`
`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` or `false`	`[tubepress embeddableOnly="true"]`
`filter_racy`	Retrieve videos that may be unsuitable for minors	`true` or `false`	`[tubepress filter_racy="true"]`
`resultCountCap`	Maximum total videos to retrieve. This can help to reduce the number of pages in your gallery. Set to "0" to remove any limit.	Any non-negative integer.	`[tubepress resultCountCap="500"]`
`searchResultsRestrictedToUser`	Restrict search results to videos uploaded by the given user.	Any valid YouTube or Vimeo username	`[tubepress mode="tag" tagValue="cats" searchResultsRestrictedToUser="3hough"]`
`vimeoKey`	Vimeo API "consumer key". Click here to register a key and secret.	Any valid Vimeo API consumer key	`[tubepress vimeoSecret="14cd6be163fa2e42" vimeoKey="e3647c0ab1953a38eaca38d6a34f8204"]`
`vimeoSecret`	Vimeo API "consumer secret". Click here to register a key and secret.	Any valid Vimeo API consumer secret	`[tubepress vimeoSecret="14cd6be163fa2e42" vimeoKey="e3647c0ab1953a38eaca38d6a34f8204"]`

Interactive Search

These shortcodes control TubePress's interactive search functionality.

`output` Value	Description	Example
`ajaxSearchInput`	TubePress Pro only. Display an ajax-enabled search input box and submit button. The HTML template used is resolved from `search/ajax_search_input.tpl.php` in the current theme. Use `searchResultsDomId` (see below) to identify where to display the search results.	`[tubepress output="ajaxSearchInput" searchResultsDomId="#someDiv"]`
`searchInput`	Display a search input box and submit button. The HTML template used is resolved from `search/search_input.tpl.php` in the current theme. See also the `searchResultsUrl` shortcode attribute.	`[tubepress output="searchInput"]`
`searchResults`	Display a gallery with the search results from `searchInput`. By default this setting will display a gallery with default settings if no search was detected. (see `searchResultsOnly` shortcode attribute). Use `searchProvider` shortcode attribute to select Vimeo or YouTube search results.	`[tubepress output="searchResults" searchProvider="vimeo"]`

Setting	Description	Valid values	Example
`searchProvider`	Used in conjunction with `output="searchResults"`, this attribute defines which video provider's videos will show up in the search results.	`youtube` or `vimeo`	`[tubepress output="searchResults" searchProvider="youtube"]`
`searchResultsDomId`	Used in conjunction with `output="ajaxSearchInput"`, this attribute defines (in jQuery selector syntax) the DOM element into which TubePress will inject search results.	Any valid DOM element that can contain HTML.	`[tubepress output="ajaxSearchInput" searchResultsDomId="#mydiv"]`
`searchResultsUrl`	Used in conjunction with `output="searchInput"`, this attribute defines the full URL that will display the search results. By default, TubePress will display the results on the same page as the search box. See `searchResultsOnly`.	A full URL of a page containing an invocation of TubePress with `output="searchResults"`	`[tubepress output="searchInput" searchResultsUrl="http://mysite.com/videos.php"]`
`searchResultsOnly`	Used in conjunction with `output="searchResults"`. Set to `true` to only display search results when a user is searching. By default, if TubePress is invoked with `output="searchResults"`, it will display a placeholder gallery.	`true` or `false`	`[tubepress output="searchResults" searchResultsOnly="true"]`

Advanced Settings

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

Setting	Description	Valid values	Example
`cacheCleaningFactor`	The inverse of this setting will determine how often the cache is cleaned. i.e. the cache will be cleaned every 1/X cache writes. Enter 0 to disable cleaning.	Any non-negative integer	`[tubepress cacheCleaningFactor="20"]`
`cacheDirectory`	The directory in which to store cache files.	The absolute path of a writeable directory on your sever.	`[tubepress cacheDiretory="/some/directory/cache"]`
`cacheLifetimeSeconds`	The number of seconds until a cached item is considered stale.	Any positive integer.	`[tubepress cacheLifetimeSeconds="3600"]`
`dateFormat`	Formatting of date information for videos. See http://us.php.net/manual/en/function.date.php for examples	Any valid string as defined by http://us.php.net/manual/en/function.date.php	`[tubepress dateFormat="l jS \of F Y h:i:s A"]`
`debugging_enabled`	Enable ability to perform remote debugging	`true` or `false`	`[tubepress debugging_enabled="false"]`
`disableHttpTransportCurl`	Disable cURL HTTP transport	`true` or `false`	`[tubepress disableHttpTransportCurl="true"]`
`disableHttpTransportExtHttp`	Disable HTTP extension transport	`true` or `false`	`[tubepress disableHttpTransportExtHttp="true"]`
`disableHttpTransportFopen`	Disable fopen HTTP transport	`true` or `false`	`[tubepress disableHttpTransportFopen="true"]`
`disableHttpTransportFsockOpen`	Disable fsockopen HTTP transport	`true` or `false`	`[tubepress disableHttpTransportFsockOpen="true"]`
`disableHttpTransportStreams`	Disable PHP streams HTTP transport	`true` or `false`	`[tubepress disableHttpTransportStreams="true"]`
`videoBlacklist`	List of video IDs that should never be displayed.	A comma-separated list of videos IDs	`[tubepress videoBlacklist="17jymDn0W6U"]`

appendix/shortcodes.txt · Last modified: 2011/07/31 23:06 by Eric Hough