[wp-trac] [WordPress Trac] #14481: Shortcode Enhancements

[WordPress Trac]

#14481: Shortcode Enhancements
-------------------------+--------------------------------------------------
 Reporter:  deadowl      |       Owner:                 
     Type:  enhancement  |      Status:  new            
 Priority:  normal       |   Milestone:  Awaiting Review
Component:  Shortcodes   |     Version:                 
 Severity:  normal       |    Keywords:                 
-------------------------+--------------------------------------------------
Description changed by nacin:

Old description:

> Somewhat of a copy of a post to wp-hackers: I wrote my own implementation
> of shortcodes. It does things a bit
> differently, has nested evaluation, and allows self-nesting. Since
> there are some significant differences to the existing implementation,
>
> A lot of the changes are borrowed
> from definitions in the HTML specification (particularly name and
> attribute matching). The following are the comments at the top of my
> shortcode file. I tried to keep track of all the differences (and
> questions) there.
>
> From Test Cases
> (http://svn.automattic.com/wordpress-tests/wp-
> testcase/test_shortcode.php)
> ==========================================================================================
> Shortcode Statuses (to implement, or not to implement?)
>         enabled = the shortcode works as normal (default)
>         strip = the shortcode will be parsed and removed.  e.g.
> '[shortcode foo="bar"]' produces ''.  '[shortcode]foo[/shortcode]'
> produces 'foo'.
>         faux = the shortcode will be abbreviated.  e.g. '[shortcode
> foo="bar"]' products '[shortcode]'.  '[shortocde]foo[/shortcode]'
> produces '[shortcode]'
>         disabled = the shortcode is not parsed at all.  e.g.
> '[shortcode foo="bar"]' products '[shortcode foo="bar"]'
>

> Major Differences/Improvements:
> ===============================
> I. Addressing http://codex.wordpress.org/Shortcode_API#Limitations
>
>        1. You can nest any tag at any depth regardless of ancestors
> (Ticket #10702)
>
>        2. Tag and attribute names may match
> /[A-Za-z][-A-Za-z0-9_:.]*//* (trialing /* because that comment ends),
>           with case-insensitive interpretation
>
>        3. Interpretation doesn't get tripped up by things like hyphens
>
> II. Addressing Ticket #12760,
>
>        1. Changed from fix in #6518
>           Reasoning: balancing double-square-brackets can have
> misleading results with nesting
>
>        2. Shortcodes escapable by using [[, ]]
>
>        3. ']]' is escaped "right to left", so '[shortcode]]]' would
> evaluate to 'result]'
>
>        4. '[[' is escaped left to right '[[[shortcode]]]' => '[result]'
>
> III. Enhancements
>
>        1. Only matches valid shortcode for registered hooks,
> everything else will appear as text
>
>        2. Can register multiple hooks to single shortcode, uses
> priority (default: 10)
>
> IV. Conflicting Design Changes
>
>        1. Quoted literals are escaped by entities rather than cslashes
>
>        2. Inline (self-closing) shortcodes get passed content to
> accomodate multiple callbacks
>
>        3. No equivalent to shortcode_parse_atts function
>           (Not marked private in function reference, but not
> documented in shortcode API page)
>
>        4. Boolean attributes take the place of positional attributes
>           [foo bar] gets attributes array('bar' => 'bar') instead of
> array('0' => 'bar')
>
>        5. Disallows attribute and tag names that don't match
> /[A-Za-z][-A-Za-z0-9_:.]*/
>
>        6. Disallows unquoted attribute values (also boolean
> attributes), unless they match /[-A-Za-z0-9_:.]+/
>

> Basic Interpretation Method:
> ============================
> 1. If an open tag is encountered, it is added to the stack
>
> 2. If a close tag is encountered and there is no matching open tag on the
> stack
>   the close tag is ignored
>
> 3. If a close tag is encountered and there is a matching open tag on the
> stack
>   all opened tags on the stack before the matched tag will be
> implicitly self-closed
>
> 4. If text or an inline tag is encountered, it will be evaluated to its
> parent's
>   content immediately
>
> 5. If tags are not closed by the end of the interpretation, they will
> be implicitly
>   self-closed
>

> Issues:
> =======
> 1. Haven't written new unit tests to reflect new functionality added,
> functionality differences
>
> 2. Documentation is not as good (though I hope most of the code is
> self-explanatory)
>
> 3. Not 100% backwards compatible

New description:

 Somewhat of a copy of a post to wp-hackers: I wrote my own implementation
 of shortcodes. It does things a bit differently, has nested evaluation,
 and allows self-nesting. Since there are some significant differences to
 the existing implementation,

 A lot of the changes are borrowed from definitions in the HTML
 specification (particularly name and attribute matching). The following
 are the comments at the top of my shortcode file. I tried to keep track of
 all the differences (and questions) there.

 == From Test Cases ==

 (http://svn.automattic.com/wordpress-tests/wp-testcase/test_shortcode.php)
 {{{
 Shortcode Statuses (to implement, or not to implement?)
         enabled = the shortcode works as normal (default)
         strip = the shortcode will be parsed and removed.  e.g.
 '[shortcode foo="bar"]' produces ''.  '[shortcode]foo[/shortcode]'
 produces 'foo'.
         faux = the shortcode will be abbreviated.  e.g. '[shortcode
 foo="bar"]' products '[shortcode]'.  '[shortocde]foo[/shortcode]'
 produces '[shortcode]'
         disabled = the shortcode is not parsed at all.  e.g.
 '[shortcode foo="bar"]' products '[shortcode foo="bar"]'
 }}}

 == Major Differences/Improvements ==

 I. Addressing http://codex.wordpress.org/Shortcode_API#Limitations

  1. You can nest any tag at any depth regardless of ancestors (#10702)

  2. Tag and attribute names may match: `/[A-Za-z][-A-Za-z0-9_:.]*//*`
 (trialing /* because that comment ends), with case-insensitive
 interpretation

  3. Interpretation doesn't get tripped up by things like hyphens

 == II. Addressing Ticket #12760, ==

  1. Changed from fix in #6518. Reasoning: balancing double-square-brackets
 can have misleading results with nesting

  2. Shortcodes escapable by using `[[`, `]]`

  3. `]]` is escaped "right to left", so `[shortcode]]]` would evaluate to
 `result]`

  4. '[[' is escaped left to right `[[[shortcode]]]` => `[result]`

 == III. Enhancements ==

  1. Only matches valid shortcode for registered hooks, everything else
 will appear as text

  2. Can register multiple hooks to single shortcode, uses priority
 (default: 10)

 == IV. Conflicting Design Changes ==

  1. Quoted literals are escaped by entities rather than cslashes

  2. Inline (self-closing) shortcodes get passed content to accomodate
 multiple callbacks

  3. No equivalent to shortcode_parse_atts function (Not marked private in
 function reference, but not documented in shortcode API page)

  4. Boolean attributes take the place of positional attributes `[foo bar]`
 gets attributes `array('bar' => 'bar')` instead of `array('0' => 'bar')`

  5. Disallows attribute and tag names that don't match
 `/[A-Za-z][-A-Za-z0-9_:.]*/`

  6. Disallows unquoted attribute values (also boolean attributes), unless
 they match `/[-A-Za-z0-9_:.]+/`

 == Basic Interpretation Method ==

  1. If an open tag is encountered, it is added to the stack

  2. If a close tag is encountered and there is no matching open tag on the
 stack the close tag is ignored

  3. If a close tag is encountered and there is a matching open tag on the
 stack all opened tags on the stack before the matched tag will be
 implicitly self-closed

  4. If text or an inline tag is encountered, it will be evaluated to its
 parent's content immediately

  5. If tags are not closed by the end of the interpretation, they will be
 implicitly self-closed

 == Issues ==

  1. Haven't written new unit tests to reflect new functionality added,
 functionality differences

  2. Documentation is not as good (though I hope most of the code is self-
 explanatory)

  3. Not 100% backwards compatible

--

-- 
Ticket URL: <http://core.trac.wordpress.org/ticket/14481#comment:1>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software