1
// Utility functions for parsing and handling shortcodes in Javascript.
3
// Ensure the global `wp` object exists.
4
window.wp = window.wp || {};
8
// ### Find the next matching shortcode
10
// Given a shortcode `tag`, a block of `text`, and an optional starting
11
// `index`, returns the next matching shortcode or `undefined`.
13
// Shortcodes are formatted as an object that contains the match
14
// `content`, the matching `index`, and the parsed `shortcode` object.
15
next: function( tag, text, index ) {
16
var re = wp.shortcode.regexp( tag ),
19
re.lastIndex = index || 0;
20
match = re.exec( text );
26
// If we matched an escaped shortcode, try again.
27
if ( '[' === match[1] && ']' === match[7] ) {
28
return wp.shortcode.next( tag, text, re.lastIndex );
34
shortcode: wp.shortcode.fromMatch( match )
37
// If we matched a leading `[`, strip it from the match
38
// and increment the index accordingly.
40
result.content = result.content.slice( 1 );
44
// If we matched a trailing `]`, strip it from the match.
46
result.content = result.content.slice( 0, -1 );
52
// ### Replace matching shortcodes in a block of text
54
// Accepts a shortcode `tag`, content `text` to scan, and a `callback`
55
// to process the shortcode matches and return a replacement string.
56
// Returns the `text` with all shortcodes replaced.
58
// Shortcode matches are objects that contain the shortcode `tag`,
59
// a shortcode `attrs` object, the `content` between shortcode tags,
60
// and a boolean flag to indicate if the match was a `single` tag.
61
replace: function( tag, text, callback ) {
62
return text.replace( wp.shortcode.regexp( tag ), function( match, left, tag, attrs, slash, content, closing, right ) {
63
// If both extra brackets exist, the shortcode has been
65
if ( left === '[' && right === ']' ) {
69
// Create the match object and pass it through the callback.
70
var result = callback( wp.shortcode.fromMatch( arguments ) );
72
// Make sure to return any of the extra brackets if they
73
// weren't used to escape the shortcode.
74
return result ? left + result + right : match;
78
// ### Generate a string from shortcode parameters
80
// Creates a `wp.shortcode` instance and returns a string.
82
// Accepts the same `options` as the `wp.shortcode()` constructor,
83
// containing a `tag` string, a string or object of `attrs`, a boolean
84
// indicating whether to format the shortcode using a `single` tag, and a
86
string: function( options ) {
87
return new wp.shortcode( options ).string();
90
// ### Generate a RegExp to identify a shortcode
92
// The base regex is functionally equivalent to the one found in
93
// `get_shortcode_regex()` in `wp-includes/shortcodes.php`.
97
// 1. An extra `[` to allow for escaping shortcodes with double `[[]]`
98
// 2. The shortcode name
99
// 3. The shortcode argument list
100
// 4. The self closing `/`
101
// 5. The content of a shortcode when it wraps some content.
102
// 6. The closing tag.
103
// 7. An extra `]` to allow for escaping shortcodes with double `[[]]`
104
regexp: _.memoize( function( tag ) {
105
return new RegExp( '\\[(\\[?)(' + tag + ')(?![\\w-])([^\\]\\/]*(?:\\/(?!\\])[^\\]\\/]*)*?)(?:(\\/)\\]|\\](?:([^\\[]*(?:\\[(?!\\/\\2\\])[^\\[]*)*)(\\[\\/\\2\\]))?)(\\]?)', 'g' );
109
// ### Parse shortcode attributes
111
// Shortcodes accept many types of attributes. These can chiefly be
112
// divided into named and numeric attributes:
114
// Named attributes are assigned on a key/value basis, while numeric
115
// attributes are treated as an array.
117
// Named attributes can be formatted as either `name="value"`,
118
// `name='value'`, or `name=value`. Numeric attributes can be formatted
119
// as `"value"` or just `value`.
120
attrs: _.memoize( function( text ) {
125
// This regular expression is reused from `shortcode_parse_atts()`
126
// in `wp-includes/shortcodes.php`.
130
// 1. An attribute name, that corresponds to...
131
// 2. a value in double quotes.
132
// 3. An attribute name, that corresponds to...
133
// 4. a value in single quotes.
134
// 5. An attribute name, that corresponds to...
135
// 6. an unquoted value.
136
// 7. A numeric attribute in double quotes.
137
// 8. An unquoted numeric attribute.
138
pattern = /(\w+)\s*=\s*"([^"]*)"(?:\s|$)|(\w+)\s*=\s*\'([^\']*)\'(?:\s|$)|(\w+)\s*=\s*([^\s\'"]+)(?:\s|$)|"([^"]*)"(?:\s|$)|(\S+)(?:\s|$)/g;
140
// Map zero-width spaces to actual spaces.
141
text = text.replace( /[\u00a0\u200b]/g, ' ' );
143
// Match and normalize attributes.
144
while ( (match = pattern.exec( text )) ) {
146
named[ match[1].toLowerCase() ] = match[2];
147
} else if ( match[3] ) {
148
named[ match[3].toLowerCase() ] = match[4];
149
} else if ( match[5] ) {
150
named[ match[5].toLowerCase() ] = match[6];
151
} else if ( match[7] ) {
152
numeric.push( match[7] );
153
} else if ( match[8] ) {
154
numeric.push( match[8] );
164
// ### Generate a Shortcode Object from a RegExp match
165
// Accepts a `match` object from calling `regexp.exec()` on a `RegExp`
166
// generated by `wp.shortcode.regexp()`. `match` can also be set to the
167
// `arguments` from a callback passed to `regexp.replace()`.
168
fromMatch: function( match ) {
172
type = 'self-closing';
173
} else if ( match[6] ) {
179
return new wp.shortcode({
192
// Shortcode objects are generated automatically when using the main
193
// `wp.shortcode` methods: `next()`, `replace()`, and `string()`.
195
// To access a raw representation of a shortcode, pass an `options` object,
196
// containing a `tag` string, a string or object of `attrs`, a string
197
// indicating the `type` of the shortcode ('single', 'self-closing', or
198
// 'closed'), and a `content` string.
199
wp.shortcode = _.extend( function( options ) {
200
_.extend( this, _.pick( options || {}, 'tag', 'attrs', 'type', 'content' ) );
202
var attrs = this.attrs;
204
// Ensure we have a correctly formatted `attrs` object.
214
// Parse a string of attributes.
215
if ( _.isString( attrs ) ) {
216
this.attrs = wp.shortcode.attrs( attrs );
218
// Identify a correctly formatted `attrs` object.
219
} else if ( _.isEqual( _.keys( attrs ), [ 'named', 'numeric' ] ) ) {
222
// Handle a flat object of attributes.
224
_.each( options.attrs, function( value, key ) {
225
this.set( key, value );
230
_.extend( wp.shortcode.prototype, {
231
// ### Get a shortcode attribute
233
// Automatically detects whether `attr` is named or numeric and routes
235
get: function( attr ) {
236
return this.attrs[ _.isNumber( attr ) ? 'numeric' : 'named' ][ attr ];
239
// ### Set a shortcode attribute
241
// Automatically detects whether `attr` is named or numeric and routes
243
set: function( attr, value ) {
244
this.attrs[ _.isNumber( attr ) ? 'numeric' : 'named' ][ attr ] = value;
248
// ### Transform the shortcode match into a string
250
var text = '[' + this.tag;
252
_.each( this.attrs.numeric, function( value ) {
253
if ( /\s/.test( value ) ) {
254
text += ' "' + value + '"';
260
_.each( this.attrs.named, function( value, name ) {
261
text += ' ' + name + '="' + value + '"';
264
// If the tag is marked as `single` or `self-closing`, close the
265
// tag and ignore any additional content.
266
if ( 'single' === this.type ) {
268
} else if ( 'self-closing' === this.type ) {
272
// Complete the opening tag.
275
if ( this.content ) {
276
text += this.content;
279
// Add the closing tag.
280
return text + '[/' + this.tag + ']';
285
// HTML utility functions
286
// ----------------------
288
// Experimental. These functions may change or be removed in the future.
290
wp.html = _.extend( wp.html || {}, {
291
// ### Parse HTML attributes.
293
// Converts `content` to a set of parsed HTML attributes.
294
// Utilizes `wp.shortcode.attrs( content )`, which is a valid superset of
295
// the HTML attribute specification. Reformats the attributes into an
296
// object that contains the `attrs` with `key:value` mapping, and a record
297
// of the attributes that were entered using `empty` attribute syntax (i.e.
299
attrs: function( content ) {
302
// If `content` ends in a slash, strip it.
303
if ( '/' === content[ content.length - 1 ] ) {
304
content = content.slice( 0, -1 );
307
result = wp.shortcode.attrs( content );
308
attrs = result.named;
310
_.each( result.numeric, function( key ) {
311
if ( /\s/.test( key ) ) {
321
// ### Convert an HTML-representation of an object to a string.
322
string: function( options ) {
323
var text = '<' + options.tag,
324
content = options.content || '';
326
_.each( options.attrs, function( value, attr ) {
329
// Use empty attribute notation where possible.
330
if ( '' === value ) {
334
// Convert boolean values to strings.
335
if ( _.isBoolean( value ) ) {
336
value = value ? 'true' : 'false';
339
text += '="' + value + '"';
342
// Return the result if it is a self-closing tag.
343
if ( options.single ) {
347
// Complete the opening tag.
350
// If `content` is an object, recursively call this function.
351
text += _.isObject( content ) ? wp.html.string( content ) : content;
353
return text + '</' + options.tag + '>';