or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ajax.mdanimations.mdcss-styling.mddata-storage.mddom-manipulation.mddom-traversal.mdevents.mdforms.mdindex.mdutilities.md
tile.json

forms.mddocs/

Form Processing

Specialized methods for working with form elements, serialization, and form data manipulation. jQuery provides comprehensive tools for handling forms, validation, and data submission.

Capabilities

Form Element Values

Get and set values for all types of form elements with automatic type handling.

/**
 * Get or set form element values
 * @param value - Optional value to set (string, number, array for multi-select)
 * @returns Current value (when getting) or jQuery object (when setting)
 */
val(): string | number | string[];
val(value: string | number | string[] | function): jQuery;

Usage Examples:

// Get values from different input types
const textValue = $('#username').val();          // String
const numberValue = $('#age').val();             // String (even for number inputs)
const checkboxValue = $('#agree').val();         // Value attribute or 'on'
const radioValue = $('input[name="gender"]:checked').val(); // Selected radio value
const selectValue = $('#country').val();         // Selected option value
const multiSelectValues = $('#skills').val();   // Array of selected values

// Set values
$('#username').val('john_doe');
$('#age').val(25);
$('#email').val('john@example.com');

// Set checkbox/radio state (use prop() for checked state)
$('#agree').prop('checked', true);
$('input[name="gender"][value="male"]').prop('checked', true);

// Set select options
$('#country').val('US');                         // Single select
$('#skills').val(['javascript', 'python']);     // Multi-select

// Clear form values
$('#myForm input, #myForm select, #myForm textarea').val('');

// Using functions to set values
$('.price-input').val(function(index, currentValue) {
  return parseFloat(currentValue).toFixed(2);
});

// Handle different input types
$('input').each(function() {
  const $input = $(this);
  const type = $input.attr('type');
  
  switch (type) {
    case 'checkbox':
    case 'radio':
      console.log($input.attr('name'), $input.prop('checked'));
      break;
    default:
      console.log($input.attr('name'), $input.val());
  }
});

Form Serialization

Convert form data to URL-encoded strings or structured arrays for easy transmission.

/**
 * Serialize form elements to URL-encoded string
 * @returns URL-encoded string suitable for query parameters or POST data
 */
serialize(): string;

/**
 * Serialize form elements to array of name/value objects
 * @returns Array of {name: string, value: string} objects
 */
serializeArray(): Array<{name: string, value: string}>;

Usage Examples:

// Basic form serialization
const formData = $('#myForm').serialize();
// Result: "username=john&email=john%40example.com&age=25&agree=on"

// Send serialized form via AJAX
$('#myForm').on('submit', function(e) {
  e.preventDefault();
  
  $.post('/api/submit', $(this).serialize())
    .done(function(response) {
      console.log('Form submitted successfully');
    })
    .fail(function() {
      console.log('Form submission failed');
    });
});

// Serialize to array format
const formArray = $('#myForm').serializeArray();
// Result: [
//   {name: "username", value: "john"},
//   {name: "email", value: "john@example.com"},
//   {name: "age", value: "25"},
//   {name: "agree", value: "on"}
// ]

// Convert array to object
function arrayToObject(formArray) {
  const obj = {};
  formArray.forEach(function(item) {
    if (obj[item.name]) {
      // Handle multiple values (checkboxes, multi-select)
      if (!Array.isArray(obj[item.name])) {
        obj[item.name] = [obj[item.name]];
      }
      obj[item.name].push(item.value);
    } else {
      obj[item.name] = item.value;
    }
  });
  return obj;
}

const formObject = arrayToObject($('#myForm').serializeArray());

// Serialize specific elements
const specificData = $('#myForm input[type="text"], #myForm select').serialize();

// Serialize with additional data
const allData = $('#myForm').serialize() + '&action=update&timestamp=' + Date.now();

Custom Form Serialization

Create custom serialization functions for complex data structures.

/**
 * Static method to serialize object to URL-encoded string
 * @param obj - Object or array to serialize
 * @param traditional - Use traditional parameter serialization
 * @returns URL-encoded string
 */
$.param(obj: any, traditional?: boolean): string;

Usage Examples:

// Serialize object
const userData = {
  name: 'John Doe',
  age: 30,
  hobbies: ['reading', 'coding'],
  address: {
    street: '123 Main St',
    city: 'Boston'
  }
};

// Modern serialization (default)
const modern = $.param(userData);
// Result: "name=John+Doe&age=30&hobbies%5B%5D=reading&hobbies%5B%5D=coding&address%5Bstreet%5D=123+Main+St&address%5Bcity%5D=Boston"

// Traditional serialization
const traditional = $.param(userData, true);
// Result: "name=John+Doe&age=30&hobbies=reading&hobbies=coding&address=%5Bobject+Object%5D"

// Serialize form data with additional parameters
function submitFormWithMetadata(form, metadata) {
  const formData = $(form).serialize();
  const metaData = $.param(metadata);
  const allData = formData + '&' + metaData;
  
  return $.post('/api/submit', allData);
}

// Usage
submitFormWithMetadata('#userForm', {
  source: 'web',
  version: '1.2.3',
  timestamp: Date.now()
});

// Custom serialization for file uploads
function serializeFormWithFiles(form) {
  const formData = new FormData();
  
  // Add regular form fields
  $(form).serializeArray().forEach(function(field) {
    formData.append(field.name, field.value);
  });
  
  // Add file inputs
  $(form).find('input[type="file"]').each(function() {
    const files = this.files;
    for (let i = 0; i < files.length; i++) {
      formData.append(this.name, files[i]);
    }
  });
  
  return formData;
}

Form Validation Patterns

Client-side Validation

Implement comprehensive form validation using jQuery's form methods.

Usage Examples:

// Basic validation setup
function validateForm($form) {
  let isValid = true;
  const errors = [];
  
  // Required fields
  $form.find('[required]').each(function() {
    const $field = $(this);
    if (!$field.val().trim()) {
      isValid = false;
      errors.push(`${$field.attr('name')} is required`);
      $field.addClass('error');
    } else {
      $field.removeClass('error');
    }
  });
  
  // Email validation
  $form.find('input[type="email"]').each(function() {
    const $field = $(this);
    const email = $field.val();
    if (email && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
      isValid = false;
      errors.push('Please enter a valid email address');
      $field.addClass('error');
    }
  });
  
  // Custom validation rules
  $form.find('[data-validate]').each(function() {
    const $field = $(this);
    const rules = $field.attr('data-validate').split('|');
    
    rules.forEach(function(rule) {
      const [ruleName, param] = rule.split(':');
      
      switch (ruleName) {
        case 'min-length':
          if ($field.val().length < parseInt(param)) {
            isValid = false;
            errors.push(`${$field.attr('name')} must be at least ${param} characters`);
            $field.addClass('error');
          }
          break;
        case 'numeric':
          if ($field.val() && isNaN($field.val())) {
            isValid = false;
            errors.push(`${$field.attr('name')} must be numeric`);
            $field.addClass('error');
          }
          break;
      }
    });
  });
  
  return { isValid, errors };
}

// Form submission with validation
$('#myForm').on('submit', function(e) {
  e.preventDefault();
  
  const validation = validateForm($(this));
  
  if (validation.isValid) {
    // Submit form
    $.post('/api/submit', $(this).serialize())
      .done(function(response) {
        showMessage('Form submitted successfully', 'success');
      })
      .fail(function() {
        showMessage('Submission failed. Please try again.', 'error');
      });
  } else {
    // Show validation errors
    showMessage(validation.errors.join('<br>'), 'error');
  }
});

// Real-time validation
$('#myForm input, #myForm select, #myForm textarea').on('blur', function() {
  validateForm($(this).closest('form'));
});

Dynamic Form Manipulation

Add, remove, and modify form elements dynamically.

Usage Examples:

// Add form fields dynamically
function addFormField(container, fieldType, name, label) {
  const fieldId = name + '_' + Date.now();
  let fieldHtml = '';
  
  switch (fieldType) {
    case 'text':
      fieldHtml = `
        <div class="form-group">
          <label for="${fieldId}">${label}</label>
          <input type="text" id="${fieldId}" name="${name}" class="form-control">
        </div>
      `;
      break;
    case 'select':
      fieldHtml = `
        <div class="form-group">
          <label for="${fieldId}">${label}</label>
          <select id="${fieldId}" name="${name}" class="form-control">
            <option value="">Choose...</option>
          </select>
        </div>
      `;
      break;
  }
  
  $(container).append(fieldHtml);
  return $('#' + fieldId);
}

// Remove form fields
$(document).on('click', '.remove-field', function() {
  $(this).closest('.form-group').remove();
});

// Clone form sections
$('#add-address').click(function() {
  const $template = $('#address-template');
  const $clone = $template.clone();
  
  // Update IDs and names to be unique
  $clone.find('input, select').each(function() {
    const $field = $(this);
    const oldId = $field.attr('id');
    const oldName = $field.attr('name');
    const suffix = '_' + $('.address-section').length;
    
    $field.attr('id', oldId + suffix);
    $field.attr('name', oldName + suffix);
    $field.val(''); // Clear values
  });
  
  $clone.removeClass('hidden').addClass('address-section');
  $('#addresses-container').append($clone);
});

// Form field dependencies
$('#country').change(function() {
  const country = $(this).val();
  const $stateField = $('#state');
  
  $stateField.empty().append('<option value="">Loading...</option>');
  
  $.get('/api/states/' + country, function(states) {
    $stateField.empty().append('<option value="">Choose state...</option>');
    states.forEach(function(state) {
      $stateField.append(`<option value="${state.code}">${state.name}</option>`);
    });
  });
});

Form State Management

Track form changes and manage form state throughout user interaction.

Usage Examples:

// Track form modifications
function initializeFormTracking($form) {
  // Store original form state
  $form.data('original-state', $form.serialize());
  $form.data('is-dirty', false);
  
  // Monitor changes
  $form.on('input change', 'input, select, textarea', function() {
    const currentState = $form.serialize();
    const originalState = $form.data('original-state');
    const isDirty = currentState !== originalState;
    
    $form.data('is-dirty', isDirty);
    $form.toggleClass('modified', isDirty);
    
    // Update save button state
    $form.find('.save-btn').prop('disabled', !isDirty);
  });
}

// Auto-save functionality
function setupAutoSave($form, saveUrl, interval = 30000) {
  let saveTimer;
  let lastSavedState = $form.serialize();
  
  function autoSave() {
    const currentState = $form.serialize();
    if (currentState !== lastSavedState) {
      $.post(saveUrl, currentState)
        .done(function() {
          lastSavedState = currentState;
          showMessage('Auto-saved', 'info');
        })
        .fail(function() {
          showMessage('Auto-save failed', 'warning');
        });
    }
  }
  
  $form.on('input change', function() {
    clearTimeout(saveTimer);
    saveTimer = setTimeout(autoSave, interval);
  });
}

// Form step management (wizard forms)
function initializeFormWizard($form) {
  const $steps = $form.find('.form-step');
  let currentStep = 0;
  
  function showStep(stepIndex) {
    $steps.hide().eq(stepIndex).show();
    $form.find('.step-indicator').removeClass('active')
         .eq(stepIndex).addClass('active');
    
    // Update navigation buttons
    $('.prev-btn').toggle(stepIndex > 0);
    $('.next-btn').toggle(stepIndex < $steps.length - 1);
    $('.submit-btn').toggle(stepIndex === $steps.length - 1);
    
    currentStep = stepIndex;
  }
  
  $('.next-btn').click(function() {
    if (validateStep(currentStep)) {
      showStep(currentStep + 1);
    }
  });
  
  $('.prev-btn').click(function() {
    showStep(currentStep - 1);
  });
  
  function validateStep(stepIndex) {
    const $currentStep = $steps.eq(stepIndex);
    return validateForm($currentStep).isValid;
  }
  
  // Initialize
  showStep(0);
}

// Form persistence in localStorage
function setupFormPersistence($form, storageKey) {
  // Load saved data
  function loadFormData() {
    const savedData = localStorage.getItem(storageKey);
    if (savedData) {
      const data = JSON.parse(savedData);
      Object.keys(data).forEach(function(name) {
        const $field = $form.find(`[name="${name}"]`);
        if ($field.attr('type') === 'checkbox' || $field.attr('type') === 'radio') {
          $field.filter(`[value="${data[name]}"]`).prop('checked', true);
        } else {
          $field.val(data[name]);
        }
      });
    }
  }
  
  // Save form data
  function saveFormData() {
    const formArray = $form.serializeArray();
    const formData = {};
    formArray.forEach(function(field) {
      formData[field.name] = field.value;
    });
    localStorage.setItem(storageKey, JSON.stringify(formData));
  }
  
  // Auto-save on changes
  $form.on('input change', 'input, select, textarea', function() {
    saveFormData();
  });
  
  // Clear saved data on successful submission
  $form.on('submit', function() {
    localStorage.removeItem(storageKey);
  });
  
  // Load data on initialization
  loadFormData();
}

Form Enhancement Patterns

AJAX Form Submission

Handle form submission without page reload using AJAX.

Usage Examples:

// Universal AJAX form handler
$(document).on('submit', 'form[data-ajax]', function(e) {
  e.preventDefault();
  
  const $form = $(this);
  const url = $form.attr('action') || window.location.href;
  const method = $form.attr('method') || 'POST';
  const data = $form.serialize();
  
  // Show loading state
  $form.find('.submit-btn').prop('disabled', true).text('Submitting...');
  
  $.ajax({
    url: url,
    method: method,
    data: data,
    dataType: 'json'
  }).done(function(response) {
    if (response.success) {
      showMessage(response.message || 'Success!', 'success');
      if (response.redirect) {
        window.location.href = response.redirect;
      } else {
        $form[0].reset(); // Clear form
      }
    } else {
      showMessage(response.message || 'An error occurred', 'error');
    }
  }).fail(function() {
    showMessage('Network error. Please try again.', 'error');
  }).always(function() {
    $form.find('.submit-btn').prop('disabled', false).text('Submit');
  });
});

// File upload with progress
function submitFormWithFiles($form) {
  const formData = new FormData($form[0]);
  
  return $.ajax({
    url: $form.attr('action'),
    type: 'POST',
    data: formData,
    processData: false,
    contentType: false,
    xhr: function() {
      const xhr = new XMLHttpRequest();
      xhr.upload.addEventListener('progress', function(e) {
        if (e.lengthComputable) {
          const percentComplete = (e.loaded / e.total) * 100;
          updateProgressBar(percentComplete);
        }
      });
      return xhr;
    }
  });
}