Shortcode Module

Shortcode is a module designed to give you the ability to inject dynamic content inside of any custom field you have defined.

At it's most basic usage, Shortcode allows the creation and re-use of macros of content that can be defined by an individual author or globally for the entire site.

Additionally, the shortcodes feature will enable you to insert forms from ProForm, embed tweets from Twitter, and a number of other things that would be far more complex or impossible to implement inside editor-managed content without the Shortcode module.

Features

ShortCode has the following features:

Compatible Add-ons

The following add-ons are known to provide shortcodes that can be used with Shortcode. More are added all the time! If you'd like to implement support for Shortcode for an add-on, simply read the Creating Shortcodes section below. Any add-on can provide shortcodes that are actually implemented by other add-ons, so you don't even need to be the add-on author to create and release a shortcode for it!

ShortCode Documentation

Functionality

Managing Macros

Macros are managed through the main Shortcode interface, accessible from the EE menu at Add-ons > Modules > Shortcode.

There are two "scopes" for any macros you might create:


Only users with Super Admin access can create Site macros.

Creating a Macro

To create a Macro:

  1. Visit the Shortcode page at Add-ons > Modules > Shortcode
  2. Click either My Macros or Site Macros (optional, the default view is of the My Macros list)
  3. Click the Create Macro button

You will be asked to provide the following values for the new macro:

SettingDescription
TypeSelect Text for a single line of text, appropriate for short values. Select Textarea for longer pieces of text.
NameThe name of the macro. This should be a short but descriptive name that will be easy to remember. This name, combined with the scope of the macro, is used to insert it into content.

Using Macros

Using macros in content is extremely simple.

Macros can be used in any field in ExpressionEngine that allows you to enter plain text in some form. Uou may reference your macros by prefixing the name of the macro with the scope it is defined in - separated by a colon - and wrapping the entire thing in square brackets. When you do so, the value set for the macro will be replaced into the published output.

For instance, say you create a macro in the "mine" scope with the name "address". You would use this macro in any content you are set as the Author of by using a token like so:

Example Usage

Accessing a macro named "address" in the "mine" scope:

            <p>My office location is [mine:address].</p>
        

Similarly, if you are a Super Admin and create a macro in the scope "site" with the name "slogan", any content authors could insert the value of this macro into content published in the entire site with this token:

Example Usage

Accessing a macro named "slogan" in the "site" scope:

            <p>Remember, [site:slogan]</p>
        

That's really all there is to using macros!

Using Shortcodes

Using shortcodes in your content is similar to using macros.

The same basic syntax is used - a tag name inside of square brackets - but the prefix for shortcodes is designated by the plugin or module that provides the shortcode, and may be absent completely.

For example, ProForm provides a shortcode which can be used to inject a form into a piece of content like so:

Example Usage

Injecting a form into content using ProForm's [form] shortcode:

            <p>Please fill out this form to apply for the posting:</p>
            [form form_name="application_form"]
        

As you can see, shortcodes can accept parameters, which are passed on to the plugin or module that provides the shortcode, and which it can use to customize the output for the shortcode.

See the Shortcode Documentation section for a list of built-in shortcodes provided out of the box.

Insert Shortcode Dialog

If you make use of the Rich Text Editor provided with ExpressionEngine, a new Insert Macro / Shortcode icon will be added to the toolbar. When you click this button, a list of all possible macros and shortcodes will be presented. Upon selecting one of these options, such as the [form] shortcode, the required parameters for the Shortcode will be presented for you to fill out.

Shortcode Documentation

For documentation on the shortcodes available built in to the module as well as by other add-ons you may have installed, goto Add-ons > Modules > Shortcode inside ExpressionEngine then click the Add-on Shortcodes button in the top right. This will display a list of all available shortcodes and their documentation.

Currently Shortcode has the following codes available by default:

Creating Shortcodes

Shortcodes can be provided by plugins or modules.

A shortcode consists of the definition of it's parameters, documentation, and other meta data - coupled with the template tag that actually implements the shortcode. These template tags may be, and often are, pre-existing tags that can also be used directly in normal ExpressionEngine templates. The meta data tells Shortcode how to wrap up these template tags into a usable form within content - using the shortcode syntax.

Shortcode meta data is specified in a global function named init_shortcodes(), which should be defined on the main plugin or module file. Note that it's perfectly fine for an add-on to register shortcodes on another add-ons behalf to add support if the original add-on doesn't support Shortcode.

Example Usage

Creating a new shortcode mapped to a plugin named twooter with a tag named twoot, which accepts a single parameter named id. This method must appear in a plugin or module to be used.

            public function init_shortcodes()
            {
                return array(
                    'twoot' => = array(
                        'class' => 'twooter',
                        'method' => 'render_tweet',
                        'label' => '[twoot] - Embed a Tweet differently from the built-in Twitter support',
                        'params' => array(
                            array('type' => 'input', 'name' => 'id', 'label' => 'ID of Tweet'),
                        ),
                        'docs' => "

Documentation for this shortcode

[twoot id='12345']" ) ); }

The array keys ("twoot" in the example) in the array are the actual names of the shortcodes that must be used to reference them in content. You may define multiple shortcodes by including more than one key / array pair in the returned array.

The class string ("twooter" in the example) is set to the name of the plugin or module that should be triggered when the shortcode is rendered. This does not have to be set to the same class name as the add-on that is actually registering the shortcode. If this value is not included it will default to the current add-on's class name.

The method string ("render_tweet" in the example) is set to the actual tag to trigger and pass the shortcode's parameters to. This method must exist and be plugin on the class set.

The label string is set to a value used to display the shortcode in the Insert Macro / Shortcode dialog box, and in the Add-on Shortcodes listing. This value should always start with the short name of the shortcode in square brackets, as shown.

The docs string should be at least somewhat more extensive than the above example, providing a list of parameters and their allowed values. Multiple real-world examples are a good idea as well.

The params element for each shortcode may be an empty array if the shortcode does not need any parameters (which is probably rare), or may consist of multiple arrays defining the parameters needed by the shortcode.

You may use the following types for each parameter:

TypeDescription
inputA simple text input field.
dropdownA dropdown select list which is populated from the attribute options added to the field's array. The options array should consist of keys that will be set as the actual parameter, and values which are used as the labels for each option.