HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS, which is now in beta. ocPortal 9 will be superseded by Composr 10.

Head over to compo.sr for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.


YouTube Channel Integration Block discussion

Login / Search

 [ Join | More ]
 Add topic 
Posted
Item has a rating of 5 (Liked by KingBast)  
Rating:
#107766 (In Topic #21001)
Avatar

Community saint

Greetings everybody!

**NOTE**
Important! If you downloaded and installed the YouTube Channel Integration addon from the links that were available at http://ocportal.com/forum/topicview/misc/deploying/problem-downloading-an.htm, you should delete that .tar file, uninstall the addon, and install it again through Adminzone>Structure>Addons>Import non-bundled addon(s) by downloading it from the ocPortal addon repository. The final version in github and in the addon downloads area contains a couple of tweaks and fixes that weren't in that previously posted version.

**IMPORTANT UPGRADE INSTRUCTIONS**
If you upgraded before reading the instructions, chances are you either don't see the correct block configuration settings or you now have a duplicate 'Time between updates' setting. You can easily correct this by logging in to your web site as an admin, click the OcCLE button in the left hand side of your web site footer, and copy and paste the following command in there (copy it exactly, including the leading colon):

:require_code('zones2'); upgrade_block('youtube_channel');

and hit Enter. Then you can type exit to close the OcCLE popup. If that doesn't work or you aren't comfortable with the OcCLE, you can also go to Adminzone>Tools>ocPortal Upgrader, login to the upgrader, and click the Do a database upgrade button in Step 5. You should now have just one 'Time between updates' setting and a YouTube API Key setting.

If you are currently using an older version of this addon, it is important you follow these steps or your site may generate Stack Trace errors or the block on your site will show Errors until you complete these steps.

First, if you don't already have one, you should get a YouTube API Key to use for this addon on your web site.
Getting Your YouTube API v3 Key:
1. If you don't have a Google account (i.e. GMail/Google+), I think you will need one.
2. Go to http://console.developers.google.com/project
3. From there you will click the Create Project button to create a new project.
4. On the New Project popup, give your project a name. Something like YouWebSite YouTube Channel Block is good. The Project ID is not important, but you can change it if you want. And then click the Create button.
5. Once created, it should take you to the Project Dashboard for your newly created project. On the left hand menu, click APIs & auth and then click APIs.
6. On the right hand side of the page you should see a list of popular APIs. Select the YouTube Data API or type YouTube into the search box and select YouTube Data API v3.
7. You should now click the the Enable API button to enable the YouTube Data API v3 for your project.
8. Next, on the left hand menu under the APIs & auth section, click Credentials.
9. On the right hand side of the page, click the Create new Key button under the Public API Access section.
10. On the Create a new key popup, click the Server key button.
11. On the Create a server key and configure allowed IPs popup, you can just click the Create button. You can also enter your web server IP(s) in the box there to restrict your API key access to requests only coming from your web server. This would prevent other people from stealing and using your key on their server. It shouldn't be a problem as long as your key isn't compromised, and it may cause problems with shared hosting since their servers are more likely to change IP addresses without warning and may result in failed API requests until you update the IPs.
12. That it. You should now see an API key listed in the Public API access section of the Credentials page.

To monitor quota usage, go back to the APIs menu option and select the YouTube Data API link. That page will have an Overview, Usage, and Quotas tabs. The Usage tab will tell you how many requests per second are being used. The Quotas tab will tell you what your API data units limit is and how many units are remaining for the current day.

Now that you have your YouTube API key, you can begin installing or upgrading the block. If you are performing a fresh new install and don't have an old version installed follow these steps:
1. Login to your site as admin and go to Adminzone>Structure>Addons, scroll down to the bottom of the page and click the Import non-bundled addon(s) link.
2. On the Import non-bunbled addon(s) page, click the Download radio button, then click the + by Third Party Integration.
3. Select YouTube Channel Integration, and then click the Import non-bundled addon(s) button at the bottom of the page.
4. Follow the prompts through to the end.
5. If only you will be using the YouTube Channel Integration block, you can enter your API key in the block configuration setting so it doesn't have to be specified in the block parameters for each usage of the block. To do that, go to Adminzone>Setup>Configuration>Block options, scroll down to the YouTube Channel Integration options, and enter your YouTube API Key. You can also set the update time setting that will control how long the block is cached. This update time basically controls how often the block makes its calls to the YouTube Data API. A shorter update time will incur more YouTube Data API quota usage and a longer update time will incur less quota usage.

If you have a previous version of the addon installed follow these steps:
1. If you are currently using the block on any of your pages, you should close your site during this upgrade process. The easy way is to do this is to open the ocPortal Upgrader in a new browser tab. Go to Adminzone>Tools>ocPortal Upgrader, login to the upgrader, and click the Close the site button by Step 2. You can refer back to this browser tab and click the Open the site button by Step 8 when you are done with these upgrade steps.
2. Go to Adminzone>Structure>Addons, find the YouTube Channel Integration Block in the addons list, and click the red X to uninstall it.
3. Go back to Adminzone>Structure>Addons, scroll down to the bottom of the page and click the Import non-bundled addon(s) link.
4. On the Import non-bunbled addon(s) page, click the Download radio button, then click the + by Third Party Integration.
5. Select YouTube Channel Integration, and then click the Import non-bundled addon(s) button at the bottom of the page.
6. Follow the prompts through to the end.
7. If only you will be using the YouTube Channel Integration block, you can enter your API key in the block configuration setting so it doesn't have to be specified in the block parameters for each usage of the block. To do that, go to Adminzone>Setup>Configuration>Block options, scroll down to the YouTube Channel Integration options, and enter your YouTube API Key. You can also set the update time setting that will control how long the block is cached. This update time basically controls how often the block makes its calls to the YouTube Data API. A shorter update time will incur more YouTube Data API quota usage and a longer update time will incur less quota usage.
8. All done. If you closed your site during this upgrade, don't forget to go back and re-open it!

Just a couple of last notes about upgrading. This is mostly backward compatible with the previous version. The two areas of concern would be the use of the orderby and start_video block parameters. The orderby parameter no longer functions and isn't supported in certain YouTube Data API v3 calls. The video results are typically in newest to oldest order for the user/channel uploads playlist. Other playlists may return results in the order specified by the playlist. The start_video parameter would previously allow you to fetch results from beyond the 50 video per API call limit. This will no longer work, so the start_video block parameter is now limited to 50.



The addon is now available in the Addons->Version 9.0->3rd Party Integration downloads section: YouTube Channel Integration Block (The addon is also committed to the v9 branch of the ocPortal github repository)

I've started this topic for the YouTube Channel Integration Block addon to report bugs, to suggest additions and improvements, and to provide some documentation for the templates. If you use the addon and find any bugs, please report them here or in the comments for the addon in the Addons page. Same goes for suggestions.

Changes from previous version:
  • The block is updated to work with the YouTube Data API v3.
  • YouTube Data API v3 requires an API key. A block config option and block parameter have been added to allow you to specify your API key.
  • Added support for specifying playlist IDs.
  • The orderby block parameter no longer functions due to changes in the YouTube Data API v3. It is left in for backward compatibility, but it doesn't do anything.
  • You won't be able to use the start_video parameter to pull video results beyond the 50 video return result limit of the YouTube API call. The v3 API implements a new next-page/prev-page mechanism that I won't be implementing in this block. You can still use the start_video parameter. For example, you can define one youtube_channel block with a start_video of 1, max_videos of 1, and a style of 2, then another youtube_channel block under it with a start_video of 2, max_videos of 9, and style of 3, to give you a page of 10 videos where the first video uses style 2 and the remaining 9 use style 3.
  • Shortened version of the descriptions are now available with the {DESCRIPTION_SHORT} tempcode.
  • Star rating images are no longer being served by YouTube so I have now included them with the addon.
  • Added two new thumbnail options (6 = Standard definition and 7 = Max resolution). They aren't available for all videos, so they may not be very useful. Thumbnails 3, 4, and 5 are no longer returned by the API calls but seem to still be available when calling their links, so I've left them in for backward compatibility and manually build the links to these three thumbnails.
  • Some minor bug fixes and code cleanup, and heavy commenting of the code.

The list of bugs and improvements:
  • None at this time.

Documentation:

Some quick notes...The block is listed in the Version 9.0 addons download section. If you are using ocPortal 9.x.x, you can download and install the addon from your web site Adminzone>Structure>Addons area. If you are using ocPortal 8.x.x, you can download the version 9.0 addon and manually upload and install it from your web site Admin Zone>Structure>Addons area. See the upgrade notes above to avoid any installation problems! This addon hasn't been tested on any version prior to ocPortal v9.0.19, but should be functional backwards to ocPortal v8.x. This addon requires a YouTube API Key to be specified as a block parameter or you can specifiy the key as a block configuration option. If you choose to specify the YouTube API Key as a block parameter, it will override the YouTube API Key block configuration setting. If you allow other members to use this block, you should leave the YouTube API Key configuration option blank and have your members get their own key and have them specify their own key as a block parameter. A 'Time between updates' block configuration option is also available to control how often the cached data for the block is generated. By default it is set to 60 minutes. This means the block will call the YouTube API to regenerate the block data no more often than once every 60 minutes. You can set this 'Time between updates' time to any value your want. A smaller value will keep things updated more often at the expense of more web site bandwidth and API quota usage. If you turn off the block caching in the advanced block parameter settings, this 'Time between updates' will have no effect and the block will call the YouTube API each time the block is called. Disabling the cache is good for testing, but keeping it disabled is highly discouraged since it will likely slow down your web site, possibly use up excessive amounts of your web site bandwidth with YouTube API calls, and use significantly more YouTube API quota usage. You will find the two block configuration options at Admin Zone>Setup>Configuration>Block options.

The addon comes with a default set of template files. The style template is used to build the individual video and metadata layout, and the main template acts as a container for all of the videos. I have created a single template with four different styles that should give you a good start without having to mess around with coding up your own template. However, if you do want to stylize and integrate videos in other ways, you can create your own custom templates. To do this, you shouldn't modify the existing templates or they may be overwritten when updating the addon in the future. Instead, you will create a new template with a specific name in the template_custom directory. Start with the original template name and append an underscore and your custom template name to it. If the original template name is BLOCK_YOUTUBE_CHANNEL_STYLE.tpl, you would copy or create a new file named something like BLOCK_YOUTUBE_CHANNEL_STYLE_myvideostyle.tpl. Keep the original part of the file name in CAPS and add the underscore and custom name. Then alter this new template or clear it and start fresh. To use your new _myvideosyle template, in the block parameters, set the Template Style parameter to myvideostyle (or whatever custom name you append to the original file name). Not tested, but I'm pretty sure case matters. If you used lower case for your appended custom name, then use lower case for the Template Style parameter. If you appended something like _MyVideoStyle, then you would use MyVideoStyle as the Template Style parameter. The Style block parameter can be used as you wish in your custom templates. I used numbers 1, 2, and 3 to define three different layouts in the default provided template, but you can change it to use text to define various layouts in a single custom template. If you're not too familiar with template logic code, you can ignore the Style parameter that is used by template logic code to control what html parts are visible. Instead, you can create as many custom templates as you want, each with a different layout.

Here is the documentation for what tempcode {VARIABLES} are used in the Style template (BLOCK_YOUTUBE_CHANNEL_STYLE.tpl). Each valid {VARIABLE} used in any Style templates will be replaced with the data specified in the documentation below:
  • {CHANNEL_NAME} = This will be one of two values. If you specify a name block parameter for a YouTube username, this will be set to that same username. If you specify a playlist_id block parameter, this will be set to the channel title returned by the YouTube API for the channel that the playlist belongs to.
  • {CHANNEL_URL} = As with the {CHANNEL_NAME}, this will be one of two values. It will either refer to the YouTube user page for the username specified or the YouTube channel page for the playlist ID specified.
  • {STYLE} = This is set with the style block parameter. The default provided template takes 1, 2, 3, or 4 as values to choose a layout style for videos. 1 = Full video data above the player/thumbnail, player/thumbnail below data. 2 = Player/thumbnail to the left, full data to the right. 3 = Player/thumbnail to the left, minimal data to the right (suitable for front page summaries). 4 = Player/thumbnail above data, full data below player/thumbnail. You can use logic template code in your custom templates and use this variable to select your own layouts. For custom templates, you don't have to use numbers, you can use also use text for the style block parameter.
  • {EMBED_ALLOWED} = This will allow you to honor the 'embed allowed' setting for each video. If set to 1, it means you want to honor the embed setting and embed the player only if it is allowed. If set to 0, it means you want the player to be embedded even if it isn't allowed. It won't allow non-embeddable video to play; the player will just play static and display a link to view the video on YouTube. This is mainly used for achieving a consistent look. If you want all videos to show as an embedded player or if you don't mind a mix of embedded players and thumbnail images.
  • {EMBEDPLAYER_ALLOWED} = If the video is allowed to be embedded outside of YouTube, this will be set to 1. If the video is not allowed to be embedded outside of YouTube, this will be set to 0.
  • {VIDEO_ID} = This is the video ID. For example, if the YouTube video URL is https://www.youtube.com/watch?v=aJNFrE4VzxU, then the video ID is aJNFrE4VzxU.
  • {MAX_VIDEOS} = This is the maximum number of videos specified with the max_videos block parameter.
  • {COUNT} = This represents the count of the current video and can be used to add numbers for video # in the template if desired. This can be used if you want a '1' in front of the first video, '2' in front of the second video, etc. It can also be used to generate alternating colored rows in the output (i.e. odd numbers are one color, even numbers are another color).
  • {VIDEO_URL} = This is the URL to the YouTube watch page for the video.
  • {CHANNEL_TITLE} = This if from the channel_title block parameter and is currently not used in the default BLOCK_YOUTUBE_CHANNEL.tpl template. You could use it to give your block a header title that is different from the YouTube username or channel name.
  • {VIDEO_TITLE} = The video title returned by the YouTube API.
  • {RATING_STARS} = This is a whole number rating of 1 to 5 for a video.
  • {RATING_LIKE_PERCENT} = This is a whole number of 0 to 100 for percentage of likes for a video. Percentage of likes = round((likes/(likes+dislikes))*100).
  • {RATING_NUM_RATES} = This is the total number of likes and dislikes for a video.
  • {RATING_LIKES} = This is the number of likes for a video.
  • {RATING_DISLIKES} = This is the number of dislikes for a video.
  • {RATING_NUMERIC} = This is a non-whole number version of {RATING_STARS} rounded to the nearest 100th (2nd decimal place). This is used in the default BLOCK_YOUTUBE_CHANNEL_STYLE.tpl template to display star ratings that include half stars.
  • {FAVORITE_COUNT} = This is the number of times a video is favorited.
  • {UPLOAD_DATE} = This is the upload date of the video. The default BLOCK_YOUTUBE_CHANNEL_STYLE.tpl template translates this to the correct time zone, assuming your ocPortal and web server timezone settings are correct.
  • {DESCRIPTION_TYPE} = This will either be long or short. This is used in the default BLOCK_YOUTUBE_CHANNEL_STYLE.tpl template with tempcode logic to display either a long full video description or a short description limited to a maximum of 250 characters.
  • {DESCRIPTION} = This is the long description and is the full and complete description for the video.
  • {DESCRIPTION_SHORT} = This is a short description and is no more than 250 characters.
  • {DESCRIPTION_SHORTENED} = This can be used along with {DESCRIPTION_SHORT} so you can add an ellipsis (...) to the short descriptions that have actually been shortened.
  • {PLAYERALIGN} = This is set by the player_align block parameter and contains center, left, or right. This can be used by the template to set the alignment of the player.
  • {PLAYERHEIGHT} = This is set by the player_height block parameter and is used to set the height (in pixels) of the video player.
  • {PLAYERWIDTH} = This is set by the player_width block parameter and is used to set the width (in pixels) of the video player.
  • {EMBEDVIDEO} = This contains the URL of the embedded video player for the video.
  • {VIDEO_PLAYER} = This is the actual embedded video player HTML iframe code.
  • {SHOWPLAYER} = This will be set to 1 if an embedded player should be shown and will be set to 0 if an embedded player shouldn't be shown. Determined by the show_player block parameter. 
  • {NOTHUMBPLAYER} = Poorly named, but this will be set to 1 if a thumbnail should always be displayed along with the embedded player. This is set with the nothumbplayer block parameter.
  • {FOR_MORE_LEAD} = This will contain the content of the formorelead block parameter and can be used if you want a 'For more videos, click here.' line anywhere in the block. Using 'For more videos, click here.' as an example, you would pass 'For more videos, ' as the formorelead block parameter. This isn't used in the default templates, but you can use these FOR_MORE_* tempcode variables to make custom links on a per-video or per-block basis instead of hardcoding it the template.
  • {FOR_MORE_TEXT}This will contain the content of the formoretext block parameter and can be used if you want a 'For more videos, click here.' line anywhere in the block. This will be the clickable text you would use in the template HTML code. Using 'For more videos, click here.' as an example, you would pass 'click here.' as the formoretext block parameter. This isn't used in the default templates, but you can use these FOR_MORE_* tempcode variables to make custom links an a per-block basis instead of hardcoding it the template.
  • {FOR_MORE_URL}This will contain the content of the formoreurl block parameter and can be used if you want a 'For more videos, click here.' line anywhere in the block. This will be the URL that you can apply to the clickable text you would use in the template HTML code. Using 'For more videos, click here.' as an example, you would pass 'http://www.youtube.com/your_link_here' as the formoreurl block parameter. This isn't used in the default templates, but you can use these FOR_MORE_* tempcode variables to make custom links an a per-block basis instead of hardcoding it the template.
  • {THUMBNAIL} =
  • {THUMBWIDTH} =
  • {THUMBHEIGHT} =
  • {THUMBALT} =

The main template is simply just a container to hold the style template. I was going to put a comcode box defined with the title block parameter as the box title, but I opted to keep it out so you can create your own box to match the style of your site. Or you can create your own custom template and use {CHANNEL_TITLE} for the box title.

Here is a list of {VARIABLES} available in the main BLOCK_YOUTUBE_CHANNEL.tpl:
  • {CHANNEL_ERROR} = This is set with a text error message or list of error messages. Earlier error messages may result in additional error messages, so address the errors one at a time starting from the first one on the list.
  • {CHANNEL_TITLE} = Unused in the default template. You can set this with the title block parameter and display it in your custom BLOCK_YOUTUBE_CHANNEL.tpl template.
  • {CONTENT} = This is all of the videos. All of the videos are styled with the Style template and then combined into this single variable.
  •  
  • {CHANNEL_NAME} = This will one of two values. If you specify a name block parameter for a YouTube username, this will be set to that same username. If you specify a playlist_id block parameter, this will be set to the channel title returned by the YouTube API for the channel that the playlist belongs to.
  • {CHANNEL_URL} = As with the {CHANNEL_NAME}, this will be one of two values. It will either refer to the YouTube user page for the username specified or the YouTube channel page for the playlist ID specified.

Here is a list of block parameters:
  • name = The YouTube user name of the channel you want to embed. If your YouTube channel URL is http://www.youtube.com/user/holleywoodstudio?feature=watch, then the name would be holleywoodstudio. This name parameter overrides the Playlist ID parameter. Leave this blank if you want to specify the Playlist ID directly. Default: ''.
  • api_key = A YouTube API Key is required either here as a block parameter or as a block configuration option at Adminzone>Setup>Configuration>Block options. If specified as a block configuration option, it is not required as a block parameter. If specified as a block parameter, it will override the block configuration option. Default: ''.
  • playlist_id = Playlist ID of playlist you want to embed. You can use this parameter instead of the 'name' parameter to embed a playlist. The 'name' parameter overrides this parameter, so be sure to blank out the 'name' parameter is you are specifying a playlist ID here. Default: ''.
  • title = The title you want to give to your YouTube channel. (currently not used in the default templates) Default: ''.
  • template_main = If you create your own main template, you can enter the suffix name of your custom main template file. This is the main template where the style template will be added to. Example: if your custom template is named BLOCK_YOUTUBE_CHANNEL_MyCustomTemplate.tpl, you would enter MyCustomTemplate here. When creating the template, be sure to use the original template file name and append an underscore and your custom name to it. I'm sure it's case sensitive as well. Default: ''.
  • template_style = If you create your own style template, you can enter the suffix name of your custom style template file. This is the style template where the actual YouTube provided data will be layed out. Check the 'YouTube Channel Integration Block discussion' topic on the ocPortal.com Forum for documentation of available template variables. Example: if your custom template is named BLOCK_YOUTUBE_CHANNEL_STYLE_MyCustomStyle.tpl, you would enter MyCustomStyle here. When creating the template, be sure to use the original template file name and append an underscore and your custom name to it. I'm sure it's case sensitive as well. Default: ''.
  • description_type = Set this to long or short to choose between long video description or short video description. Default: 'long'.
  • start_video = For multi-page use, you can specify which video to start at when fetching videos from YouTube. If start_video is set to 1 and max_videos is set to 25 for page one, set start_video to 26 for page two to continue where page one left off. Can be set up to 50. Default: '1'.
  • max_videos = You can specify the maximum number of videos to show. Minimum value is 1, maximum value is 50 (max allowed by YouTube API). Default: '25'.
  • orderby = ***THIS PARAMETER NO LONGER WORKS! IT WAS ONLY LEFT IN FOR BACKWARD COMPATIBILITY.*** Default: '1'.
  • show_player = Set this to 0 to not show the embedded player at all. Any other number will show the embedded player for that many videos in your list. For example, set to 1 will only show embedded video for first video in list, set to 5 will only show embedded video for first 5 videos in list, set to same value as max_videos parameter to show the embedded player for all videos. Default: '1'.
  • embed_allowed = Set this to 1 to honor embed player permission from channel feed and display a thumbnail instead of the embedded video player if embedding isn't allowed for video. Set this to 0 to ignore embed permission and display the embedded video player anyway. Setting this to 0 won't allow embedded videos to play if they don't allow embedding. Instead, when pressing the play button in the video player, the player will display static and a link to view the video on the YouTube site. Default: '1'.
  • player_align = Set this to center, left, or right to align the embedded player accordingly. Default: 'center'.
  • player_width = Set this to the width, in pixels, you want the embedded player to be. Default: '480'.
  • player_height = Set this to the height, in pixels, you want the embedded player to be. Default: '270'.
  • style = Set this to the style of output you want. If no style template is manually defined, style can be chosen by one of three styles: 1 = Full data above, player below. 2 = Player left, full data right. 3 = Player left, minimal data right (suitable for front page summaries). 4 = Player above, full data below. If you create a simple template, this can be ignored. If you create an advanced template, you can set this to a number or name that is referenced in your custom template file. See the 'YouTube Channel Integration Block discussion' topic on the ocPortal.com Forum for more documentation. Default: '1'.
  • nothumbplayer = Disable thumbnails when using player. 0 = Don't show thumbnail when using embedded player. 1 = Always show thumbnails. Default: '0'.
  • thumbnail = Choose which thumbnail image to use. These are available through the YouTube API: 0 = default image, low res. 1 = default image, medium res. 2 = default image, higher res. 3 = first frame of vid, low res. 4 = middle frame, low res. 5 = last frame, low res. 6 = default standard definition image. 7 = default max resolution image. 0, 1, and 2, are the best thumbnails to use. 3 through 7 may not exist for all videos. Default: '0'.
  • formorelead = Set this to some text leading up to the formoretext/foremoreurl properties. Example: 'For more videos'. Default: ''.
  • formoretext = Set this to some text to attach the formoreurl property to. Example: 'click here...'. Default:''.
  • formoreurl = Set this to a URL users can click for more videos. This URL will be attached to formoretext property defined text. For example, enter your YouTube channel URL, including the http:// at the beginning. Default: ''.


Last edit: by Jason Verhagen
Back to the top
 
Posted
Rating:
#107767
Avatar

Community saint

This post will contain additional example templates.
Back to the top
 
Posted
Rating:
#107800
Avatar

Community saint

The YouTube Channel Integration block addon should be all set to go. I will be finishing off and prettying up the documentation in the first message post of this thread over the next couple of days, but everything needed to get started is ready and available.

If you have problems, post them here. If you had a previous version of the addon installed and have problems after upgrading, try uninstalling the addon and reinstalling it. If problems persist, post them here.
Back to the top
 
1 guests and 0 members have just viewed this: None
Control functions:
 Add topic 

Quick reply   Contract

Your name:
Your message: