Component

[jgaskins]

HTML5 tag names

The Component mixin provides methods as shorthand for all currently supported HTML5 tag names in the format tag_name(properties, content). Both properties and content are optional. Examples:

div('Hello, world!') # Properties omitted
img(src: 'https://example.com/logo.jpg') # Content omitted
hr # Both properties and content omitted
h1({ class_name: 'title' }, 'Welcome to Clearwater') # Includes both properties and content

Notice in the last example that the class_name property is used instead of the HTML class attribute. Clearwater uses the DOM properties API rather than HTML attributes. This is because we are working with DOM nodes rather than strings of HTML text. You can still set properties as HTML attributes if you nest them within the attributes key. This is required for some attributes that do not have DOM-property counterparts. For example, aria-* and role attributes:

div({ attributes: { role: 'alert' } }, 'Item is out of stock')

The content argument can be any of the following types:

• String
• Number
• nil
• Another component
• An array containing any combination of the above

Example:

ul(articles.map { |a|      # Array content in this ul
  li([                     # Array content for this li
    h1(a.title),           # String
    div(a.author_name),    # String or nil if anonymous
    Timestamp.new(a.timestamp), # Component
    div(a.comments.count), # Number
  ])
})

Component#tag(properties=nil, content=nil)

Returns a virtual-DOM node with the specified properties and content. Unlike the HTML5 tag methods above, properties cannot be omitted if the content argument is supplied.

Component#call

Re-renders all Clearwater apps in the registry. Due to Clearwater's asynchronous rendering, this method takes an optional block that will be invoked after the UI is updated.

Component#params

Routing targets can use this method to get the route params they care about from their router. For example:

class ArticleDetail
  include Clearwater::Component

  # ...

  def selected_article
    # Assumes a global Store object that knows about all of the articles loaded
    # and has them indexed by id.
    Store.articles[params[:article_id]]
  end
end