shortcode-tree

shortcode-tree

A node.js parser library for reading shortcodes.

Introduction

shortcode-tree offers generic parsing functionality for text containing short codes (also known as bb codes).

This library does not convert short codes to HTML (like many other libraries do), but it converts generic shortcode/HTML input to pure JavaScript objects.

No set up is required, and you do not need to pre-define a list of shortcodes.

Example:

ShortcodeParser.parseShortcode('[image id=123 src="bla.jpg" align="center"/]');

// Shortcode {
//     name: 'image',
//     content: null,
//     properties: { id: '123', src: 'bla.jpg', align: 'center' },
//     isSelfClosing: true,
//     codeText: '[image id=123 src="bla.jpg" align="center"/]',
//     offset: 0 }

Features

• Parse sets of mixed shortcodes and text/HTML into a tree structure
• Parse individual shortcode fragments
• Supports self-closing tags
• Supports tag properties (with or without string literals)
• Stringify Shortcode objects to shortcode text or HTML equivalent
• Extract only text / HTML from a document containg shortcodes

Installation

Installation with npm:

npm install shortcode-tree --save

Usage

Start with the raw text you want to process, and feed it to the parse function:

var ShortcodeTree = require('shortcode-tree').ShortcodeTree;

var rootNode = ShortcodeTree.parse(inputText);
console.log(rootNode.children.length);

This function will return a ShortcodeNode object. Each ShortcodeNode may contain a set of child nodes.

If you have regular text or HTML mixed in at the same level as a shortcode, a ShortcodeNode may also contain TextNode children to hold these items. Text nodes themselves cannot hold children, only text.

The ShortcodeNode object

A shortcode node contains the following fields:

Field	Type	Description
text	string	The raw text content (code) of this node.
shortcode	Shortcode or null	Information about the parsed Shortcode represented by this node. Will be null if this is the root node.
children	array	List of children. May contain ShortcodeNode and TextNode items.

The Shortcode object

A parsed shortcode. Typically available through the shortcode field of a shortcode node.

Fields

Field	Type	Description
name	string	Tag name
properties	object	Key/value object with property values indexed by their name
content	string or null	The raw, unparsed content of the tag. May contain HTML and other short codes. NULL for self-closing tags.
isSelfClosing	bool	Indicates whether this is a self-closing tag without any content.
codeText	string	The raw shortcode text, as it was parsed.
offset	integer	Offset index, relative to the original input string.

Methods

Signature	Returns	Description
stringify()	string	Formats the data in the Shortcode object to shortcode text
stringifyHtml([string/null] tagName)	string	Formats the data in the Shortcode object to HTML text
hasProperty([string] key)	boolean	Gets whether property with name key exists.
getProperty([string] key)	value or null	Gets value of property with name key, or NULL if not set.
setProperty([string] key, value)	void	Add or update property with given key and value.
addChild([Shortcode] shortcode)	void	Append a shortcode item to this shortcode's content using stringify.
appendContent([string] content)	void	Append content to the existing content.

The TextNode object

A piece of raw text or HTML that was placed on the same level as another shortcode. This is always a child of a shortcode node.

Field	Type	Description
text	string	Raw text or code

Dumping tree structure

By calling traceTree() on a node, you can dump a simple visualisation of the parsed tree structure.

var sampleInput =
    "[row]" +
        "[col]" +
            "<h1>My article</h1>" +
            "[img src=\"image.jpg\"/]" +
        "[/col]" +
        "[col]" +
            "<p>Just a boring text sample column</p>" +
        "[/col]" +
    "[/row]"

var rootNode = ShortcodeTree.parse(sampleInput);
rootNode.traceTree();

The above example would generate the following console output:

+++++ Root Node +++++
[Shortcode Node: row], content: [col]<h1>My article</h1>[img src="image.jpg"/][/col][col]<p>Just a boring text sample column</p>[/col]
--- [Shortcode Node: col], content: <h1>My article</h1>[img src="image.jpg"/]
------ [Text Node], content: <h1>My article</h1>
------ [Shortcode Node: img], content: null
--- [Shortcode Node: col], content: <p>Just a boring text sample column</p>

Advanced usage

Parsing a single short code fragment

To parse one individual short code, use the ShortcodeParser:

var parser = require('shortcode-tree').ShortcodeParser;

var shortcode = parser.parseShortcode("[b]example content[/b]");
console.log(shortcode.content); // example content

The parseShortcode method returns a Shortcode object.

Custom parser options

When calling parseShortcode, you can add an options object as a second argument.

parser.parseShortcode("[b]example content[/b]", { /** insert options **/ })

The following options are available:

Option	Type	Default	Description
mode	string	normal	Parser mode to operate in. See table below.
offset	integer	0	Offset from the start of the input string, where parsing should begin.
throwErrors	boolean	true	If enabled: On shortcode parse error, an Error is thrown. If disabled: false is returned on parse error.
precise	boolean	false	If things aren't working as expected, enable this for deep recursive parsing. Reduces performance exponentially.
selfClosingTags	array	[]	You can specify a list of tags that should always be treated as self-closing. Needed when they don't use the "[selfcloser/]" syntax.
predictSelfClosing	bool	true	If enabled, self-closing tags will be predicted by checking if any closing tags can be found anywhere in the input buffer. Improves stability in most situations, but breaks if your tags are "sometimes" self closing.

The default options are defined in ShortcodeParser.DEFAULT_OPTIONS.

Parser modes

Constant	Value	Description
MODE_NORMAL	normal	Parses text into a Shortcode object.
MODE_GET_OPENING_TAG_NAME	tag_name	Halts parsing once the tag name is found, and returns it as a string.

Extracting one level of shortcodes from text

The ShortcodeExtractor is a component that can extract a set of Shortcodes from a single piece of text, without traversing deeper than one level.

var extractor = require('shortcode-tree').ShortcodeExtractor;

var shortcodes = extractor.extractShortcodes("Hey, [b]bold[/b] and [i]beautiful[/i].");
console.log(shortcodes);

// [ Shortcode {
//     name: 'b',
//     content: 'bold',
//     properties: {},
//     isSelfClosing: false,
//     codeText: '[b]bold[/b]',
//     offset: 5 },
//   Shortcode {
//     name: 'i',
//     content: 'beautiful',
//     properties: {},
//     isSelfClosing: false,
//     codeText: '[i]beautiful[/i]',
//     offset: 21 } ]

The extractShortcodes method returns an array of Shortcode objects.

Extracting text/HTML from a shortcode fragment

var treeParser = require('shortcode-tree').ShortcodeTree;

var input = `root [row][column]deep[/column][/row]`;
treeParser.extractTextContent(input);

// returns: "root deep"