SCEditor

Custom BBCodes

Creating/Updating a BBCode

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

Important: When creating or updating a BBCode, it must be done before creating an instance of the editor, e.g. before calling sceditor.create().

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

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

  • name String
    Should be the name of the BBCode e.g. for [b] it would be "b". This value must be lower-case!
  • bbcode Object
    The BBCode object. See below for more information

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,
    strictMatch: 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.

Warning

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]';

}

Matching behaviour can be changed by changing the strictMatch property.

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.

Matching behaviour can be changed by changing the strictMatch property.

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.

strictMatch

strictMatch Bool Defaults to false

Whether to use strict matching on attributes and styles.

When true this will perform AND matching requiring all tag attributes and styles to match.

When false will perform OR matching and will match if any of a tags attributes or styles match.

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.

Note: This does not apply to self closing tags.

breakEnd

breakEnd Bool Defaults to false

If to insert a new line before the end tag.

Note: 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.

  • element HTMLElement
    The DOM HTMLElement object to be converted
  • content String
    A string containing the BBCodes content

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.

  • token Object
    TokenizeToken object
  • attrs Object
    Map of attributes. The default attribute [tag=default] will be set to defaultattr
  • content String
    The HTML content of this tag

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:

  • sceditor.BBCodeParser.QuoteType.always
    Always quote the attribute value
  • sceditor.BBCodeParser.QuoteType.never
    Never quote the attributes value
  • sceditor.BBCodeParser.QuoteType.auto
    Only quote the attributes value when it contains spaces ot equals