Requirements – Syntax
Easy and intuitive, labour saving
| Requirement | Priority |
|---|---|
| Allow positional ( unnamed ) parameters | H |
| Allow parameter values to contain HTML | M |
| Allow parameter values to contain shortcodes | M |
| Provide some method for escaping shortcodes | L |
| Allow shortcode expansion depending on context | H |
| Allow shortcodes in inner content | H |
| Allow mixed case parameters | M |
| Allow nested shortcodes (multiple enclosures?) | L |
- Some of these requirements are already satisfied by WordPress
- For others I already have an acceptable solution
- The Priority column reflects my personal requirements
- The Priority is lower in those cases where I already have a solution
- In other cases I don’t have the requirement
Requirements – Formatting
Content generated by shortcodes should be respected by other filters
- Allow user to control the filtering applied to their content
- Allow fine grained selection of filtering options
- Allow shortcodes to define what filtering can be applied
- Shortcode expansion may have to cater for multiple passes
- Provide pre and post content filtering to allow for content enhancement
- Allow shortcode expansion depending on filtering context
- Allow pre and post processing of shortcodes and their parameters
Requirements – Editor
Editors shouldn’t change my hand crafted content
- Switching between Text and Visual editors should never change the source content
- Cutting and pasting and dragging and dropping should not filter out text based content
- The Editor should be able to assist in the creation and editing of shortcodes
- Allow shortcodes to define their expected parameters
- Allow selective expansion of shortcodes in the Visual editor, depending on context
- Allow user control of selective expansion
Requirements – Non Functional
- Security
- Solution should clearly explain how security will be achieved
- Security
- Known security issues should be clearly communicated
- Security
- Perceived security issues should be openly discussed
- Scalability
- Solution should be scalable: support hundreds of registered shortcodes and thousands of uses
- Performance
- Solution should be highly performant in normal use: many shortcodes defined but few used
- User Experience
- No surprises – What You Get Is What You Wanted
- Errors
- Solution should cater for error situations
- Documentation
- Clearly defined conventions for shortcode names
Proposed solutions
- Revisit the parser
- Revisit the filter functions and the sequence in which they’re invoked
- Extend the shortcode API to allow shortcodes to better define their rules of engagement
- Syntax, help, examples, links to documentation
- Contextual behaviour in content, filter context
- Develop shortcodes that will implement requirements for mixing different markup styles in source
- Improve the visual editor
- Lots and lots of test cases, including complicated but sensible ones
Additional notes
- I didn’t have time to flesh out these requirements
- Some of them will need explaining
- Some are already covered in WordPress TRACs
- Solving some of the problems may require a little bit of lateral thinking
- In my opinion it should not be necessary to deprecate any of the existing logic
You can’t get what you want until you know what you want
Joe Jackson, 1984
Further reading
- Shortcode Roadmap Extended Discussion
- Testing compatibility with Shortcake v0.5.0
- APIs:
- Sample shortcodes: All used in this post: [bw_link], [bw_blockquote], [bw_csv], [apis]
