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 );
25 // If we matched an escaped shortcode, try again.
26 if ( match[1] === '[' && match[7] === ']' )
27 return wp.shortcode.next( tag, text, re.lastIndex );
32 shortcode: wp.shortcode.fromMatch( match )
35 // If we matched a leading `[`, strip it from the match
36 // and increment the index accordingly.
38 result.match = result.match.slice( 1 );
42 // If we matched a trailing `]`, strip it from the match.
44 result.match = result.match.slice( 0, -1 );
49 // ### Replace matching shortcodes in a block of text
51 // Accepts a shortcode `tag`, content `text` to scan, and a `callback`
52 // to process the shortcode matches and return a replacement string.
53 // Returns the `text` with all shortcodes replaced.
55 // Shortcode matches are objects that contain the shortcode `tag`,
56 // a shortcode `attrs` object, the `content` between shortcode tags,
57 // and a boolean flag to indicate if the match was a `single` tag.
58 replace: function( tag, text, callback ) {
59 return text.replace( wp.shortcode.regexp( tag ), function( match, left, tag, attrs, slash, content, closing, right, offset ) {
60 // If both extra brackets exist, the shortcode has been
62 if ( left === '[' && right === ']' )
65 // Create the match object and pass it through the callback.
66 var result = callback( wp.shortcode.fromMatch( arguments ) );
68 // Make sure to return any of the extra brackets if they
69 // weren't used to escape the shortcode.
70 return result ? left + result + right : match;
74 // ### Generate a string from shortcode parameters
76 // Creates a `wp.shortcode` instance and returns a string.
78 // Accepts the same `options` as the `wp.shortcode()` constructor,
79 // containing a `tag` string, a string or object of `attrs`, a boolean
80 // indicating whether to format the shortcode using a `single` tag, and a
82 string: function( options ) {
83 return new wp.shortcode( options ).string();
86 // ### Generate a RegExp to identify a shortcode
88 // The base regex is functionally equivalent to the one found in
89 // `get_shortcode_regex()` in `wp-includes/shortcodes.php`.
93 // 1. An extra `[` to allow for escaping shortcodes with double `[[]]`
94 // 2. The shortcode name
95 // 3. The shortcode argument list
96 // 4. The self closing `/`
97 // 5. The content of a shortcode when it wraps some content.
98 // 6. The closing tag.
99 // 7. An extra `]` to allow for escaping shortcodes with double `[[]]`
100 regexp: _.memoize( function( tag ) {
101 return new RegExp( '\\[(\\[?)(' + tag + ')(?![\\w-])([^\\]\\/]*(?:\\/(?!\\])[^\\]\\/]*)*?)(?:(\\/)\\]|\\](?:([^\\[]*(?:\\[(?!\\/\\2\\])[^\\[]*)*)(\\[\\/\\2\\]))?)(\\]?)', 'g' );
105 // ### Parse shortcode attributes
107 // Shortcodes accept many types of attributes. These can chiefly be
108 // divided into named and numeric attributes:
110 // Named attributes are assigned on a key/value basis, while numeric
111 // attributes are treated as an array.
113 // Named attributes can be formatted as either `name="value"`,
114 // `name='value'`, or `name=value`. Numeric attributes can be formatted
115 // as `"value"` or just `value`.
116 attrs: _.memoize( function( text ) {
121 // This regular expression is reused from `shortcode_parse_atts()`
122 // in `wp-includes/shortcodes.php`.
126 // 1. An attribute name, that corresponds to...
127 // 2. a value in double quotes.
128 // 3. An attribute name, that corresponds to...
129 // 4. a value in single quotes.
130 // 5. An attribute name, that corresponds to...
131 // 6. an unquoted value.
132 // 7. A numeric attribute in double quotes.
133 // 8. An unquoted numeric attribute.
134 pattern = /(\w+)\s*=\s*"([^"]*)"(?:\s|$)|(\w+)\s*=\s*\'([^\']*)\'(?:\s|$)|(\w+)\s*=\s*([^\s\'"]+)(?:\s|$)|"([^"]*)"(?:\s|$)|(\S+)(?:\s|$)/g;
136 // Map zero-width spaces to actual spaces.
137 text = text.replace( /[\u00a0\u200b]/g, ' ' );
139 // Match and normalize attributes.
140 while ( (match = pattern.exec( text )) ) {
142 named[ match[1].toLowerCase() ] = match[2];
143 } else if ( match[3] ) {
144 named[ match[3].toLowerCase() ] = match[4];
145 } else if ( match[5] ) {
146 named[ match[5].toLowerCase() ] = match[6];
147 } else if ( match[7] ) {
148 numeric.push( match[7] );
149 } else if ( match[8] ) {
150 numeric.push( match[8] );
160 // ### Generate a Shortcode Object from a RegExp match
161 // Accepts a `match` object from calling `regexp.exec()` on a `RegExp`
162 // generated by `wp.shortcode.regexp()`. `match` can also be set to the
163 // `arguments` from a callback passed to `regexp.replace()`.
164 fromMatch: function( match ) {
168 type = 'self-closing';
174 return new wp.shortcode({
187 // Shortcode objects are generated automatically when using the main
188 // `wp.shortcode` methods: `next()`, `replace()`, and `string()`.
190 // To access a raw representation of a shortcode, pass an `options` object,
191 // containing a `tag` string, a string or object of `attrs`, a string
192 // indicating the `type` of the shortcode ('single', 'self-closing', or
193 // 'closed'), and a `content` string.
194 wp.shortcode = _.extend( function( options ) {
195 _.extend( this, _.pick( options || {}, 'tag', 'attrs', 'type', 'content' ) );
197 var attrs = this.attrs;
199 // Ensure we have a correctly formatted `attrs` object.
208 // Parse a string of attributes.
209 if ( _.isString( attrs ) ) {
210 this.attrs = wp.shortcode.attrs( attrs );
212 // Identify a correctly formatted `attrs` object.
213 } else if ( _.isEqual( _.keys( attrs ), [ 'named', 'numeric' ] ) ) {
216 // Handle a flat object of attributes.
218 _.each( options.attrs, function( value, key ) {
219 this.set( key, value );
224 _.extend( wp.shortcode.prototype, {
225 // ### Get a shortcode attribute
227 // Automatically detects whether `attr` is named or numeric and routes
229 get: function( attr ) {
230 return this.attrs[ _.isNumber( attr ) ? 'numeric' : 'named' ][ attr ];
233 // ### Set a shortcode attribute
235 // Automatically detects whether `attr` is named or numeric and routes
237 set: function( attr, value ) {
238 this.attrs[ _.isNumber( attr ) ? 'numeric' : 'named' ][ attr ] = value;
242 // ### Transform the shortcode match into a string
244 var text = '[' + this.tag;
246 _.each( this.attrs.numeric, function( value ) {
247 if ( /\s/.test( value ) )
248 text += ' "' + value + '"';
253 _.each( this.attrs.named, function( value, name ) {
254 text += ' ' + name + '="' + value + '"';
257 // If the tag is marked as `single` or `self-closing`, close the
258 // tag and ignore any additional content.
259 if ( 'single' === this.type )
261 else if ( 'self-closing' === this.type )
264 // Complete the opening tag.
268 text += this.content;
270 // Add the closing tag.
271 return text + '[/' + this.tag + ']';
276 // HTML utility functions
277 // ----------------------
279 // Experimental. These functions may change or be removed in the future.
281 wp.html = _.extend( wp.html || {}, {
282 // ### Parse HTML attributes.
284 // Converts `content` to a set of parsed HTML attributes.
285 // Utilizes `wp.shortcode.attrs( content )`, which is a valid superset of
286 // the HTML attribute specification. Reformats the attributes into an
287 // object that contains the `attrs` with `key:value` mapping, and a record
288 // of the attributes that were entered using `empty` attribute syntax (i.e.
290 attrs: function( content ) {
293 // If `content` ends in a slash, strip it.
294 if ( '/' === content[ content.length - 1 ] )
295 content = content.slice( 0, -1 );
297 result = wp.shortcode.attrs( content );
298 attrs = result.named;
300 _.each( result.numeric, function( key ) {
301 if ( /\s/.test( key ) )
310 // ### Convert an HTML-representation of an object to a string.
311 string: function( options ) {
312 var text = '<' + options.tag,
313 content = options.content || '';
315 _.each( options.attrs, function( value, attr ) {
318 // Use empty attribute notation where possible.
322 // Convert boolean values to strings.
323 if ( _.isBoolean( value ) )
324 value = value ? 'true' : 'false';
326 text += '="' + value + '"';
329 // Return the result if it is a self-closing tag.
330 if ( options.single )
333 // Complete the opening tag.
336 // If `content` is an object, recursively call this function.
337 text += _.isObject( content ) ? wp.html.string( content ) : content;
339 return text + '</' + options.tag + '>';