Class: Phlex::Reactive::Response

Inherits:
Object
  • Object
show all
Defined in:
lib/phlex/reactive/response.rb

Overview

An explicit, immutable description of the ACTOR’s HTTP response to a reactive action. An action MAY return one; if it returns anything else (the legacy contract — return value ignored), the endpoint falls back to the implicit single component.to_stream_replace.

A Response governs ONLY the actor’s HTTP reply. Cross-tab updates still go through Streamable’s broadcast_*_to(…, exclude: reactive_connection_id).

Response.replace(self)                          # re-render in place (the default, explicit)
Response.replace(self).flash(:error, msg)       # surface a validation error
Response.replace(self).also_update("heading", html: @record.name)  # + a companion element
Response.remove(self)                           # drop the element (e.g. moderation queue)
Response.redirect(article_url(@article))        # slug changed -> Turbo.visit the new URL
Response.replace(self).stream(Totals.update(@order))  # multi-stream

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(streams: [], redirect_url: nil, render_self: true) ⇒ Response

render_self: when true (default for replace/update/with), the endpoint GUARANTEES the component’s own replace is present so its data-reactive-token-value refreshes (the client extracts the next token from the response HTML). remove/redirect set it false (nothing stays).



76
77
78
79
80
81
 
# File 'lib/phlex/reactive/response.rb', line 76

def initialize(streams: [], redirect_url: nil, render_self: true)
  @streams = streams.freeze
  @redirect_url = redirect_url
  @render_self = render_self
  freeze
end

Instance Attribute Details

#redirect_url ⇒ Object (readonly)

Returns the value of attribute redirect_url.



20
21
22
 
# File 'lib/phlex/reactive/response.rb', line 20

def redirect_url
  @redirect_url
end

#streams ⇒ Object (readonly)

Returns the value of attribute streams.



20
21
22
 
# File 'lib/phlex/reactive/response.rb', line 20

def streams
  @streams
end

Class Method Details

.flash_stream(_level, content, target:) ⇒ Object

Build a flash turbo-stream that appends ‘content` into a host-app container. `content` is a Phlex component instance (rendered through the configured renderer so t()/url_for work) or a ready HTML string —supplied by the caller because the render context is off-request (there is no Rails `flash`).



47
48
49
 
# File 'lib/phlex/reactive/response.rb', line 47

def flash_stream(_level, content, target:)
  Phlex::Reactive.flash_builder.append(target, html: render_html(content))
end

.redirect(url) ⇒ Object

Client-side full navigation (Turbo.visit). Use when the current URL is dead (slug rename) or the outcome belongs on another page. Pass a *_url (the off-request render context has no request host for *_path).



37
 
# File 'lib/phlex/reactive/response.rb', line 37

def redirect(url) = new(redirect_url: url, render_self: false)

.remove(component) ⇒ Object

Remove the component’s element from the DOM. Uses the instance to_stream_remove (the component already knows its own #id — no class-builder reconstruction; works for record- and state-backed).



32
 
# File 'lib/phlex/reactive/response.rb', line 32

def remove(component) = new(streams: [component.to_stream_remove], render_self: false)

.render_html(content) ⇒ Object

Resolve ‘content` to the HTML for a turbo-stream’s ‘html:`. Two forms, both SAFE against injection by default:

* a Phlex component instance — rendered through the configured
  renderer, which auto-escapes interpolated values.
* any other value — coerced with to_s and handed to Turbo's
  TagBuilder, which HTML-ESCAPES a plain String. So a model value
  (`html: @record.name`) cannot inject markup. To emit intentional
  raw HTML, pass an `html_safe` String (Turbo leaves those verbatim)
  or a Phlex component. Same contract as the pre-existing flash_stream.



67
68
69
 
# File 'lib/phlex/reactive/response.rb', line 67

def render_html(content)
  content.is_a?(::Phlex::SGML) ? Phlex::Reactive.render(content) : content.to_s
end

.replace(component) ⇒ Object

Re-render the component in place (explicit form of today’s default).



24
 
# File 'lib/phlex/reactive/response.rb', line 24

def replace(component) = new(streams: [component.to_stream_replace])

.update(component) ⇒ Object

Morph only inner HTML (preserves the root element + its token attr).



27
 
# File 'lib/phlex/reactive/response.rb', line 27

def update(component) = new(streams: [component.to_stream_update])

.update_stream(target, content) ⇒ Object

Build a turbo-stream that updates an arbitrary target id with ‘content` (a Phlex component instance or an HTML string). Used by #also_update to re-render a companion element that isn’t itself a Streamable component.



54
55
56
 
# File 'lib/phlex/reactive/response.rb', line 54

def update_stream(target, content)
  Phlex::Reactive.flash_builder.update(target, html: render_html(content))
end

.with(*strings) ⇒ Object

Escape hatch / multi-stream root: zero or more raw turbo-stream strings.



40
 
# File 'lib/phlex/reactive/response.rb', line 40

def with(*strings) = new(streams: strings.flatten)

Instance Method Details

#also_replace(component) ⇒ Object

Like #also_update, but renders ANOTHER Streamable component and replaces it by its own #id — for a companion that is itself a component.

Response.replace(self).also_replace(SummaryCard.new(order: @order))



116
117
118
 
# File 'lib/phlex/reactive/response.rb', line 116

def also_replace(component)
  stream(component.to_stream_replace)
end

#also_update(target, html:) ⇒ Object

Also re-render a COMPANION element alongside self — a page heading, a summary card, a badge that recomputes from the saved value (issue #25). ‘target` is the sibling element’s DOM id. ‘html` is either:

* a plain String — HTML-ESCAPED by Turbo, so a model value is safe:
    Response.replace(self).also_update("page_heading", html: @record.name)
* a Phlex component — rendered + auto-escaped through the renderer (use
  this when the companion has its own markup), or an `html_safe` String
  for intentional raw HTML.

Returns a NEW Response (immutable). The common “re-render self + N siblings” case no longer needs raw turbo_stream_builder.



109
110
111
 
# File 'lib/phlex/reactive/response.rb', line 109

def also_update(target, html:)
  stream(self.class.update_stream(target, html))
end

#flash(level, content, target: Phlex::Reactive.flash_target) ⇒ Object

Append a flash turbo-stream into a host-app container (default <div id=“flash”>, configurable via Phlex::Reactive.flash_target).



95
96
97
 
# File 'lib/phlex/reactive/response.rb', line 95

def flash(level, content, target: Phlex::Reactive.flash_target)
  stream(self.class.flash_stream(level, content, target:))
end

#redirect? ⇒ Boolean

Returns:

  • (Boolean) 


120
 
# File 'lib/phlex/reactive/response.rb', line 120

def redirect? = !@redirect_url.nil?

#render_self? ⇒ Boolean

Returns:

  • (Boolean) 


121
 
# File 'lib/phlex/reactive/response.rb', line 121

def render_self? = @render_self

#stream(*more) ⇒ Object

Append extra turbo-stream strings (a sibling component, a flash). Returns a NEW Response (immutable).



85
86
87
88
89
90
91
 
# File 'lib/phlex/reactive/response.rb', line 85

def stream(*more)
  self.class.new(
    streams: @streams + more.flatten,
    redirect_url: @redirect_url,
    render_self: @render_self
  )
end