Async Component API

The async component enables us to rerender/defer parts of the UI based on events/timing without full page reload.

Please be aware that, if not configured otherwise, the async core component does get loaded and displayed on initial pageload!

Parameters

The async core component accepts the following parameters:

ID - required

The async component needs an ID in order to resolve the correct content on an async HTTP request

async id: "some-unique-id" do
  #...
end

Rerender_on

The rerender_on option lets us define an event on which the component gets rerendered.

async rerender_on: 'my_event', id: "some-unique-id" do
  div id: 'my-div' do
    plain "#{DateTime.now.strftime('%Q')}"
  end
end

Note: The rerender_on option lets you rerender parts of your UI asynchronously. But please consider that, if not configured differently, it

a) is not lazily loaded and

b) and does get displayed on initial pageload

by default.

Lazy (or defered) loading can be configured like shown here.

You can pass in multiple, comma-separated events on which the component should rerender.

async rerender_on: 'my_event, some_other_event', id: "some-unique-id"

Defer

The defer option may be used in two ways:

simple defer

defer: true implies that the content of the async component gets requested within a separate GET request right after initial page load is done.

async defer: true, id: "some-unique-id"do
  div id: 'my-div' do
    plain 'I will be requested within a separate GET request right after initial page load is done'
  end
end

delayed defer

defer: 2000 means that the content of the async component gets requested within a separate GET request 2000 milliseconds after initial page load is done.

async defer: 2000, id: "some-unique-id" do
  div id: 'my-div' do
    plain 'I will be requested within a separate GET request 2000ms after initial page load is done'
  end
end

The content of an async component with activated defer behavior is not resolved within the first page load!

#...
async defer: 1000, id: "some-unique-id" do
  some_database_data = SomeModel.some_heavy_query
  div id: 'my-div' do
    some_database_data.each do |some_instance|
      plain some_instance.id
    end
  end
end
async defer: 2000, id: "some-unique-id" do
  some_other_database_data = SomeModel.some_other_heavy_query
  div id: 'my-div' do
    some_other_database_data.each do |some_instance|
      plain some_instance.id
    end
  end
end
#...

The SomeModel.some_query does not get executed within the first page load and only will be called within the deferred GET request. This helps us to render a complex UI with loads of heavy method calls step by step without slowing down the initial page load and rendering of simple content.

DOM structure, loading state and animations

Async components will be wrapped by a DOM structure like this:

<div class="matestack-async-component-container">
  <div class="matestack-async-component-wrapper">
    <div class="matestack-async-component-root" >
      hello!
    </div>
  </div>
</div>

During async rendering a loading class will automatically be applied, which can be used for CSS styling and animations:

<div class="matestack-async-component-container loading">
  <div class="matestack-async-component-wrapper loading">
    <div class="matestack-async-component-root" >
      hello!
    </div>
  </div>
</div>

Examples

See some common use cases below:

Rerender on event

On our example page, we wrap a simple timestamp in an async component and tell it to rerender when the event my_event gets triggered.

class ExamplePage < Matestack::Ui::Page

  def response
    async rerender_on: 'my_event', id: "some-unique-id" do
      div id: 'my-div' do
        plain "#{DateTime.now.strftime('%Q')}"
      end
    end
  end

end

Not surprisingly, the timestamp gets updated after our event was fired!

Deferred loading

On our example page, we wrap our async event around a placeholder for the event message.

class ExamplePage < Matestack::Ui::Page

  def response 
    async defer: true, id: "some-unique-id" do 
      div id: 'my-div' do 
        plain 'I will be requested within a separate GET request right after initial page load is done' 
      end 
    end 
  end

end