wp/wp-admin/js/editor.js
changeset 9 177826044cd9
parent 7 cf61fcea0001
child 16 a86126ab1dd4
equal deleted inserted replaced
8:c7c34916027a 9:177826044cd9
       
     1 /**
       
     2  * @output wp-admin/js/editor.js
       
     3  */
       
     4 
     1 window.wp = window.wp || {};
     5 window.wp = window.wp || {};
     2 
     6 
     3 ( function( $, wp ) {
     7 ( function( $, wp ) {
     4 	wp.editor = wp.editor || {};
     8 	wp.editor = wp.editor || {};
     5 
     9 
     6 	/**
    10 	/**
     7 	 * @summary Utility functions for the editor.
    11 	 * Utility functions for the editor.
     8 	 *
    12 	 *
     9 	 * @since 2.5.0
    13 	 * @since 2.5.0
    10 	 */
    14 	 */
    11 	function SwitchEditors() {
    15 	function SwitchEditors() {
    12 		var tinymce, $$,
    16 		var tinymce, $$,
    16 			if ( ! tinymce && window.tinymce ) {
    20 			if ( ! tinymce && window.tinymce ) {
    17 				tinymce = window.tinymce;
    21 				tinymce = window.tinymce;
    18 				$$ = tinymce.$;
    22 				$$ = tinymce.$;
    19 
    23 
    20 				/**
    24 				/**
    21 				 * @summary Handles onclick events for the Visual/Text tabs.
    25 				 * Handles onclick events for the Visual/Text tabs.
    22 				 *
    26 				 *
    23 				 * @since 4.3.0
    27 				 * @since 4.3.0
    24 				 *
    28 				 *
    25 				 * @returns {void}
    29 				 * @returns {void}
    26 				 */
    30 				 */
    36 				});
    40 				});
    37 			}
    41 			}
    38 		}
    42 		}
    39 
    43 
    40 		/**
    44 		/**
    41 		 * @summary Returns the height of the editor toolbar(s) in px.
    45 		 * Returns the height of the editor toolbar(s) in px.
    42 		 *
    46 		 *
    43 		 * @since 3.9.0
    47 		 * @since 3.9.0
    44 		 *
    48 		 *
    45 		 * @param {Object} editor The TinyMCE editor.
    49 		 * @param {Object} editor The TinyMCE editor.
    46 		 * @returns {number} If the height is between 10 and 200 return the height,
    50 		 * @returns {number} If the height is between 10 and 200 return the height,
    56 
    60 
    57 			return 30;
    61 			return 30;
    58 		}
    62 		}
    59 
    63 
    60 		/**
    64 		/**
    61 		 * @summary Switches the editor between Visual and Text mode.
    65 		 * Switches the editor between Visual and Text mode.
    62 		 *
    66 		 *
    63 		 * @since 2.5.0
    67 		 * @since 2.5.0
    64 		 *
    68 		 *
    65 		 * @memberof switchEditors
    69 		 * @memberof switchEditors
    66 		 *
    70 		 *
   182 				window.setUserSetting( 'editor', 'html' );
   186 				window.setUserSetting( 'editor', 'html' );
   183 			}
   187 			}
   184 		}
   188 		}
   185 
   189 
   186 		/**
   190 		/**
   187 		 * @summary Checks if a cursor is inside an HTML tag.
   191 		 * Checks if a cursor is inside an HTML tag or comment.
   188 		 *
   192 		 *
   189 		 * In order to prevent breaking HTML tags when selecting text, the cursor
   193 		 * In order to prevent breaking HTML tags when selecting text, the cursor
   190 		 * must be moved to either the start or end of the tag.
   194 		 * must be moved to either the start or end of the tag.
   191 		 *
   195 		 *
   192 		 * This will prevent the selection marker to be inserted in the middle of an HTML tag.
   196 		 * This will prevent the selection marker to be inserted in the middle of an HTML tag.
   205 				lastGtPos = content.lastIndexOf( '>', cursorPosition );
   209 				lastGtPos = content.lastIndexOf( '>', cursorPosition );
   206 
   210 
   207 			if ( lastLtPos > lastGtPos || content.substr( cursorPosition, 1 ) === '>' ) {
   211 			if ( lastLtPos > lastGtPos || content.substr( cursorPosition, 1 ) === '>' ) {
   208 				// find what the tag is
   212 				// find what the tag is
   209 				var tagContent = content.substr( lastLtPos ),
   213 				var tagContent = content.substr( lastLtPos ),
   210 					tagMatch = tagContent.match( /<\s*(\/)?(\w+)/ );
   214 					tagMatch = tagContent.match( /<\s*(\/)?(\w+|\!-{2}.*-{2})/ );
   211 
   215 
   212 				if ( ! tagMatch ) {
   216 				if ( ! tagMatch ) {
   213 					return null;
   217 					return null;
   214 				}
   218 				}
   215 
   219 
   225 			}
   229 			}
   226 			return null;
   230 			return null;
   227 		}
   231 		}
   228 
   232 
   229 		/**
   233 		/**
   230 		 * @summary Check if the cursor is inside a shortcode
   234 		 * Checks if the cursor is inside a shortcode
   231 		 *
   235 		 *
   232 		 * If the cursor is inside a shortcode wrapping tag, e.g. `[caption]` it's better to
   236 		 * If the cursor is inside a shortcode wrapping tag, e.g. `[caption]` it's better to
   233 		 * move the selection marker to before or after the shortcode.
   237 		 * move the selection marker to before or after the shortcode.
   234 		 *
   238 		 *
   235 		 * For example `[caption]` rewrites/removes anything that's between the `[caption]` tag and the
   239 		 * For example `[caption]` rewrites/removes anything that's between the `[caption]` tag and the
   279 
   283 
   280 			return result;
   284 			return result;
   281 		}
   285 		}
   282 
   286 
   283 		/**
   287 		/**
   284 		 * @summary Get all shortcodes and their positions in the content
   288 		 * Gets all shortcodes and their positions in the content
   285 		 *
   289 		 *
   286 		 * This function returns all the shortcodes that could be found in the textarea content
   290 		 * This function returns all the shortcodes that could be found in the textarea content
   287 		 * along with their character positions and boundaries.
   291 		 * along with their character positions and boundaries.
   288 		 *
   292 		 *
   289 		 * This is used to check if the selection cursor is inside the boundaries of a shortcode
   293 		 * This is used to check if the selection cursor is inside the boundaries of a shortcode
   376 					} )
   380 					} )
   377 					.html( content ? content : '' );
   381 					.html( content ? content : '' );
   378 		}
   382 		}
   379 
   383 
   380 		/**
   384 		/**
   381 		 * @summary Get adjusted selection cursor positions according to HTML tags/shortcodes
   385 		 * Gets adjusted selection cursor positions according to HTML tags, comments, and shortcodes.
   382 		 *
   386 		 *
   383 		 * Shortcodes and HTML codes are a bit of a special case when selecting, since they may render
   387 		 * Shortcodes and HTML codes are a bit of a special case when selecting, since they may render
   384 		 * content in Visual mode. If we insert selection markers somewhere inside them, it's really possible
   388 		 * content in Visual mode. If we insert selection markers somewhere inside them, it's really possible
   385 		 * to break the syntax and render the HTML tag or shortcode broken.
   389 		 * to break the syntax and render the HTML tag or shortcode broken.
   386 		 *
   390 		 *
   459 				cursorEnd: cursorEnd
   463 				cursorEnd: cursorEnd
   460 			};
   464 			};
   461 		}
   465 		}
   462 
   466 
   463 		/**
   467 		/**
   464 		 * @summary Adds text selection markers in the editor textarea.
   468 		 * Adds text selection markers in the editor textarea.
   465 		 *
   469 		 *
   466 		 * Adds selection markers in the content of the editor `textarea`.
   470 		 * Adds selection markers in the content of the editor `textarea`.
   467 		 * The method directly manipulates the `textarea` content, to allow TinyMCE plugins
   471 		 * The method directly manipulates the `textarea` content, to allow TinyMCE plugins
   468 		 * to run after the markers are added.
   472 		 * to run after the markers are added.
   469 		 *
   473 		 *
   509 				textArea.value.slice( htmlModeCursorEndPosition )		// text from last cursor/selection position to end
   513 				textArea.value.slice( htmlModeCursorEndPosition )		// text from last cursor/selection position to end
   510 			].join( '' );
   514 			].join( '' );
   511 		}
   515 		}
   512 
   516 
   513 		/**
   517 		/**
   514 		 * @summary Focus the selection markers in Visual mode.
   518 		 * Focuses the selection markers in Visual mode.
   515 		 *
   519 		 *
   516 		 * The method checks for existing selection markers inside the editor DOM (Visual mode)
   520 		 * The method checks for existing selection markers inside the editor DOM (Visual mode)
   517 		 * and create a selection between the two nodes using the DOM `createRange` selection API
   521 		 * and create a selection between the two nodes using the DOM `createRange` selection API
   518 		 *
   522 		 *
   519 		 * If there is only a single node, select only the single node through TinyMCE's selection API
   523 		 * If there is only a single node, select only the single node through TinyMCE's selection API
   548 
   552 
   549 			editor.save();
   553 			editor.save();
   550 		}
   554 		}
   551 
   555 
   552 		/**
   556 		/**
   553 		 * @summary Remove selection marker and the parent node if it is an empty paragraph.
   557 		 * Removes selection marker and the parent node if it is an empty paragraph.
   554 		 *
   558 		 *
   555 		 * By default TinyMCE wraps loose inline tags in a `<p>`.
   559 		 * By default TinyMCE wraps loose inline tags in a `<p>`.
   556 		 * When removing selection markers an empty `<p>` may be left behind, remove it.
   560 		 * When removing selection markers an empty `<p>` may be left behind, remove it.
   557 		 *
   561 		 *
   558 		 * @param {object} $marker The marker to be removed from the editor DOM, wrapped in an instnce of `editor.$`
   562 		 * @param {object} $marker The marker to be removed from the editor DOM, wrapped in an instnce of `editor.$`
   567 				$markerParent.remove();
   571 				$markerParent.remove();
   568 			}
   572 			}
   569 		}
   573 		}
   570 
   574 
   571 		/**
   575 		/**
   572 		 * @summary Scrolls the content to place the selected element in the center of the screen.
   576 		 * Scrolls the content to place the selected element in the center of the screen.
   573 		 *
   577 		 *
   574 		 * Takes an element, that is usually the selection start element, selected in
   578 		 * Takes an element, that is usually the selection start element, selected in
   575 		 * `focusHTMLBookmarkInVisualEditor()` and scrolls the screen so the element appears roughly
   579 		 * `focusHTMLBookmarkInVisualEditor()` and scrolls the screen so the element appears roughly
   576 		 * in the middle of the screen.
   580 		 * in the middle of the screen.
   577 		 *
   581 		 *
   642 			// Keep empty paragraphs :(
   646 			// Keep empty paragraphs :(
   643 			event.content = event.content.replace( /<p>(?:<br ?\/?>|\u00a0|\uFEFF| )*<\/p>/g, '<p>&nbsp;</p>' );
   647 			event.content = event.content.replace( /<p>(?:<br ?\/?>|\u00a0|\uFEFF| )*<\/p>/g, '<p>&nbsp;</p>' );
   644 		}
   648 		}
   645 
   649 
   646 		/**
   650 		/**
   647 		 * @summary Finds the current selection position in the Visual editor.
   651 		 * Finds the current selection position in the Visual editor.
   648 		 *
   652 		 *
   649 		 * Find the current selection in the Visual editor by inserting marker elements at the start
   653 		 * Find the current selection in the Visual editor by inserting marker elements at the start
   650 		 * and end of the selection.
   654 		 * and end of the selection.
   651 		 *
   655 		 *
   652 		 * Uses the standard DOM selection API to achieve that goal.
   656 		 * Uses the standard DOM selection API to achieve that goal.
   809 				end: endIndex
   813 				end: endIndex
   810 			};
   814 			};
   811 		}
   815 		}
   812 
   816 
   813 		/**
   817 		/**
   814 		 * @summary Selects text in the TinyMCE `textarea`.
   818 		 * Selects text in the TinyMCE `textarea`.
   815 		 *
   819 		 *
   816 		 * Selects the text in TinyMCE's textarea that's between `selection.start` and `selection.end`.
   820 		 * Selects the text in TinyMCE's textarea that's between `selection.start` and `selection.end`.
   817 		 *
   821 		 *
   818 		 * For `selection` parameter:
   822 		 * For `selection` parameter:
   819 		 * @link findBookmarkedPosition
   823 		 * @link findBookmarkedPosition
   850 				focusHTMLBookmarkInVisualEditor( editor );
   854 				focusHTMLBookmarkInVisualEditor( editor );
   851 			}
   855 			}
   852 		} );
   856 		} );
   853 
   857 
   854 		/**
   858 		/**
   855 		 * @summary Replaces <p> tags with two line breaks. "Opposite" of wpautop().
   859 		 * Replaces <p> tags with two line breaks. "Opposite" of wpautop().
   856 		 *
   860 		 *
   857 		 * Replaces <p> tags with two line breaks except where the <p> has attributes.
   861 		 * Replaces <p> tags with two line breaks except where the <p> has attributes.
   858 		 * Unifies whitespace.
   862 		 * Unifies whitespace.
   859 		 * Indents <li>, <dt> and <dd> for better readability.
   863 		 * Indents <li>, <dt> and <dd> for better readability.
   860 		 *
   864 		 *
   989 
   993 
   990 			return html;
   994 			return html;
   991 		}
   995 		}
   992 
   996 
   993 		/**
   997 		/**
   994 		 * @summary Replaces two line breaks with a paragraph tag and one line break with a <br>.
   998 		 * Replaces two line breaks with a paragraph tag and one line break with a <br>.
   995 		 *
   999 		 *
   996 		 * Similar to `wpautop()` in formatting.php.
  1000 		 * Similar to `wpautop()` in formatting.php.
   997 		 *
  1001 		 *
   998 		 * @since 2.5.0
  1002 		 * @since 2.5.0
   999 		 *
  1003 		 *
  1118 
  1122 
  1119 			return text;
  1123 			return text;
  1120 		}
  1124 		}
  1121 
  1125 
  1122 		/**
  1126 		/**
  1123 		 * @summary Fires custom jQuery events `beforePreWpautop` and `afterPreWpautop` when jQuery is available.
  1127 		 * Fires custom jQuery events `beforePreWpautop` and `afterPreWpautop` when jQuery is available.
  1124 		 *
  1128 		 *
  1125 		 * @since 2.9.0
  1129 		 * @since 2.9.0
  1126 		 *
  1130 		 *
  1127 		 * @memberof switchEditors
  1131 		 * @memberof switchEditors
  1128 		 *
  1132 		 *
  1144 
  1148 
  1145 			return obj.data;
  1149 			return obj.data;
  1146 		}
  1150 		}
  1147 
  1151 
  1148 		/**
  1152 		/**
  1149 		 * @summary Fires custom jQuery events `beforeWpautop` and `afterWpautop` when jQuery is available.
  1153 		 * Fires custom jQuery events `beforeWpautop` and `afterWpautop` when jQuery is available.
  1150 		 *
  1154 		 *
  1151 		 * @since 2.9.0
  1155 		 * @since 2.9.0
  1152 		 *
  1156 		 *
  1153 		 * @memberof switchEditors
  1157 		 * @memberof switchEditors
  1154 		 *
  1158 		 *
  1198 
  1202 
  1199 		return exports;
  1203 		return exports;
  1200 	}
  1204 	}
  1201 
  1205 
  1202 	/**
  1206 	/**
  1203 	 * @namespace {SwitchEditors} switchEditors
       
  1204 	 * Expose the switch editors to be used globally.
  1207 	 * Expose the switch editors to be used globally.
       
  1208 	 *
       
  1209 	 * @namespace switchEditors
  1205 	 */
  1210 	 */
  1206 	window.switchEditors = new SwitchEditors();
  1211 	window.switchEditors = new SwitchEditors();
  1207 
  1212 
  1208 	/**
  1213 	/**
  1209 	 * Initialize TinyMCE and/or Quicktags. For use with wp_enqueue_editor() (PHP).
  1214 	 * Initialize TinyMCE and/or Quicktags. For use with wp_enqueue_editor() (PHP).