Live Components

Azu's live components enable real-time UI updates through WebSocket connections. These components automatically sync with the server and update the DOM in real-time, providing a seamless interactive experience.

Overview

Live components provide:

Real-time DOM updates without page refreshes
Server-side state management with client synchronization
Event-driven interactions with immediate feedback
Component lifecycle management for proper cleanup
Type-safe event handling with Crystal's type system

Architecture

Basic Live Component

Simple Counter Component

class CounterComponent < Azu::Component
  def initialize(@initial_count : Int32 = 0)
    @count = @initial_count
  end

  def content
    div class: "counter", id: "counter-#{object_id}" do
      h3 "Counter"
      span id: "count", class: "count" do
        text @count.to_s
      end

      div class: "controls" do
        button onclick: "increment()", class: "btn btn-primary" do
          text "Increment"
        end
        button onclick: "decrement()", class: "btn btn-secondary" do
          text "Decrement"
        end
        button onclick: "reset()", class: "btn btn-danger" do
          text "Reset"
        end
      end
    end
  end

  def on_event("increment", data)
    @count += 1
    update_element "count", @count.to_s
  end

  def on_event("decrement", data)
    @count -= 1
    update_element "count", @count.to_s
  end

  def on_event("reset", data)
    @count = @initial_count
    update_element "count", @count.to_s
  end
end

Using the Component

struct CounterEndpoint
  include Endpoint(CounterRequest, CounterResponse)

  get "/counter"

  def call : CounterResponse
    component = CounterComponent.new(10)
    CounterResponse.new(component)
  end
end

Component Lifecycle

Lifecycle Methods

class LifecycleComponent < Azu::Component
  def initialize(@user_id : String)
    @connected = false
    @data = [] of String
  end

  def content
    div class: "lifecycle-component", id: "lifecycle-#{object_id}" do
      h3 "Lifecycle Component"
      div id: "status" do
        text @connected ? "Connected" : "Disconnected"
      end
      div id: "data" do
        @data.each do |item|
          div class: "item" do
            text item
          end
        end
      end
    end
  end

  # Called when component is mounted
  def on_mount
    @connected = true
    update_element "status", "Connected"

    # Load initial data
    load_data
  end

  # Called when component is unmounted
  def on_unmount
    @connected = false
    # Cleanup resources
    cleanup_resources
  end

  # Called when WebSocket connects
  def on_connect
    Log.info { "Component #{object_id} connected" }
  end

  # Called when WebSocket disconnects
  def on_disconnect
    Log.info { "Component #{object_id} disconnected" }
    @connected = false
    update_element "status", "Disconnected"
  end

  private def load_data
    # Simulate loading data
    @data = ["Item 1", "Item 2", "Item 3"]
    render_data
  end

  private def render_data
    content = @data.map do |item|
      "<div class='item'>#{item}</div>"
    end.join

    update_element "data", content
  end

  private def cleanup_resources
    # Clean up any resources
    @data.clear
  end
end

Event Handling

Client-Side Events

class InteractiveComponent < Azu::Component
  def initialize(@user : User)
    @likes = @user.likes_count
    @comments = [] of Comment
  end

  def content
    div class: "interactive-component", id: "interactive-#{object_id}" do
      h3 @user.name

      div class: "stats" do
        span id: "likes" do
          text "#{@likes} likes"
        end
        span id: "comments" do
          text "#{@comments.size} comments"
        end
      end

      div class: "actions" do
        button onclick: "like()", class: "btn btn-primary" do
          text "Like"
        end
        button onclick: "comment()", class: "btn btn-secondary" do
          text "Comment"
        end
      end

      div id: "comments-list" do
        @comments.each do |comment|
          div class: "comment" do
            text comment.text
          end
        end
      end
    end
  end

  def on_event("like", data)
    @likes += 1
    update_element "likes", "#{@likes} likes"

    # Broadcast to other users
    broadcast_update({
      type: "user_liked",
      user_id: @user.id,
      likes: @likes
    })
  end

  def on_event("comment", data)
    comment_text = data["text"]?.try(&.as_s)
    return unless comment_text

    comment = Comment.new(comment_text, @user.id)
    @comments << comment

    # Add comment to DOM
    append_element "comments-list" do
      div class: "comment" do
        text comment.text
      end
    end

    # Update comment count
    update_element "comments", "#{@comments.size} comments"

    # Broadcast to other users
    broadcast_update({
      type: "new_comment",
      user_id: @user.id,
      comment: comment_text
    })
  end
end

Form Handling

class FormComponent < Azu::Component
  def initialize
    @errors = {} of String => String
    @form_data = {} of String => String
  end

  def content
    form onsubmit: "submitForm(event)", class: "form-component", id: "form-#{object_id}" do
      div class: "form-group" do
        label "Name", for: "name"
        input type: "text", id: "name", name: "name", value: @form_data["name"]?
        if error = @errors["name"]?
          span class: "error" do
            text error
          end
        end
      end

      div class: "form-group" do
        label "Email", for: "email"
        input type: "email", id: "email", name: "email", value: @form_data["email"]?
        if error = @errors["email"]?
          span class: "error" do
            text error
          end
        end
      end

      button type: "submit", class: "btn btn-primary" do
        text "Submit"
      end
    end
  end

  def on_event("submit_form", data)
    # Clear previous errors
    @errors.clear
    @form_data = data

    # Validate form
    validate_form

    if @errors.empty?
      # Process form
      process_form
    else
      # Show errors
      render_errors
    end
  end

  private def validate_form
    name = @form_data["name"]?
    email = @form_data["email"]?

    @errors["name"] = "Name is required" if name.try(&.strip.empty?)
    @errors["email"] = "Email is required" if email.try(&.strip.empty?)
    @errors["email"] = "Invalid email format" if email && !email.matches?(/\A[^@\s]+@[^@\s]+\z/)
  end

  private def render_errors
    @errors.each do |field, message|
      update_element "#{field}-error", message
    end
  end

  private def process_form
    # Process the form data
    user = User.create(@form_data)

    # Show success message
    update_element "form-#{object_id}" do
      div class: "success" do
        text "Form submitted successfully!"
      end
    end
  end
end

State Management

Component State

class StatefulComponent < Azu::Component
  def initialize(@initial_state : Hash(String, JSON::Any))
    @state = @initial_state
    @listeners = [] of Proc(Hash(String, JSON::Any), Nil)
  end

  def content
    div class: "stateful-component", id: "stateful-#{object_id}" do
      h3 "Stateful Component"

      div id: "state-display" do
        render_state
      end

      div class: "controls" do
        button onclick: "updateState()", class: "btn" do
          text "Update State"
        end
        button onclick: "resetState()", class: "btn" do
          text "Reset State"
        end
      end
    end
  end

  def on_event("update_state", data)
    # Update state
    new_state = data["state"]?.try(&.as_h)
    return unless new_state

    @state.merge!(new_state)
    notify_listeners
    render_state
  end

  def on_event("reset_state", data)
    @state = @initial_state
    notify_listeners
    render_state
  end

  # Add state change listener
  def on_state_change(&block : Hash(String, JSON::Any) -> Nil)
    @listeners << block
  end

  # Get current state
  def state : Hash(String, JSON::Any)
    @state
  end

  # Set state
  def set_state(new_state : Hash(String, JSON::Any))
    @state = new_state
    notify_listeners
    render_state
  end

  private def render_state
    content = @state.map do |key, value|
      "<div><strong>#{key}:</strong> #{value}</div>"
    end.join

    update_element "state-display", content
  end

  private def notify_listeners
    @listeners.each do |listener|
      listener.call(@state)
    end
  end
end

Real-time Updates

Broadcasting Updates

class ChatComponent < Azu::Component
  def initialize(@room_id : String)
    @messages = [] of Message
    @users = Set(String).new
  end

  def content
    div class: "chat-component", id: "chat-#{object_id}" do
      h3 "Chat Room: #{@room_id}"

      div id: "users" do
        text "Users: #{@users.size}"
      end

      div id: "messages", class: "messages" do
        @messages.each do |message|
          div class: "message" do
            span class: "user" do
              text message.user
            end
            span class: "text" do
              text message.text
            end
            time message.timestamp.to_s("%H:%M")
          end
        end
      end

      form onsubmit: "sendMessage(event)" do
        input type: "text", id: "message-input", placeholder: "Type a message..."
        button type: "submit" do
          text "Send"
        end
      end
    end
  end

  def on_event("send_message", data)
    message_text = data["text"]?.try(&.as_s)
    user = data["user"]?.try(&.as_s)
    return unless message_text && user

    message = Message.new(user, message_text)
    @messages << message

    # Add message to DOM
    append_element "messages" do
      div class: "message" do
        span class: "user" do
          text message.user
        end
        span class: "text" do
          text message.text
        end
        time message.timestamp.to_s("%H:%M")
      end
    end

    # Broadcast to room
    broadcast_to_room(@room_id, {
      type: "new_message",
      user: user,
      text: message_text,
      timestamp: message.timestamp.to_rfc3339
    })
  end

  def on_event("user_joined", data)
    user = data["user"]?.try(&.as_s)
    return unless user

    @users << user
    update_element "users", "Users: #{@users.size}"

    # Add join message
    append_element "messages" do
      div class: "system-message" do
        text "#{user} joined the room"
      end
    end
  end

  def on_event("user_left", data)
    user = data["user"]?.try(&.as_s)
    return unless user

    @users.delete(user)
    update_element "users", "Users: #{@users.size}"

    # Add leave message
    append_element "messages" do
      div class: "system-message" do
        text "#{user} left the room"
      end
    end
  end
end

Component Composition

Reusable Components

class ButtonComponent < Azu::Component
  def initialize(@text : String, @variant : String = "primary", @size : String = "md")
  end

  def content
    button class: "btn btn-#{@variant} btn-#{@size}" do
      text @text
    end
  end
end

class ModalComponent < Azu::Component
  def initialize(@title : String, @id : String)
  end

  def content
    div class: "modal", id: @id do
      div class: "modal-dialog" do
        div class: "modal-content" do
          div class: "modal-header" do
            h5 class: "modal-title" do
              text @title
            end
            button type: "button", class: "btn-close", onclick: "closeModal('#{@id}')"
          end
          div class: "modal-body" do
            yield
          end
        end
      end
    end
  end
end

class UserListComponent < Azu::Component
  def initialize(@users : Array(User))
  end

  def content
    div class: "user-list" do
      @users.each do |user|
        UserCardComponent.new(user).render
      end

      div class: "actions" do
        ButtonComponent.new("Add User", "success").render
        ButtonComponent.new("Export", "secondary").render
      end
    end
  end
end

Performance Optimization

Lazy Loading

class LazyListComponent < Azu::Component
  def initialize(@items : Array(Item), @page_size : Int32 = 20)
    @current_page = 0
    @loaded_items = [] of Item
  end

  def content
    div class: "lazy-list", id: "lazy-list-#{object_id}" do
      div id: "items-container" do
        load_items(@current_page)
      end

      if @items.size > (@current_page + 1) * @page_size
        button onclick: "loadMore()", class: "btn btn-secondary" do
          text "Load More"
        end
      end
    end
  end

  def on_event("load_more", data)
    @current_page += 1
    new_items = load_items(@current_page)

    append_element "items-container", new_items
  end

  private def load_items(page : Int32) : String
    start_index = page * @page_size
    end_index = Math.min(start_index + @page_size, @items.size)

    @items[start_index...end_index].map do |item|
      "<div class='item'>#{item.name}</div>"
    end.join
  end
end

Caching

class CachedComponent < Azu::Component
  def initialize(@cache_key : String)
    @cache_ttl = 300 # 5 minutes
  end

  def content
    cached_fragment @cache_key, ttl: @cache_ttl do
      div class: "cached-component" do
        h3 "Cached Content"
        p "This content is cached for #{@cache_ttl} seconds"

        # Expensive operation
        expensive_data = load_expensive_data
        div class: "data" do
          text expensive_data
        end
      end
    end
  end

  private def load_expensive_data : String
    # Simulate expensive operation
    sleep 1.second
    "Expensive data loaded at #{Time.utc}"
  end
end

Testing Components

Component Testing

# spec/components/counter_component_spec.cr
require "spec"
require "../src/azu"

describe CounterComponent do
  it "increments counter" do
    component = CounterComponent.new(5)

    # Simulate increment event
    component.on_event("increment", {} of String => JSON::Any)

    # Check internal state
    component.instance_variable_get(:@count).should eq(6)
  end

  it "updates DOM element" do
    component = CounterComponent.new(0)

    # Mock DOM update
    component.stub(:update_element, ->(id : String, content : String) {
      # Verify update was called
      id.should eq("count")
      content.should eq("1")
    })

    component.on_event("increment", {} of String => JSON::Any)
  end
end

Best Practices

1. Component Design

Keep components focused and single-purpose
Use composition over inheritance
Implement proper lifecycle management
Handle cleanup in on_unmount

2. State Management

Use immutable state updates
Implement proper state serialization
Minimize state complexity
Use state change listeners

3. Performance

Implement lazy loading for large lists
Use caching for expensive operations
Minimize DOM updates
Optimize event handlers

4. Event Handling

Validate all event data
Use type-safe event structures
Implement proper error handling
Log important events

Next Steps

WebSocket Channels - Build real-time communication
Spark System - Client-side real-time updates
Component Examples - Working examples

Ready to build interactive components? Start with the basic examples above, then explore WebSocket Channels for real-time communication.

PreviousWebSocket Channels NextSpark System

Last updated 1 month ago

Was this helpful?