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:

The Shortcode object

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

Fields

Methods

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.

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:

The default options are defined in ShortcodeParser.DEFAULT_OPTIONS.

Parser modes

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"