msgProc: Form Messages

Complete reference for form-related msgProc events. Covers text input tracking, validation, and form submission for implementing real-time validation, character limits, and custom form handling.

Text Field Input (MSG_INPUT)

MSG_INPUT fires when text fields change from ANY source (typing, paste, autocomplete, IME composition). This event fires BEFORE the DOM is mutated, allowing you to validate or prevent the input. Return false to block the input. Use this for input validation, character filtering, or preventing unwanted changes.

Message Parameters

Parameter Type Description
wParam number Input delta: positive = number of characters inserted, negative (-1) = deletion operation, zero = formatting or non-text mutation
lParam number Modifier key flags active during input: MK_SHIFT, MK_CONTROL, MK_ALT. Useful for detecting Ctrl+V paste or Shift+Insert

Detail Properties

Property Type Description
inputType string The type of input operation from the Input Events specification: 'insertText', 'insertFromPaste', 'deleteContentBackward', 'deleteContentForward', 'insertCompositionText' (IME), and others
elementType string Element type: 'input', 'textarea', or other editable element tag name
text string|null The text being inserted or deleted. For insertions, the inserted characters. For deletions on text inputs and textareas, the character(s) about to be removed. Null when the text cannot be determined
selectionStart number|null Start of the selection range (0-based) at the time of input, before the mutation is applied. Null for contenteditable elements
selectionEnd number|null End of the selection range (0-based) at the time of input, before the mutation is applied. Equal to selectionStart when the caret is collapsed (no selection). Null for contenteditable elements
beforeinput Timing: MSG_INPUT fires during the browser's beforeinput event, before the DOM is mutated. The selectionStart and selectionEnd properties reflect the caret or selection state before the edit is applied, which is useful for undo systems, input validation, and custom text processing. Return false to prevent the input from being applied.

Example: Paste Detection

msgProc(event) {
    if (event.message === wakaPAC.MSG_INPUT) {
        // Detect paste operations
        if (event.detail.inputType === 'insertFromPaste') {
            console.log('User pasted:', event.detail.text);

            // Sanitize pasted content
            if (event.detail.text.includes('<script>')) {
                return false; // Block dangerous paste
            }
        }
    }
}

Example: Character Limit

msgProc(event) {
    if (event.message === wakaPAC.MSG_INPUT) {
        const currentLength = event.target.value.length;
        const delta = event.wParam;

        // Block input if it would exceed 100 characters
        if (delta > 0 && currentLength + delta > 100) {
            return false;
        }
    }
}

Text Field Input Complete (MSG_INPUT_COMPLETE)

MSG_INPUT_COMPLETE fires after the DOM has been updated following a text input operation. It is the post-mutation companion to MSG_INPUT: where MSG_INPUT fires before the edit is applied (providing delta and selection data for validation or interception), MSG_INPUT_COMPLETE fires after the element's value reflects the final result. Use this for two-way data binding, live character counts, and any logic that needs to read the committed value.

Message Parameters

Parameter Type Description
wParam number Current length of the element's value after the mutation. For <input> and <textarea> this is target.value.length; for contenteditable elements it is target.textContent.length. Zero indicates an empty field
lParam number Modifier key flags active during input: MK_SHIFT, MK_CONTROL, MK_ALT. Consistent with MSG_INPUT

Detail Properties

Property Type Description
inputType string|null The type of input operation that caused the mutation (same values as MSG_INPUT's inputType: 'insertText', 'insertFromPaste', 'deleteContentBackward', etc.). Null when the browser does not provide it
elementType string Element type: 'input', 'textarea', or other editable element tag name
value string The element's complete value after the mutation. For <input> and <textarea> this is target.value; for contenteditable elements it is target.textContent
Timing: MSG_INPUT_COMPLETE fires during the browser's input event, after the DOM has been mutated. Unlike MSG_INPUT (which fires during beforeinput and can prevent the edit by returning false), returning false from MSG_INPUT_COMPLETE only stops further event processing — the DOM mutation has already been applied.

Example: Two-Way Binding

msgProc(event) {
    if (event.message === wakaPAC.MSG_INPUT_COMPLETE) {
        // Sync model with the final committed value
        this.username = event.detail.value;
        return false;
    }
}

Example: Character Counter

msgProc(event) {
    if (event.message === wakaPAC.MSG_INPUT_COMPLETE) {
        const length = event.wParam;

        this.characterCount = length;
        this.remainingChars = 500 - length;

        return false;
    }
}

Form Submit (MSG_SUBMIT)

MSG_SUBMIT fires when a form is submitted (via submit button click, Enter key in text field, or programmatic submission). Use this to handle form submission, validate complete forms, or prevent default submission and handle via AJAX. Return false to prevent the default browser form submission.

Message Parameters

Parameter Type Description
wParam number Reserved (always 0)
lParam number Reserved (always 0)

Detail Properties

Property Type Description
entries object Form field key-value pairs. Note: Only captures first value for fields with duplicate names
action string Form submission URL
method string HTTP method: 'GET', 'POST', etc.
enctype string Form encoding type (e.g., 'multipart/form-data')
name string Form's name attribute
isValid boolean Whether form passes HTML5 validation
submitter object|null Submit button info: { name, value, id }. Null if submitted via Enter key or JavaScript
files object File upload metadata by field name. Each file has: { name, size, type }. Does not contain actual file data
multiEntries object Fields with multiple values (checkboxes, multi-selects). Keys map to arrays of values
Preventing Default: Return false from MSG_SUBMIT to prevent the default browser form submission. This allows you to handle submission via AJAX, perform custom validation, or implement multi-step forms.
File Data: The files property contains metadata only (name, size, type). To access actual file contents, access event.originalEvent.target to get the form element and read files from the file input elements.

Example: AJAX Form Submission

msgProc(event) {
    if (event.message === wakaPAC.MSG_SUBMIT) {
        // Prevent default browser submission
        // Handle via AJAX instead
        this.submitForm(event.detail.entries);
        return false;
    }
}

Example: Form Validation

msgProc(event) {
    if (event.message === wakaPAC.MSG_SUBMIT) {
        const { entries, isValid } = event.detail;

        // Check HTML5 validation
        if (!isValid) {
            this.showError('Please fill in all required fields');
            return false;
        }

        // Custom validation
        if (entries.password !== entries.confirmPassword) {
            this.showError('Passwords do not match');
            return false;
        }

        // Submit
        this.submitForm(entries);
        return false;
    }
}

Best Practices

  • Use MSG_INPUT for validation: Block unwanted input before it's applied by returning false
  • Use MSG_INPUT_COMPLETE for binding: Read final values for two-way data binding and UI updates
  • Check inputType: Different handling for typing vs paste vs IME (e.g., allow paste but sanitize it)
  • Handle all input sources: MSG_INPUT captures typing, paste, autocomplete, IME — don't rely on MSG_CHAR or MSG_KEYDOWN alone
  • Return false from MSG_SUBMIT: Prevent default browser submission when handling forms via AJAX
  • Validate on submit: Even with real-time validation, always validate again on submit
  • Store state privately: Use underscore-prefixed properties during validation to avoid triggering unnecessary reactivity