Custom Banners Shortcode

Below, you’ll find a detailed guide on how to add the Custom Banners Shortcode to your WordPress website, including its parameters, examples, and PHP function code. Additionally, we’ll assist you with common issues that might cause the Custom Banners Plugin shortcode not to show or not to work correctly.

Before starting, here is an overview of the Custom Banners Plugin and the shortcodes it provides:

Plugin Icon
Custom Banners

"Custom Banners is a WordPress plugin designed to help you easily create and manage dynamic banners. With this plugin, you can effortlessly customize the style and layout of your banners."

★★★☆✩ (8) Active Installs: 5000+ Tested with: 5.7.10 PHP Version: 5.3
Included Shortcodes:
  • [custom_banners]

Custom Banners [custom_banners] Shortcode

The Custom Banners shortcode allows users to display a banner or a series of banners on their WordPress site. It offers a variety of customization options, including banner dimensions, transition effects, and caption settings.

Shortcode: [custom_banners]

Parameters

Here is a list of all possible custom_banners shortcode parameters and attributes:

  • id – Specifies the unique ID of the banner.
  • group – Used to group banners together.
  • caption_position – Sets the position of the caption.
  • transition – Defines the type of banner transition.
  • pager – Enables or disables the pager.
  • count – Sets the number of banners to display.
  • timer – Sets the duration of banner display.
  • use_image_tag – Decides whether to use image tags.
  • show_pager_icons – Controls the display of pager icons.
  • use_pager_thumbnails – Decides if pager thumbnails are used.
  • hide – Hides the banner if set to true.
  • width – Sets the width of the banner.
  • height – Sets the height of the banner.
  • pause_on_hover – Pauses banner transition on hover.
  • auto_height – Adjusts banner height automatically.
  • prev_next – Enables or disables previous and next buttons.
  • paused – Pauses the banner transition.
  • banner_height – Sets a specific height for the banner widget.
  • banner_width – Sets a specific width for the banner widget.
  • link_entire_banner – Links the entire banner if set to true.
  • open_link_in_new_window – Opens banner link in a new window.
  • show_caption – Controls the display of the banner caption.
  • show_cta_button – Controls the display of the CTA button.
  • theme – Sets the theme of the banner.

Examples and Usage

Basic example – Display a banner using its ID

[banner id=1 /]

Advanced examples

Display a banner with a specific theme and with the caption turned off.

[banner id=1 theme="custom" show_caption=0 /]

Show a banner from a specific group, with a transition effect, and a custom width and height.

[banner group="group1" transition="fade" width=300 height=200 /]

Display a banner with a Call To Action (CTA) button turned off, and the link opening in a new window.

[banner id=1 show_cta_button=0 open_link_in_new_window=1 /]

Display a banner with a custom width and height in pixels, and link the entire banner.

[banner id=1 banner_width_px=500 banner_height_px=300 link_entire_banner=1 /]

Display a banner with a specific caption position and a custom timer.

[banner id=1 caption_position="top" timer=5000 /]

PHP Function Code

In case you have difficulties debugging what causing issues with [custom_banners] shortcode, check below the related PHP functions code.

Shortcode line:

add_shortcode($banner_shortcode, array($this, 'banner_shortcode'));

Shortcode PHP function:

function banner_shortcode($atts, $content = '')
	{
		// load the shortcodes attributes and merge with our defaults
		
		// show_caption is defaulted to 1 (on), UNLESS the never_show_captions flag is set
		$show_caption_default = get_option('custom_banners_never_show_captions', 0)
								? 0 // never_show_captions is on, so turn captions off
								: 1; // never_show_captions is off, so default to captions on
			
		// show_cta is defaulted to 1 (on), UNLESS the never_show_cta_buttons flag is set
		$show_cta_default = get_option('custom_banners_never_show_cta_buttons', 0)
								? 0 // never_show_cta_buttons is on, so turn CTAs off
								: 1; // never_show_cta_buttons is off, so default to CTAs on
			
		$defaults = array(	'id' => '',
							'group' => '',
							'caption_position' => 'bottom',
							'transition' => 'none',
							'pager' => false,
							'count' => -1,
							'timer' => 4000,
							'use_image_tag' => true,
							'show_pager_icons' => false,
							'use_pager_thumbnails' => false,
							'hide' => false,
							'width' => get_option('custom_banners_default_width', ''), // 'auto', '100_percent', or integer (width in px)
							'height' => get_option('custom_banners_default_height', ''), // 'auto', or integer (height in px)
							'pause_on_hover' => false,
							'auto_height' => false,
							'prev_next' => false,
							'paused' => false,
							'banner_height' => '', // (only for widget) used to override height with a px value
							'banner_height_px' =>get_option('custom_banners_default_height', ''),
							'banner_width' => '', // (only for widget) used to override width with a px value
							'banner_width_px' =>  get_option('custom_banners_default_width', ''),
							'link_entire_banner' => get_option('custom_banners_use_big_link', 0),
							'open_link_in_new_window' => get_option('custom_banners_open_link_in_new_window', 0),
							'show_caption' => $show_caption_default,
							'show_cta_button' => $show_cta_default,
							'theme' => get_option('custom_banners_theme')
						);

		$atts = shortcode_atts($defaults, $atts);
		
/* 		echo "<pre>";
		var_dump($atts);
		echo "</pre>";
 */		
		$banner_id = intval($atts['id']);
		
		// if theme is not available, fallback to default style
		$atts['theme'] = $this->filter_theme_name($atts['theme'], $banner_id);

		// card theme requires image tags
		if ( strpos($atts['theme'], 'card-') !== false ) {
			$atts['use_image_tag'] = true;
		}
				
		// Generate the HTML for the requested banners (could be a single banner, or many)
		if( $banner_id > 0 ) {
			// A single banner ID was specified, so just load it directly
			$banner = $this->get_banner_by_id($banner_id);
			if ($banner !== false) {
				$html = $this->buildBannerHTML($banner, $banner_id, $atts);
			}
		}
		else {
			// choose a banner based on the other attributes 	
			$banners = $this->get_banners_by_atts($atts);
			$atts['slideshow'] = $this->atts_contain_valid_slideshow_transition($atts);
			$is_slideshow = $atts['slideshow'];
			
			//generate a random number to have a unique wrapping class on each slideshow
			//this should prevent controls that effect more than one slideshow on a page
			$target = rand();

			$banners_html = '';
			// build the HTML for each banner, concatenating its output to $html
			foreach($banners as $index => $banner) {
				// If we are outputting a slideshow, hide all but the first banner
				$atts['hide'] = ( $is_slideshow && ($index > 0) );
				
				// Add this banner's HTML to the output
				$banners_html .= $this->buildBannerHTML($banner, $banner_id, $atts);
			}

			/*
			 * If its a slideshow, wrap the banners in the slideshow HTML now
			*/
			
			if( $is_slideshow ) {
				
				if ($atts['banner_width'] == 'specify') { //if the width was specified via the widget, use it here, otherwise go with global option
					$atts['width'] = intval($atts['banner_width_px']);
				}
				
				// start the slideshow's HTML (if required). This returns a <div> with attributes 
				// reflecting the shortcode settings, and instructions for cycle2			
				$wrapper_html = $this->get_opening_tag_for_slideshow($target, $atts);

				// insert list of banners into t he middle of the slideshow
				$wrapper_html .= $banners_html;
								
				// add a pager and close the slideshow's HTML (if requested)
				$wrapper_html .= $this->get_slideshow_controls_html( $atts, $target );
				
				$wrapper_html .= '</div><!-- end slideshow -->';
				$html = $wrapper_html;
			} else {
				$html = $banners_html;
			}
		}
		
		// return the generated HTML
		return $html;
	}

Code file location:

custom-banners/custom-banners/custom-banners.php

Conclusion

Now that you’ve learned how to embed the Custom Banners Plugin shortcode, understood the parameters, and seen code examples, it’s easy to use and debug any issue that might cause it to ‘not work’. If you still have difficulties with it, don’t hesitate to leave a comment below.

Comments

Leave a Reply

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