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.