wp_enqueue_code_editor()
Connects all necessary (scripts, styles, settings, languages) for using the built-in code editor in WordPress.
For editing code in the textarea field, the library CodeMirror is used, starting from WP version 4.9.
What does the function do?
The function enqueues the following basic WP scripts and styles:
wp_enqueue_script( 'code-editor' ); wp_enqueue_style( 'code-editor' );
Then, based on the specified or determined type of code that will be used in the textarea, it may enqueue additional lint/hint scripts needed by CodeMirror. For example, for the HTML type, these additions will auto-close tags, provide hints, etc.
wp_enqueue_script( 'htmlhint' ); wp_enqueue_script( 'csslint' ); wp_enqueue_script( 'jshint' );
Next, based on the parameters passed to the function, it collects parameters for CodeMirror and replaces/augments the default parameters: wp.codeEditor.defaultSettings.
Filter wp_code_editor_settings
Plugins can filter CodeMirror parameters before they are merged with the defaults through the filter wp_code_editor_settings.
If the filter returns false, the function will not enqueue any scripts.
Disabling syntax highlighting
If syntax highlighting is disabled in the current user's options (Users > Profile), the function will do nothing and terminate its operation at the very beginning:
Global variable wp.codeEditor
When the CodeMirror script is enqueued, a global variable is not registered in JS to avoid conflicts if some plugin uses its own version of this library. The instance of the CodeMirror object is located in the variable wp.codeEditor. That is, you can write like this: window.CodeMirror = wp.CodeMirror.
The method initialize() - wp.codeEditor.initialize( id, options ) - is analogous to CodeMirror.fromTextArea(). The first argument takes an id or the textarea element object, and the second takes options for CodeMirror. Such options are returned by this function, but in the form of a PHP array.
Also, in the options for the initialize() method, you can specify additional callback functions: onChangeLintingErrors, onUpdateErrorNotice, onTabPrevious, onTabNext. These callbacks allow you to manage the display of lint error blocks and keyboard navigation (for hints).
Hooks from the function
Returns
Array|false. An array of settings for CodeMirror in PHP format.
Usage
$settings = wp_enqueue_code_editor( $args );
- $args(array) (required)
Parameters.
-
type(string)
MIME type of the file to be edited. For example:text/html, indicates that HTML code will be written in the editing field. Possible types:type language text/html html xml xml application/javascript javascript json json application/x-httpd-php php text/x-sql sql text/css css text/x-scss scss text/x-less less text/x-sass sass text/nginx nginx text/x-markdown markdown text/x-gfm gfm jsx jsx text/x-diff diff -
file(string)
An alternative to the $type parameter. The name of the file, for example file.php. Used to determine the type ($type) by the file extension. -
codemirror(array)
Allows you to directly specify parameters for CodeMirror. Will overwrite the current ones. The array has the same structure as if we were passing CodeMirror parameters in JS. See documentation. -
csslint(array)
Allows you to directly specify parameters for CSSLint. Will overwrite the current ones. -
jshint(array)
Allows you to directly specify parameters for JSHint. Will overwrite the current ones. -
htmlhint(array)
Allows you to directly specify parameters for HTMLHint. Will overwrite the current ones. -
theme(WP_Theme)
The theme being edited. For the theme file editing page. - plugin(string)
The plugin being edited. For the plugin file editing page.
-
Examples
#1 Example of creating a code editor for textarea
To do this, let's turn the Biography field on the profile edit page into an HTML code editor.
To get a better idea of what the code does, let's look at the HTML code of the textarea, which will eventually become a code editor:
<textarea id="description" name="description" rows="5" cols="30"></textarea>
add_action( 'admin_enqueue_scripts', function() {
if ( 'profile' !== get_current_screen()->id ) {
return;
}
// connect the code editor for HTML.
$settings = wp_enqueue_code_editor( array( 'type' => 'text/html' ) );
// do nothing if CodeMirror is disabled.
if ( false === $settings ) {
return;
}
// initialization
wp_add_inline_script(
'code-editor',
sprintf( 'jQuery( function() { wp.codeEditor.initialize( "description", %s ); } );', wp_json_encode( $settings ) )
);
} );
The result is:
The variable $settings contains such an array:
JS function wp.codeEditor.initialize(textarea, settings)
Located in the file wp-admin/js/code-editor.js
Parameters:
- textarea(string|jQuery|Element) (required)
- The id attribute of the element as a string, a jQuery element, or a DOM element of the textarea field for which the editor will be used.
- settings(object) (required)
JS object of settings for codeMirror. This function returns it as a PHP array: wp_enqueue_code_editor().
What can be specified in the object:
- settings.onChangeLintingErrors(Function) - Callback when linting errors change.
- settings.onUpdateErrorNotice(Function) - Callback for when the error notice should be displayed.
- settings.onTabPrevious(Function) - Callback for handling TAB key to the previous element.
- settings.onTabNext(Function) - Callback for handling TAB key to the next element.
- settings.codemirror(object) - CodeMirror options.
- settings.csslint(object) - CSSLint rules.
- settings.htmlhint(object) - HTMLHint rules.
- settings.jshint(object) - JSHint rules.
Looks like this:
Notes
Changelog
| Since 4.9.0 | Introduced. |