Shortcode

Intro

Ultimate Fields allows you to create custom shortcodes. Shortcodes are small macros, which you can add to a post's content, which are replaced by actual markup when the content is being displayed.

When you associate a container with the Shortcode location, the plugin will automatically create a new shortcode based on the container's title, description and fields. Ultimate Fields will then provide the interface to create and edit the shortcode, but you will have to manually define the function, which displays it in the front-end.

Here is how a simple "Quote" shortcode looks like from a user's perspective:

Play Preview Video

As you can see, the plugin adds zero to no additional UI. The shortcode is simply available to add from the media modal. Once added, there is a custom popup for editing the shortcode.

Usage through the interface

To add fields to users with the the Administration Interface, please follow these steps:

1. If you are not on the "Add Container" screen already, locate the "Ultimate Fields" section in the administration area and click the "Add New" button on the top (next to the "Containers" title).
2. Locate the "Locations" box.
3. Click "Shortcode" from the bottom row.
4. Enter a tag for the shortcode and setup the preview.

Usage through PHP

The user location in Ultimate Fields is handled by the Ultimate_Fields\Location\Shortcode class. In order to use it, you can either create the new location object manually or let the container do it for you.

The constructor of the class looks like this:

public function __construct( $args = array() ) {

$args is an array, which allows you to set arguments without having to explicitly call the particular setter.

Manual creation

Create a new location by using the new keyword and assign it to the container through the add_location() method.

use Ultimate_Fields\Container;
use Ultimate_Fields\Location\Shortcode;

$container = Container::create( 'quote' );

// Create a new location and add definitions to it
$location = new Shortcode();

// Once the location has been fully set up, add it to the container
$container->add_location( $location );

Do not forget to use the correct namespace for the location class!

Automatic creation

You can also let the container create the location for you by providing the "shortcode" string as the first parameter to add_location().

use Ultimate_Fields\Container;

Container::create( 'quote' )
	->add_location( 'shortcode' );

This method allows you to use method chaining and shortens the syntax, in order to make the code more readable.

Data retrival

To retrieve the values of fields, associated with the Shortcode location, $type parameter of all *_value functions should be "shortcode". This will automatically link the functions with the currently displayed shortcode.

Examples:

$text   = get_value( 'text', 'shortcode' );
$author = get_value( 'author', 'shortcode' );

Options

Tag

Shortcodes, like HTML elements, must have a special tag in order to be parsed.

If you have a shortcode that looks like this, its tag is quote:

[quote author="John Doe" text="Hello!"]

When you are using the administration interface, you must manually enter a tag for the shortcode.

If you are using the PHP API to create your fields, you have two options:

1. Add a location without a tag. In this case the ID of the container will be used for the tag.
2. Enter a tag manually by using the second parameter of the location or the set_tag method.

All three examples are equivalent:

use Ultimate_Fields\Container;
use Ultimate_Fields\Location\Shortcode;

// Use the container ID
Container::create( 'quote' )->add_location( 'shortcode' );

// Use a parameter
Container::create( 'my-quote-container' )
  ->add_location( 'shortcode', array(
	'tag' => 'quote'
  ));

// Create the location separately
$location = new Shortcode();
$location->set_tag( 'quote' );

Container::create( 'my-quite-container' )
	->add_location( $location );

Template

By default Ultimate Fields is not aware how your shortcode should look, which is why the preview in the editor would look like this:

If you want to, you can provide a custom template for the shortcode by using the template argument or the set_template method of the location. The template must use the default Underscore.js templating language and will have all fields available as local variables.

The template for the Quote shortcode looks like this:

<blockquote>
	<div><%= text %></div>
	<p><%= author %></p>
</blockquote>

As you can see, we are using the <%= var_name %> structure to output a variable.

Here is how you set the template in PHP:

use Ultimate_Fields\Container;
use Ultimate_Fields\Location\Shortcode;

$template = '<blockquote>
	<div><%= text %></div>
	<p><%= author %></p>
</blockquote>';

// Add automatically
Container::create( 'quote' )
	->add_location( 'shortcode', array(
		'template' => $template
	));

// Add manually
$container = Container::create( 'quote' );
$location = new Quote();
$location->set_template( $template );
$container->add_location( $location );