Migration guide for Rocker users

[nedtwigg]

I have used fizzed Rocker templates for several years, and they are fantastic. My primary complaint was IDE support, secondary complaint was that the github repo didn't have public CI and it was hard to get PR's merged.

I tinkered with jte, and the IDE support is really incredible. Converting a template from rocker to jte is extremely easy, the syntax is nearly identical. I bet you could whip up an autoconverter out of just a few regexes, and we might do that at some point.

The big thing missing from jte at the moment is calling templates in a typesafe way

• improve typesafe API experience #131

We filled this gap by defining

interface JteModel {
  fun render(engine: TemplateEngine, output: TemplateOutput)
}

and then we wrote a little Gradle plugin that lives in our buildSrc directory which autogenerates Kotlin model files out of the .jte templates which look like this:

class main(
	val title: String,
	val description: String,
	val content: gg.jte.Content,
	) : common.JteModel {

	override fun render(engine: TemplateEngine, output: TemplateOutput) {
		engine.render("pages/main.jte", mapOf(
			"title" to title,
			"description" to description,
			"content" to content,
		), output)
	}
}

And now we are able to swap over from Rocker to JTE with very little effort. Our webapp is a monolith which has run continuously since 2011 without ever having a full rewrite, just ship-of-theseus upgrages over a decade+. So it's quite idiosyncratic, but I put our integration code up as GitHub gists in case they are helpful to others.

• the gradle plugin that we put into buildSrc
• the model files which it generates, along with Jooby 1.x integration code

[casid]

Thanks for sharing @nedtwigg! I added a migration section to the jte documentation and included a link to this issue.

And nice one, ship-of-theseus upgrade is the way to go.

Good luck with the migration!

[nedtwigg]

.rocker.html -> .jte

• imports are @import in both -> unchanged
• RockerBody -> gg.jte.Content
• @args -> @param, one line to multiline
  • @args (AdminState adminState, RockerBody content)
  • @param AdminState adminState
  • @param gg.jte.Content
• remove curly braces from ifs
  • @if (...) { ... } else if (...) { ... } else { ... }
  • @if (...) @elseif (...) @else @endif (needs own line, no curly braces)
• inline substitutions / variables are @ -> ${}
  • @content
  • ${content}
• template invocation is a lot different
  • @views.main.template("Admin home") -> { ... content of RockerBody ... }
  • @template.views.main(title = "Admin home", @` ... content of gg.jte.Content ... `)