8
0
Просмотр исходного кода

Docs: Reviewed and improved documentation of the bindings.

Aleksander Nowodzinski 8 лет назад
Родитель
Сommit
e8c8969554

+ 10 - 7
packages/ckeditor5-ui/src/bindings/clickoutsidehandler.js

@@ -10,16 +10,19 @@
 /* global document */
 /* global document */
 
 
 /**
 /**
- * Handles a DOM `click` event outside of specified elements and fires an action.
+ * Handles clicking **outside** of a specified set of elements, then fires an action.
  *
  *
- * Note that it is not handled by a `click` event, this is to avoid situation when click on some trigger
- * opens and closes element at the same time.
+ * **Note**: Actually, the action is executed upon `mousedown`, not `click`. It prevents
+ * certain issues when the user keeps holding the mouse button and the UI cannot react
+ * properly.
  *
  *
  * @param {Object} options Configuration options.
  * @param {Object} options Configuration options.
- * @param {module:utils/dom/emittermixin~Emitter} options.emitter The emitter to which this behavior should be added.
- * @param {Function} options.activator Function returning a `Boolean`, to determine whether handler is active.
- * @param {Array.<HTMLElement>} options.contextElements `HTMLElement`s that clicking inside of any of them will not fire the callback.
- * @param {Function} options.callback Function fired after clicking outside of specified elements.
+ * @param {module:utils/dom/emittermixin~Emitter} options.emitter The emitter to which this behavior
+ * should be added.
+ * @param {Function} options.activator Function returning a `Boolean`, to determine whether the handler is active.
+ * @param {Array.<HTMLElement>} options.contextElements HTML elements that determine the scope of the
+ * handler. Clicking any of them or their descendants will **not** fire the callback.
+ * @param {Function} options.callback An action executed by the handler.
  */
  */
 export default function clickOutsideHandler( { emitter, activator, callback, contextElements } ) {
 export default function clickOutsideHandler( { emitter, activator, callback, contextElements } ) {
 	emitter.listenTo( document, 'mousedown', ( evt, { target } ) => {
 	emitter.listenTo( document, 'mousedown', ( evt, { target } ) => {

+ 18 - 3
packages/ckeditor5-ui/src/bindings/preventdefault.js

@@ -8,10 +8,25 @@
  */
  */
 
 
 /**
 /**
- * Returns a {module:ui/template~TemplateToBinding} resulting in a native `event#preventDefault`
- * for the DOM event if `event#target` equals {@link module:ui/view~View#element}.
+ * A helper which executes a native `Event.preventDefault()` if the target of an event equals the
+ * {@link module:ui/view~View#element element of the view}. It shortens the definition of a
+ * {@link module:ui/view~View#template template}.
  *
  *
- * @param {module:ui/view~View} view View instance that uses the template.
+ *		// In a class extending View.
+ *		import preventDefault from '@ckeditor/ckeditor5-ui/src/bindings/preventdefault';
+ *
+ *		// ...
+ *
+ *		this.template = new Template( {
+ *			tag: 'div',
+ *
+ *			on: {
+ *				// Prevent the default mousedown action on this view.
+ *				mousedown: preventDefault( this )
+ *			}
+ *		} );
+ *
+ * @param {module:ui/view~View} view View instance that defines the template.
  * @returns {module:ui/template~TemplateToBinding}
  * @returns {module:ui/template~TemplateToBinding}
  */
  */
 export default function preventDefault( view ) {
 export default function preventDefault( view ) {

+ 31 - 4
packages/ckeditor5-ui/src/bindings/submithandler.js

@@ -8,12 +8,39 @@
  */
  */
 
 
 /**
 /**
- * Handles native DOM `submit` event by preventing it and firing
- * the {@link module:ui/view~View view's} `submit` event, which can be then handled by the
- * parent controller.
+ * A handler useful for {@link module:ui/view~View views} working as HTML forms. It intercepts a native DOM
+ * `submit` event, prevents the default web browser behavior (navigation and page reload) and
+ * fires the `submit` event on a view instead. Such a custom event can be then used by any
+ * {@link module:utils/dom/emittermixin~Emitter emitter}, e.g. to serialize the form data.
+ *
+ *		import submitHandler from '@ckeditor/ckeditor5-ui/src/bindings/submithandler';
+ *
+ *		// ...
+ *
+ *		class AnyFormView extends View {
+ *			constructor() {
+ *				super();
+ *
+ *				// ...
+ *
+ *				submitHandler( {
+ *					view: this
+ *				} );
+ *			}
+ *		}
+ *
+ *		// ...
+ *
+ *		const view = new AnyFormView();
+ *
+ *		// A sample listener attached by an emitter working with the view.
+ *		this.listenTo( view, 'submit', () => {
+ *			saveTheFormData();
+ *			hideTheForm();
+ *		} );
  *
  *
  * @param {Object} [options] Configuration options.
  * @param {Object} [options] Configuration options.
- * @param {module:ui/view~View} options.view The view to which this behavior should be added.
+ * @param {module:ui/view~View} options.view The view which DOM `submit` events should be handled.
  */
  */
 export default function submitHandler( { view } ) {
 export default function submitHandler( { view } ) {
 	view.listenTo( view.element, 'submit', ( evt, domEvt ) => {
 	view.listenTo( view.element, 'submit', ( evt, domEvt ) => {