Chris@0: /**
Chris@0:  * @file
Chris@0:  * Form features.
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * Triggers when a value in the form changed.
Chris@0:  *
Chris@0:  * The event triggers when content is typed or pasted in a text field, before
Chris@0:  * the change event triggers.
Chris@0:  *
Chris@0:  * @event formUpdated
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * Triggers when a click on a page fragment link or hash change is detected.
Chris@0:  *
Chris@0:  * The event triggers when the fragment in the URL changes (a hash change) and
Chris@0:  * when a link containing a fragment identifier is clicked. In case the hash
Chris@0:  * changes due to a click this event will only be triggered once.
Chris@0:  *
Chris@0:  * @event formFragmentLinkClickOrHashChange
Chris@0:  */
Chris@0: 
Chris@17: (function($, Drupal, debounce) {
Chris@0:   /**
Chris@0:    * Retrieves the summary for the first element.
Chris@0:    *
Chris@0:    * @return {string}
Chris@0:    *   The text of the summary.
Chris@0:    */
Chris@17:   $.fn.drupalGetSummary = function() {
Chris@0:     const callback = this.data('summaryCallback');
Chris@17:     return this[0] && callback ? $.trim(callback(this[0])) : '';
Chris@0:   };
Chris@0: 
Chris@0:   /**
Chris@0:    * Sets the summary for all matched elements.
Chris@0:    *
Chris@0:    * @param {function} callback
Chris@0:    *   Either a function that will be called each time the summary is
Chris@0:    *   retrieved or a string (which is returned each time).
Chris@0:    *
Chris@0:    * @return {jQuery}
Chris@0:    *   jQuery collection of the current element.
Chris@0:    *
Chris@0:    * @fires event:summaryUpdated
Chris@0:    *
Chris@0:    * @listens event:formUpdated
Chris@0:    */
Chris@17:   $.fn.drupalSetSummary = function(callback) {
Chris@0:     const self = this;
Chris@0: 
Chris@0:     // To facilitate things, the callback should always be a function. If it's
Chris@0:     // not, we wrap it into an anonymous function which just returns the value.
Chris@0:     if (typeof callback !== 'function') {
Chris@0:       const val = callback;
Chris@17:       callback = function() {
Chris@0:         return val;
Chris@0:       };
Chris@0:     }
Chris@0: 
Chris@17:     return (
Chris@17:       this.data('summaryCallback', callback)
Chris@17:         // To prevent duplicate events, the handlers are first removed and then
Chris@17:         // (re-)added.
Chris@17:         .off('formUpdated.summary')
Chris@17:         .on('formUpdated.summary', () => {
Chris@17:           self.trigger('summaryUpdated');
Chris@17:         })
Chris@17:         // The actual summaryUpdated handler doesn't fire when the callback is
Chris@17:         // changed, so we have to do this manually.
Chris@17:         .trigger('summaryUpdated')
Chris@17:     );
Chris@0:   };
Chris@0: 
Chris@0:   /**
Chris@0:    * Prevents consecutive form submissions of identical form values.
Chris@0:    *
Chris@0:    * Repetitive form submissions that would submit the identical form values
Chris@0:    * are prevented, unless the form values are different to the previously
Chris@0:    * submitted values.
Chris@0:    *
Chris@0:    * This is a simplified re-implementation of a user-agent behavior that
Chris@0:    * should be natively supported by major web browsers, but at this time, only
Chris@0:    * Firefox has a built-in protection.
Chris@0:    *
Chris@0:    * A form value-based approach ensures that the constraint is triggered for
Chris@0:    * consecutive, identical form submissions only. Compared to that, a form
Chris@0:    * button-based approach would (1) rely on [visible] buttons to exist where
Chris@0:    * technically not required and (2) require more complex state management if
Chris@0:    * there are multiple buttons in a form.
Chris@0:    *
Chris@0:    * This implementation is based on form-level submit events only and relies
Chris@0:    * on jQuery's serialize() method to determine submitted form values. As such,
Chris@0:    * the following limitations exist:
Chris@0:    *
Chris@0:    * - Event handlers on form buttons that preventDefault() do not receive a
Chris@0:    *   double-submit protection. That is deemed to be fine, since such button
Chris@0:    *   events typically trigger reversible client-side or server-side
Chris@0:    *   operations that are local to the context of a form only.
Chris@0:    * - Changed values in advanced form controls, such as file inputs, are not
Chris@0:    *   part of the form values being compared between consecutive form submits
Chris@0:    *   (due to limitations of jQuery.serialize()). That is deemed to be
Chris@0:    *   acceptable, because if the user forgot to attach a file, then the size of
Chris@0:    *   HTTP payload will most likely be small enough to be fully passed to the
Chris@0:    *   server endpoint within (milli)seconds. If a user mistakenly attached a
Chris@0:    *   wrong file and is technically versed enough to cancel the form submission
Chris@0:    *   (and HTTP payload) in order to attach a different file, then that
Chris@0:    *   edge-case is not supported here.
Chris@0:    *
Chris@0:    * Lastly, all forms submitted via HTTP GET are idempotent by definition of
Chris@0:    * HTTP standards, so excluded in this implementation.
Chris@0:    *
Chris@0:    * @type {Drupal~behavior}
Chris@0:    */
Chris@0:   Drupal.behaviors.formSingleSubmit = {
Chris@0:     attach() {
Chris@0:       function onFormSubmit(e) {
Chris@0:         const $form = $(e.currentTarget);
Chris@0:         const formValues = $form.serialize();
Chris@0:         const previousValues = $form.attr('data-drupal-form-submit-last');
Chris@0:         if (previousValues === formValues) {
Chris@0:           e.preventDefault();
Chris@17:         } else {
Chris@0:           $form.attr('data-drupal-form-submit-last', formValues);
Chris@0:         }
Chris@0:       }
Chris@0: 
Chris@17:       $('body')
Chris@17:         .once('form-single-submit')
Chris@0:         .on('submit.singleSubmit', 'form:not([method~="GET"])', onFormSubmit);
Chris@0:     },
Chris@0:   };
Chris@0: 
Chris@0:   /**
Chris@0:    * Sends a 'formUpdated' event each time a form element is modified.
Chris@0:    *
Chris@0:    * @param {HTMLElement} element
Chris@0:    *   The element to trigger a form updated event on.
Chris@0:    *
Chris@0:    * @fires event:formUpdated
Chris@0:    */
Chris@0:   function triggerFormUpdated(element) {
Chris@0:     $(element).trigger('formUpdated');
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Collects the IDs of all form fields in the given form.
Chris@0:    *
Chris@0:    * @param {HTMLFormElement} form
Chris@0:    *   The form element to search.
Chris@0:    *
Chris@0:    * @return {Array}
Chris@0:    *   Array of IDs for form fields.
Chris@0:    */
Chris@0:   function fieldsList(form) {
Chris@17:     const $fieldList = $(form)
Chris@17:       .find('[name]')
Chris@17:       .map(
Chris@17:         // We use id to avoid name duplicates on radio fields and filter out
Chris@17:         // elements with a name but no id.
Chris@17:         (index, element) => element.getAttribute('id'),
Chris@17:       );
Chris@0:     // Return a true array.
Chris@0:     return $.makeArray($fieldList);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Triggers the 'formUpdated' event on form elements when they are modified.
Chris@0:    *
Chris@0:    * @type {Drupal~behavior}
Chris@0:    *
Chris@0:    * @prop {Drupal~behaviorAttach} attach
Chris@0:    *   Attaches formUpdated behaviors.
Chris@0:    * @prop {Drupal~behaviorDetach} detach
Chris@0:    *   Detaches formUpdated behaviors.
Chris@0:    *
Chris@0:    * @fires event:formUpdated
Chris@0:    */
Chris@0:   Drupal.behaviors.formUpdated = {
Chris@0:     attach(context) {
Chris@0:       const $context = $(context);
Chris@0:       const contextIsForm = $context.is('form');
Chris@17:       const $forms = (contextIsForm ? $context : $context.find('form')).once(
Chris@17:         'form-updated',
Chris@17:       );
Chris@0:       let formFields;
Chris@0: 
Chris@0:       if ($forms.length) {
Chris@0:         // Initialize form behaviors, use $.makeArray to be able to use native
Chris@0:         // forEach array method and have the callback parameters in the right
Chris@0:         // order.
Chris@17:         $.makeArray($forms).forEach(form => {
Chris@0:           const events = 'change.formUpdated input.formUpdated ';
Chris@17:           const eventHandler = debounce(event => {
Chris@0:             triggerFormUpdated(event.target);
Chris@0:           }, 300);
Chris@0:           formFields = fieldsList(form).join(',');
Chris@0: 
Chris@0:           form.setAttribute('data-drupal-form-fields', formFields);
Chris@0:           $(form).on(events, eventHandler);
Chris@0:         });
Chris@0:       }
Chris@0:       // On ajax requests context is the form element.
Chris@0:       if (contextIsForm) {
Chris@0:         formFields = fieldsList(context).join(',');
Chris@0:         // @todo replace with form.getAttribute() when #1979468 is in.
Chris@0:         const currentFields = $(context).attr('data-drupal-form-fields');
Chris@0:         // If there has been a change in the fields or their order, trigger
Chris@0:         // formUpdated.
Chris@0:         if (formFields !== currentFields) {
Chris@0:           triggerFormUpdated(context);
Chris@0:         }
Chris@0:       }
Chris@0:     },
Chris@0:     detach(context, settings, trigger) {
Chris@0:       const $context = $(context);
Chris@0:       const contextIsForm = $context.is('form');
Chris@0:       if (trigger === 'unload') {
Chris@17:         const $forms = (contextIsForm
Chris@17:           ? $context
Chris@17:           : $context.find('form')
Chris@17:         ).removeOnce('form-updated');
Chris@0:         if ($forms.length) {
Chris@17:           $.makeArray($forms).forEach(form => {
Chris@0:             form.removeAttribute('data-drupal-form-fields');
Chris@0:             $(form).off('.formUpdated');
Chris@0:           });
Chris@0:         }
Chris@0:       }
Chris@0:     },
Chris@0:   };
Chris@0: 
Chris@0:   /**
Chris@0:    * Prepopulate form fields with information from the visitor browser.
Chris@0:    *
Chris@0:    * @type {Drupal~behavior}
Chris@0:    *
Chris@0:    * @prop {Drupal~behaviorAttach} attach
Chris@0:    *   Attaches the behavior for filling user info from browser.
Chris@0:    */
Chris@0:   Drupal.behaviors.fillUserInfoFromBrowser = {
Chris@0:     attach(context, settings) {
Chris@0:       const userInfo = ['name', 'mail', 'homepage'];
Chris@17:       const $forms = $('[data-user-info-from-browser]').once(
Chris@17:         'user-info-from-browser',
Chris@17:       );
Chris@0:       if ($forms.length) {
Chris@17:         userInfo.forEach(info => {
Chris@0:           const $element = $forms.find(`[name=${info}]`);
Chris@0:           const browserData = localStorage.getItem(`Drupal.visitor.${info}`);
Chris@17:           const emptyOrDefault =
Chris@17:             $element.val() === '' ||
Chris@17:             $element.attr('data-drupal-default-value') === $element.val();
Chris@0:           if ($element.length && emptyOrDefault && browserData) {
Chris@0:             $element.val(browserData);
Chris@0:           }
Chris@0:         });
Chris@0:       }
Chris@0:       $forms.on('submit', () => {
Chris@17:         userInfo.forEach(info => {
Chris@0:           const $element = $forms.find(`[name=${info}]`);
Chris@0:           if ($element.length) {
Chris@0:             localStorage.setItem(`Drupal.visitor.${info}`, $element.val());
Chris@0:           }
Chris@0:         });
Chris@0:       });
Chris@0:     },
Chris@0:   };
Chris@0: 
Chris@0:   /**
Chris@0:    * Sends a fragment interaction event on a hash change or fragment link click.
Chris@0:    *
Chris@0:    * @param {jQuery.Event} e
Chris@0:    *   The event triggered.
Chris@0:    *
Chris@0:    * @fires event:formFragmentLinkClickOrHashChange
Chris@0:    */
Chris@17:   const handleFragmentLinkClickOrHashChange = e => {
Chris@0:     let url;
Chris@0:     if (e.type === 'click') {
Chris@17:       url = e.currentTarget.location
Chris@17:         ? e.currentTarget.location
Chris@17:         : e.currentTarget;
Chris@17:     } else {
Chris@17:       url = window.location;
Chris@0:     }
Chris@0:     const hash = url.hash.substr(1);
Chris@0:     if (hash) {
Chris@0:       const $target = $(`#${hash}`);
Chris@0:       $('body').trigger('formFragmentLinkClickOrHashChange', [$target]);
Chris@0: 
Chris@0:       /**
Chris@0:        * Clicking a fragment link or a hash change should focus the target
Chris@0:        * element, but event timing issues in multiple browsers require a timeout.
Chris@0:        */
Chris@0:       setTimeout(() => $target.trigger('focus'), 300);
Chris@0:     }
Chris@0:   };
Chris@0: 
Chris@17:   const debouncedHandleFragmentLinkClickOrHashChange = debounce(
Chris@17:     handleFragmentLinkClickOrHashChange,
Chris@17:     300,
Chris@17:     true,
Chris@17:   );
Chris@0: 
Chris@0:   // Binds a listener to handle URL fragment changes.
Chris@17:   $(window).on(
Chris@17:     'hashchange.form-fragment',
Chris@17:     debouncedHandleFragmentLinkClickOrHashChange,
Chris@17:   );
Chris@0: 
Chris@0:   /**
Chris@0:    * Binds a listener to handle clicks on fragment links and absolute URL links
Chris@0:    * containing a fragment, this is needed next to the hash change listener
Chris@0:    * because clicking such links doesn't trigger a hash change when the fragment
Chris@0:    * is already in the URL.
Chris@0:    */
Chris@17:   $(document).on(
Chris@17:     'click.form-fragment',
Chris@17:     'a[href*="#"]',
Chris@17:     debouncedHandleFragmentLinkClickOrHashChange,
Chris@17:   );
Chris@17: })(jQuery, Drupal, Drupal.debounce);