A tiny library allowing to compose website components being used repeatedly by wrapping them in the callbacks that produce respective HTML markup.
Using the library
First of all, you need to include ShortcodeJS library. When you're done with the former, new shortcodes are meant to be registered with
Shortcode.register() method. Finally, sources can be parsed by the
There are two kinds of shortcode:
- empty shortcode being standalone shortcode with no content surrounded, e.g.
- content shortcode being shortcode that surrounds a content, e.g.
In addition, both can have attributes assigned, e.g.
Registers new shortcode.
stringthat represents the name of the shortcode
cb- a callback
functionthat returns HTML markup, having taken up to 2 parameters:
objectcontaining attributes assigned to a shortcode
stringrepresenting the content of a shortcode
Parses a source turning registered shortcodes into respecitve HTML markup.
string being HTML markup.
stringthat holds the content to be parsed
objectthat holds variables that can be interpolated in the content (consult Interpolating variables for details)
Sets a particular option using given value.
stringrepresenting a name of the option being set
stringrepresenting a value to set
The table below shows available options to set.
||Whether to turn dash-case attribute name into camelCase, for example
Note that the name of a shortcode is passed as first argument of the
Shortcode.register() method, then this name is used within
a content that will be processed.
Composing a component
Simplest component only consists of name.
Neither component's attributes nor its content is involved, therefore no parameters are used with the callback composing HTML markup.
Shortcode;/*given input:[separator/]expected output:<hr />*/
Empty shortcode with attributes
Right beside the name, a shortcode can have attributes assigned.
It can be done the same way as if it were regular HTML element.
Shortcode;/*given input:[separator width="50%"/]expected output:<hr style="width: 50%" />*/
As well, the shortcodes are able to hold content, including another nested shortcodes.
Though the example below does not use attributes, passing
attr parameter is essential as it precedes the
content parameter that we make use of.
Shortcode;/*given input:[frame]This content is important.[/frame]expected output:<div style="border: solid 1px #333">This content is important.</div>*/
Content shortcode with attributes
Content shortcodes are any less different when it comes to assigning attributes.
Shortcode;/*given input:[cite user="damianc"]I hope you will make good use of it.[/cite]expected output:@damianc: I hope you will make good use of it.*/
An input string can have assigned variables whose values will be inserted when parsing.
To indicate placeholder for a variable, it's necessary to use
There are two kinds of such variables:
- pre-parsing - these variables will be interpolated before processing shortcodes (use
- post-parsing - these variables will be interpolated after processing shortcodes (use
Values of variables are being received from an object passed as a second parameter of the
parse() method call.
The keys of the object are mapped to variable names used within an input string while while their values correspond to the
values of the object's properties with identical names.
In the code below, following steps are being done:
@@:textDecorationis replaced with
- the input string with shortcodes embedded is processed
@:languageNameis replaced with
@:libraryNameis replaced with
Among @:languageName libraries worth to discover is [@@:textDecoration]@:libraryName[/@@:textDecoration].
As done in the code above, using pre-parsing variables is recommended mostly for things that can affect process of parsing a shortcode, i.e., name of a shortcode or values that its attributes have assigned. Other values can be inserted after the shortcode parsing is perfrormed; this is what post-parsing variables are meant to.
Default attribute values
It may happen that your shortcode is to take a multiple of attributes of which not all are required. In the case, default values should be guaranteed to be delivered.
Note that attribute names must not contain uppercase characters as they will not be preserved.
Even if you use a shortcode like
[frame borderColor="red"], the
attrobject is to contain
bordercolorproperty rather than
Still, you could use dash-case name, e.g.
[frame border-color="red"], in which case the respective property name can remain the same, i.e.
border-color(keep in mind that such a name is required to be surrounded with quotes when accessed). See Combined attribute names for details.
Shortcode;/*given input:[frame bordercolor="red"]This message is very important![/frame]expected output:<div style="border: solid 1px red">This message is very important!</div>*/
Combined attribute names
By default, attribute names consisting of the words separated by dash are turning into the camelCase form to be accessed with the
attr object in the shortcode callback (e.g.
scAttr). Why that happens is because the
attributeNameToCamelCase setting is set to
true by default. To keep attribute names dash-case set this option to
Running out of browser
ShortcodeJS is supposed to run in browser environment that delivers the
For environments like Node.js (without the
document object by default), function returning ShortcodeJS API is provided - this function takes appropriate
document object that can be derived from an external library like jsdom.
const JSDOM = ;const dom = '<!DOCTYPE html></html>';const document = domwindow;const Shortcode = document;// ...