[wp-trac] [WordPress Trac] #19906: Quicktags docs recommend code causing JS error: Uncaught ReferenceError: QTags is not defined

[WordPress Trac]

#19906: Quicktags docs recommend code causing JS error: Uncaught ReferenceError:
QTags is not defined
--------------------------+------------------------------------------------
 Reporter:  jeremyclarke  |      Owner:
     Type:  enhancement   |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  Inline Docs   |    Version:  3.3.1
 Severity:  trivial       |   Keywords:  has-patch needs-codex dev-feedback
--------------------------+------------------------------------------------
 Right now the docs for qt.addbutton in quicktags.dev.js have the following
 text:

 {{{
          * If you are echoing JS directly from PHP,
          * use add_action( 'admin_print_footer_scripts', 'output_my_js',
 100 ) or add_action( 'wp_footer', 'output_my_js', 100 )
 }}}

 This works, but if you add the QTags.addButton() calls on those hooks then
 they will cause JS errors on any screen without an editor:

 {{{Uncaught ReferenceError: QTags is not defined}}}

 The issue is avoided if you use the other option, enqueuing a script
 dependent on 'quicktags', but that is a lot more work and forces all pages
 in the admin to load the quicktags script unnecessarily.

 Maybe there is some way to magically make calling QTags.addbutton() safe
 no matter what, but I think at minimum we need to add a note to the PHPdoc
 about checking QTags before using it, as that solves the problem pretty
 simply:

 {{{
  if ( typeof QTags != 'undefined' ) {
         QTags.addButton( 'gv_translation', 'translation', '<div
 class="translation">', '</div>' );
 }
 }}}

 So the phodoc could say :

 {{{
          * If you are echoing JS directly from PHP use
          *      add_action( 'admin_print_footer_scripts', 'output_my_js',
 100 )
          * or
          *      add_action( 'wp_footer', 'output_my_js', 100 )
          *
          * If echoing the addButton calls directly instead of enqueing
 with the 'quicktags' dependency
          * make sure to check that the QTags object is defined first,
 otherwise your code will throw errors
          * when no editor is present:
          *      if ( typeof QTags != 'undefined' ) { QTags.addButton(...)
 }
          *
 }}}

 The attached patch just adds that to the docs. If a committer has a
 preferred wording then just use that instead, obviously the patch didn't
 take me long :)

 BTW: I created a Codex article with the docblock after not finding a
 reference to the new API anywhere other than in the JS file itself.
 Nacin's posts mentioned that they had changed but not what was new ;)

 http://codex.wordpress.org/Quicktags_API

 Clearly it needs work, I didn't want to put too much time into it at first
 because I didn't understand the system yet (as I'm learning now, by
 finding JS errors).

-- 
Ticket URL: <http://core.trac.wordpress.org/ticket/19906>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software