Update QuickTags Documentation

[smileBeda]

Issue Description

This DOC's code example is outdated and suboptimal.
It should be updated to use a more modern approach.
I have already put a newer example on this page.

URL of the Page with the Issue

https://developer.wordpress.org/apis/handbook/quicktags/

Section of Page with the issue

https://developer.wordpress.org/apis/handbook/quicktags/#examples

Why is this a problem?

The first Problem is, the example shows to print a script instead of enqueueing it.
The second Problem is, it does not elaborate on the fact that any script trying to target those QuickTags has to be inside the call-back Function.
See my "More modern example" on the old codex.

Suggested Fix

Add this example along with the existing one (which is not wrong, it is just suboptimal and shouldn't be done like that if possible to avoid).

[atachibana]

@smileBeda, @audrasjb, and @tomjn from #357
I would like to modify current Quicktags page as followings. In that page, there were many errors besides the example program, which required major changes. Can I have your comments? If this is not a problem, I will edit the appropriate page.
Ref: https://core.trac.wordpress.org/browser/tags/5.2.1/src/js/_enqueues/lib/quicktags.js#L317

Key points (See below for the changed contents)

• Usage
  • add 'object' as last parameter
• Parameter
  • 'access_key' was deprecated.
  • 'object' was added so that we can pass the ariaLabel (instead of access_key?)
• Examples
  • Tradition Example
    • access_key = '', object = ariaLabel
    • Since 6.0, this example wont't work due to script loading order changes. Add 3rd parameter of add_action. Add some explanation of it
    • Update generated HTML
  • Modern Example 1
    • Insert @tomjn example from QTags handbook page has a broken code example #357
    • access_key = '', object = ariaLabel
  • Modern Example 2
    • Insert @smileBeda example
    • access_key = '', object = ariaLabel
• Default Quicktags
  • remove AccessKey column and sort by toolbar

Contens

(Please also refer https://developer.wordpress.org/apis/quicktags/. Belows are just differences)

Usage

QTags.addButton( id, display, arg1, arg2, access_key, title, priority, instance, object );

Parameters

...

• access_key: Deprecated and Not used (string) (optional): Shortcut access key for the button. Default: None
  ...
• object: (attr) (optional): Used to pass additional attributes. Currently supports ariaLabel and ariaLabelClose (for "close tag" state)

Examples

Below examples would add HTML buttons to the default Quicktags in the Text editor.

Traditional example

This example manually add hardcoded JavaScript with wp_script_is on the admin footer hook. You should consider to use modern example. See below.

// add more buttons to the html editor
function appthemes_add_quicktags() {
    if (wp_script_is('quicktags')){
?>
    <script type="text/javascript">
    QTags.addButton( 'eg_paragraph', 'p', '<p>', '</p>', '', 'Paragraph tag', 1, '', { ariaLabel: 'Paragraph', ariaLabelClose: 'Close Paragraph tag' } );
    QTags.addButton( 'eg_hr', 'hr', '<hr />', '', '', 'Horizontal rule line', 201, '', { ariaLabel: 'Horizontal' } );
    QTags.addButton( 'eg_pre', 'pre', '<pre lang="php">', '</pre>', '', 'Preformatted text tag', 111, '', { ariaLabel: 'Pre', ariaLabelClose: 'Close Pre tag' } );
    </script>
<?php
    }
}
add_action( 'admin_print_footer_scripts', 'appthemes_add_quicktags', 11 );

Note:

• To avoid a Reference Error we check to see whether or not the ‘quicktags’ script is in use.
• Since WordPress 6.0, the script loading order was changed and the error "QTags is not defined" occurs without 3rd parameter of add_action(). Also, you have to specfy the larger number than 10 (ex.11).

The “p” button HTML would be:

<input type="button" id="qt_content_eg_paragraph" class="ed_button button button-small" title="Paragraph tag" aria-label="Paragraph" value="p">

The ID value for each button is automatically prepended with the string qt_content_.

Modern example

This example uses the inline JS API to add the JavaScript when quicktags are enqueued.

function add_quicktag_paragraph() {
    wp_add_inline_script(
        'quicktags',
        "QTags.addButton( 'eg_paragraph_v2', 'p_v2', '<p>', '</p>', '', 'Paragraph tag v2', 2, '', { ariaLabel: 'Paragraph', ariaLabelClose: 'Close Paragraph tag' });"
	);
}
add_action( 'admin_enqueue_scripts', 'add_quicktag_paragraph' );

Another Modern example

In this example,

1. Enqueue a script using the proper WordPress function wp_enqueue_script.
2. Call any JavaScript that you want to fire when or after the QuickTag was clicked inside the QuickTag call-back.

Enqueue the script

Put below codes into active theme's functions.php.

function enqueue_quicktag_script(){
	wp_enqueue_script( 'your-handle', get_template_directory_uri() . '/editor-script.js', array( 'jquery', 'quicktags' ), '1.0.0', true );
}
add_action( 'admin_enqueue_scripts', 'enqueue_quicktag_script' );

The JavaScript itself

Create new file editor-script and save under the active theme directory.

QTags.addButton( 'eg_paragraph_v3', 'p_v3', my_callback, '', '', 'Prompted Paragraph tag', 3, '', { ariaLabel: 'Prompted Paragraph' } ); 

function my_callback(){
  var my_stuff = prompt( 'Enter Some Stuff:', '' );
  if ( my_stuff ) {
    QTags.insertContent( '<p>' + my_stuff + '</p>' );
  }
}

...

Default Quicktags

Here are the values of the default Quicktags added by WordPress to the Text editor. ID must be unique. When adding your own buttons, do not use these values:

(omitted. I will edit the table)

[tomjn]

@atachibana I would make one or two adjustments to the code examples

The Traditional example

This version has:

• use phpdocs for the fuction comment
• rename the function to not mention a theme
• use tabs for indentation and apply WP coding standards
• use an early exit check to avoid nesting everything
• fix the indentation of the script tag
• added a wporg_ function name prefix

/**
 * Add more buttons to the quicktags HTML editor
 *
 * @return void
 */
function wporg_traditional_add_quicktags() {
	if ( ! wp_script_is( 'quicktags' ) ) {
		return;
	}

	?>
	<script type="text/javascript">
		QTags.addButton( 'eg_paragraph', 'p', '<p>', '</p>', '', 'Paragraph tag', 1, '', { ariaLabel: 'Paragraph', ariaLabelClose: 'Close Paragraph tag' } );
		QTags.addButton( 'eg_hr', 'hr', '<hr />', '', '', 'Horizontal rule line', 201, '', { ariaLabel: 'Horizontal' } );
		QTags.addButton( 'eg_pre', 'pre', '<pre lang="php">', '</pre>', '', 'Preformatted text tag', 111, '', { ariaLabel: 'Pre', ariaLabelClose: 'Close Pre tag' } );
	</script>
	<?php
}

add_action( 'admin_print_footer_scripts', 'wporg_traditional_add_quicktags', 11 );

Modern Example

• fixed indentation
• added PHPDoc
• added a wporg_ function name prefix

/**
 * Add a paragraph tag button to the quicktags toolbar
 *
 * @return void
 */
function wporg_add_quicktag_paragraph() {
	wp_add_inline_script(
		'quicktags',
		"QTags.addButton( 'eg_paragraph_v2', 'p_v2', '<p>', '</p>', '', 'Paragraph tag v2', 2, '', { ariaLabel: 'Paragraph', ariaLabelClose: 'Close Paragraph tag' });"
	);
}
add_action( 'admin_enqueue_scripts', 'wporg_add_quicktag_paragraph' );

[tomjn]

@atachibana a final note, people are probably going to pick the example closest to the top and stick with that to save time reading through, so the modern example, aka the best example should be first. the traditional example if it's mentioned at all, should go further down the page.

I'd even argue that it should be removed as of the 3 options it provides no benefits over the alternatives, and has multiple caveats.

[atachibana]

@tomjn Thank you so much for detailed adjustments!

I would like to move Tradition Example to the end, not remove it, because the issue of Quicktags not working in WordPress 6.0 has caused so many problems

https://www.google.com/search?q=wordpress+6.0+quicktags+not+working&rlz=1C5GCEM_enJP1004JP1006&oq=wordpress+6.0+quicktags+not+working&aqs=chrome..69i57j0i546l3j35i39i362l6.6015j0j15&sourceid=chrome&ie=UTF-8

I'd like to keep some explanation about it. Of course if everyone uses the Modern Example, we won't have this loading priority-dependent problem.