BB Code

BB code is a widely-used system of markup that allows text to be formatted with different fonts, colors and sizes, along with other abilities like emboldening or italicising text. It is loosely based on HTML markup, so for example the BB code to define bold text is [b], and you would use it like this to use it to embolden the word bold:

This message contains some [b]bold[/b] text.

It can also be used for more complex structures, like quoting other users' messages, adding spoilers or blocks of code. In these instances, the BB code may be given an option, like this:

This message contains some text in [font="Helvetica"]a font called Helvetica[/font]...

Custom BB codes

In addition to the standard BB codes that come with XenForo, you may also define your own.

The custom BB code manager lists all custom BB codes available on your forum, and allows you to create your own. You may also delete or temporarily disable any custom BB codes using the toggle and delete gadgets available here.

You may import and export multiple custom BB codes using the controls at the top of the manager page.

Custom BB code editor

Clicking the title of a custom BB code will take you to the editor for that BB code, within which you can lay out exactly how you want your BB code to function.

In this example, we will create a BB code that will draw a box around the tagged text, and allow the user to specify a color for the box.

We will call the BB code 'box', and aim to be able to convert this text:

Input: [BOX="red"]Here is some text in a red box[/BOX]

into this HTML:

Output: <div style="background-color: red">Here is some text in a red box</div>

BB code tag

Enter the key word that will trigger your BB code here. In our example, this is 'BOX'.

Title

We'll call this 'Colored box'

Replacement mode

For our example, we wil use a simple replacement.

A PHP callback may be used for more complex replacements that involve running PHP code to work out what the output HTML should be. This is more of a developer option. If this is used, the callback should be specified using the Class and Method fields provided below.

Supports option parameter

As we need the user to define a color, we must use Yes here.

If the BB code we were defining did not need, or would not support an option, we would set this to Optional or No.

HTML replacement

Here, we enter the HTML that will replace our BB code when it is used. We will need to employ the special tokens {option} and {text} to represent the value of the option and the content of the text respectively.

Our replacement HTML will be as follows:

<div style="background-color: {option}">{text}</div>

Editor icon

You may want your users to be able to simply click a button in their text editor to insert your BB code. If so, specify a Font Awesome icon, or an image to use for your button, otherwise leave this as None and the BB code will only be available through being typed directly.

Example usage and output

Use these boxes to provide examples of something that would use your custom BB code, and what that example would output. You can use the Input/Output examples provided above.

Allow this BB code in signatures

Some BB codes are large and obnoxious, and are not suitable for use in user signatures. You may prevent any custom BB codes from being used in signatures by leaving this box unchecked.

Advanced options

Under the advanced options section, you will find controls to allow you to further refine your custom BB code.

Option match regular expression

Allows you to define a regular expression to limit acceptable values for your option value. For our example, we could use a regular expression that allows only alphanumeric characters, so that only named colors could be used.

Within this BB code

Options here allow you to prevent smilie parsing within your BB code, to prevent line breaks being converted, to disable auto-parsing of hyperlinks and to stop parsing of any other BB codes within the text component of this BB code.

Trim line breaks after

You may use this option to prevent lots of white space being left after your BB code has been used. With a value of 0, no additional line breaks will be permitted, so your HTML output should account for this.

HTML email and text replacements

It may be that you want a different output when the final format is HTML email or plain text. Use these boxes to define alternative outputs, using {option} and {text} as before.

BB code media sites

BB code media sites are a means by which links to content hosted on external sites, such as YouTube or Instagram can be converted into embedded media in users' messages automatically.

XenForo comes with a collection of predefined BB code media sites for popular sources including Facebook, Twitter, Flickr and Spotify.

Links posted in user messages will automatically be processed and turned into embedded media if the Auto-embed media links option is enabled under the Media embedding section of XenForo's options system.

BB code media site manager

Within the BB code media site manager, you can view all of the available media sites and temporarily disable each of them with a single click on the toggle gadget. You can also delete sites or add a new one.

Clicking the title of a BB code media site will load the editor for that site.

BB code media site editor

BB code media sites work by extracting data from the URL posted by the user and translating that into a snippet of HTML that can be used to embed the referenced media in a message. In some cases, this is a simple case of taking a piece of the URL and inserting it into the HTML, and in other cases further steps are required to convert the URL into usable HTML.

This can be a compex process, but for the purpose of this document we will look at a relatively simple example: Pinterest, which is simple because Pinterest URLs contain all the information we need to create the embedded HTML.

Match URLs

In this box, we define all the URLs that we would like to have converted into embedded HTML. Each URL goes on a separate line, and includes an {id} token, which represents the data in which we are interested.

In the case of Pinterest, the data is always a number, so we extend {id} to {id:digits}, which will force the pattern to only match whole numbers. The other available extension is {id:alphanum}, which limits the match to numbers and letters only. You may use a * as a wildcard in the match URLs to match anything.

Under Advanced options is a setting that allows these match URLs to be regular expressions. If you use regular expressions, each line must define delimiters and switches.

Embed template

This box is used to define the HTML that will be output if a matching URL is found. You may use any HTML, but it's a good idea to wrap your output in the <div class="bbMediaWrapper"><div class="bbMediaWrapper-inner"> code that is used by most of the default XenForo sites, as this handles styling to match the rest of the site,

Within your HTML, you may use {$id} to refer to the {id} value fetched by the Match URL. You may also use {$idDigits} or {$idAlphanum} if you used those extensions in the Match URLs.

In the case of Pinterest, the important section is the href attribute, in which we define the source of the link to be https://www.pinterest.com/pin/{$idDigits}, making use of the data grabbed by the Match URLs.

oEmbed

oEmbed is an open format that allows sites to return information about a URL, including embed HTML. In some cases, when the embed HTML cannot be constructed directly from the URL, it may be possible to use oEmbed to query the site for oEmbed data and get the HTML that way.

In order to use oEmbed, you must know the oEmbed API endpoint for the site you are querying, and the format of the URLs their API expects.

For example, Flickr's oEmbed API endpoint lives at https://www.flickr.com/services/oembed and their URL scheme is https://flic.kr/p/{$id}, where (again), {$id} represents the data matched by the Match URLs.

Finally, you must decide whether or not to execute any Javascript code that is returned from the oEmbed site along with the embed HTML. If you decide not to allow the foreign Javascript to run, you must handle any required initialization for the embedded HTML with your own Javascript routines.

Further information about oEmbed can be found at oEmbed.com, including a regularly-updated list of sites that make use of oEmbed.

Advanced options

Sometimes, even further processing is required in order to get workable embed HTML. In these cases, a PHP callback is available both for matching and embedding purposes.

It is beyond the scope of this document to go into exactly how this works, but developers will be able to inspect the code for sites in the default XenForo installation that make use of matching and embedding callbacks.

BB code button manager

When composing a message with the XenForo text editor, controls are provided to allow users to easily format their text with styles of their choice.

The layout of the buttons within the editor is customizable through the BB code button manager, located in the Admin control panel at Content > BB code > BB code button manager.

On the main button manager page, several editor toolbars are listed, along with a variety of dropdowns.

Editor dropdowns

A dropdown is a button that expands when clicked to reveal additional buttons.

Click on an existing dropdown or click Add dropdown to enter the dropdown editor.

Within the dropdown editor, you must provide a command ID (for internal system identification use only) together with a title and a Font Awesome icon class name, such as fa-align-center, which will be used as the graphical representation for the button.

To define the contents of the dropdown, drag buttons from the Available buttons area into the Dropdown buttons area and arrange them as you see fit. The first icon shown will be displayed first in the dropdown.

When all edits are complete, hit the Save button to commit changes.

Editor toolbars

With each toolbar is listed a size range. This range denotes the width in pixels of the browser window at which size the toolbar will be shown.

The actual ranges are subject to change, but at the time of writing the large toolbar is shown when the browser window measures 900 pixels wide or more. Shrinking the toolbar below this size will activate the medium toolbar, until the width of the window is less than 575 pixels, at which point the small toolbar will be used. An extra small toolbar is used below viewport widths of 420 pixels.

Clicking on any toolbar will open the editor for that toolbar.

At the top of the window is a 'pool' of Available buttons and dropdown menus. Any of these buttons and dropdowns may be dragged from the 'pool' into one of the available slots below, the buttons within which can be dragged into whatever order is appropriate.

Each slot has a set of controls, within which it is possible to define the alignment of the group and the number of buttons visible, which controls the number of buttons shown for each toolbar group before additional buttons are pushed to the 'more' toolbar, accessed with the vertical ellipsis control next to each button group.

A preview of the finished toolbar is displayed at the bottom of the page.

When all edits are complete, hit the Save button to commit changes.