Shortcodes Ultimate API overview

Since version 4.0.0 you can add your custom shortcodes to plugin or modify existing.

To add new shortcode you need to create custom filter function that is modify shortcodes data. This is simple filter that accepts as argument array with original shortcodes data and returns it modified. Filter name is su/data/shortcodes.

Registering new shortcode

add_filter( 'su/data/shortcodes', 'register_my_custom_shortcode' );

/**
 * Filter to modify original shortcodes data and add custom shortcodes
 *
 * @param array   $shortcodes Original plugin shortcodes
 * @return array Modified array
 */
function register_my_custom_shortcode( $shortcodes ) {
	// Add new shortcode
	$shortcodes['heading2'] = array(
		// Shortcode name
		'name' => __( 'Heading 2', 'textdomain' ),
		// Shortcode type. Can be 'wrap' or 'single'
		// Example: [b]this is wrapped[/b], [this_is_single]
		'type' => 'wrap',
		// Shortcode group.
		// Can be 'content', 'box', 'media' or 'other'.
		// Groups can be mixed, for example 'content box'
		'group' => 'content',
		// List of shortcode params (attributes)
		'atts' => array(
			// Style attribute
			'style' => array(
				// Attribute type.
				// Can be 'select', 'color', 'bool' or 'text'
				'type' => 'select',
				// Available values
				'values' => array(
					'default' => __( 'Default', 'textdomain' ),
					'small' => __( 'Small', 'textdomain' )
				),
				// Default value
				'default' => 'default',
				// Attribute name
				'name' => __( 'Style', 'textdomain' ),
				// Attribute description
				'desc' => __( 'Heading 2 style', 'textdomain' )
			)
		),
		// Default content for generator (for wrap-type shortcodes)
		'content' => __( 'Heading 2 text', 'textdomain' ),
		// Shortcode description for cheatsheet and generator
		'desc' => __( 'Styled heading 2', 'textdomain' ),
		// Custom icon (font-awesome)
		'icon' => 'plus',
		// Name of custom shortcode function
		'function' => 'su_heading2_shortcode'
	);
	// Return modified data
	return $shortcodes;
}

Creating function for custom shortcode

This function should be named equal to value specified in previous filter. See the function parameter above.

/**
 * Heading2 shortcode function
 *
 * @param array   $atts    Shortcode attributes
 * @param string  $content Shortcode content
 * @return string Shortcode markup
 */
function su_heading2_shortcode( $atts, $content = null ) {
	$atts = shortcode_atts( array(
			'style' => 'default',
			'foo' => 'bar'
		), $atts );
	// Open div
	$return = '<div class="su-heading-2 su-heading-2-style-' . $atts['style'] . '">';
	// Append content
	$return .= $content;
	// Close div
	$return .= '</div>';
	// Return result
	return $return;
}

Modifying original shortcodes data

For example, you can create additional button styles and bundle it with your theme. Next snippet will show you how to remove all button style presets, add your custom style and remove "Link target" attribute.

add_filter( 'su/data/shortcodes', 'add_custom_button_style' );

/**
 * Filter to modify original shortcodes data
 *
 * @param array   $shortcodes Basic plugin shortcodes
 * @return array Modified array
 */
function add_custom_button_style( $shortcodes ) {
	// You can remove all presets before adding custom style
	$shortcodes['button']['atts']['style']['values'] = array();
	// Add new button style
	$shortcodes['button']['atts']['style']['values']['custom-style'] = 'Custom style';
	// You can even remove unwanted attributes like links target
	unset( $shortcodes['button']['atts']['target'] );
	// Return modified data
	return $shortcodes;
}

Theme integration

Theme integration is deadly simple process. You just need to check plugin installation and show admin notice if plugin not installed. After plugin is installed, you can modify all shortcodes as you want from your theme.

add_action( 'admin_notices', 'my_admin_notice' );

/**
 * Function to show admin notice if Shortcodes Ultimate is not installed
 */
function my_admin_notice() {
	// Check that plugin is installed
	if ( function_exists( 'shortcodes_ultimate' ) ) return;
	// If plugin isn't installed, show notice
	echo '<div class="error">For full functionality of this theme you need to install and activate plugin <strong>Shortcodes Ultimate</strong>. <a href="' . admin_url( 'plugin-install.php?tab=search&s=shortcodes+ultimate' ) . '">Install now</a></div>';
}
You can find much more useful filters and actions in the source code on GitHub