Creating Customized Turbo Stream Actions In Hotwire And Lucee CFML

The Hotwire Turbo framework makes use of <turbo-stream> components to apply focused DOM (Doc Object Mannequin) manipulations to the present web page. These Turbo Stream components might be rendered in response to a Type POST; or, as we noticed yesterday, they are often returned inline in any web page response. The default Turbo Stream actions are all DOM-related. Nonetheless, we are able to outline our personal customized actions as effectively. To discover this, I’ll create a customized Turbo Stream motion that invokes Turbo.go to().

View this code in my ColdFusion + Hotwire Demos venture on GitHub.

To outline a customized Turbo Stream motion, we’ve to monkey patch an motion handler onto the StreamActions object. The title of the tactic maps to the motion attribute on the <turbo-stream> component. On this case, we will name the motion, go to:

// Import core modules.
import * as Turbo from "@hotwired/turbo";
import { StreamActions } from "@hotwired/turbo";

// ----------------------------------------------------------------------------------- //
// ----------------------------------------------------------------------------------- //

/**
* I help Turbo.go to() stream actions.
*/
StreamActions.go to = operate() {

	var url = this.dataset.url;
	var motion = ( this.dataset.motion || "advance" );
	var body = ( this.dataset.body || undefined );

	Turbo.go to(
		url,
		{
			motion: motion,
			body: body
		}
	);

}

When Turbo Drive invokes the .go to() methodology, it’s binding the <turbo-stream> component because the this context. As such, with the intention to entry extra information in regards to the motion, we are able to question the DOM node utilizing this.getAttribute() or, in my case, this.dataset to entry the data-* attributes.

ASIDE: There are not any guidelines on the way you outline information and the way you title your attributes. My resolution to make use of data-url, for instance, was utterly arbitrary.

With this .go to() handler outlined, our ColdFusion server can then reply with <turbo-stream> components of sort motion="go to":

<turbo-stream
	motion="go to"
	url="https://www.bennadel.com/weblog/index.htm">
	<!--- No content material is related for this motion. --->
</turbo-stream>

To see this in motion, I’ve created a fairly trite ColdFusion software with two pages: a fundamental web page; and, one other web page which does nothing however redirect the person again to the primary web page utilizing our new Turbo Stream motion.

This is the primary web page:

<cfmodule template="./tags/web page.cfm">
	<cfoutput>

		<h2>
			Welcome to My Web site
		</h2>

		<p>
			<a href="https://www.bennadel.com/weblog/bounce.htm">Go to Bouncer</a>
		</p>

	</cfoutput>
</cfmodule>

This offers a hyperlink to bounce.htm, which does nothing by redirect again to the primary web page:

<cfmodule template="./tags/web page.cfm">
	<cfoutput>

		<h2>
			Bouncing Again to Residence
		</h2>

		<p>
			<!--- Required for restoration visits - see be aware under. --->
			<a href="https://www.bennadel.com/weblog/index.htm">Return to dwelling</a> &rarr;
		</p>

		<!---
			CAUTION: If the person returns to this web page by means of a restoration go to (ie,
			hitting the browser's BACK BUTTON), this Turbo-Stream component will not
			be right here since it's eliminated in the course of the stream analysis. As such, it's
			necessary to offer the handbook hyperlink above.
			--
			Additionally, by including [data-action="replace"], we are able to override the present historical past
			entry, considerably stopping the again button downside.
		--->
		<turbo-stream
			motion="go to"
			data-url="https://www.bennadel.com/weblog/index.htm">
		</turbo-stream>

	</cfoutput>
</cfmodule>

As you may see, I’ve included an inline <turbo-stream [action="visit"]> component. After the web page renders (briefly), Turbo Drive will kick-in, collect up all of the Turbo Stream components, after which redirect the person again to the primary web page.

NOTE: For maximal security, I’ve additionally included a handbook “Again to dwelling” hyperlink for restoration visits (when web page is pulled from cache); and, for when the person hits this web page instantly with out loading JavaScript. I am all the time making an attempt to maintain my eye on progressive enhancement, by no means assuming that Hotwire is even loaded.

Now, if we load this ColdFusion web page and attempt to entry the bounce web page, we get the next output:

As you may see, the bounce.cfm web page, nearly instantly redirects the person again to the primary web page due to our customized Turbo Stream.

On this demo, we use the browser’s again button to render the cached model of bounce.cfm, which renders with none inline Turbo Stream components. That is the place our static anchor hyperlink comes into play. We are able to additionally, considerably, get round this challenge by together with data-action="substitute" in our <turbo-stream> component. This may substitute the present window.historical past merchandise as an alternative of pushing a brand new merchandise onto the stack.

Turbo ships with a handful of DOM manipulation stream actions that can probably offer you most of what you want. However, it is nice to see that we are able to fill out that final mile of performance with customized Turbo Stream actions. For extra data, strive taking a look at TurboPower, a Third-party assortment of customized stream actions.

Wish to use code from this put up?
Try the license.