or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

forms.mdhtml-safety.mdindex.mdjavascript.md
tile.json

tessl/hex-phoenix-html

Building blocks for working with HTML in Phoenix - provides HTML safety mechanisms, form abstractions, and JavaScript enhancements

Workspace
tessl
Visibility
Public
Created
Last updated
Describes

pkg:hex/phoenix_html@4.2.x

To install, run

npx @tessl/cli install tessl/hex-phoenix-html@4.2.0

index.mddocs/

Phoenix.HTML

Building blocks for working with HTML in Phoenix. Phoenix.HTML provides essential functionality for generating secure, dynamic HTML content in Elixir web applications through three core capabilities: HTML safety mechanisms that prevent XSS attacks, comprehensive form abstractions for data binding and validation, and client-side JavaScript enhancements.

Package Information

  • Package Name: phoenix_html
  • Package Type: hex
  • Language: Elixir
  • Installation: {:phoenix_html, "~> 4.2"}

Core Imports

# Core HTML safety functions
import Phoenix.HTML

# Form handling
import Phoenix.HTML.Form

For templates and views:

# Import in your view modules or templates
import Phoenix.HTML
import Phoenix.HTML.Form

Basic Usage

import Phoenix.HTML

# HTML safety and escaping
safe_content = raw("<p>This is safe HTML</p>")
escaped = html_escape("<script>alert('XSS')</script>")
string_result = safe_to_string(escaped)

# Attribute escaping for dynamic HTML generation
attrs = [class: ["btn", "btn-primary"], data: [confirm: "Are you sure?"]]
escaped_attrs = attributes_escape(attrs)

# Form creation from data structures
form_data = %{name: "John", email: "john@example.com"}
form = Phoenix.HTML.FormData.to_form(form_data, as: :user)

# Field access and information
field = form[:name]
field_id = Phoenix.HTML.Form.input_id(form, :name)
field_name = Phoenix.HTML.Form.input_name(form, :name)
field_value = Phoenix.HTML.Form.input_value(form, :name)

Architecture

Phoenix.HTML is built around several key components:

  • Safety Protocol: The Phoenix.HTML.Safe protocol ensures all data is properly escaped before rendering
  • Form Data Protocol: The Phoenix.HTML.FormData protocol converts various data structures to form representations
  • Engine Integration: The Phoenix.HTML.Engine integrates with EEx templates for automatic HTML safety
  • Client Enhancement: JavaScript library provides progressive enhancement for forms and links

This design provides a comprehensive, secure foundation for HTML generation in Phoenix applications while maintaining performance through iodata optimization.

Capabilities

HTML Safety and Escaping

Core functions for preventing XSS attacks by properly escaping HTML content, marking safe content, and handling attribute escaping. These functions form the security foundation of Phoenix HTML generation.

@type safe :: {:safe, iodata}
@type unsafe :: Phoenix.HTML.Safe.t()

def raw(iodata | safe | nil) :: safe
def html_escape(unsafe) :: safe
def safe_to_string(safe) :: String.t()
def attributes_escape(attrs) :: safe
def javascript_escape(binary | safe) :: binary | safe
def css_escape(String.t()) :: String.t()

HTML Safety

Form Handling and Data Binding

Comprehensive form abstractions that convert data structures into form representations, handle field access, validation, and provide utilities for form rendering and data binding.

defmodule Phoenix.HTML.Form do
  @type t :: %Phoenix.HTML.Form{
    source: Phoenix.HTML.FormData.t(),
    name: String.t(),
    data: %{field => term},
    action: atom(),
    params: %{binary => term}
  }
  @type field :: atom | String.t()
end

def input_value(t | atom, field) :: term
def input_id(t | atom, field) :: String.t()
def input_id(t | atom, field, value) :: String.t()
def input_name(t | atom, field) :: String.t()
def input_validations(t, field) :: Keyword.t()
def input_changed?(t, t, field) :: boolean()
def normalize_value(String.t(), term) :: term
def options_for_select(options, selected_values) :: safe
def fetch(t, field) :: {:ok, Phoenix.HTML.FormField.t()} | :error

Forms and Data Binding

JavaScript Integration

Client-side enhancements through a lightweight JavaScript library that provides confirmation dialogs, HTTP method support for links, and custom event handling for progressive enhancement.

// Automatic handling of data attributes:
// data-confirm="message" - Shows confirmation dialog
// data-method="patch|post|put|delete" - Sends HTTP request
// data-to="url" - Target URL for method requests
// data-csrf="token" - CSRF token inclusion

// Custom event for integration:
window.addEventListener('phoenix.link.click', function(e) {
  // Custom behavior before default handling
});

JavaScript Enhancement

Types

# HTML Safety Types
@type Phoenix.HTML.safe :: {:safe, iodata}
@type Phoenix.HTML.unsafe :: Phoenix.HTML.Safe.t()

# Form Types
defmodule Phoenix.HTML.Form do
  @type t :: %__MODULE__{
    source: Phoenix.HTML.FormData.t(),
    impl: module,
    id: String.t(),
    name: String.t(),
    data: %{field => term},
    action: atom(),
    hidden: Keyword.t(),
    params: %{binary => term},
    errors: [{field, term}],
    options: Keyword.t(),
    index: nil | non_neg_integer
  }

  @type field :: atom | String.t()
end

defmodule Phoenix.HTML.FormField do
  @type t :: %__MODULE__{
    id: String.t(),
    name: String.t(),
    errors: [term],
    field: Phoenix.HTML.Form.field(),
    form: Phoenix.HTML.Form.t(),
    value: term
  }
end

# Protocol Types
defprotocol Phoenix.HTML.FormData do
  @type t :: term  # Any data structure implementing this protocol
end

defprotocol Phoenix.HTML.Safe do
  @type t :: term  # Any data structure that can be converted to safe HTML
end

Error Handling

Phoenix.HTML handles errors gracefully with informative messages:

  • Missing Assigns: fetch_assign!/2 provides clear error messages for undefined template variables
  • Invalid Field Access: Form field access validates field types (atom or string)
  • Protocol Errors: Safe protocol implementations handle unsupported data types appropriately
  • JavaScript Errors: Client-side code includes IE<=9 compatibility and graceful degradation