Documentation: Shortcodes

Shortcodes are small blocks of customizable code that can be inserted directly into content in order to generate pre-formatted content blocks, or to add independent content blocks (such as forms or tables) into the primary content.

They are simple to use and do not require any programming or development knowledge. Shortcodes are defined using square brackets and are structured in one of two formats:

[shortcode attribute=”value”]
[shortcode attribute=”value”]Internal Content[/shortcode]

In the first instance, the name shortcode indicates the type of shortcode that we want to use. There are a number of different shortcodes, which are covered below. We should also note that if a shortcode name is not recognized by the system (because it is either misspelled or entirely non-existent), the code itself will not be translated and will appear entered in the content.

Within the shortcode, there is an attribute/value pair. Attributes are used to pass additional information to the shortcode. This information is used to control the output, and the available attributes will vary, based on the shortcode that is being used.

Both shortcode formats include the shortcode name and attribute. The primary difference between them is that the first format is self-contained. It will simply render in place, with no other connection to the surrounding content.

The second format is a bit different. It has an opening code and a matching end code, with (simple) internal content between. This allows us to apply shortcodes to larger blocks of content, which can be useful in a number of circumstances.

With these basic concepts in mind, let’s take a look at some of the different shortcodes that are available.

Custom Shortcodes

There are five custom shortcodes that have been created specifically for the Cambrian website. These shortcodes are built into the WordPress theme.

Button

The button shortcode is, as implied by its name, a shortcode specifically designed for adding buttons to page content. It is quite simple to implement and accepts a number of attributes for customizing the button.

Attributes

  • text (required) – This attribute defines the text that will appear in the button.
  • href (required) – This attribute defines the URL that the button will link to. It can also be used to create a jump link by including the anchor ID of a block or module within the page.
  • size – This attribute allows you to set the size of the button. Options include normal (default) and large.
  • icon – This attribute allows you to include an icon in the button by specifying the slug of the icon. A complete list of icons and slugs can be found by viewing the available icons.

Examples

The following are examples of how the shorcode can be implemented.

Simple Link Button
[button text="Documentation" href="http://cambrianinternational.ca/docs/documentation/"]

This simple shortcode will render this button:

Documentation
Anchor Icon Button
[button text="Testimonials" href="testimonial" icon="diamond-speech-bubble"]

This shortcode will render a button with an icon. And, because the href attribute is not a URL, the button will assume that it should be a jump link.

Testimonials
Large Button
[button text="Large Button" href="http://cambrianinternational.ca/docs/documentation/" size="large"]

This shortcode will render a larger version of the button.

Large Button

Links List

The links list shortcode is designed to apply an alternate, more predominant appearance to an unordered list of links. Usage involves wrapping an ordered list within the opening and closing codes. It’s important to note that the full contents needs to be a fully formatted list. The shortcode adds a wrapper. It does not build the list itself.

Attributes

  • columns – Setting this attribute to true will render the list in two columns on screens with wider viewports.

Examples

The following are examples of how the shorcode can be implemented.

Single Column
[links_list]
<ul>
<li><a href="#">Regular list style eget auctor duiut faucibus.</a></li>
<li><a href="#">Regular list style eget auctor duiut faucibus.</a></li>
<li><a href="#">Regular list style eget auctor duiut faucibus.</a></li>
<li><a href="#">Regular list style eget auctor duiut faucibus.</a></li>
</ul>
[/links_list]

This will render a list of links that appears as:

Two Column
[links_list columns="true"]
<ul>
<li><a href="#">Regular list style eget auctor duiut faucibus.</a></li>
<li><a href="#">Regular list style eget auctor duiut faucibus.</a></li>
<li><a href="#">Regular list style eget auctor duiut faucibus.</a></li>
<li><a href="#">Regular list style eget auctor duiut faucibus.</a></li>
<li><a href="#">Regular list style eget auctor duiut faucibus.</a></li>
<li><a href="#">Regular list style eget auctor duiut faucibus.</a></li>
<li><a href="#">Regular list style eget auctor duiut faucibus.</a></li>
<li><a href="#">Regular list style eget auctor duiut faucibus.</a></li>
</ul>
[/links_list]

This code will render a list of links that appears as:

Columns

The columns shortcode is one of the simplest of the available shortcodes, and is designed to apply a two column layout to a block of content. Usage involves wrapping the content within the opening and closing codes. Note that these two column layouts will not render in IE9.

Attributes

This shortcode does not have any attributes.

Example

[columns]Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam elementum pulvinar velit vitae pellentesque. Donec dignissim consequat arcu, quis malesuada mauris venenatis vel. Maecenas viverra arcu tortor, nec congue leo pretium tincidunt. Maecenas non turpis et nisl egestas eleifend non sit amet turpis. Donec at cursus mi. Phasellus consequat risus sed odio aliquet, eu porta massa placerat. Maecenas ac lectus neque. Phasellus lobortis felis id turpis mattis, et sagittis nulla pretium. Nulla ligula orci, sagittis pretium mollis quis, malesuada et nunc. Integer hendrerit ex quam, egestas facilisis lectus lacinia convallis. Donec facilisis, urna a volutpat porta, lectus quam lacinia augue, eu suscipit leo neque eu turpis.[/columns]

This will render the content in this two column format:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam elementum pulvinar velit vitae pellentesque. Donec dignissim consequat arcu, quis malesuada mauris venenatis vel. Maecenas viverra arcu tortor, nec congue leo pretium tincidunt. Maecenas non turpis et nisl egestas eleifend non sit amet turpis. Donec at cursus mi. Phasellus consequat risus sed odio aliquet, eu porta massa placerat. Maecenas ac lectus neque. Phasellus lobortis felis id turpis mattis, et sagittis nulla pretium. Nulla ligula orci, sagittis pretium mollis quis, malesuada et nunc. Integer hendrerit ex quam, egestas facilisis lectus lacinia convallis. Donec facilisis, urna a volutpat porta, lectus quam lacinia augue, eu suscipit leo neque eu turpis.

Testimonial

The testimonial block is intended for creating testimonials within a block of content. Usage involves wrapping the testimonial content within the opening and closing codes.

Attributes

  • name – This attribute defines the name of the individual providing the testimonial.
  • designation – This optional attribute defines the designation to go along with the name. This could be a job title or a field of study.
  • photo – This optional attribute defines the ID of the photo to be included along side the testimonial.

Examples

The following are examples of how the shorcode can be implemented. Note that testimonials (and other block quotes) have more top and bottom padding than typical paragraphs.

Simple Testimonial
[testimonial name="Jane Doe"]This is my testimonial, lorem ipsum dolor sit amet.[/testimonial]
This code will render a testimonial as:
This is my testimonial, lorem ipsum dolor sit amet.
Jane Doe
Longer Testimonial with Photo
[testimonial name="Jane Doe" designation="Cambrian College Alumna" photo="5970"]This is my testimonial, lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam elementum pulvinar velit vitae pellentesque. Donec dignissim consequat arcu, quis malesuada mauris venenatis vel. Maecenas viverra arcu tortor, nec congue leo pretium tincidunt. Maecenas non turpis et nisl egestas eleifend non sit amet turpis. [/testimonial]
This code will render a testimonial as:
In January, Meet Thakkar won a $1,000 scholarship from the College Student Alliance, an advocacy organization that represents more than 135,000 full-time student members in the province of Ontario.
This is my testimonial, lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam elementum pulvinar velit vitae pellentesque. Donec dignissim consequat arcu, quis malesuada mauris venenatis vel. Maecenas viverra arcu tortor, nec congue leo pretium tincidunt. Maecenas non turpis et nisl egestas eleifend non sit amet turpis.
Jane Doe Cambrian College Alumna

Emphasis

Add emphasis to a block of text by wrapping it in the “emphasis” shortcode.

[emphasis]This text will be emphasized thanks to the use of the emphasis shortcode.[/emphasis]

This text is emphasized thanks to the use of the emphasis shortcode.

Plugin Shortcodes

TablePress

TablePress is a relatively simple plugin that has been implemented for the purpose of creating tables for use in site content. To read more about TablePress, read the documentation. It is included here because adding a table to page content involves using the simple TablePress shortcode.

Gravity Forms

Similar to TablePress, Gravity Forms is a plugin that his been implemented for the purpose of creating and managing contact forms on the site. To read more about using Gravity Forms, please read the documentation. It is included here because adding a form to a page involves using the Gravity Forms shortcode.

Image Captions

Adding images into WordPress can be achieved using the Add Media button in the rich text editor. Generally speaking, this will simply inject an image tag into the content. However, when adding a caption to an image, WordPress makes use of one of its own builtin shortcodes—namely the caption shortcode. When an image is inserted into the content through the rich text editor, the image and its caption will appear in the standard WordPress admin format. Checking the content in the Text (HTML) editor will reveal that the image is actually wrapped in the caption shortcode. Take the following image and caption for example:

An image of a city's skyline
A caption on an image of a city skyline.

This image block was rendered using the following code:


[caption id="attachment_475" align="alignnone" width="700"]<img decoding="async" class="wp-image-475 size-large" src="http://cambrianinternational.ca/wp-content/uploads/2016/03/HWijjF7RwOPGEJ1nb4Zb_IMG_3773-700x467.jpg" alt="An image of a city's skyline" width="700" height="330" /> A caption on an image of a city skyline.[/caption]

For the most part, content editors will not need to make use of this shortcode directly. It is included here simply as a reference for any content editors that might be reviewing content in the plain text (HTML) editor.

Other Builtin Shortcodes

WordPress also comes with a number of “builtin” short codes. These are codes that are available for including various types of media within content blocks.

These include:

  • audio – this shortcode allows you to render a simple player for audio files such as MP3s.
  • embed – this shortcode allows you to render a container for an embed (such as YouTube of Vimeo).
  • gallery – this shortcode allows you to render a gallery of images. Note: the Cambrian theme overrides WordPress’ default gallery, and instead uses the same module that is used for galleries on other areas of the site.
  • playlist – this shortcode allows you to render a playlist of audio files OR video files (but not both in the same list)
  • video – this shortcode allows you to render a simple player for video files.

These shortcodes are covered extensively in WordPress’ own documentation. Rather than replicating that information here, please refer to the Shortcode overview on WordPress.org