SCEditor Documentation

Custom BBCodes

Creating/Updating a BBCode

To add a new BBCode, use the sceditor.formats.bbcode.set() function.

This function will update any existing BBCode with the same name.

sceditor.formats.bbcode.set() takes two arguments, name and bbcode.

Structure of a BBCode object

{
    styles: {
        "stylename": null,
        "another-style-name": ["value1", "value2"]
    }
    tags: {
        "tag": null,
        "another-tag": {
            "attribute1": null,
            "attribute2": ["value1", "value2"]
        }
    }
    isSelfClosing: false,
    isInline: true,
    isHtmlInline: undefined,
    allowedChildren: null,
    allowsEmpty: false,
    excludeClosing: false,
    skipLastLineBreak: false,

    breakBefore: false,
    breakStart: false,
    breakEnd: false,
    breakAfter: false,

    format: 'string|function',
    html: 'string|function',

    quoteType: sceditor.BBCodeParser.QuoteType.auto
}

styles

styles object Defaults to null

All matching tags will be passed to the format function or string to be converted into BBCode.

To match all occurrences of a CSS style do with a specific value do:

"style-name": ["value1", "value2"]

Any DOM node that has the style style-name with the value value1 or value2 will be matched and passed to the format property to be converted.

To match all occurrences of a style regardless of value do:

"style-name": null

The null value means that the value of the CSS property doesn’t matter all that matters is the node has the property style-name.

Currently it's not possible to target both styles and tags at the same time via the styles and tags properties.

To target a tags that have specific styles, target the tag using the tags property and then in the format method check if the node has the desired styles. If it does handle it otherwise just return the contents.

For example:


format: function(element, content) {
    // Only handle tags with the font-weight: bold style
    if(element.style.fontWeight !== 'bold') {
        return content;
    }

    return '[b]' + content + '[/b]';
}

tags

tags object Defaults to null

All matching tags will be passed to the format function or string to be converted into BBCode.

To match all occurrences of a specific tag do:

"tag-name": null

Any DOM node that is an instance of <tag-name> will be passed to the format property to be converted.

To match all occurrences of a tag with that has a specific attribute do:

"tag-name": {
    "attribute-name": null,
    "another-attribute-name": null
}

That will match any tag that is an instance of <tag-name> and has the attribute attribute-name or another-attribute-name.

To match all occurrences of a tag with an attribute with a specific value do:

"tag-name": {
    "attribute-name": ["value1", "value2"]
}

This will match any tag that is an instance of <tag-name> and has the attribute attribute-name with the value value1 or value2.

isSelfClosing

isSelfClosing Bool Defaults to false

If this BBCode is a self closing tag (has no closing tag i.e. [hr]).

isInline

isInline Bool Defaults to true

If this BBCode is an inline or block level BBCode.

isHtmlInline

isHtmlInline Bool or undefined Defaults to undefined

If this output HTML for this BBCode is inline or not. Only needs to be set if it differs from the BBCodes isInline value. If undefined this is ignored and isInline is used.

allowedChildren

allowedChildren Array or null Defaults to null

If null/undefined then all children will be allowed. If it’s an array only the tags specified will be allowed. To allow plain text use # as the tag name.

To only allow plain text: allowedChildren: ['#']

To only allow bold and italic as children: allowedChildren: ['b', 'i']

allowsEmpty

allowsEmpty Bool Defaults to false

If this tag is allowed to be empty (have no children or content).

excludeClosing

excludeClosing Bool Defaults to false

If to not add a closing tag. Mostly so that [*] can be used without [/*].

skipLastLineBreak

skipLastLineBreak Bool Defaults to false

Block level tags have an extra <br /> added to the end of them in all browsers except IE. If this is set to true the extra line break will not be added.

breakBefore

breakBefore Bool Defaults to false

If to insert a new line before the start tag.

breakStart

breakStart Bool Defaults to false

If to insert a new line after the start tag.

This does not apply to self closing tags.

breakEnd

breakEnd Bool Defaults to false

If to insert a new line before the end tag.

This does not apply to self closing tags.

breakAfter

breakAfter Bool Defaults to false

If to insert a new line after the end tag.

format

format String or function

Should be either a string in the format "[b]{0}[/b]" where {0} will be replaced with the BBCode tags content.

Or a function that takes two arguments, element & content and returns the formatted BBCode string.

e.g.:

function(element, content) {
    if(!element.attr('data-youtube-id'))
        return content;

    return '[youtube]' + element.attr('data-youtube-id') + '[/youtube]';
}

html

html String or function

Should be either a string in the format "<strong>{0}</strong>" where {0} will be replaced with the HTML tags content.

Or a function that takes 3 arguments (token, attrs, content) and returns the HTML string.

e.g.:

html: function(token, attrs, content) {
    if(typeof attrs.defaultattr !== 'undefined')
        content = '<cite>' + attrs.defaultattr + '</cite>' + content;

    return '<blockquote>' + content + '</blockquote>';
}

quoteType

quoteType sceditor.BBCodeParser.QuoteType Defaults to sceditor.BBCodeParser.QuoteType.auto

The attribute quote type.

Should either be a function or one of the following values: