Useful hooks in YouTube video import WP plugin

From time to time, depending on how things are set up, you might want to import videos using our YouTube video import WP plugin in a different way that may better suit your needs.

To achieve this, the plugin implements a series of hooks and filters that can be used to modify things on the fly.

Please note that a minimal knowledge of writing PHP code will be needed before using the examples described here.

The actions and filters described below and the functionality you want to implement when using them should be placed in your WordPress theme/child theme functions.php file.
We suggest that you use a child theme since if you place them in your theme functions.php file, when you update the theme you will lose your modifications.
More about WordPress child themes can be found here: https://codex.wordpress.org/Child_Themes.

Filters that modify post details when importing YouTube videos

Below you will find several filters that deal with different post content (post title, post description, post excerpt and so on) inserted into the database when importing videos from YouTube as WordPress posts.

cbc_video_post_title

The cbc_video_post_title is used to filter the post title right before inserting the post into the database after a video is successfully processed and ready to be imported. Can be used to modify post title on the fly for any imported video.

/**
 * Filter callback to modify post title when importing videos
 *
 * @param string $post_title - the post title
 * @param array $video - array of video details
 * @param boolean/array $theme - whether is a theme compatible import (array) or not (false)
 * @return string - the modified title
 */
function my_title_filter( $post_title, $video, $theme ){
    // do modifications to title here

    // return the title
    return $post_title;
}
add_filter( 'cbc_video_post_title', 'my_title_filter', 10, 3 );

cbc_video_post_content

The cbc_video_post_content is used to filter the post content right before inserting it into the database after the video is processed. Can be used to modify the content and format the text retrieved from YouTube.

/**
 * Filter callback to modify post content when importing videos
 *
 * @param string $post_content - the post content
 * @param array $video - array of video details
 * @param boolean/array $theme - whether is a theme compatible import (array) or not (false)
 * @return string - the modified post content
 */
function my_content_filter( $post_content, $video, $theme ){
    // do modifications to post content here

    // return the content
    return $post_content;
}
add_filter( 'cbc_video_post_content', 'my_content_filter', 10, 3 );

cbc_video_post_excerpt

The cbc_video_post_excerpt is used to filter the post excerpt before inserting the video post into the database.

/**
 * Filter callback to modify post excerpt when importing videos
 *
 * @param string $post_excerpt - the post excerpt
 * @param array $video - array of video details
 * @param boolean/array $theme - whether is a theme compatible import (array) or not (false)
 * @return string - the modified post excerpt
 */
function my_excerpt_filter( $post_excerpt, $video, $theme ){
    // do modifications to post excerpt here

    // return the excerpt
    return $post_excerpt;
}
add_filter( 'cbc_video_post_excerpt', 'my_excerpt_filter', 10, 3 );

cbc_video_post_status

Filter cbc_video_post_status allows you to change the post status to whatever you need. Unless you truly know what you’re doing, don’t use this filter. Using this filter will override any plugin settings for imports post status.

/**
 * Filter callback to modify post status when importing videos
 *
 * @param string $post_status - the post status
 * @param array $video - array of video details
 * @param boolean/array $theme - whether is a theme compatible import (array) or not (false)
 * @return string - the modified post status
 */
function my_post_status_filter( $post_status, $video, $theme ){
    // do modifications to post status here

    // return the status
    return $post_status;
}
add_filter( 'cbc_video_post_status', 'my_post_status_filter', 10, 3 );

cbc_video_post_date

Filter cbc_video_post_date allows you to modify the post date when importing videos. Please note that in order for this filter to work, you must have option to import video date enabled in plugin Settings page. Date returned by the callback function for this filter must be in MySQL format ( YYYY-MM-DD HH:MM:SS )

/**
 * Filter callback to modify post date when importing videos
 *
 * @param string $post_date - the post date in MySQL format
 * @param array $video - array of video details
 * @param boolean/array $theme - whether is a theme compatible import (array) or not (false)
 * @return string - the modified post date
 */
function my_post_date_filter( $post_date, $video, $theme ){
    // do modifications to post date here

    // return the date
    return $post_date;
}
add_filter( 'cbc_video_post_date', 'my_post_date_filter', 10, 3 );

Actions for adding extra details when importing YouTube videos

The following actions can be used to add any other extra information to newly created video posts.

cbc_post_insert

Action cbc_post_insert is fired right after a new video post is created. This action allows you to, for example, set up any extra custom fields that you might need, like video likes/dislikes but in reality you can do almost anything, like asigning tags, new categories, set up things needed by third party plugins and so on.

/**
 * Post insert action callback
 *
 * @param int $post_id - the newly created post ID
 * @param array $video - array of video details
 * @param boolean/array $theme - whether is a theme compatible import (array) or not (false)
 * @param string $post_type - the post type of the newly created post
 */
function my_post_insert_action( $post_id, $video, $theme_import, $post_type ){

    // let's assume that we want to store video likes in custom meta likes
    update_post_meta( $post_id, 'likes', $video['stats']['likes'] );

    /*
	Additional stats are stored like this:

	1. Views: $video['stats']['views']
	2. Likes: $video['stats']['likes']
	3. Dislikes: $video['stats']['dislikes']
	4. Favourite: $video['stats']['favourite']
	5. Comment count: $video['stats']['comments']
	*/

}
add_action( 'cbc_post_insert', 'my_post_insert_action', 10, 4 );

Plugin admin area filters

Following filters are used in plugin admin area pages.

cbc_allow_single_video_import

Filter cbc_allow_single_video_import uses a simple, boolean value to determine if single video import functionality is allowed. By default, for post type video the plugin will override the default new post functionality with its own, ID query video on YouTube. In some cases, themes might be using the post type video to display its videos and in this case you might need the theme functioanlity instead of the plugin’s.

/**
 * Callback function that can prevent single video
 * import functionality implemented by the plugin
 * @return boolean - prevent plugin functionality (false) or allow it (true)
 */
function my_single_import_function(){
	// return false to prevent the plugin's functionality for single video import
	return true;
}
add_filter( 'cbc_allow_single_video_import', 'my_single_import_function', 10 );

Font-end and embedding filters

Following filters are used when performing front-end tasks and on video embedding for post type video.

cbc_check_video_status

Filter cbc_check_video_status allows you to skip the post status checkup on YouTube even if the setting is allowed from plugin settings.

/**
 * Callback function that can prevent checking video status on YouTube
 *
 * @return boolean - prevent checking on YouTube (false) or allow it (true)
 */
function my_video_status_function( $allow, $post, $video_id ){
	// here, maybe do some checking based on $post

	// return false to prevent the plugin from checking the video status on YouTube
	return true;
}
add_filter( 'cbc_check_video_status', 'my_video_status_function', 10, 3 );

ccb_embed_videos

When this filter is set to return false, all video embeds managed by the plugin for post type video will be skipped. This particular filter is useful if your theme uses the same post type video as the plugin does but you want your theme to manage all embedding.

/**
 * Callback function that can prevent embedding YouTube videos on video post type pages
 *
 * @param boolean $allow - allow or deny embedding
 * @param object $post - post object
 * @param array $video - video details array
 * @return boolean - prevent checking on YouTube (false) or allow it (true)
 */
function my_video_embeds_function( $allow, $post, $video ){
	// here, maybe do some checking based on $post or $video

	// return false to prevent the plugin from embedding YouTube videos
	return true;
}
add_filter( 'ccb_embed_videos', 'my_video_embeds_function', 10, 3 );

ccb_video_post_css_class

For post type video embeds, if you need to add extra CSS classes that will allow you to customize the embed conatiner div, use this filter.

/**
 * Callback function to add new CSS class to embed container div
 *
 * @param array $classes - extra classes array
 * @param object $post - post object
 * @return array - array of CSS classes
 */
function my_embed_css_class( $classes, $post ){
	// here, maybe do some checking based on $post

	// add a new class
	$classes[] = 'my-new-css-class';
	return $classes;
}
add_filter( 'ccb_video_post_css_class', 'my_embed_css_class', 10, 2 );

cbc_before_video_embed

For post type video, this filter allows you to display HTML markup before the video embed container.

/**
 * Callback function to add extra HTML before the video embed
 *
 * @param string $html - html displayed before the embed
 * @param object $post - post object
 * @param array $video - video details array
 * @return string - the string to display before the video embed
 */
function my_before_embed( $html, $post, $video ){
	// add an h2 title before the video embed
	$html .= '<h2>' . apply_filters( 'the_title', $post->post_title ) . '</h2>';
	return $html;
}
add_filter( 'cbc_before_video_embed', 'my_before_embed', 10, 3 );

cbc_after_video_embed

For post type video, this filter allows you to display HTML markup after the video embed container.

/**
 * Callback function to add extra HTML after the video embed
 *
 * @param string $html - html displayed after the embed
 * @param object $post - post object
 * @param array $video - video details array
 * @return string - the string to display after the video embed
 */
function my_after_embed( $html, $post, $video ){
	// add stats after the video embed
	$html .= '<span>' . __( 'Likes: ' ) . $video['stats']['likes'] . '</span>';
	return $html;
}
add_filter( 'cbc_after_video_embed', 'my_after_embed', 10, 3 );

Leave a Reply

Your email address will not be published. Required fields are marked *