Glimmer DSL for Web

Glimmer DSL for Web is built on several core principles designed to provide a 'Rails-like' experience for the frontend:

• The Ruby Way: Emphasizing idiomatic Ruby and the principle of 'There Is More Than One Way To Do It' (TIMTOWTDI).
• Convention over Configuration: Using smart defaults and automation to reduce low-level boilerplate.
• Declarative Syntax: Providing a syntax that visually maps to the DOM hierarchy.
• Hybrid Code: Allowing the convenient mixing of declarative and imperative code in a single language.
• Modular Design: Supporting component-based architecture.

The most minimal and declarative way to sync a View property with a Model attribute is using the <=> operator. This performs bidirectional data-binding: changes in the UI update the model, and changes in the model update the UI.

This approach significantly reduces the amount of boilerplate code compared to manual observers or oninput listeners.

class HelloObserver
  include Glimmer::Web::Component

  before_render do
    @number_holder = NumberHolder.new
  end

  markup {
    div {
      input(type: 'number', min: 0, max: 100) {
        # Bidirectional binding between input value and @number_holder.number
        value <=> [@number_holder, :number]
      }
      input(type: 'range', min: 0, max: 100) {
        # Bidirectional binding between range slider and @number_holder.number
        value <=> [@number_holder, :number]
      }
    }
  }
end

Glimmer components support slots to allow consumers to inject content into specific parts of a component's markup.

• Default Slots: Use default_slot :name to define a primary insertion point. Content nested inside the component call in consumer code is automatically inserted into this slot.
• Named Slots: Use slot: :name within the markup block to specify where content should be placed.
• Markup Root Slot: If no slots are specified, content nested under a component is added to the :markup_root_slot (the top-level element in the markup block).

Content Data-Binding allows you to regenerate HTML element content dynamically based on changes to a Model attribute. This is useful for rebuilding lists or complex structures when the underlying data changes.

Use the content(model, attribute) method to bind the content of an element to a model attribute. You can use the computed_by: option to specify which attributes should trigger a re-render of the content.

# Re-render content when address_count or street_count changes
content(@user, :address_count, computed_by: [:address_count, :street_count])

Custom Mounting Point

By default, Glimmer elements mount to the <body>. To mount to a specific HTML element, pass the parent: option with a CSS selector:

div(parent: '#app-container') {
  label(class: 'greeting') { 'Hello, World!' }
}

Bulk Rendering vs Piecemeal Rendering

By default, elements are rendered in bulk for better performance. This means you cannot interact with element objects until the full rendering process is complete.

If you need to interact with elements immediately, you can disable this behavior by passing bulk_render: false to the top-level component or top-level element.

include Glimmer

Document.ready? do
  div(parent: '#app-container', bulk_render: false) {
    label(class: 'greeting') { 'Hello, World!' }
  }
end

To build a reusable component, include Glimmer::Web::Component in your class. You can use lifecycle hooks like before_render to initialize state and after_render for setup tasks. The UI is defined within a markup block, and styles are defined within a style block.

Example structure:

class MyComponent
  include Glimmer::Web::Component

  before_render do
    @state = MyState.new
  end

  markup {
    div { 
      # UI elements here 
    }
  }

  style {
    # CSS rules here
  }
end

MyComponent.render

class ButtonCounter
  include Glimmer::Web::Component

  before_render do
    @counter = Counter.new
  end

  markup {
    div {
      button {
        inner_text <= [@counter, :count, on_read: ->(value) { "Click To Increment: #{value}  " }]
        onclick { @counter.count += 1 }
      }
    }
  }
end

ButtonCounter.render

If you need to dynamically rebuild or re-render HTML elements based on changes to a Model attribute, use the content method. This is useful for scenarios like generating a list of forms where the number of forms depends on a specific count attribute in your model.

Use content(model, :attribute) to define the scope. The block provided to content will be re-executed (re-rendering the content) whenever the specified attribute changes. You can also use the computed_by option to trigger re-renders based on multiple attributes.

# Re-renders the block whenever @user.address_count changes
content(@user, :address_count) do
  @user.addresses.each do |address|
    div { 
      # ... render address form ...
    }
  end
end

# Re-renders based on multiple attributes
content(@user, computed_by: [:address_count, :street_count]) do
  # ...
end