or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ajax-remote.mdcsrf-protection.mddom-utilities.mdelement-state.mdevent-system.mdfeature-handlers.mdform-handling.mdindex.md
tile.json

tessl/npm-rails--ujs

Ruby on Rails unobtrusive scripting adapter that enables modern JavaScript behaviors through HTML5 data attributes

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@rails/ujs@7.1.x

To install, run

npx @tessl/cli install tessl/npm-rails--ujs@7.1.0

index.mddocs/

Rails UJS

Rails UJS (@rails/ujs) is a JavaScript library that provides unobtrusive scripting support for Ruby on Rails applications. It enables modern JavaScript behaviors without requiring inline event handlers by using HTML5 data attributes. The library works independently of any JavaScript framework and provides comprehensive support for AJAX requests, form handling, CSRF protection, and UI element state management.

Package Information

  • Package Name: @rails/ujs
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install @rails/ujs --save

Core Imports

import Rails from "@rails/ujs";
Rails.start();

For CommonJS:

const Rails = require("@rails/ujs");
Rails.start();

Asset Pipeline (Sprockets):

//= require rails-ujs

Basic Usage

import Rails from "@rails/ujs";

// Initialize the library (required for ES modules)
Rails.start();

// The library automatically binds to elements with data attributes:
// <a href="/posts/1" data-method="delete" data-confirm="Are you sure?">Delete</a>
// <form data-remote="true" data-confirm="Submit form?">...</form>
// <input type="submit" data-disable-with="Processing..." />

Architecture

Rails UJS is organized around several key components:

  • Event Delegation System: Uses a single event delegation approach for performance and dynamic content support
  • Data Attribute Processing: Converts HTML5 data attributes into JavaScript behaviors
  • Modular Design: Organized into utilities (DOM, AJAX, CSRF) and features (confirm, disable, method, remote)
  • Framework Independence: Works without jQuery or other frameworks, with optional jQuery integration
  • CSRF Protection: Automatic Cross-Site Request Forgery token management for all AJAX requests

Capabilities

AJAX and Remote Requests

Core AJAX functionality for making HTTP requests with Rails conventions, including automatic CSRF protection, response processing, and cross-domain detection.

function ajax(options: AjaxOptions): boolean | XMLHttpRequest;

interface AjaxOptions {
  url?: string;
  type?: string;
  data?: string | FormData;
  dataType?: string;
  beforeSend?: (xhr: XMLHttpRequest, options: AjaxOptions) => boolean;
  success?: (response: any, statusText: string, xhr: XMLHttpRequest) => void;
  error?: (response: any, statusText: string, xhr: XMLHttpRequest) => void;
  complete?: (xhr: XMLHttpRequest, statusText: string) => void;
  crossDomain?: boolean;
  withCredentials?: boolean;
}

AJAX and Remote Requests

CSRF Protection

Cross-Site Request Forgery protection system that automatically handles CSRF tokens for all requests and forms, including Content Security Policy nonce support for secure script execution.

function csrfToken(): string | null;
function csrfParam(): string | null;
function CSRFProtection(xhr: XMLHttpRequest): void;
function refreshCSRFTokens(): void;
function cspNonce(): string | null;
function loadCSPNonce(): string | null;

CSRF Protection

Element State Management

System for enabling and disabling form elements and links during processing, including visual feedback management.

function enableElement(element: Element | Event): void;
function disableElement(element: Element | Event): void;
function handleDisabledElement(event: Event): void;

Element State Management

DOM Utilities

Core DOM manipulation and querying utilities used throughout the library.

function $(selector: string): Element[];
function matches(element: Element, selector: string | SelectorObject): boolean;
function getData(element: Element, key: string): any;
function setData(element: Element, key: string, value: any): any;
function isContentEditable(element: Element): boolean;

DOM Utilities

Event System

Custom event system and delegation utilities for managing user interactions and library events.

function fire(obj: EventTarget, name: string, data?: any): boolean;
function delegate(element: Element, selector: string, eventType: string, handler: Function): void;
function stopEverything(event: Event): void;

Event System

Form Handling

Form serialization and element management utilities for handling form submissions and form state.

function serializeElement(element: Element, additionalParam?: {name: string, value: string}): string;
function formElements(form: Element, selector: string): Element[];
function formSubmitButtonClick(event: Event): void;

Form Handling

Feature Handlers

High-level handlers that implement the core Rails UJS behaviors for method overrides, remote requests, confirmations, and element disabling.

function handleConfirm(event: Event): void;
function handleMethod(event: Event): void;
function handleRemote(event: Event): void;
function preventInsignificantClick(event: Event): void;

Feature Handlers

Initialization

Core initialization functionality required to activate Rails UJS event delegation and data attribute processing.

/**
 * Initialize Rails UJS and set up all event delegation
 * @returns true if successfully initialized
 * @throws Error if Rails UJS has already been loaded
 */
function start(): boolean;

Selector Constants

CSS selectors used internally by Rails UJS for element targeting and event delegation.

const linkClickSelector: string;
const buttonClickSelector: SelectorObject;
const inputChangeSelector: string;
const formSubmitSelector: string;
const formInputClickSelector: string;
const formDisableSelector: string;
const formEnableSelector: string;
const fileInputSelector: string;
const linkDisableSelector: string;
const buttonDisableSelector: string;

Global Types

interface SelectorObject {
  selector: string;
  exclude: string;
}

interface RailsObject {
  $: (selector: string) => Element[];
  ajax: (options: AjaxOptions) => boolean | XMLHttpRequest;
  confirm: (message: string, element: Element) => boolean;
  href: (element: Element) => string;
  start: () => boolean;
  [key: string]: any;
}