|
1 // Utility functions for parsing and handling shortcodes in Javascript. |
|
2 |
|
3 // Ensure the global `wp` object exists. |
|
4 window.wp = window.wp || {}; |
|
5 |
|
6 (function(){ |
|
7 wp.shortcode = { |
|
8 // ### Find the next matching shortcode |
|
9 // |
|
10 // Given a shortcode `tag`, a block of `text`, and an optional starting |
|
11 // `index`, returns the next matching shortcode or `undefined`. |
|
12 // |
|
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 ), |
|
17 match, result; |
|
18 |
|
19 re.lastIndex = index || 0; |
|
20 match = re.exec( text ); |
|
21 |
|
22 if ( ! match ) |
|
23 return; |
|
24 |
|
25 // If we matched an escaped shortcode, try again. |
|
26 if ( match[1] === '[' && match[7] === ']' ) |
|
27 return wp.shortcode.next( tag, text, re.lastIndex ); |
|
28 |
|
29 result = { |
|
30 index: match.index, |
|
31 content: match[0], |
|
32 shortcode: wp.shortcode.fromMatch( match ) |
|
33 }; |
|
34 |
|
35 // If we matched a leading `[`, strip it from the match |
|
36 // and increment the index accordingly. |
|
37 if ( match[1] ) { |
|
38 result.match = result.match.slice( 1 ); |
|
39 result.index++; |
|
40 } |
|
41 |
|
42 // If we matched a trailing `]`, strip it from the match. |
|
43 if ( match[7] ) |
|
44 result.match = result.match.slice( 0, -1 ); |
|
45 |
|
46 return result; |
|
47 }, |
|
48 |
|
49 // ### Replace matching shortcodes in a block of text |
|
50 // |
|
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. |
|
54 // |
|
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 |
|
61 // properly escaped. |
|
62 if ( left === '[' && right === ']' ) |
|
63 return match; |
|
64 |
|
65 // Create the match object and pass it through the callback. |
|
66 var result = callback( wp.shortcode.fromMatch( arguments ) ); |
|
67 |
|
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; |
|
71 }); |
|
72 }, |
|
73 |
|
74 // ### Generate a string from shortcode parameters |
|
75 // |
|
76 // Creates a `wp.shortcode` instance and returns a string. |
|
77 // |
|
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 |
|
81 // `content` string. |
|
82 string: function( options ) { |
|
83 return new wp.shortcode( options ).string(); |
|
84 }, |
|
85 |
|
86 // ### Generate a RegExp to identify a shortcode |
|
87 // |
|
88 // The base regex is functionally equivalent to the one found in |
|
89 // `get_shortcode_regex()` in `wp-includes/shortcodes.php`. |
|
90 // |
|
91 // Capture groups: |
|
92 // |
|
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' ); |
|
102 }), |
|
103 |
|
104 |
|
105 // ### Parse shortcode attributes |
|
106 // |
|
107 // Shortcodes accept many types of attributes. These can chiefly be |
|
108 // divided into named and numeric attributes: |
|
109 // |
|
110 // Named attributes are assigned on a key/value basis, while numeric |
|
111 // attributes are treated as an array. |
|
112 // |
|
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 ) { |
|
117 var named = {}, |
|
118 numeric = [], |
|
119 pattern, match; |
|
120 |
|
121 // This regular expression is reused from `shortcode_parse_atts()` |
|
122 // in `wp-includes/shortcodes.php`. |
|
123 // |
|
124 // Capture groups: |
|
125 // |
|
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; |
|
135 |
|
136 // Map zero-width spaces to actual spaces. |
|
137 text = text.replace( /[\u00a0\u200b]/g, ' ' ); |
|
138 |
|
139 // Match and normalize attributes. |
|
140 while ( (match = pattern.exec( text )) ) { |
|
141 if ( match[1] ) { |
|
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] ); |
|
151 } |
|
152 } |
|
153 |
|
154 return { |
|
155 named: named, |
|
156 numeric: numeric |
|
157 }; |
|
158 }), |
|
159 |
|
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 ) { |
|
165 var type; |
|
166 |
|
167 if ( match[4] ) |
|
168 type = 'self-closing'; |
|
169 else if ( match[6] ) |
|
170 type = 'closed'; |
|
171 else |
|
172 type = 'single'; |
|
173 |
|
174 return new wp.shortcode({ |
|
175 tag: match[2], |
|
176 attrs: match[3], |
|
177 type: type, |
|
178 content: match[5] |
|
179 }); |
|
180 } |
|
181 }; |
|
182 |
|
183 |
|
184 // Shortcode Objects |
|
185 // ----------------- |
|
186 // |
|
187 // Shortcode objects are generated automatically when using the main |
|
188 // `wp.shortcode` methods: `next()`, `replace()`, and `string()`. |
|
189 // |
|
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' ) ); |
|
196 |
|
197 var attrs = this.attrs; |
|
198 |
|
199 // Ensure we have a correctly formatted `attrs` object. |
|
200 this.attrs = { |
|
201 named: {}, |
|
202 numeric: [] |
|
203 }; |
|
204 |
|
205 if ( ! attrs ) |
|
206 return; |
|
207 |
|
208 // Parse a string of attributes. |
|
209 if ( _.isString( attrs ) ) { |
|
210 this.attrs = wp.shortcode.attrs( attrs ); |
|
211 |
|
212 // Identify a correctly formatted `attrs` object. |
|
213 } else if ( _.isEqual( _.keys( attrs ), [ 'named', 'numeric' ] ) ) { |
|
214 this.attrs = attrs; |
|
215 |
|
216 // Handle a flat object of attributes. |
|
217 } else { |
|
218 _.each( options.attrs, function( value, key ) { |
|
219 this.set( key, value ); |
|
220 }, this ); |
|
221 } |
|
222 }, wp.shortcode ); |
|
223 |
|
224 _.extend( wp.shortcode.prototype, { |
|
225 // ### Get a shortcode attribute |
|
226 // |
|
227 // Automatically detects whether `attr` is named or numeric and routes |
|
228 // it accordingly. |
|
229 get: function( attr ) { |
|
230 return this.attrs[ _.isNumber( attr ) ? 'numeric' : 'named' ][ attr ]; |
|
231 }, |
|
232 |
|
233 // ### Set a shortcode attribute |
|
234 // |
|
235 // Automatically detects whether `attr` is named or numeric and routes |
|
236 // it accordingly. |
|
237 set: function( attr, value ) { |
|
238 this.attrs[ _.isNumber( attr ) ? 'numeric' : 'named' ][ attr ] = value; |
|
239 return this; |
|
240 }, |
|
241 |
|
242 // ### Transform the shortcode match into a string |
|
243 string: function() { |
|
244 var text = '[' + this.tag; |
|
245 |
|
246 _.each( this.attrs.numeric, function( value ) { |
|
247 if ( /\s/.test( value ) ) |
|
248 text += ' "' + value + '"'; |
|
249 else |
|
250 text += ' ' + value; |
|
251 }); |
|
252 |
|
253 _.each( this.attrs.named, function( value, name ) { |
|
254 text += ' ' + name + '="' + value + '"'; |
|
255 }); |
|
256 |
|
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 ) |
|
260 return text + ']'; |
|
261 else if ( 'self-closing' === this.type ) |
|
262 return text + ' /]'; |
|
263 |
|
264 // Complete the opening tag. |
|
265 text += ']'; |
|
266 |
|
267 if ( this.content ) |
|
268 text += this.content; |
|
269 |
|
270 // Add the closing tag. |
|
271 return text + '[/' + this.tag + ']'; |
|
272 } |
|
273 }); |
|
274 }()); |
|
275 |
|
276 // HTML utility functions |
|
277 // ---------------------- |
|
278 // |
|
279 // Experimental. These functions may change or be removed in the future. |
|
280 (function(){ |
|
281 wp.html = _.extend( wp.html || {}, { |
|
282 // ### Parse HTML attributes. |
|
283 // |
|
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. |
|
289 // with no value). |
|
290 attrs: function( content ) { |
|
291 var result, attrs; |
|
292 |
|
293 // If `content` ends in a slash, strip it. |
|
294 if ( '/' === content[ content.length - 1 ] ) |
|
295 content = content.slice( 0, -1 ); |
|
296 |
|
297 result = wp.shortcode.attrs( content ); |
|
298 attrs = result.named; |
|
299 |
|
300 _.each( result.numeric, function( key ) { |
|
301 if ( /\s/.test( key ) ) |
|
302 return; |
|
303 |
|
304 attrs[ key ] = ''; |
|
305 }); |
|
306 |
|
307 return attrs; |
|
308 }, |
|
309 |
|
310 // ### Convert an HTML-representation of an object to a string. |
|
311 string: function( options ) { |
|
312 var text = '<' + options.tag, |
|
313 content = options.content || ''; |
|
314 |
|
315 _.each( options.attrs, function( value, attr ) { |
|
316 text += ' ' + attr; |
|
317 |
|
318 // Use empty attribute notation where possible. |
|
319 if ( '' === value ) |
|
320 return; |
|
321 |
|
322 // Convert boolean values to strings. |
|
323 if ( _.isBoolean( value ) ) |
|
324 value = value ? 'true' : 'false'; |
|
325 |
|
326 text += '="' + value + '"'; |
|
327 }); |
|
328 |
|
329 // Return the result if it is a self-closing tag. |
|
330 if ( options.single ) |
|
331 return text + ' />'; |
|
332 |
|
333 // Complete the opening tag. |
|
334 text += '>'; |
|
335 |
|
336 // If `content` is an object, recursively call this function. |
|
337 text += _.isObject( content ) ? wp.html.string( content ) : content; |
|
338 |
|
339 return text + '</' + options.tag + '>'; |
|
340 } |
|
341 }); |
|
342 }()); |