glimmer-dsl-web

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

glimmer-dsl-web

★ 238 Open GitHub ↗

Glimmer DSL for Web (Ruby-in-the-Browser Web Frontend Framework). The "Rails" of Frontend Frameworks!!!

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for Web 0.9.2 (Beta)
## Ruby-in-the-Browser Web Frontend Framework
### The "Rails" of Frontend Frameworks!!! ([Fukuoka Award Winning](https://andymaleh.blogspot.com/2025/01/glimmer-dsl-for-web-wins-in-fukuoka.html))
#### Finally, Ruby Developer Productivity, Happiness, and Fun in the Frontend!!!
[![Gem Version](https://badge.fury.io/rb/glimmer-dsl-web.svg)](http://badge.fury.io/rb/glimmer-dsl-web)
[![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

**(Based on Original [Glimmer](https://github.com/AndyObtiva/glimmer) Library Handling World’s Ruby GUI Needs Since 2007. Beware of Imitators!)**

**([Fukuoka Prefecture Future IT Initiative 2025 Money Forward Award Winner](https://andymaleh.blogspot.com/2025/01/glimmer-dsl-for-web-wins-in-fukuoka.html)) [(Award Announcement)](https://digitalfukuoka.jp/news/info/528/)**

(**Workshops: [wroclove.rb 2026 Ruby conference workshop exercises: "Building Rails SPAs in Frontend Ruby with Glimmer DSL for Web"](https://github.com/AndyObtiva/glimmer_commerce)**)

**(Talk Videos: [Intro to Ruby in the Browser](https://youtu.be/4AdcfbI6A4c?si=MmxOrkhIXTDHQoYi) / [Frontend Ruby with Glimmer DSL for Web \[Montreal.rb\]](https://youtu.be/rIZ-ILUv9ME?si=raygUXVPd_7ypWuE) / [Frontend Ruby with Glimmer DSL for Web \[/dev/mtl 2024\]](https://www.youtube.com/watch?v=J2VIY9DMJo4)) / [Frontend Ruby with Glimmer DSL for Web at Ruby on Rio 2025-06-06 Talk](https://www.youtube.com/watch?v=LY6ulYICuzE) / [Frontend Ruby on Rails with Glimmer DSL for Web at RubyConf Austria 2026](https://www.youtube.com/watch?v=qTukq5AcSK0))**

**(Ruby Rogues Podcast: [Building Better Ruby Apps: Glimmer Component Slots and More](https://topenddevs.com/podcasts/ruby-rogues/episodes/building-better-ruby-apps-glimmer-s-component-slots-and-more-ruby-653))**

[![Todo MVC](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-regular-todo-mvc.gif)](https://sample-glimmer-dsl-web-rails7-app-black-sound-6793.fly.dev/)

**Endorsement:** *"I'd like to endorse Andy Maleh’s work (Glimmer DSL for Web). I got introduced to it at RubyConf 2024 and have been playing around with it pretty successfully. What I have found most interesting is that I have been writing inside of a rails app, where I have been running the same code for models and presenters inside of MRI rspec. That way I can write tests that verify behavior of the presenters and models and still see them run successfully in the browser. That allows me to have a very nice cycle of refactoring and being confident in my changes without even running it in browser. I just assume that the binding will work and it usually works perfectly."* - Steve Tuckner on January 9, 2024

You can finally live in pure Rubyland on the Web in both the frontend and backend with [Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web)! [Glimmer](https://github.com/AndyObtiva/glimmer) DSL for Web enables building Web Frontends (aka SPA: Single Page Applications) using [Ruby in the Browser](https://www.youtube.com/watch?v=4AdcfbI6A4c), as per [Matz's recommendation in his RubyConf 2022 keynote speech to replace JavaScript with Ruby](https://youtu.be/knutsgHTrfQ?t=789). It supports Rails' principle of the One Person Framework by not requiring any extra developers with JavaScript expertise, yet enabling Ruby (Backend) Software Engineers to develop the Frontend with Ruby code that is better than any JavaScript code produced by JS developers. It aims at providing the simplest, most intuitive, most straight-forward, and most productive frontend framework in existence. The framework follows the Ruby way (with [DSLs](https://martinfowler.com/books/dsl.html) and [TIMTOWTDI](https://en.wiktionary.org/wiki/TMTOWTDI#English)) and the Rails way ([Convention over Configuration](https://rubyonrails.org/doctrine)) in building Isomorphic Ruby on Rails Applications. It provides a Ruby [HTML DSL](#usage) (including full support for [SVG](#hello-svg)), which uniquely enables writing both structure code and logic code in one language. It supports both Unidirectional (One-Way) [Data-Binding](#hello-data-binding) (using `<=`) and Bidirectional (Two-Way) [Data-Binding](#hello-data-binding) (using `<=>`). Dynamic rendering (and re-rendering) of HTML content is also supported via [Content Data-Binding](#hello-content-data-binding). Modular design is supported with [Glimmer Web Components](#hello-component) (including a standalone general components gem called [glimmer-web-components](https://github.com/AndyObtiva/glimmer-web-components)), [Component Slots](#hello-component-slots), Component Attribute Listeners, and [Component Custom Event Listeners](#hello-component-listeners). And, a Ruby CSS DSL is supported with the included [Glimmer DSL for CSS](https://github.com/AndyObtiva/glimmer-dsl-css). To automatically convert legacy HTML & CSS code to Glimmer DSL Ruby code, Software Engineers could use the included [`html_to_glimmer`](https://github.com/AndyObtiva/glimmer-dsl-xml#html-to-glimmer-converter) and [`css_to_glimmer`](https://github.com/AndyObtiva/glimmer-dsl-css#css-to-glimmer-converter) commands. Many [samples](#samples) are demonstrated in the [Rails sample app](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app) (there is a very minimal [Standalone [No Rails] static site sample app](https://github.com/Largo/glimmer-dsl-web-standalone-demo) too).

You can finally have Ruby developer happiness and productivity in the Frontend! No more wasting time splitting your resources across multiple languages, using badly engineered, over-engineered, or premature-optimization-obsessed JavaScript libraries, fighting JavaScript build issues (e.g. webpack), or rewriting Ruby Backend code in Frontend JavaScript. With [Ruby in the Browser](https://www.youtube.com/watch?v=4AdcfbI6A4c), you can have an exponential jump in development productivity (2x or higher), time-to-release (1/2 or less time), cost (1/2 or cheaper), and maintainability (~50% the code that is simpler and more readable) over JavaScript libraries like React, Angular, Ember, Vue, and Svelte, while being able to reuse Backend Ruby code as is in the Frontend for faster interactions when needed. Also, with Frontend Ruby SPA (Single Page Applications), companies can cut their hiring budget in half by having Backend Ruby Software Engineers do Frontend Development in Ruby! [Ruby in the Browser](https://www.youtube.com/watch?v=4AdcfbI6A4c) finally fulfills every smart highly-productive Rubyist's dream by bringing Ruby productivity fun to Frontend Development, the same productivity fun you had for years and decades in Backend Development.

[Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web) aims to be a very simple Ruby-based SPA drop-in replacement for your existing JavaScript Frontend SPA library (e.g. React, Angular, Vue, Ember, Svelte) or your JavaScript Frontend layer in general. It does not change how your Frontend interacts with the Backend, meaning you can continue to write Rails Backend API endpoints as needed and make HTTP/Ajax requests or read data embedded in elements, but from [Ruby in the Browser](https://www.youtube.com/watch?v=4AdcfbI6A4c). Whatever is possible in JavaScript is possible when using Glimmer DSL for Web as it integrates with any existing JavaScript library. The [Rails sample app](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app) demonstrates how to [make HTTP calls](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app/blob/master/app/assets/opal/sample_selector/models/sample_api.rb) or [Rails REST API index/show/create/update/destroy web requests for Resources](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app/blob/master/app/assets/opal/contact_manager/presenters/contact_presenter.rb) via [Rails::ResourceService](/lib/rails/resource_service.rb) and how to [integrate with a JavaScript library](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app/blob/master/app/views/layouts/application.html.erb) (highlightjs) that performs [code syntax highlighting](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app/blob/master/app/assets/opal/sample_selector.rb). [Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web) currently runs on [Opal](https://opalrb.com/) ([Fukuoka Ruby 2023 Award Winner](https://www.digitalfukuoka.jp/topics/228?locale=ja)), a Ruby-to-JavaScript transpiler. In the future, it might support other Frontend Ruby environments, such as [ruby.wasm](https://github.com/ruby/ruby.wasm).

After looking through the [samples](#samples) below, read the [FAQ (Frequently Asked Questions)](#faq) to learn more about how Glimmer DSL for Web compares to other approaches/libraries like Hotwire (Turbo), Phlex, ViewComponent, Angular, Vue, React, Svelte, and other JS frameworks.

Anyone not considering this kind of technology in 2024 is like someone stuck in the dark ages riding horse carriage (e.g. JavaScript developers using frameworks like React) despite cars having been invented already and providing exponential jumps in productivity (way more than small linear jumps provided by some JavaScript libraries, which are akin of modifying horse carriage). Obviously, those who do make this jump will end up winning their work over from customers and beating the competition while delivering the best Frontend value possible to customers.

(Attention Software Engineers, Bloggers, and Contributors: Please use Glimmer DSL for Web in web projects, blog about it, and submit a PR with your article, project, and/or open-source-repo added to the README. Also, I give everyone permission to present this project at their local Ruby user group, local Software Engineering meetup, or Software Conferences outside of North America (e.g. Europe). I am willing to present at Software Conferences in North America and Japan (the birthplace of Ruby) only. If you want to have this project presented elsewhere, like in Europe or South America, feel free to prepare and give your own presentations of the project, and if needed, hit me up for help on the [Glimmer Gitter chat](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge))

**Hello, World! Sample**

(Note: in real app development, we build [Glimmer Web Components](#hello-component) and we rely on the [glimmer_component Rails Helper](#hello-glimmer_component-rails-helper) to embed components in ERB Views without needing `Document.ready?`, but this sample is just introducing basic building blocks towards building [components](#hello-component))

[lib/glimmer-dsl-web/samples/hello/hello_world.rb](/lib/glimmer-dsl-web/samples/hello/hello_world.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

include Glimmer

Document.ready? do
  div {
    'Hello, World!'
  }
end
```

That produces the following under `<body></body>`:

```html
<div data-parent="body" class="element element-1">
  Hello, World!
</div>
```

![setup is working](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-setup-example-working.png)

You can also mount the `div` elsewhere by passing the `parent: parent_css_selector` option (e.g. `div(parent: 'div#app-container') { 'Hello, World!' }`).

**Hello, Button!**

Event listeners can be setup on any element using the same event names used in HTML (e.g. `onclick`) while passing in a standard Ruby block to handle behavior. `$$` gives access to JS global scope from Ruby to invoke functions like `alert`.

[lib/glimmer-dsl-web/samples/hello/hello_button.rb](/lib/glimmer-dsl-web/samples/hello/hello_button.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

include Glimmer

Document.ready? do
  div {
    button('Greet') {
      onclick do
        $$.alert('Hello, Button!')
      end
    }
  }
end
```

That produces the following under `<body></body>`:

```html
<div data-parent="body" class="element element-1">
  <button class="element element-2">Greet</button>
</div>
```

Screenshot:

![Hello, Button!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-button.gif)

**Hello, Form!**

[Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web) gives access to all Web Browser built-in features like HTML form validations, input focus, events, and element functions from a very terse and productive Ruby HTML DSL. Also, you can apply CSS styles by including directly in Ruby code as a string, using [Glimmer DSL for CSS](https://github.com/AndyObtiva/glimmer-dsl-css), or managing CSS completely separately using something like [SCSS](https://sass-lang.com/). The CSS techniques could be combined as well, like by managing common reusable CSS styles separately in SCSS, but adding component specific CSS styles in Ruby when it is more convenient.

[lib/glimmer-dsl-web/samples/hello/hello_form.rb](/lib/glimmer-dsl-web/samples/hello/hello_form.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

include Glimmer

Document.ready? do
  div {
    h1('Contact Form')
    
    form {
      div {
        label('Name: ', for: 'name-field')
        @name_input = input(:required, :autofocus, type: 'text', id: 'name-field')
      }
      
      div {
        label('Email: ', for: 'email-field')
        @email_input = input(:required, type: 'email', id: 'email-field')
      }
      
      div {
        input(type: 'submit', value: 'Add Contact') {
          onclick do |event|
            if ([@name_input, @email_input].all? {|input| input.check_validity })
              # re-open table content and add row
              @table.content {
                tr {
                  td { @name_input.value }
                  td { @email_input.value }
                }
              }
              @email_input.value = @name_input.value = ''
              @name_input.focus
            end
          end
        }
      }
    }
    
    h1('Contacts Table')
    
    @table = table {
      tr {
        th('Name')
        th('Email')
      }
      
      tr {
        td('John Doe')
        td('johndoe@example.com')
      }
      
      tr {
        td('Jane Doe')
        td('janedoe@example.com')
      }
    }
    
    # CSS Styles
    style {
      # CSS can be included as a String as done below, or as Glimmer DSL for CSS syntax (Ruby code) as done in other samples
      <<~CSS
        input {
          margin: 5px;
        }
        input[type=submit] {
          margin: 5px 0;
        }
        table {
          border:1px solid grey;
          border-spacing: 0;
        }
        table tr td, table tr th {
          padding: 5px;
        }
        table tr:nth-child(even) {
          background: #ccc;
        }
      CSS
    }
  }
end
```

That produces the following under `<body></body>`:

```html
<div data-parent="body" class="element element-1">
  <h1 class="element element-2">Contact Form</h1>
  
  <form class="element element-3">
    <div class="element element-4">
      <label for="name-field" class="element element-5">Name: </label>
      <input type="text" id="name-field" required="true" autofocus="true" class="element element-6">
    </div>
    
    <div class="element element-7">
      <label for="email-field" class="element element-8">Email: </label>
      <input type="email" id="email-field" required="true" class="element element-9">
    </div>
    
    <div class="element element-10">
      <input type="submit" value="Add Contact" class="element element-11">
    </div>
  </form>
  
  <h1 class="element element-12">Contacts Table</h1>
  
  <table class="element element-13">
    <tr class="element element-14">
      <th class="element element-15">Name</th>
      <th class="element element-16">Email</th>
    </tr>
    
    <tr class="element element-17">
      <td class="element element-18">John Doe</td>
      <td class="element element-19">johndoe@example.com</td>
    </tr>
    
    <tr class="element element-20">
      <td class="element element-21">Jane Doe</td>
      <td class="element element-22">janedoe@example.com</td>
    </tr>
  </table>
  
  <style class="element element-23">
    input {
      margin: 5px;
    }
    input[type=submit] {
      margin: 5px 0;
    }
    table {
      border:1px solid grey;
      border-spacing: 0;
    }
    table tr td, table tr th {
      padding: 5px;
    }
    table tr:nth-child(even) {
      background: #ccc;
    }
  </style>
</div>
```

Screenshot:

![Hello, Form!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-form.gif)

**Hello, Data-Binding!**

[Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web) intuitively supports both Unidirectional (One-Way) Data-Binding via the `<=` operator and Bidirectional (Two-Way) Data-Binding via the `<=>` operator, incredibly simplifying how to sync View properties with Model attributes with the simplest code to reason about.

[lib/glimmer-dsl-web/samples/hello/hello_data_binding.rb](/lib/glimmer-dsl-web/samples/hello/hello_data_binding.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

Address = Struct.new(:street, :street2, :city, :state, :zip_code, :billing_and_shipping, keyword_init: true) do
  STATES = {
    "AK"=>"Alaska",
    "AL"=>"Alabama",
    "AR"=>"Arkansas",
    "AS"=>"American Samoa",
    "AZ"=>"Arizona",
    "CA"=>"California",
    "CO"=>"Colorado",
    "CT"=>"Connecticut",
    "DC"=>"District of Columbia",
    "DE"=>"Delaware",
    "FL"=>"Florida",
    "GA"=>"Georgia",
    "GU"=>"Guam",
    "HI"=>"Hawaii",
    "IA"=>"Iowa",
    "ID"=>"Idaho",
    "IL"=>"Illinois",
    "IN"=>"Indiana",
    "KS"=>"Kansas",
    "KY"=>"Kentucky",
    "LA"=>"Louisiana",
    "MA"=>"Massachusetts",
    "MD"=>"Maryland",
    "ME"=>"Maine",
    "MI"=>"Michigan",
    "MN"=>"Minnesota",
    "MO"=>"Missouri",
    "MS"=>"Mississippi",
    "MT"=>"Montana",
    "NC"=>"North Carolina",
    "ND"=>"North Dakota",
    "NE"=>"Nebraska",
    "NH"=>"New Hampshire",
    "NJ"=>"New Jersey",
    "NM"=>"New Mexico",
    "NV"=>"Nevada",
    "NY"=>"New York",
    "OH"=>"Ohio",
    "OK"=>"Oklahoma",
    "OR"=>"Oregon",
    "PA"=>"Pennsylvania",
    "PR"=>"Puerto Rico",
    "RI"=>"Rhode Island",
    "SC"=>"South Carolina",
    "SD"=>"South Dakota",
    "TN"=>"Tennessee",
    "TX"=>"Texas",
    "UT"=>"Utah",
    "VA"=>"Virginia",
    "VI"=>"Virgin Islands",
    "VT"=>"Vermont",
    "WA"=>"Washington",
    "WI"=>"Wisconsin",
    "WV"=>"West Virginia",
    "WY"=>"Wyoming"
  }
  
  def state_code
    STATES.invert[state]
  end
  
  def state_code=(value)
    self.state = STATES[value]
  end

def summary
    string_attributes = to_h.except(:billing_and_shipping)
    summary = string_attributes.values.map(&:to_s).reject(&:empty?).join(', ')
    summary += " (Billing & Shipping)" if billing_and_shipping
    summary
  end
end

@address = Address.new(
  street: '123 Main St',
  street2: 'Apartment 3C, 2nd door to the right',
  city: 'San Diego',
  state: 'California',
  zip_code: '91911',
  billing_and_shipping: true,
)

include Glimmer

Document.ready? do
  div {
    div(style: 'display: grid; grid-auto-columns: 80px 260px;') { |address_div|
      label('Street: ', for: 'street-field')
      input(id: 'street-field') {
        # Bidirectional Data-Binding with <=> ensures input.value and @address.street
        # automatically stay in sync when either side changes
        value <=> [@address, :street]
      }
      
      label('Street 2: ', for: 'street2-field')
      textarea(id: 'street2-field') {
        value <=> [@address, :street2]
      }
      
      label('City: ', for: 'city-field')
      input(id: 'city-field') {
        value <=> [@address, :city]
      }
      
      label('State: ', for: 'state-field')
      select(id: 'state-field') {
        Address::STATES.each do |state_code, state|
          option(value: state_code) { state }
        end
        
        value <=> [@address, :state_code]
      }
      
      label('Zip Code: ', for: 'zip-code-field')
      input(id: 'zip-code-field', type: 'number', min: '0', max: '99999') {
        # Bidirectional Data-Binding with <=> ensures input.value and @address.zip_code
        # automatically stay in sync when either side changes
        # on_write option specifies :to_s method to invoke on value before writing to model attribute
        # to ensure the numeric zip code value is stored as a String
        value <=> [@address, :zip_code,
                    on_write: :to_s,
                  ]
      }
      
      div(style: 'grid-column: 1 / span 2') {
        input(id: 'billing-and-shipping-field', type: 'checkbox') {
          checked <=> [@address, :billing_and_shipping]
        }
        label(for: 'billing-and-shipping-field') {
          'Use this address for both Billing & Shipping'
        }
      }
      
      # Programmable CSS using Glimmer DSL for CSS
      style {
        # `r` is an alias for `rule`, generating a CSS rule
        r("#{address_div.selector} *") {
          margin '5px'
        }
        r("#{address_div.selector} input, #{address_div.selector} select") {
          grid_column '2'
        }
      }
    }
  
    div(style: 'margin: 5px') {
      # Unidirectional Data-Binding is done with <= to ensure @address.summary changes
      # automatically update div.inner_text
      # (computed by changes to address attributes, meaning if street changes,
      # @address.summary is automatically recomputed.)
      inner_text <= [@address, :summary,
                      computed_by: @address.members + ['state_code'],
                    ]
    }
  }
end
```

Screenshot:

![Hello, Data-Binding!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-data-binding.gif)

**Hello, Content Data-Binding!**

If you need to regenerate HTML element content dynamically, you can use Content Data-Binding to effortlessly
rebuild HTML elements based on changes in a Model attribute that provides the source data.
In this example, we generate multiple address forms based on the number of addresses the user has using `content(@user, :address_count)` (you can add a `computed_by: array_of_attributes` option if you want to re-render content based on changes to multiple attributes like `content(@user, computed_by: [:address_count, :street_count])`, which fires on changes to `address_count` or `street_count`) .

[lib/glimmer-dsl-web/samples/hello/hello_content_data_binding.rb](/lib/glimmer-dsl-web/samples/hello/hello_content_data_binding.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

class Address
  attr_accessor :text
  attr_reader :name, :street, :city, :state, :zip
  
  def name=(value)
    @name = value
    update_text
  end
  
  def street=(value)
    @street = value
    update_text
  end
  
  def city=(value)
    @city = value
    update_text
  end
  
  def state=(value)
    @state = value
    update_text
  end
  
  def zip=(value)
    @zip = value
    update_text
  end
  
  private
  
  def update_text
    self.text = [name, street, city, state, zip].compact.reject(&:empty?).join(', ')
  end
end

class User
  attr_accessor :addresses
  attr_reader :address_count
  
  def initialize
    @address_count = 1
    @addresses = []
    update_addresses
  end
  
  def address_count=(value)
    value = [[1, value.to_i].max, 3].min
    @address_count = value
    update_addresses
  end
  
  private
  
  def update_addresses
    address_count_change = address_count - addresses.size
    if address_count_change > 0
      address_count_change.times { addresses << Address.new }
    else
      address_count_change.abs.times { addresses.pop }
    end
  end
end

@user = User.new

include Glimmer

Document.ready? do
  div {
    div {
      label('Number of addresses: ', for: 'address-count-field')
      input(id: 'address-count-field', type: 'number', min: 1, max: 3) {
        value <=> [@user, :address_count]
      }
    }
    
    div {
      # Content Data-Binding is used to dynamically (re)generate content of div
      # based on changes to @user.addresses, replacing older content on every change
      content(@user, :address_count) do
        @user.addresses.each do |address|
          div {
            div(style: 'display: grid; grid-auto-columns: 80px 280px;') { |address_div|
              [:name, :street, :city, :state, :zip].each do |attribute|
                label(attribute.to_s.capitalize, for: "#{attribute}-field")
                input(id: "#{attribute}-field", type: 'text') {
                  value <=> [address, attribute]
                }
              end
              
              div(style: 'grid-column: 1 / span 2;') {
                inner_text <= [address, :text]
              }
              
              style {
                r(address_div.selector) {
                  margin '10px 0'
                }
                r("#{address_div.selector} *") {
                  margin '5px'
                }
                r("#{address_div.selector} label") {
                  grid_column '1'
                }
                r("#{address_div.selector} input, #{address_div.selector} select") {
                  grid_column '2'
                }
              }
            }
          }
        end
      end
    }
  }
end
```

Screenshot:

![Hello, Content Data-Binding!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-content-data-binding.gif)

**Hello, Component!**

You can define Glimmer web components (View components) to reuse visual concepts to your heart's content,
by simply defining a class with `include Glimmer::Web::Component` and encasing the reusable markup inside
a `markup {...}` block. Glimmer web components automatically extend the Glimmer HTML DSL with new keywords
that match the underscored versions of the component class names (e.g. an `OrderSummary` class yields
the `order_summary` keyword for reusing that component within the Glimmer HTML DSL).
You may insert a Glimmer component anywhere into a Rails View using `glimmer_component(component_path, *args)`
Rails helper (more about it in [Hello, glimmer_component Rails Helper!](#hello-glimmer_component-rails-helper)).
Below, we define an `AddressForm` component that generates an `address_form` keyword, and then we
reuse it twice inside an `AddressPage` component displaying a Shipping Address and a Billing Address.

You can specify CSS styles that apply to all instances of a component by opening a `style {...}` block, which is
evaluated against the component class given that it applies to all instances.
That would automatically generate one `<style>` element for a component inside `<head>` if at least one instance
of it exists. Every Glimmer web component's markup root element will automatically get a CSS class matching its Ruby
class name underscored, which can be used to scope styles for all component instances inside its `style {...}` block.
For example, `AddressForm` gets the CSS class `address-form` on its top-level `div`. You can find out the default CSS class
that is attached to every component by calling `ComponentClass.component_element_class`. You can get a CSS selector version of
it by calling `ComponentClass.component_element_selector`.

[lib/glimmer-dsl-web/samples/hello/hello_component.rb](/lib/glimmer-dsl-web/samples/hello/hello_component.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

Address = Struct.new(:full_name, :street, :street2, :city, :state, :zip_code, keyword_init: true) do
  STATES = {
    "AK"=>"Alaska",
    "AL"=>"Alabama",
    "AR"=>"Arkansas",
    "AS"=>"American Samoa",
    "AZ"=>"Arizona",
    "CA"=>"California",
    "CO"=>"Colorado",
    "CT"=>"Connecticut",
    "DC"=>"District of Columbia",
    "DE"=>"Delaware",
    "FL"=>"Florida",
    "GA"=>"Georgia",
    "GU"=>"Guam",
    "HI"=>"Hawaii",
    "IA"=>"Iowa",
    "ID"=>"Idaho",
    "IL"=>"Illinois",
    "IN"=>"Indiana",
    "KS"=>"Kansas",
    "KY"=>"Kentucky",
    "LA"=>"Louisiana",
    "MA"=>"Massachusetts",
    "MD"=>"Maryland",
    "ME"=>"Maine",
    "MI"=>"Michigan",
    "MN"=>"Minnesota",
    "MO"=>"Missouri",
    "MS"=>"Mississippi",
    "MT"=>"Montana",
    "NC"=>"North Carolina",
    "ND"=>"North Dakota",
    "NE"=>"Nebraska",
    "NH"=>"New Hampshire",
    "NJ"=>"New Jersey",
    "NM"=>"New Mexico",
    "NV"=>"Nevada",
    "NY"=>"New York",
    "OH"=>"Ohio",
    "OK"=>"Oklahoma",
    "OR"=>"Oregon",
    "PA"=>"Pennsylvania",
    "PR"=>"Puerto Rico",
    "RI"=>"Rhode Island",
    "SC"=>"South Carolina",
    "SD"=>"South Dakota",
    "TN"=>"Tennessee",
    "TX"=>"Texas",
    "UT"=>"Utah",
    "VA"=>"Virginia",
    "VI"=>"Virgin Islands",
    "VT"=>"Vermont",
    "WA"=>"Washington",
    "WI"=>"Wisconsin",
    "WV"=>"West Virginia",
    "WY"=>"Wyoming"
  }
  
  def state_code
    STATES.invert[state]
  end
  
  def state_code=(value)
    self.state = STATES[value]
  end

def summary
    to_h.values.map(&:to_s).reject(&:empty?).join(', ')
  end
end

# AddressForm Glimmer Web Component (View component)
#
# Including Glimmer::Web::Component makes this class a View component and automatically
# generates a new Glimmer HTML DSL keyword that matches the lowercase underscored version
# of the name of the class. AddressForm generates address_form keyword, which can be used
# elsewhere in Glimmer HTML DSL code as done inside AddressPage below.
class AddressForm
  include Glimmer::Web::Component
  
  option :address
  
  # Optionally, you can execute code before rendering markup.
  # This is useful for pre-setup of variables (e.g. Models) that you would use in the markup.
  #
  # before_render do
  # end
  
  # Optionally, you can execute code after rendering markup.
  # This is useful for post-setup of extra Model listeners that would interact with the
  # markup elements and expect them to be rendered already.
  #
  # after_render do
  # end
  
  # markup block provides the content of the
  markup {
    div {
      div(style: 'display: grid; grid-auto-columns: 80px 260px;') { |address_div|
        label('Full Name: ', for: 'full-name-field')
        input(id: 'full-name-field') {
          value <=> [address, :full_name]
        }
        
        @somelabel = label('Street: ', for: 'street-field')
        input(id: 'street-field') {
          value <=> [address, :street]
        }
        
        label('Street 2: ', for: 'street2-field')
        textarea(id: 'street2-field') {
          value <=> [address, :street2]
        }
        
        label('City: ', for: 'city-field')
        input(id: 'city-field') {
          value <=> [address, :city]
        }
        
        label('State: ', for: 'state-field')
        select(id: 'state-field') {
          Address::STATES.each do |state_code, state|
            option(value: state_code) { state }
          end

value <=> [address, :state_code]
        }
        
        label('Zip Code: ', for: 'zip-code-field')
        input(id: 'zip-code-field', type: 'number', min: '0', max: '99999') {
          value <=> [address, :zip_code,
                      on_write: :to_s,
                    ]
        }
        
        style {
          r("#{address_div.selector} *") {
            margin '5px'
          }
          r("#{address_div.selector} input, #{address_div.selector} select") {
            grid_column '2'
          }
        }
      }
      
      div(style: 'margin: 5px') {
        inner_text <= [address, :summary,
                        computed_by: address.members + ['state_code'],
                      ]
      }
    }
  }
end

# AddressPage Glimmer Web Component (View component)
#
# This View component represents the main page being rendered,
# as done by its `render` class method below
class AddressPage
  include Glimmer::Web::Component
  
  before_render do
    @shipping_address = Address.new(
      full_name: 'Johnny Doe',
      street: '3922 Park Ave',
      street2: 'PO BOX 8382',
      city: 'San Diego',
      state: 'California',
      zip_code: '91913',
    )
    @billing_address = Address.new(
      full_name: 'John C Doe',
      street: '123 Main St',
      street2: 'Apartment 3C',
      city: 'San Diego',
      state: 'California',
      zip_code: '91911',
    )
  end
  
  markup {
    div {
      h1('Shipping Address')
      
      address_form(address: @shipping_address)
      
      h1('Billing Address')
      
      address_form(address: @billing_address)
    }
  }
end

Document.ready? do
  # renders a top-level (root) AddressPage component
  AddressPage.render
end
```

Screenshot:

![Hello, Component!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-component.png)

**Hello, glimmer_component Rails Helper!**

You may insert a Glimmer component anywhere into a Rails View using
`glimmer_component(component_path, *args)` Rails helper. Add `include GlimmerHelper` to `ApplicationHelper`
or another Rails helper, and use `<%= glimmer_component("path/to/component", *args) %>` in Views.

[lib/glimmer-dsl-web/samples/hello/hello_glimmer_component_helper/address_form.rb](/lib/glimmer-dsl-web/samples/hello/hello_glimmer_component_helper/address_form.rb)

Rails `ApplicationHelper` setup code:

```ruby
require 'glimmer/helpers/glimmer_helper'

module ApplicationHelper
  # ...
  include GlimmerHelper
  # ...
end
```

Rails View code:

```erb
<div id="address-container">
  <h1>Shipping Address </h1>
  <legend>Please enter your shipping address information (Zip Code must be a valid 5 digit number)</legend>
  
  <%= glimmer_component('address_form',
        full_name: params[:full_name],
        street: params[:street],
        street2: params[:street2],
        city: params[:city],
        state: params[:state],
        zip_code: params[:zip_code]
      )
   %>
   <div>
     <a href="/">&lt;&lt; Back Home</a>
   </div>
</div>
```

Glimmer HTML DSL Ruby code in the frontend (`app/assets/opal/address_form.rb`):

```ruby
require 'glimmer-dsl-web'

class AddressForm
  Address = Struct.new(:full_name, :street, :street2, :city, :state, :zip_code, keyword_init: true) do
    def state_code
      STATES.invert[state]
    end
    
    def state_code=(value)
      self.state = STATES[value]
    end
  
    def summary
      to_h.values.map(&:to_s).reject(&:empty?).join(', ')
    end
  end
  
  STATES = {
    "AK"=>"Alaska",
    "AL"=>"Alabama",
    "AR"=>"Arkansas",
    "AS"=>"American Samoa",
    "AZ"=>"Arizona",
    "CA"=>"California",
    "CO"=>"Colorado",
    "CT"=>"Connecticut",
    "DC"=>"District of Columbia",
    "DE"=>"Delaware",
    "FL"=>"Florida",
    "GA"=>"Georgia",
    "GU"=>"Guam",
    "HI"=>"Hawaii",
    "IA"=>"Iowa",
    "ID"=>"Idaho",
    "IL"=>"Illinois",
    "IN"=>"Indiana",
    "KS"=>"Kansas",
    "KY"=>"Kentucky",
    "LA"=>"Louisiana",
    "MA"=>"Massachusetts",
    "MD"=>"Maryland",
    "ME"=>"Maine",
    "MI"=>"Michigan",
    "MN"=>"Minnesota",
    "MO"=>"Missouri",
    "MS"=>"Mississippi",
    "MT"=>"Montana",
    "NC"=>"North Carolina",
    "ND"=>"North Dakota",
    "NE"=>"Nebraska",
    "NH"=>"New Hampshire",
    "NJ"=>"New Jersey",
    "NM"=>"New Mexico",
    "NV"=>"Nevada",
    "NY"=>"New York",
    "OH"=>"Ohio",
    "OK"=>"Oklahoma",
    "OR"=>"Oregon",
    "PA"=>"Pennsylvania",
    "PR"=>"Puerto Rico",
    "RI"=>"Rhode Island",
    "SC"=>"South Carolina",
    "SD"=>"South Dakota",
    "TN"=>"Tennessee",
    "TX"=>"Texas",
    "UT"=>"Utah",
    "VA"=>"Virginia",
    "VI"=>"Virgin Islands",
    "VT"=>"Vermont",
    "WA"=>"Washington",
    "WI"=>"Wisconsin",
    "WV"=>"West Virginia",
    "WY"=>"Wyoming"
  }

include Glimmer::Web::Component
  
  option :full_name
  option :street
  option :street2
  option :city
  option :state
  option :zip_code
  
  attr_reader :address
  
  before_render do
    @address = Address.new(
      full_name: full_name,
      street: street,
      street2: street2,
      city: city,
      state: state,
      zip_code: zip_code,
    )
  end
  
  markup {
    div {
      div(style: 'display: grid; grid-auto-columns: 80px 260px;') { |address_div|
        label('Full Name: ', for: 'full-name-field')
        input(id: 'full-name-field') {
          value <=> [address, :full_name]
        }
        
        @somelabel = label('Street: ', for: 'street-field')
        input(id: 'street-field') {
          value <=> [address, :street]
        }
        
        label('Street 2: ', for: 'street2-field')
        textarea(id: 'street2-field') {
          value <=> [address, :street2]
        }
        
        label('City: ', for: 'city-field')
        input(id: 'city-field') {
          value <=> [address, :city]
        }
        
        label('State: ', for: 'state-field')
        select(id: 'state-field') {
          STATES.each do |state_code, state|
            option(value: state_code) { state }
          end

Screenshot:

![Hello, glimmer_component Rails Helper!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-component.png)

**Hello, Paragraph!**

To facilitate building formatted textual paragraphs in Ruby, thanks to [Glimmer](https://github.com/AndyObtiva/glimmer#dsl-engine), the most advanced DSL engine in Ruby, the Glimmer HTML DSL is advanced enough to intelligently behave differently under different situations, like when using HTML formatting elements: `<br>`, `<strong>`, `<em>`, `<br>`, `<i>`, `<sub>`, `<sup>`, `<del>`, `<ins>`, `<small>`, `<mark>`

Instead of returning Ruby objects that are nested as children within their parent, the Glimmer HTML DSL returns `String` objects directly that can be concatenated to or embedded within other `String` objects via interpolation.

This enables writing code like:

`p {"#{strong('Yesterday, ')}Robert suggested adding a new #{em('feature')} to our software product.#{br}}`

That is close to how it is written in HTML, albeit briefer in Ruby:

`<p><strong>Yesterday, </strong>Robert suggested adding a new <em>feature</em> to our software product.<br></p>`

Formatting elements just like regular elements can accept text content as their first argument or as their block return value. So, the code above could equally be written as follows:

`p {"#{strong{'Yesterday, '}}Robert suggested adding a new #{em{'feature'}} to our software product.#{br}}`

This enables seggregating formatting element attributes if desired, as in this example:

`p {"#{strong(class: 'very-string'){'Yesterday, '}}Robert suggested adding a new #{em(class: 'very-emphasized'){'feature'}} to our software product.#{br}}`

Another way of writing the same code is to pass the text content as the first argument, before attributes:

`p {"#{strong('Yesterday, ', class: 'very-string')}Robert suggested adding a new #{em('feature', class: 'very-emphasized')} to our software product.#{br}}`

One last bit of info to keep in mind is that `<span>` generally generates a normal element, except when used inside a `<p>`'s content block, in which case it is assumed to be used for formatting, so
it returns a `String` to enable code like this:

`p {"#{span('Yesterday, ', style: 'text-decoration: underline;')}Robert suggested adding a new #{em('feature', class: 'very-emphasized')} to our software product.#{br}}`

In any case, below is a full example leveraging the Glimmer HTML DSL alternative approach when utilizing formatting elements underneath a paragraph.

[lib/glimmer-dsl-web/samples/hello/hello_paragraph.rb](/lib/glimmer-dsl-web/samples/hello/hello_paragraph.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

class HelloParagraph
  include Glimmer::Web::Component
  
  markup {
    div {
      h1(class: 'title') {
        'Flying Cars Become 100% Safe with AI Powered Balance!'
      }
      
      p(class: 'intro') {"
        In the early 2030's, #{em('flying cars')} became affordable after their prices dropped
        below #{small(del('$100,000'))}#{ins('$80,000')} as a result of the innovations of #{strong('Travel-X')}. Still, that did not
        make #{em('flying cars')} any popular due to the extreme difficulty in piloting such flying vehicles for the average
        person, making it very tough to pass the tests for getting a piloting license given the learning curve.
      "}
      
      p {"
        That said, #{b('Travel-X')} has recently come up with a new feature for their flagship #{i('flying car')},
        the Ptero#{sub(1)}#{sup('TM')}, which relies on AI#{sub(2)} to automatically balance the flying cars in mid-air,
        thus significantly facilitating their piloting by the average consumer.
      "}
      
      p(class: 'conclusion') {"
        That Ptero#{sup('TM')} will be so stable and well balanced while flying that the consumer will be able to drive
        as if it is a plain old car, with the only difference being vertical elevation, the control of which will be handled
        automatically by AI. The Ptero#{sup('TM')} will debut for #{span(style: 'text-decoration: underline dashed;'){'$79,000'}}.
      "}
      
      h2(class: 'legend-title') {
        mark('Legend:')
      }
      
      p(class: 'legend') {"
        #{strong("1- Ptero:")} Pterosaur is flying dinosaur species#{br}
        #{strong("2- AI:")} Artificial Intelligence#{br}
      "}
        
    }
  }
end

Document.ready? do
  HelloParagraph.render
end
```

Screenshot:

![Hello, Paragraph!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-paragraph.png)

**Hello, Observer!**

[Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web) provides the `observe(model, attribute) { ... }` keyword to employ the [Observer Design Pattern](https://en.wikipedia.org/wiki/Observer_pattern) as per [MVC](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) (Model View Controller), enabling Views to observe Models and update themselves in response to changes. If the `observe` keyword is used from inside a [Component](#hello-component), when the Component is removed or its top-level element is removed, the observer is automatically cleaned up. The need for such explicit observers is significantly diminished by the availablility of the more advanced Unidirectional [Data-Binding](#hello-data-binding) Support and Bidirectional [Data-Binding](#hello-data-binding) Support.

[lib/glimmer-dsl-web/samples/hello/hello_observer.rb](/lib/glimmer-dsl-web/samples/hello/hello_observer.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

class NumberHolder
  attr_accessor :number
  
  def initialize
    self.number = 50
  end
end

class HelloObserver
  include Glimmer::Web::Component
  
  before_render do
    @number_holder = NumberHolder.new
  end
  
  after_render do
    @number_input.value = @number_holder.number
    @range_input.value = @number_holder.number
    
    # Observe Model attribute @number_holder.number for changes and update View elements.
    # Observer is automatically cleaned up when `remove` method is called on rendered
    # HelloObserver web component or its top-level markup element (div)
    observe(@number_holder, :number) do
      number_string = @number_holder.number.to_s
      @number_input.value = number_string unless @number_input.value == number_string
      @range_input.value = number_string unless @range_input.value == number_string
    end
    # Bidirectional Data-Binding does the same thing automatically as per alternative sample: Hello, Observer (Data-Binding)!
  end
  
  markup {
    div {
      div {
        @number_input = input(type: 'number', min: 0, max: 100) {
          # oninput listener (observer) updates Model attribute @number_holder.number
          oninput do
            @number_holder.number = @number_input.value.to_i
          end
        }
      }
      div {
        @range_input = input(type: 'range', min: 0, max: 100) {
          # oninput listener (observer) updates Model attribute @number_holder.number
          oninput do
            @number_holder.number = @range_input.value.to_i
          end
        }
      }
    }
  }
end
```

Screenshot:

![Hello, Observer!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-observer.gif)

**Hello, Observer (Data-Binding)!**

This is the data-binding edition of Hello, Observer!, which uses the `<=>` operator to perform bidirectional data-binding between a View property and a Model attribute, thus yield a lot less code that is declarative and is the most minimal code possible to express the requirements.

[lib/glimmer-dsl-web/samples/hello/hello_observer_data_binding.rb](/lib/glimmer-dsl-web/samples/hello/hello_observer_data_binding.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

class NumberHolder
  attr_accessor :number
  
  def initialize
    self.number = 50
  end
end

class HelloObserver
  include Glimmer::Web::Component
  
  before_render do
    @number_holder = NumberHolder.new
  end
  
  markup {
    div {
      div {
        input(type: 'number', min: 0, max: 100) {
          value <=> [@number_holder, :number]
        }
      }
      div {
        input(type: 'range', min: 0, max: 100) {
          value <=> [@number_holder, :number]
        }
      }
    }
  }
end

Document.ready? do
  HelloObserver.render
end
```

Screenshot:

![Hello, Observer!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-observer.gif)

**Todo MVC**

[Todo MVC Ruby Edition Is the One Todo MVC To Rule Them All!!!](https://andymaleh.blogspot.com/2024/06/todo-mvc-in-ruby-is-one-todo-mvc-to.html)

[lib/glimmer-dsl-web/samples/regular/todo_mvc.rb](/lib/glimmer-dsl-web/samples/regular/todo_mvc.rb)

[lib/glimmer-dsl-web/samples/regular/todo_mvc](/lib/glimmer-dsl-web/samples/regular/todo_mvc)

```ruby
require 'glimmer-dsl-web'

require_relative 'todo_mvc/presenters/todo_presenter'

require_relative 'todo_mvc/views/new_todo_form'
require_relative 'todo_mvc/views/todo_list'
require_relative 'todo_mvc/views/todo_filters'
require_relative 'todo_mvc/views/todo_mvc_footer'

class TodoMvc
  include Glimmer::Web::Component
  
  before_render do
    @presenter = TodoPresenter.new
  end
  
  after_render do
    @presenter.setup_filter_routes
  end
  
  markup {
    div(class: 'todomvc') {
      section(class: 'todoapp') {
        new_todo_form(presenter: @presenter)
        
        todo_list(presenter: @presenter)
        
        todo_filters(presenter: @presenter)
      }
      
      todo_mvc_footer
      
      on_remove do
        @presenter.unsetup_filter_routes
      end
    }
  }
  
  style {
    r('body, button, html') {
      margin 0
      padding 0
    }
    
    r('button') {
      _webkit_font_smoothing :antialiased
      _webkit_appearance :none
      appearance :none
      background :none
      border 0
      color :inherit
      font_family :inherit
      font_size '100%'
      font_weight :inherit
      vertical_align :baseline
    }
    
    r('.todoapp') {
      background '#fff'
      margin '130px 0 40px 0'
      position :relative
      box_shadow '0 2px 4px 0 rgba(0, 0, 0, 0.2), 0 25px 50px 0 rgba(0, 0, 0, 0.1)'
    }
  
    media('screen and (-webkit-min-device-pixel-ratio:0)') {
      r('body') {
        font "14px 'Helvetica Neue', Helvetica, Arial, sans-serif"
        line_height 1.4.em
        background '#f5f5f5'
        color '#111111'
        min_width 230
        max_width 550
        margin '0 auto'
        _webkit_font_smoothing :antialiased
        font_weight '300'
      }
    }
  }
end

Document.ready? do
  TodoMvc.render
end
```

![Todo MVC](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-regular-todo-mvc.gif)

To get started, [Setup](#setup) Ruby gem, read [Usage](#usage) instructions, and check out more [Samples](#samples) (including playing around with a [Rails sample app](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app)).

NOTE: Glimmer DSL for Web is a Beta project. If you want it developed faster, please [open an issue report](https://github.com/AndyObtiva/glimmer-dsl-web/issues/new). I have completed some GitHub project features much faster before due to [issue reports](https://github.com/AndyObtiva/glimmer-dsl-web/issues) and [pull requests](https://github.com/AndyObtiva/glimmer-dsl-web/pulls). Please help make better by contributing, adopting for small or low risk projects, and providing feedback. It is still a Beta, so the more feedback and issues you report the better.

Learn more about the differences between various [Glimmer](https://github.com/AndyObtiva/glimmer) DSLs by looking at:

**[Glimmer DSL Comparison Table](https://github.com/AndyObtiva/glimmer#glimmer-dsl-comparison-table)**.

## Table of Contents

- [Glimmer DSL for Web](#)
  - [Prerequisites](#prerequisites)
  - [Setup](#setup)
    - [Rails 8](#rails-8)
    - [Rails 7](#rails-7)
    - [Standalone (No Rails)](#standalone-no-rails)
  - [Usage](#usage)
  - [Supported Glimmer DSL Keywords](#supported-glimmer-dsl-keywords)
  - [Coming from Glimmer DSL for Opal](#coming-from-glimmer-dsl-for-opal)
  - [Samples](#samples)
    - [Hello Samples](#hello-samples)
      - [Hello, World!](#hello-world)
      - [Hello, Button!](#hello-button)
      - [Hello, Form!](#hello-form)
      - [Hello, Form (MVP)!](#hello-form-mvp)
      - [Hello, Observer!](#hello-observer)
      - [Hello, Observer (Data-Binding)!](#hello-observer)
      - [Hello, Data-Binding!](#hello-data-binding)
      - [Hello, Content Data-Binding!](#hello-content-data-binding)
      - [Hello, Component!](#hello-component)
      - [Hello, Component Slots!](#hello-component-slots)
      - [Hello, Component Listeners!](#hello-component-listeners)
      - [Hello, Component Listeners (Default Slot)!](#hello-component-listeners-default-slot)
      - [Hello, Component Attribute Listeners!](#hello-component-attribute-listeners)
      - [Hello, Component Attribute Data-Binding!](#hello-component-attribute-data-binding)
      - [Hello, glimmer_component Rails Helper!](#hello-glimmer_component-rails-helper)
      - [Hello, Modal!](#hello-modal)
      - [Hello, Paragraph!](#hello-paragraph)
      - [Hello, Style!](#hello-style)
      - [Hello, SVG!](#hello-svg)
      - [Hello, Input (Date/Time)!](#hello-input-datetime)
      - [Button Counter](#button-counter)
      - [Todo MVC](#todo-mvc)
  - [Design Principles](#design-principles)
  - [Supporting Libraries](#supporting-libraries)
  - [Influences and Inspiration](#influences-and-inspiration)
  - [Glimmer Process](#glimmer-process)
  - [Help](#help)
    - [Issues](#issues)
    - [Chat](#chat)
  - [Feature Suggestions](#feature-suggestions)
  - [Change Log](#change-log)
  - [Contributing](#contributing)
  - [Contributors](#contributors)
  - [License](#license)

## Prerequisites

[Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web) will begin by supporting [Opal Ruby](https://opalrb.com/) on [Rails](https://rubyonrails.org/). [Opal](https://opalrb.com/) ([Fukuoka Ruby 2023 Award Winner](https://www.digitalfukuoka.jp/topics/228?locale=ja)) is a lightweight Ruby to JavaScript transpiler that results in small downloadables compared to WASM. In the future, the project might grow to support [Ruby WASM](https://github.com/ruby/ruby.wasm) as an alternative to [Opal Ruby](https://opalrb.com/) that could be switched to with a simple configuration change.

- Ruby 3.1+
- Rails 7.0-7.2: [https://github.com/rails/rails](https://github.com/rails/rails)

## Setup

You can setup Glimmer DSL for Web in one of the following ways:

- [Rails 7/8 (Build pipeline)](#rails-78-build-pipeline)
- [Rails 7 (Sprockets pipeline)](#rails-7-sprockets-pipeline)
- [Standalone (No Rails)](#standalone-no-rails)

Once done, read [Usage](#usage) instructions. Note that for serious app usage, it is recommended to build [components](#hello-component) and use the [`glimmer_component` Rails Helper](#hello-glimmer_component-rails-helper) to embed the top-level Web Frontend component in a Rails View.

(NOTE: Keep in mind this is a Beta. If you run into issues, read the [FAQ](#faq) in case they are addressed there (e.g. [I sometimes get an Opal error that makes no sense in relation to my code. How do I fix it?](https://github.com/AndyObtiva/glimmer-dsl-web/blob/master/README.md#i-sometimes-get-an-opal-error-that-makes-no-sense-in-relation-to-my-code-how-do-i-fix-it)) and try to go back to a [previous revision](https://rubygems.org/gems/glimmer-dsl-web/versions). Also, there is a slight chance any issues you encounter are fixed in master or some other branch that you could check out instead)

### Rails 7/8 (Build pipeline)

For the modern build-based `opal-rails` flow, follow [docs/setup/rails_7_8_build_pipeline.md](docs/setup/rails_7_8_build_pipeline.md).

This is the recommended setup for:

- Rails 8 apps
- Rails 7 apps that you want on the same explicit build/watch flow, whether the host app serves assets with Propshaft or Sprockets

It is based on the current `opal-rails` build pipeline and the verified migration path used in the [Sample Glimmer DSL for Web Rails 7 App](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app). In this flow, Rails just serves the compiled assets from `app/assets/builds`; it does not compile Opal source files at request time.

If you are migrating an existing app from the legacy request-time pipeline to this build pipeline, start with [docs/setup/rails_7_8_build_pipeline.md](docs/setup/rails_7_8_build_pipeline.md) and the `opal-rails` porting notes at https://github.com/opal/opal-rails/blob/master/PORTING.md.

### Rails 7 (Sprockets pipeline)

For the legacy Rails 7 + Sprockets/request-time compilation flow, follow [docs/setup/rails_7_sprockets_pipeline.md](docs/setup/rails_7_sprockets_pipeline.md).

That guide explicitly pins `opal-rails` to `~> 2.0.4`. If you are starting a new app or want the newer build/watch workflow, use the build-pipeline guide above instead.

Next, read [Usage](#usage) instructions, and check out [Samples](#samples).

### Standalone (No Rails)

Andreas Idogawa-Wildi ([@Largo](https://github.com/Largo)) created a project that demonstrates how to use Glimmer DSL for Web standalone (without Rails):

[https://github.com/Largo/glimmer-dsl-web-standalone-demo](https://github.com/Largo/glimmer-dsl-web-standalone-demo)

## Usage

### Glimmer HTML DSL

Glimmer DSL for Web offers a HTML DSL ([Graphical User Interface](https://en.wikipedia.org/wiki/Graphical_user_interface) [Domain Specific Language](https://en.wikipedia.org/wiki/Domain-specific_language)) for building HTML Web User Interfaces declaratively in Ruby.

1- **Keywords (HTML Elements)**

You can declare any HTML element by simply using the lowercase version of its name (Ruby convention for method names) like `div`, `span`, `form`, `input`, `button`, `table`, `tr`, `th`, and `td`.

Under the hood, HTML element DSL keywords are invoked as Ruby methods.

2- **Arguments (HTML Attributes + Text Content)**

You can set any HTML element attributes by passing as keyword arguments to element methods like `div(id: 'container', class: 'stack')` or `input(:required, type: 'email')`

Also, if the element has a little bit of text content that can fit in one line, it can be passed as the 1st argument like `label('Name: ', for: 'name_field')`, `button('Calculate', :disabled, class: 'round-button')`, or `span('Mr')`

3- **Content Block (Properties + Listeners + Nested Elements + Text Content)**

Element methods can accept a Ruby content block. It intentionally has a `{...}` style even as a multi-line block to indicate that the code is declarative HTML DSL structure code (intentionally breaking away from Ruby imperative code conventions given this is a declarative HTML DSL ([Domain Specific Language](https://en.wikipedia.org/wiki/Domain-specific_language)), meaning a different language that has its own conventions, embedded within Ruby).

You can nest HTML element properties under an element like:

```ruby
input(type: 'text') {
  content_editable false
}
```

You can nest HTML event listeners under an element by using the HTML event listener name (e.g. `onclick`, `onchange`, `onblur`):

```ruby
button('Add') {
  onclick do
    @model.add_selected_element
  end
}
```

Given that listener code is imperative, it uses a `do; end` style for Ruby blocks to separate it from declarative HTML DSL structure code and enable quicker readability of the code.

You can nest other HTML elements under an HTML element the same way you do so in HTML, like:

```ruby
form {
  div(class: 'field-row') {
    label('Name: ', for: 'name-field')
    input(id: 'name-field', class: 'field', type: 'text', required: true)
  }
  div(class: 'field-row') {
    label('Email: ', for: 'email-field')
    input(id: 'email-field', class: 'field', type: 'email', required: true)
  }
  button('Add Contact', class: 'submit-button') {
    onclick do
      ...
    end
  }
}
```

You can nest text content underneath an element's Ruby block provided it is the return value of the block (last declared value), like:

```ruby
p(class: 'summary') {
  'This text content is going into the body of the span element'
}
```

4- **Operations (Properties + Functions)**

You can get/set any element property or invoke any element function by simply calling the lowercase underscored version of their name in Ruby like `input.check_validity`, `input.value`, and `input.id`.

Next, check out [Samples](#samples).

Note that for serious app usage, it is recommended to build [components](#hello-component) and use the [`glimmer_component` Rails Helper](#hello-glimmer_component-rails-helper) to embed the top-level Web Frontend component in a Rails View.

### Rails::ResourceService

To make REST API calls (web requests) to the Backend of a Rails application in order to index/show/create/update/delete resources,
you can use [Rails::ResourceService](/lib/rails/resource_service.rb) (`require 'rails/resource_service'` to use). Consult
the `Rails::ResourceService` class source code to find out what its API is. It can work with a basic Rails Scaffold of a Resource
if Developers would rather not write the Backend by hand.

`Rails::ResourceService` API:
- `index(resource: nil, resource_class: nil, singular_resource_name: nil, plural_resource_name: nil, index_resource_url: nil, params: nil, root: nil) { |response, resources, metadata| ... }`
- `show(resource: nil, resource_class: nil, resource_id: nil, singular_resource_name: nil, plural_resource_name: nil, show_resource_url: nil, params: nil) { |response, resource| ... }`
- `create(resource: nil, resource_class: nil, resource_attributes: nil, singular_resource_name: nil, plural_resource_name: nil, create_resource_url: nil, params: nil) { |response, created_resource, errors| ... }`
- `update(resource: nil, resource_class: nil, resource_id: nil, resource_attributes: nil, singular_resource_name: nil, plural_resource_name: nil, update_resource_url: nil, params: nil) { |response, updated_resource, errors| ... }`
- `destroy(resource: nil, resource_class: nil, resource_id: nil, singular_resource_name: nil, plural_resource_name: nil, destroy_resource_url: nil, params: nil) { |response| ... }`

`Rails::ResourceService` follows the 'Convention over Configuration' Rails principle as it auto-derives the URL to call based on the `resource` class and data.
`resource` can be a Ruby class with attribute method declarations or `attr_accessor` declarations, or a Ruby `Struct` class.
`Rails::ResourceService` is flexible enough to work with all options.
If you are making an `index` request that receives pagination `metadata`, make sure to specify the `root` argument as `true` (to determine root key by convention) or by specifying a custom `root` explicitly.

Examples from [ContactPresenter](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app/blob/master/app/assets/opal/contact_manager/presenters/contact_presenter.rb) in the [Contact Manager](#contact-manager) sample:

(note: `form_contact` is an instance of the [Contact](https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app/blob/master/app/assets/opal/contact_manager/models/contact.rb) class)

```ruby
  def add_contact
    Rails::ResourceService.create(resource: form_contact) do |response, created_contact, errors|
      if response.ok?
        contacts << created_contact
        form_contact.reset
        form_contact.errors = nil
      else
        form_contact.errors = errors
      end
    end
  end
  
  def update_contact
    Rails::ResourceService.update(resource: form_contact) do |response, updated_contact, errors|
      if response.ok?
        contacts[edit_index].load_with(updated_contact)
        self.edit_index = nil
        form_contact.reset
        form_contact.errors = nil
      else
        form_contact.errors = errors
      end
    end
  end
```

Note that there are alternative ways of invoking the `Rails::ResourceService.update` call:
- `Rails::ResourceService.update(resource: form_contact) { |response, resource, errors| ... }`
- `Rails::ResourceService.update(resource_class: Contact, resource_id: form_contact.id, resource_attributes: {first_name: form_contact.first_name, ...}) { |response, resource, errors| ... }`
- `Rails::ResourceService.update(singular_resource_name: 'contact', resource_id: form_contact.id, resource_attributes: {first_name: form_contact.first_name, ...}) { |response, resource, errors| ... }`
- `Rails::ResourceService.update(update_resource_url: "/contacts/#{form_contact.id}.json", resource_attributes: {first_name: form_contact.first_name, ...}) { |response, resource, errors| ... }`
- `Rails::ResourceService.update(update_resource_url: "/contacts/#{form_contact.id}.json", params: {contact: {first_name: form_contact.first_name, ...}}) { |response, resource, errors| ... }`

### Glimmer::Util::UrlBuilder

`Glimmer::Util::UrlBuilder` is a convenience class that facilitates building URLs (with protocol scheme, host, path, query params, and fragment)

First, make sure to require the class file:
```ruby
require 'glimmer/util/url_builder'
```

Usage:
```ruby
Glimmer::Util::UrlBuilder.new.scheme('http').host('www.google.com').path('/results').param('q', 'sports').fragment('#yesterday').to_url
# => 'http://www.google.com/results?q=sports#yesterday'
```

Or you can start from the URL of the current webpage, and amend the URL with extra params:
```ruby
# Current URL: http://www.google.com/results?q=sports
Glimmer::Util::UrlBuilder.current.param('year', '2036').to_url
# => 'http://www.google.com/results?q=sports&year=2036'
```

### Glimmer::Util::UrlQueryStringBuilder

`Glimmer::Util::UrlQueryStringBuilder` is a convenience class that facilitates building URL query strings

First, make sure to require the class file:
```ruby
require 'glimmer/util/url_builder'
```

Usage:
```ruby
subject.with_question_mark.param('q', 'sports').param('year', '2040').to_s
# => '?q=sports&year=2040'
```

## Supported Glimmer DSL Keywords

[All HTML elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element), following the Ruby method name standard of lowercase and underscored names.

[All HTML attributes](https://www.w3schools.com/html/html_attributes.asp), following the Ruby method name standard of lowercase and underscored names.

[All HTML events](https://www.w3schools.com/tags/ref_eventattributes.asp), same event attribute names as in HTML.

## Coming from Glimmer DSL for Opal

This project is inspired by [Glimmer DSL for Opal](https://github.com/AndyObtiva/glimmer-dsl-opal) and is similar in enabling Web Frontend development with Ruby. [Glimmer DSL for Web](https://rubygems.org/gems/glimmer-dsl-web) mainly differs from Glimmer DSL for Opal by adopting a DSL that follows web-like HTML syntax in Ruby to facilitate leveraging existing HTML/CSS/JS skills instead of adopting a desktop HTML DSL that is webified. As a result, applications written in Glimmer DSL for Opal are not compatible with Glimmer DSL for Web.

## Samples

This external Sample Selector app is built using Rails and Glimmer DSL for Web, including all the samples mentioned below configured inside a Rails [Opal](https://opalrb.com/) web app with all the prerequisites ready to go for convenience (there is a very minimal [Standalone [No Rails] static site sample app](https://github.com/Largo/glimmer-dsl-web-standalone-demo) too):

https://github.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app

A deployed version of the Sample Selector app can be accessed over here:

https://sample-glimmer-dsl-web-rails7-app-black-sound-6793.fly.dev/

[![Sample Selector](https://raw.githubusercontent.com/AndyObtiva/sample-glimmer-dsl-web-rails7-app/master/sample-glimmer-dsl-web-rails7-app.png)](https://sample-glimmer-dsl-web-rails7-app-black-sound-6793.fly.dev/)

### Hello Samples

#### Hello, World!

[lib/glimmer-dsl-web/samples/hello/hello_world.rb](/lib/glimmer-dsl-web/samples/hello/hello_world.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

include Glimmer

Document.ready? do
  div {
    'Hello, World!'
  }
end
```

That produces the following under `<body></body>`:

```html
<div data-parent="body" class="element element-1">
  Hello, World!
</div>
```

![setup is working](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-setup-example-working.png)

Alternative syntax (useful when an element has text content that fits in one line):

```ruby
require 'glimmer-dsl-web'

include Glimmer

Document.ready? do
  div('Hello, World!')
end
```

That produces the following under `<body></body>`:

```html
<div data-parent="body" class="element element-1">
  Hello, World!
</div>
```

![setup is working](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-setup-example-working.png)

You can also mount the `div` elsewhere by passing the `parent: parent_css_selector` option (e.g. `div(parent: 'div#app-container') { 'Hello, World!' }`).

#### Hello, Button!

[lib/glimmer-dsl-web/samples/hello/hello_button.rb](/lib/glimmer-dsl-web/samples/hello/hello_button.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

include Glimmer

Document.ready? do
  div {
    button('Greet') {
      onclick do
        $$.alert('Hello, Button!')
      end
    }
  }
end
```

That produces the following under `<body></body>`:

```html
<div data-parent="body" class="element element-1">
  <button class="element element-2">Greet</button>
</div>
```

Screenshot:

![Hello, Button!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-button.gif)

#### Hello, Form!

[lib/glimmer-dsl-web/samples/hello/hello_form.rb](/lib/glimmer-dsl-web/samples/hello/hello_form.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

include Glimmer

That produces the following under `<body></body>`:

Screenshot:

![Hello, Form!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-form.gif)

#### Hello, Form (MVP)!

This is the MVP (Model-View-Presenter) edition of Hello, Form! leveraging Glimmer Web Components and the MVP Architectural Pattern.

Main file:

[lib/glimmer-dsl-web/samples/hello/hello_form_mvp.rb](/lib/glimmer-dsl-web/samples/hello/hello_form_mvp.rb)

Other files:

[lib/glimmer-dsl-web/samples/hello/hello_form_mvp](/lib/glimmer-dsl-web/samples/hello/hello_form_mvp)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

require_relative 'hello_form_mvp/presenters/hello_form_mvp_presenter'

require_relative 'hello_form_mvp/views/contact_form'
require_relative 'hello_form_mvp/views/contact_table'

class HelloFormMvp
  include Glimmer::Web::Component
  
  before_render do
    @presenter = HelloFormMvpPresenter.new
  end
  
  markup {
    div {
      h1('Contact Form')
      
      contact_form(presenter: @presenter)
      
      h1('Contacts Table')
      
      contact_table(presenter: @presenter)
    }
  }
end

Document.ready? do
  HelloFormMvp.render
end
```

Screenshot:

![Hello, Form!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-form.gif)

#### Hello, Observer!

[lib/glimmer-dsl-web/samples/hello/hello_observer.rb](/lib/glimmer-dsl-web/samples/hello/hello_observer.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

class NumberHolder
  attr_accessor :number
  
  def initialize
    self.number = 50
  end
end

Document.ready? do
  HelloObserver.render
end
```

Screenshot:

![Hello, Observer!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-observer.gif)

#### Hello, Observer (Data-Binding)!

[lib/glimmer-dsl-web/samples/hello/hello_observer_data_binding.rb](/lib/glimmer-dsl-web/samples/hello/hello_observer_data_binding.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

class NumberHolder
  attr_accessor :number
  
  def initialize
    self.number = 50
  end
end

Document.ready? do
  HelloObserver.render
end
```

Screenshot:

![Hello, Observer!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-observer.gif)

#### Hello, Data-Binding!

[lib/glimmer-dsl-web/samples/hello/hello_data_binding.rb](/lib/glimmer-dsl-web/samples/hello/hello_data_binding.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

@address = Address.new(
  street: '123 Main St',
  street2: 'Apartment 3C, 2nd door to the right',
  city: 'San Diego',
  state: 'California',
  zip_code: '91911',
  billing_and_shipping: true,
)

include Glimmer

Screenshot:

![Hello, Data-Binding!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-data-binding.gif)

#### Hello, Content Data-Binding!

If you need to regenerate (re-render) HTML element content dynamically, you can use Content Data-Binding to effortlessly
rebuild (rerender) HTML elements based on changes in a Model attribute that provides the source data.
In this example, we generate multiple address forms based on the number of addresses the user has using `content(@user, :address_count)` (you can add a `computed_by: array_of_attributes` option if you want to re-render content based on changes to multiple attributes like `content(@user, computed_by: [:address_count, :street_count])`, which fires on changes to `address_count` or `street_count`) .

[lib/glimmer-dsl-web/samples/hello/hello_content_data_binding.rb](/lib/glimmer-dsl-web/samples/hello/hello_content_data_binding.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

@user = User.new

include Glimmer

Document.ready? do
  div {
    div {
      label('Number of addresses: ', for: 'address-count-field')
      input(id: 'address-count-field', type: 'number', min: 1, max: 3) {
        value <=> [@user, :address_count]
      }
    }
    
    div {
      # Content Data-Binding is used to dynamically (re)generate content of div
      # based on changes to @user.address_count, replacing older content on every change
      content(@user, :address_count) do
        @user.addresses.each do |address|
          div {
            div(style: 'display: grid; grid-auto-columns: 80px 280px;') { |address_div|
              [:name, :street, :city, :state, :zip].each do |attribute|
                label(attribute.to_s.capitalize, for: "#{attribute}-field")
                input(id: "#{attribute}-field", type: 'text') {
                  value <=> [address, attribute]
                }
              end
              
              div(style: 'grid-column: 1 / span 2;') {
                inner_text <= [address, :text]
              }
              
              style {
                r(address_div.selector) {
                  margin '10px 0'
                }
                r("#{address_div.selector} *") {
                  margin '5px'
                }
                r("#{address_div.selector} label") {
                  grid_column '1'
                }
                r("#{address_div.selector} input, #{address_div.selector} select") {
                  grid_column '2'
                }
              }
            }
          }
        end
      end
    }
  }
end
```

Screenshot:

![Hello, Content Data-Binding!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-content-data-binding.gif)

#### Hello, Component!

[lib/glimmer-dsl-web/samples/hello/hello_component.rb](/lib/glimmer-dsl-web/samples/hello/hello_component.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

def summary
    to_h.values.map(&:to_s).reject(&:empty?).join(', ')
  end
end

Document.ready? do
  # renders a top-level (root) AddressPage component
  AddressPage.render
end
```

Screenshot:

![Hello, Component!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-component.png)

#### Hello, Component Slots!

Component slots enables consumers of components to contribute content in designated areas inside them called slots.

Inside a Glimmer web component, you can designate an element (e.g. `div`) as a component slot by passing the `slot: :slotname` option,
which enables consumers to contribute elements inside the component slot by opening a `slotname {...}` inside the component content block.

If you want content that is added to a component block direclty added to a specific slot by default, you can specify a `default_slot :slot_name`.
In that case, if you ever want to add content to the component markup root element, there is a slot that is always available for that, called `:markup_root_slot`.
The default slot feature is demonstrated in the [Hello, Component Listeners (Default Slot)!](#hello-component-listeners-default-slot) sample.

For an example of using component slots, below is a sample that demonstrates how to contribute slot content to `address_header` and `address_footer` in an `address_form` component.

[lib/glimmer-dsl-web/samples/hello/hello_component_slots.rb](/lib/glimmer-dsl-web/samples/hello/hello_component_slots.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

def summary
    to_h.values.map(&:to_s).reject(&:empty?).join(', ')
  end
end

# AddressForm Glimmer Web Component (View component)
#
# Including Glimmer::Web::Component makes this class a View component and automatically
# generates a new Glimmer HTML DSL keyword that matches the lowercase underscored version
# of the name of the class. AddressForm generates address_form keyword, which can be used
# elsewhere in Glimmer HTML DSL code as done inside HelloComponentSlots below.
class AddressForm
  include Glimmer::Web::Component
  
  option :address
  
  # markup block provides the content of the
  markup {
    div {
      # designate this div as a slot with the slot name :address_header to enable
      # consumers to contribute elements to `address_header {...}` slot
      div(slot: :address_header, class: 'address-form-header')
      
      div(class: 'address-field-container', style: {display: :grid, grid_auto_columns: '80px 260px'}) {
        label('Full Name: ', for: 'full-name-field')
        input(id: 'full-name-field') {
          value <=> [address, :full_name]
        }
        
        @somelabel = label('Street: ', for: 'street-field')
        input(id: 'street-field') {
          value <=> [address, :street]
        }
        
        label('Street 2: ', for: 'street2-field')
        textarea(id: 'street2-field') {
          value <=> [address, :street2]
        }
        
        label('City: ', for: 'city-field')
        input(id: 'city-field') {
          value <=> [address, :city]
        }
        
        label('State: ', for: 'state-field')
        select(id: 'state-field') {
          Address::STATES.each do |state_code, state|
            option(value: state_code) { state }
          end

value <=> [address, :state_code]
        }
        
        label('Zip Code: ', for: 'zip-code-field')
        input(id: 'zip-code-field', type: 'number', min: '0', max: '99999') {
          value <=> [address, :zip_code,
                      on_write: :to_s,
                    ]
        }
      }
      
      div(style: 'margin: 5px') {
        inner_text <= [address, :summary,
                        computed_by: address.members + ['state_code'],
                      ]
      }
      
      # designate this div as a slot with the slot name :address_footer to enable
      # consumers to contribute elements to `address_footer {...}` slot
      div(slot: :address_footer, class: 'address-form-footer')
    }
  }
  
  style {
    r('.address-field-container *') {
      margin 5
    }
    r('.address-field-container input, .address-field-container select') {
      grid_column '2'
    }
  }
end

# HelloComponentSlots Glimmer Web Component (View component)
#
# This View component represents the main page being rendered,
# as done by its `render` class method below
class HelloComponentSlots
  include Glimmer::Web::Component
  
  before_render do
    @shipping_address = Address.new(
      full_name: 'Johnny Doe',
      street: '3922 Park Ave',
      street2: 'PO BOX 8382',
      city: 'San Diego',
      state: 'California',
      zip_code: '91913',
    )
    @billing_address = Address.new(
      full_name: 'John C Doe',
      street: '123 Main St',
      street2: 'Apartment 3C',
      city: 'San Diego',
      state: 'California',
      zip_code: '91911',
    )
  end
  
  markup {
    div {
      address_form(address: @shipping_address) {
        address_header { # contribute elements to the address_header component slot
          h1('Shipping Address')
          legend('This is the address that is used for shipping your purchase.', style: {margin_bottom: 10})
        }
        address_footer { # contribute elements to the address_footer component slot
          p(sub("#{strong('Note:')} #{em('Purchase will be returned if the Shipping Address does not accept it in one week.')}"))
        }
      }
      
      address_form(address: @billing_address) {
        address_header { # contribute elements to the address_header component slot
          h1('Billing Address')
          legend('This is the address that is used for your billing method (e.g. credit card).', style: {margin_bottom: 10})
        }
        address_footer { # contribute elements to the address_footer component slot
          p(sub("#{strong('Note:')} #{em('Payment will fail if payment method does not match the Billing Address.')}"))
        }
      }
    }
  }
end

Document.ready? do
  # renders a top-level (root) HelloComponentSlots component
  HelloComponentSlots.render
end
```

Screenshot:

![Hello, Component Slots!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-component-slots.png)

#### Hello, Component Listeners!

Component listeners enable consumers of components to listen to any custom events generated by components. Component supported events are declared with class method invocations `events :eventname1, :eventname2, ...` or `event :eventname`. Consumers can listen to those events by simply nesting `on_eventname do; ... end` matching the name of the declared event inside the component.

For example, an `AccordionSection` component might generate events `:expanded` and `:collapsed` when a user clicks on the section title to expand it or collapse it. Consumers can then use `on_expanded` and `on_collapsed` to listen to those events.

Also, it is possible to listen to any component attribute by nesting `on_some_attribute_update`. And, it is possible to set component attributes by nesting `some_attribute value` or data-binding to them by nesting `some_attribute <=> [model, :attribute]`.

[lib/glimmer-dsl-web/samples/hello/hello_component_listeners.rb](/lib/glimmer-dsl-web/samples/hello/hello_component_listeners.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

def summary
    to_h.values.map(&:to_s).reject(&:empty?).join(', ')
  end
end

# AddressForm Glimmer Web Component (View component)
#
# Including Glimmer::Web::Component makes this class a View component and automatically
# generates a new Glimmer HTML DSL keyword that matches the lowercase underscored version
# of the name of the class. AddressForm generates address_form keyword, which can be used
# elsewhere in Glimmer HTML DSL code as done inside HelloComponentListeners below.
class AddressForm
  include Glimmer::Web::Component
  
  option :address
  
  markup {
    div {
      div(style: {display: :grid, grid_auto_columns: '80px 260px'}) { |address_div|
        label('Full Name: ', for: 'full-name-field')
        input(id: 'full-name-field') {
          value <=> [address, :full_name]
        }
        
        label('Street: ', for: 'street-field')
        input(id: 'street-field') {
          value <=> [address, :street]
        }
        
        label('Street 2: ', for: 'street2-field')
        textarea(id: 'street2-field') {
          value <=> [address, :street2]
        }
        
        label('City: ', for: 'city-field')
        input(id: 'city-field') {
          value <=> [address, :city]
        }
        
        label('State: ', for: 'state-field')
        select(id: 'state-field') {
          Address::STATES.each do |state_code, state|
            option(value: state_code) { state }
          end

value <=> [address, :state_code]
        }
        
        label('Zip Code: ', for: 'zip-code-field')
        input(id: 'zip-code-field', type: 'number', min: '0', max: '99999') {
          value <=> [address, :zip_code,
                      on_write: :to_s,
                    ]
        }
        
        style {
          r("#{address_div.selector} *") {
            margin '5px'
          }
          r("#{address_div.selector} input, #{address_div.selector} select") {
            grid_column '2'
          }
        }
      }
      
      div(style: {margin: 5}) {
        inner_text <= [address, :summary,
                        computed_by: address.members + ['state_code'],
                      ]
      }
    }
  }
end

class AccordionSection
  class Presenter
    attr_accessor :collapsed, :instant_transition
    
    def toggle_collapsed(instant: false)
      self.instant_transition = instant
      self.collapsed = !collapsed
    end
    
    def expand(instant: false)
      self.instant_transition = instant
      self.collapsed = false
    end
    
    def collapse(instant: false)
      self.instant_transition = instant
      self.collapsed = true
    end
  end
  
  include Glimmer::Web::Component
  
  events :expanded, :collapsed
  
  option :title
  
  attr_reader :presenter
  
  before_render do
    @presenter = Presenter.new
  end
  
  markup {
    section {
      # Unidirectionally data-bind the class inclusion of 'collapsed' to the @presenter.collapsed boolean attribute,
      # meaning if @presenter.collapsed changes to true, the CSS class 'collapsed' is included on the element,
      # and if it changes to false, the CSS class 'collapsed' is removed from the element.
      class_name(:collapsed) <= [@presenter, :collapsed]
      class_name(:instant_transition) <= [@presenter, :instant_transition]
    
      header(title, class: 'accordion-section-title') {
        onclick do |event|
          @presenter.toggle_collapsed
          if @presenter.collapsed
            notify_listeners(:collapsed)
          else
            notify_listeners(:expanded)
          end
        end
      }
      
      div(slot: :section_content, class: 'accordion-section-content')
    }
  }
  
  style {
    r('.accordion-section-title') {
      font_size 2.em
      font_weight :bold
      cursor :pointer
      padding_left 20
      position :relative
      margin_block_start 0.33.em
      margin_block_end 0.33.em
    }
    
    r('.accordion-section-title::before') {
      content '"▼"'
      position :absolute
      font_size 0.5.em
      top 10
      left 0
    }
    
    r('.accordion-section-content') {
      height 246
      overflow :hidden
      transition 'height 0.5s linear'
    }
    
    r("#{component_element_selector}.instant_transition .accordion-section-content") {
      transition 'initial'
    }
    
    r("#{component_element_selector}.collapsed .accordion-section-title::before") {
      content '"►"'
    }
    
    r("#{component_element_selector}.collapsed .accordion-section-content") {
      height 0
    }
  }
end

class Accordion
  include Glimmer::Web::Component
  
  events :accordion_section_expanded, :accordion_section_collapsed
  
  markup {
    # given that no slots are specified, nesting content under the accordion component
    # in consumer code adds content directly inside the markup root div.
    div { |accordion|
      # on render, all accordion sections would have been added by consumers already, so we can
      # attach listeners to all of them by re-opening their content with `.content { ... }` block
      on_render do
        accordion_section_elements = accordion.children
        accordion_sections = accordion_section_elements.map(&:component)
        accordion_sections.each_with_index do |accordion_section, index|
          accordion_section_number = index + 1

# ensure only the first section is expanded
          accordion_section.presenter.collapse(instant: true) if accordion_section_number != 1

accordion_section.content {
            on_expanded do
              other_accordion_sections = accordion_sections.reject {|other_accordion_section| other_accordion_section == accordion_section }
              other_accordion_sections.each { |other_accordion_section| other_accordion_section.presenter.collapse }
              notify_listeners(:accordion_section_expanded, accordion_section_number)
            end

on_collapsed do
              notify_listeners(:accordion_section_collapsed, accordion_section_number)
            end
          }
        end
      end
    }
  }
end

# HelloComponentListeners Glimmer Web Component (View component)
#
# This View component represents the main page being rendered,
# as done by its `render` class method below
class HelloComponentListeners
  class Presenter
    attr_accessor :status_message
    
    def initialize
      @status_message = "Accordion section 1 is expanded!"
    end
  end
  
  include Glimmer::Web::Component
  
  before_render do
    @presenter = Presenter.new
    @shipping_address = Address.new(
      full_name: 'Johnny Doe',
      street: '3922 Park Ave',
      street2: 'PO BOX 8382',
      city: 'San Diego',
      state: 'California',
      zip_code: '91913',
    )
    @billing_address = Address.new(
      full_name: 'John C Doe',
      street: '123 Main St',
      street2: 'Apartment 3C',
      city: 'San Diego',
      state: 'California',
      zip_code: '91911',
    )
    @emergency_address = Address.new(
      full_name: 'Mary Doe',
      street: '2038 Ipswitch St',
      street2: 'Suite 300',
      city: 'San Diego',
      state: 'California',
      zip_code: '91912',
    )
  end
  
  markup {
    div {
      h1(style: {font_style: :italic}) {
        inner_html <= [@presenter, :status_message]
      }
        
      accordion { # any content nested under component directly is added under its markup root div element
        accordion_section(title: 'Shipping Address') {
          section_content { # contribute elements to section_content slot declared in AccordionSection component
            address_form(address: @shipping_address)
          }
        }
        
        accordion_section(title: 'Billing Address') {
          section_content {
            address_form(address: @billing_address)
          }
        }
        
        accordion_section(title: 'Emergency Address') {
          section_content {
            address_form(address: @emergency_address)
          }
        }
        
        # on_accordion_section_expanded listener matches event :accordion_section_expanded declared in Accordion component
        on_accordion_section_expanded { |accordion_section_number|
          @presenter.status_message = "Accordion section #{accordion_section_number} is expanded!"
        }
        
        on_accordion_section_collapsed { |accordion_section_number|
          @presenter.status_message = "Accordion section #{accordion_section_number} is collapsed!"
        }
      }
    }
  }
end

Document.ready? do
  # renders a top-level (root) HelloComponentListeners component
  HelloComponentListeners.render
end
```

Screenshot:

![Hello, Component Listeners!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-component-listeners.gif)

#### Hello, Component Listeners (Default Slot)!

This is a modified simpler version of Hello, Component Listeners! that takes advantage of the Component Default Slot feature.

For example, an `AccordionSection` component specifies `default_slot :section_content` to simplify inserting content for consumers of the component.

[lib/glimmer-dsl-web/samples/hello/hello_component_listeners_default_slot.rb](/lib/glimmer-dsl-web/samples/hello/hello_component_listeners_default_slot.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

unless Object.const_defined?(:Address)
  Address = Struct.new(:full_name, :street, :street2, :city, :state, :zip_code, keyword_init: true) do
    STATES = {
      "AK"=>"Alaska",
      "AL"=>"Alabama",
      "AR"=>"Arkansas",
      "AS"=>"American Samoa",
      "AZ"=>"Arizona",
      "CA"=>"California",
      "CO"=>"Colorado",
      "CT"=>"Connecticut",
      "DC"=>"District of Columbia",
      "DE"=>"Delaware",
      "FL"=>"Florida",
      "GA"=>"Georgia",
      "GU"=>"Guam",
      "HI"=>"Hawaii",
      "IA"=>"Iowa",
      "ID"=>"Idaho",
      "IL"=>"Illinois",
      "IN"=>"Indiana",
      "KS"=>"Kansas",
      "KY"=>"Kentucky",
      "LA"=>"Louisiana",
      "MA"=>"Massachusetts",
      "MD"=>"Maryland",
      "ME"=>"Maine",
      "MI"=>"Michigan",
      "MN"=>"Minnesota",
      "MO"=>"Missouri",
      "MS"=>"Mississippi",
      "MT"=>"Montana",
      "NC"=>"North Carolina",
      "ND"=>"North Dakota",
      "NE"=>"Nebraska",
      "NH"=>"New Hampshire",
      "NJ"=>"New Jersey",
      "NM"=>"New Mexico",
      "NV"=>"Nevada",
      "NY"=>"New York",
      "OH"=>"Ohio",
      "OK"=>"Oklahoma",
      "OR"=>"Oregon",
      "PA"=>"Pennsylvania",
      "PR"=>"Puerto Rico",
      "RI"=>"Rhode Island",
      "SC"=>"South Carolina",
      "SD"=>"South Dakota",
      "TN"=>"Tennessee",
      "TX"=>"Texas",
      "UT"=>"Utah",
      "VA"=>"Virginia",
      "VI"=>"Virgin Islands",
      "VT"=>"Vermont",
      "WA"=>"Washington",
      "WI"=>"Wisconsin",
      "WV"=>"West Virginia",
      "WY"=>"Wyoming"
    }
    
    def state_code
      STATES.invert[state]
    end
    
    def state_code=(value)
      self.state = STATES[value]
    end
  
    def summary
      to_h.values.map(&:to_s).reject(&:empty?).join(', ')
    end
  end
end

unless Object.const_defined?(:AddressForm)
  # AddressForm Glimmer Web Component (View component)
  #
  # Including Glimmer::Web::Component makes this class a View component and automatically
  # generates a new Glimmer HTML DSL keyword that matches the lowercase underscored version
  # of the name of the class. AddressForm generates address_form keyword, which can be used
  # elsewhere in Glimmer HTML DSL code as done inside HelloComponentListenersDefaultSlot below.
  class AddressForm
    include Glimmer::Web::Component
    
    option :address
    
    markup {
      div {
        div(style: {display: :grid, grid_auto_columns: '80px 260px'}) { |address_div|
          label('Full Name: ', for: 'full-name-field')
          input(id: 'full-name-field') {
            value <=> [address, :full_name]
          }
          
          label('Street: ', for: 'street-field')
          input(id: 'street-field') {
            value <=> [address, :street]
          }
          
          label('Street 2: ', for: 'street2-field')
          textarea(id: 'street2-field') {
            value <=> [address, :street2]
          }
          
          label('City: ', for: 'city-field')
          input(id: 'city-field') {
            value <=> [address, :city]
          }
          
          label('State: ', for: 'state-field')
          select(id: 'state-field') {
            Address::STATES.each do |state_code, state|
              option(value: state_code) { state }
            end
  
            value <=> [address, :state_code]
          }
          
          label('Zip Code: ', for: 'zip-code-field')
          input(id: 'zip-code-field', type: 'number', min: '0', max: '99999') {
            value <=> [address, :zip_code,
                        on_write: :to_s,
                      ]
          }
          
          style {
            r("#{address_div.selector} *") {
              margin '5px'
            }
            r("#{address_div.selector} input, #{address_div.selector} select") {
              grid_column '2'
            }
          }
        }
        
        div(style: {margin: 5}) {
          inner_text <= [address, :summary,
                          computed_by: address.members + ['state_code'],
                        ]
        }
      }
    }
  end
end

unless Object.const_defined?(:AccordionSection2)
  # Note: this is similar to AccordionSection in HelloComponentSlots but specifies default_slot for simpler consumption
  class AccordionSection2
    class Presenter
      attr_accessor :collapsed, :instant_transition
      
      def toggle_collapsed(instant: false)
        self.instant_transition = instant
        self.collapsed = !collapsed
      end
      
      def expand(instant: false)
        self.instant_transition = instant
        self.collapsed = false
      end
      
      def collapse(instant: false)
        self.instant_transition = instant
        self.collapsed = true
      end
    end
    
    include Glimmer::Web::Component
    
    events :expanded, :collapsed
    
    default_slot :section_content # automatically insert content in this element slot inside markup
    
    option :title
    
    attr_reader :presenter
    
    before_render do
      @presenter = Presenter.new
    end
    
    markup {
      section { # represents the :markup_root_slot to allow inserting content here instead of in default_slot
        # Unidirectionally data-bind the class inclusion of 'collapsed' to the @presenter.collapsed boolean attribute,
        # meaning if @presenter.collapsed changes to true, the CSS class 'collapsed' is included on the element,
        # and if it changes to false, the CSS class 'collapsed' is removed from the element.
        class_name(:collapsed) <= [@presenter, :collapsed]
        class_name(:instant_transition) <= [@presenter, :instant_transition]
      
        header(title, class: 'accordion-section-title') {
          onclick do |event|
            @presenter.toggle_collapsed
            if @presenter.collapsed
              notify_listeners(:collapsed)
            else
              notify_listeners(:expanded)
            end
          end
        }
        
        div(slot: :section_content, class: 'accordion-section-content')
      }
    }
    
    style {
      r('.accordion-section-title') {
        font_size 2.em
        font_weight :bold
        cursor :pointer
        padding_left 20
        position :relative
        margin_block_start 0.33.em
        margin_block_end 0.33.em
      }
      
      r('.accordion-section-title::before') {
        content '"▼"'
        position :absolute
        font_size 0.5.em
        top 10
        left 0
      }
      
      r('.accordion-section-content') {
        height 246
        overflow :hidden
        transition 'height 0.5s linear'
      }
      
      r("#{component_element_selector}.instant_transition .accordion-section-content") {
        transition 'initial'
      }
      
      r("#{component_element_selector}.collapsed .accordion-section-title::before") {
        content '"►"'
      }
      
      r("#{component_element_selector}.collapsed .accordion-section-content") {
        height 0
      }
    }
  end
end

unless Object.const_defined?(:Accordion)
  class Accordion
    include Glimmer::Web::Component
    
    events :accordion_section_expanded, :accordion_section_collapsed
    
    markup {
      # given that no slots are specified, nesting content under the accordion component
      # in consumer code adds content directly inside the markup root div.
      div { |accordion| # represents the :markup_root_slot (top-level element)
        # on render, all accordion sections would have been added by consumers already, so we can
        # attach listeners to all of them by re-opening their content with `.content { ... }` block
        on_render do
          accordion_section_elements = accordion.children
          accordion_sections = accordion_section_elements.map(&:component)
          accordion_sections.each_with_index do |accordion_section, index|
            accordion_section_number = index + 1
  
            # ensure only the first section is expanded
            accordion_section.presenter.collapse(instant: true) if accordion_section_number != 1
  
            accordion_section.content { # re-open content and add component custom event listeners
              on_expanded do
                other_accordion_sections = accordion_sections.reject {|other_accordion_section| other_accordion_section == accordion_section }
                other_accordion_sections.each { |other_accordion_section| other_accordion_section.presenter.collapse }
                notify_listeners(:accordion_section_expanded, accordion_section_number)
              end
  
              on_collapsed do
                notify_listeners(:accordion_section_collapsed, accordion_section_number)
              end
            }
          end
        end
      }
    }
  end
end

unless Object.const_defined?(:HelloComponentListenersDefaultSlot)
  # HelloComponentListenersDefaultSlot Glimmer Web Component (View component)
  #
  # This View component represents the main page being rendered,
  # as done by its `render` class method below
  #
  # Note: this is a simpler version of HelloComponentSlots as it leverages the default slot feature
  class HelloComponentListenersDefaultSlot
    class Presenter
      attr_accessor :status_message
      
      def initialize
        @status_message = "Accordion section 1 is expanded!"
      end
    end
    
    include Glimmer::Web::Component
    
    before_render do
      @presenter = Presenter.new
      @shipping_address = Address.new(
        full_name: 'Johnny Doe',
        street: '3922 Park Ave',
        street2: 'PO BOX 8382',
        city: 'San Diego',
        state: 'California',
        zip_code: '91913',
      )
      @billing_address = Address.new(
        full_name: 'John C Doe',
        street: '123 Main St',
        street2: 'Apartment 3C',
        city: 'San Diego',
        state: 'California',
        zip_code: '91911',
      )
      @emergency_address = Address.new(
        full_name: 'Mary Doe',
        street: '2038 Ipswitch St',
        street2: 'Suite 300',
        city: 'San Diego',
        state: 'California',
        zip_code: '91912',
      )
    end
    
    markup {
      div {
        h1(style: {font_style: :italic}) {
          inner_html <= [@presenter, :status_message]
        }
          
        accordion {
          # any content nested under component directly is added to its markup_root_slot element if no default_slot is specified
          accordion_section2(title: 'Shipping Address') {
            address_form(address: @shipping_address) # automatically inserts content in default_slot :section_content
          }
          
          accordion_section2(title: 'Billing Address') {
            address_form(address: @billing_address) # automatically inserts content in default_slot :section_content
          }
          
          accordion_section2(title: 'Emergency Address') {
            address_form(address: @emergency_address) # automatically inserts content in default_slot :section_content
          }
          
          # on_accordion_section_expanded listener matches event :accordion_section_expanded declared in Accordion component
          on_accordion_section_expanded { |accordion_section_number|
            @presenter.status_message = "Accordion section #{accordion_section_number} is expanded!"
          }
          
          on_accordion_section_collapsed { |accordion_section_number|
            @presenter.status_message = "Accordion section #{accordion_section_number} is collapsed!"
          }
        }
      }
    }
  end
end

Document.ready? do
  # renders a top-level (root) HelloComponentListenersDefaultSlot component
  # Note: this is a simpler version of hello_component_slots.rb as it leverages the default slot feature
  HelloComponentListenersDefaultSlot.render
end
```

Screenshot:

![Hello, Component Listeners!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-component-listeners.gif)

#### Hello, Component Attribute Listeners!

[lib/glimmer-dsl-web/samples/hello/hello_component_attribute_listeners.rb](/lib/glimmer-dsl-web/samples/hello/hello_component_attribute_listeners.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

class AddressTypeSelector
  include Glimmer::Web::Component
  
  attribute :address_types, default: []
  attribute :selected_address_type
  
  before_render do
    self.selected_address_type ||= address_types.first
  end
  
  markup {
    select { |select_element|
      address_types.each do |address_type|
        option(value: address_type) { address_type }
      end
      
      # Bidirectionally data-bind select value to selected_address_type attribute on self (component)
      value <=> [self, :selected_address_type]
    }
  }
  
  style {
    r(component_element_selector) {
      font_size 2.em
      margin_left 5.px
    }
  }
end

class AddressTypeSelectorPage
  include Glimmer::Web::Component
  
  markup {
    div {
      h1('Address type for delivery:', style: {display: :inline})
      
      address_type_selector(address_types: ['Home', 'Work', 'Other']) {
        # We can listen to the updates of any attribute/option in a Glimmer Web Component
        # on_{attribute_name}_update do execute code when component attribute/option with attribute_name is updated
        # This is an alternative to using Component Listeners, which require that the component explicitly calls notify_listeners,
        # whereas Component Attribute Listeners get tracked automatically, but depend on a specific attribute
        # The trade-off is Component Listeners provide more flexibility when needed as they are not bound to specific attributes,
        # but often Component Attribute Listeners are good enough as a solution for certain problems.
        on_selected_address_type_update do |address_type|
          $$.alert("You selected the address type: #{address_type}")
        end
      }
    }
  }
end

Document.ready? do
  AddressTypeSelectorPage.render
end
```

Screenshot:

![Hello, Component Attribute Listeners!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-component-attribute-listeners.png)

![Hello, Component Attribute Listeners Selected Address Type!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-component-attribute-listeners-selected-address-type.png)

![Hello, Component Attribute Listeners Selected Address Type Dialog!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-component-attribute-listeners-selected-address-type-dialog.png)

#### Hello, Component Attribute Data-Binding!

[lib/glimmer-dsl-web/samples/hello/hello_component_attribute_data_binding.rb](/lib/glimmer-dsl-web/samples/hello/hello_component_attribute_data_binding.rb)

```ruby
require 'glimmer-dsl-web'

class AddressTypePresenter
  attr_accessor :address_types, :selected_address_type
  
  def initialize(address_types:, selected_address_type: nil)
    @address_types = address_types
    @selected_address_type = selected_address_type
    @selected_address_type ||= address_types.first
  end
end

class AddressTypeSelect
  include Glimmer::Web::Component
  
  attribute :address_types, default: []
  attribute :selected_address_type
  
  markup {
    select { |select_element|
      address_types.each do |address_type|
        option(value: address_type) { address_type }
      end
      
      value <=> [self, :selected_address_type]
    }
  }
  
  style {
    r(component_element_selector) {
      font_size 2.em
      margin_left 5.px
    }
  }
end

class AddressTypeRadioGroup
  include Glimmer::Web::Component
  
  attribute :address_types, default: []
  attribute :selected_address_type
  
  markup {
    div { |select_element|
      address_types.each do |address_type|
        input_id = "radio_address_type_#{address_type}"
        input(id: input_id, type: 'radio', name: 'radio_address_type', value: address_type) {
          checked <=> [self, :selected_address_type,
                       on_read: ->(address_type_string_value) { address_type_string_value == address_type },
                       on_write: ->(radio_input_boolean_value) { radio_input_boolean_value ? address_type : selected_address_type },
                      ]
        }
        label(for: input_id) { address_type }
      end
    }
  }
  
  style {
    r(component_element_selector) {
      font_size 2.em
      margin_top 10.px
    }
    r("#{component_element_selector} label") {
      margin_left 2.px
      margin_right 10.px
    }
  }
end

class AddressTypeComponentAttributeDataBindingPage
  include Glimmer::Web::Component
  
  before_render do
    @presenter = AddressTypePresenter.new(address_types: ['Home', 'Work', 'Other'])
  end
  
  markup {
    div {
      h1('Address type for delivery:')
      
      address_type_select(address_types: @presenter.address_types, selected_address_type: @presenter.selected_address_type) {
        # Not only can we data-bind attributes on basic HTML elements,
        # but we can also data-bind custom attributes on Glimmer Web Components
        selected_address_type <=> [@presenter, :selected_address_type]
      }
      
      address_type_radio_group(address_types: @presenter.address_types, selected_address_type: @presenter.selected_address_type) {
        # Not only can we data-bind attributes on basic HTML elements,
        # but we can also data-bind custom attributes on Glimmer Web Components
        selected_address_type <=> [@presenter, :selected_address_type]
      }
    }
  }
end

Document.ready? do
  AddressTypeComponentAttributeDataBindingPage.render
end
```

Screenshot:

![Hello, Component Attribute Data-Binding!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-component-attribute-data-binding.gif)

#### Hello, glimmer_component Rails Helper!

[lib/glimmer-dsl-web/samples/hello/hello_glimmer_component_helper/address_form.rb](/lib/glimmer-dsl-web/samples/hello/hello_glimmer_component_helper/address_form.rb)

Rails `ApplicationHelper` setup code:

```ruby
require 'glimmer/helpers/glimmer_helper'

module ApplicationHelper
  # ...
  include GlimmerHelper
  # ...
end
```

Rails View code:

Glimmer HTML DSL Ruby code in the frontend (`app/assets/opal/address_form.rb`):

```ruby
require 'glimmer-dsl-web'

Screenshot:

![Hello, glimmer_component Rails Helper!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-component.png)

#### Hello, Modal!

[lib/glimmer-dsl-web/samples/hello/hello_modal.rb](/lib/glimmer-dsl-web/samples/hello/hello_modal.rb)

Glimmer HTML DSL Ruby code in the frontend:

```ruby
require 'glimmer-dsl-web'

# only in the sample we need the unless statement to avoid conflicting with other samples, but not in real usage
unless Object.const_defined?(:GreetingPerson)
  GreetingPerson = Struct.new(:name, keyword_init: true)
end

# only in the sample we need the unless statement to avoid conflicting with other samples, but not in real usage
unless Object.const_defined?(:GreetingModal)
  class GreetingModal
    include Glimmer::Web::Component
    
    attribute :greeting_target, default: 'World'
    
    markup {
      div(class: 'modal-outer') {
        div(class: 'modal-inner') {
          h2 { 'Greeting' }
          
          h3 { "Hello, #{greeting_target}!" }
          
          div {
            button('Close') {
              onclick do
                markup_root.remove
              end
            }
          }
        }
      }
    }
    
    style {
      r('.modal-outer') {
        display 'flex'
        position 'fixed'
        left 0
        top 0
        width 100.vw
        height 100.vh
        background 'rgba(200, 200, 200, 0.8)'
        margin 0
        padding 0
        justify_content 'center'
        align_items 'center'
      }
      
      r('div.modal-inner') {
        display 'flex'
        flex_direction 'column'
        width 300
        height 160
        justify_content 'center'
        align_items 'center'
        box_shadow '0 10px 30px rgba(0, 0, 0, 0.5)'
        background :white
        border_radius 15
        padding 15
      }
      
      r('div.modal-inner button') {
        width 135
        margin 5
        border_radius 5
        padding 5
        background :white
      }
      
      r('div.modal-inner button:hover') {
        background :black
        color :white
      }
      
      
      r('div.modal-inner h2') {
        margin_top 10
      }
    }
  end
end

# only in the sample we need the unless statement to avoid conflicting with other samples, but not in real usage
unless Object.const_defined?(:HelloModal)
  class HelloModal
    include Glimmer::Web::Component
    
    before_render do
      @greeting_person = GreetingPerson.new
    end
    
    markup {
      div {
        div {
          button('Greet The World') {
            onclick do
              # renders Modal under body by default, which works for Modals because they rely on fixed positioning
              GreetingModal.render
            end
          }
        }
        div {
          button('Greet Laura') {
            onclick do
              # renders Modal under body explicitly (parent takes a CSS expression) while passing it an attribute value
              GreetingModal.render(parent: 'body', greeting_target: 'Laura')
            end
          }
        }
        div {
          label { 'Greeting Person Name:' }
          input(type: 'text') {
            value <=> [@greeting_person, :name]
          }
          button {
            inner_text <= [@greeting_person, :name, on_read: ->(name) { "Greet #{name}" }]
            
            onclick do
              # renders Modal under body by default while passing it a Model attribute value
              GreetingModal.render(greeting_target: @greeting_person.name)
            end
          }
        }
      }
    }
    
    style {
      r('.hello-modal div') {
        margin_bottom 10
      }
      r('.hello-modal label, .hello-modal input, .hello-modal button') {
        margin_right 5
      }
    }
  end
end

# only in the sample we need the Document.ready? call; in real usage,
# we rely on the glimmer_component helper to load this file inside a Rails View
Document.ready? do
  HelloModal.render
end
```

Screenshot:

![Hello, Modal!](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-web/master/images/glimmer-dsl-web-samples-hello-hello-modal.gif)

#### Hello, Paragraph!