Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/floodfx/undead

LiveView server implementation for the JVM
https://github.com/floodfx/undead
java kotlin liveview stringtemplate undead
Last synced: 2 months ago
JSON representation
LiveView server implementation for the JVM
Host: GitHub
URL: https://github.com/floodfx/undead
Owner: floodfx
Created: 2023-10-11T15:18:07.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2023-12-17T00:39:00.000Z (about 1 year ago)
Last Synced: 2024-09-27T00:19:38.840Z (4 months ago)
Topics: java, kotlin, liveview, stringtemplate, undead
Language: JavaScript
Homepage:
Size: 466 KB
Stars: 58
Watchers: 2
Forks: 2
Open Issues: 1
Metadata Files:
- Readme: README.md
Awesome Lists containing this project

README

        # 🧟🧛‍♀️🐺 Undead - LiveViews for the JVM

[![javadoc](https://javadoc.io/badge2/run.undead/undead-core/javadoc.svg)](https://javadoc.io/doc/run.undead/undead-core)

## What is Undead?

`Undead` is dead-serious library for JVM devs who want to build scary fast, bewitching front-end experiences on the JVM

*without writing javascript* 🙀.  

`Undead` is a LiveView implementation for the JVM. (The name "Undead" is a play on the "Live" part of LiveViews 👻.)

LiveViews let you build front-end experiences like those you can build with [React](https://react.dev)

or [Vue.js](https://vuejs.org)

but all without leaving the server.  (See [what is a liveview](#what-is-a-liveview) for more details on LiveViews but 

you don't need to know what a LiveView is to use `Undead`.)

### NOTE: Undead relies on Java 21 Preview Features

`Undead` is built on top [StringTemplate](https://openjdk.org/jeps/430)s which is a "Preview Feature" of Java 21.  In order to 

build and run `Undead` apps you have to run your IDE and/or the JVM with the `--enable-preview` flag and target Java `21`.  The `pom.xml` 

in this repo show you where you need to add flags.  If you are running IntelliJ you have to futz with the settings...again this repo ships

with the IntelliJ settings.  I don't know about Eclipse and last time I checked VSCode plugins they didn't support Java 21 yet.  

Sometimes you have to work a little to be on the bleeding edge...🔪

## 🍬 Benefits of building apps with Undead

* No need to write javascript

* Very fast, SEO-friendly, fully rendered HTML initial response

* Extremely efficient, diff-based updates over Websockets

* Small, easy-to-learn, yet powerful API

* Modern, type-safe templating engine (String Templates)

* Just another route on your existing web server

Further `Undead` does the following:

* Makes _normal_ things **trivial**

  * Dynamic, validated forms that map into model objects (and vice versa)

  * Dynamic page updates based on user actions (clicks, keys, focus, etc)

  * Debounce and throttle user events with ease

* Makes _hard_ things **easy**

  * File uploads with drag-n-drop, progress, and image previews

  * Multiplayer UIs, presence, and other real-time interactions using pub/sub

  * Only ship diffs reducing network overhead by huge amounts (transparent to dev btw)

* Makes _expensive_/_complicated_ things **unecessary**

  * No need for REST or GraphQL APIs (but easier to integrate with them if you do)

  * No need for front-end vs back-end code bases, FE vs BE state synchronization, etc

  * No need to build or maintain a large Javascript component library

  * No need to write Javascript period.

## 🦠 Current Status: Incubating / Alpha

`Undead` is currently in the "incubating" stage. It is probably not yet ready for production but "it's alive!" and

a decent chunk of functionality is implemented along with pretty good documentation (especially the javadocs). If you

aren't too afraid 👻 you can try it out and provide feedback. Check out working examples in

the [example](src/main/java/run/undead/javalin/example)

code directory. You can run these examples by checking out this repository and running:

```shell

mvn package exec:exec

```

Then open your browser to http://localhost:1313 and you should see the examples.

## ⭐️ Stars, Feedback, and Signups Welcome

Please feel free to open an issue or PR if you have any feedback or suggestions. If you like this project, feel free

to ⭐️ it!  You can also [signup for updates](https://mailchi.mp/40717440e95b/undead-signup).  (Only the cursed would

share your email address.)

## Adding `Undead` to your project

If you are brave enough to try it out, you can add `Undead` to your project by adding the following dependency to your

`pom.xml`:

```xml

    run.undead

    undead-core

    0.0.15

```

## Example Undead View

```java

// Sample View that counts up and down 

public class UndeadCounter implements View {

  private int count;

  public UndeadCounter() {

    this.count = 0;

  }

  // Handle events from the browser

  public void handleEvent(Socket context, UndeadEvent event) {

    if ("inc".equals(event.type())) {

      this.count++;

    } else if ("dec".equals(event.type())) {

      this.count--;

    }

  }

  // Render the HTML based on the current state (e.g. count)

  public UndeadTemplate render(Meta meta) {

    return HTML."""

        


          Count:

            

              \{ count }

            

          

          

            Decrement

            Increment

          

          """;

  }

}

```

## Undead Views

Undead `View`s are the lifeblood of the Undead framework.  `View` provides a simple yet powerful interface that for

handling events from the browser, updating state, and rendering HTML.

### `Undead` View interface

The View interface defines the lifecycle callbacks for an Undead View. Views have a lifecycle that consists of a short,

fast HTTP request/response and a long-lived WebSocket connection.

**Implementation Note:** Views should have a no-arg constructor as they are instantiated by reflection.

#### View Interface methods

- `View.mount` - (optional) mount is where a View can be initialized based on session data and/or path or query

  parameters

- `View.handleParams` - (optional) handleParams is called after mount and whenever there is a URI change

- `View.handleEvent` - (optional) handleEvent is called when an event (click, keypress, etc) is received from the

  browser

- `View.handleInfo` - (optional) handleInfo is called when an event (a.k.a info) is received from the server

- `View.render` - (required) render returns an `UndeadTemplate` based on the state of the View

- `View.shutdown` - (optional) shutdown is called when the View is shutting down and is a good place to clean up

As you can see the only required method is `View.render` which is called to render the View based on its state. The

other methods are optional so you can implement only the callbacks that you need for your View.

## Templating

Undead provides a [String Templates](https://openjdk.java.net/jeps/430)-based template engine that make LiveViews

possible.  

String Templates are a new feature in Java 21 and therefore Undead **only works on Java 21** (and theoretically above).

String

Templates have a slightly weird escape syntax (e.g. `\{ count }`) but they are very powerful, easy to use, type-safe,

and can

create whatever HTML you want. Undead provides a number of pre-built directives that make building complex HTML easy.

### Example Undead Template

```java

Undead.HTML."""



  Count:

    

      \{ count }

    

  

  

    Decrement

    Increment

  

  """;

```

### `Undead.HTML` Templates

The `Undead.HTML` processor is a [String Template Processor](https://openjdk.java.net/jeps/430) that is used to build

HTML template in a type-safe, LiveView-friendly way.  `Undead.HTML` automatically escapes HTML entities in order to

prevent XSS attacks. Beyond escaping HTML

entities, it does no other parsing or validation of the HTML but it does take advantage of StringTemplates to optimize

diff being sent over the wire.  

A simple example of `Undead.HTML` in action is below:

```java

// Single line

Undead.HTML."Hello, \{ name }!";

// Multiline

Undead.HTML."""

  


    Hello, \{ name }!      

  

""";

```

You can read more about String Templates [here](https://openjdk.java.net/jeps/430)

and [here](https://www.infoq.com/news/2023/04/java-gets-a-boost-with-string/). But you really don't

need to know much about them to use `Undead.HTML` templates other than how to embed values (i.e. `\{ myValue }`). Note,

you can statically import `Undead.HTML` to shorten it to `HTML`.

### Undead Template Directives

Undead provides template directives for common needs like if statements, switch statements, mapping over a collection,

ranges, etc. Basically all the normal

templating things you'd expect. You can also easily add your own template directives and/or custom functions that can be

used in your templates. Below is a list

of the built-in directives:

* `If` Directive - `If` models an if statement in a template. If the provided condition is true the trueCase template is

  returned

  otherwise an empty template is returned. There is also an `If` directive that can return either the trueCase or

  falseCase template.

* `Switch` Directive - `Switch` models a switch statement in a template. The provided value is compared to each case and

  if there is a match

  the corresponding template is returned. If there is no match, the default template is returned (or an empty template

  if there is no default).

* `For` Directive - `For` enables transforming a collection of values into a collection of templates. The provided

  collection is iterated applying the provided template function to each value in the collection.

* `Range` Directive - `Range` enables iterating over a range of integer values optionally by a given step.

* `Join` Directive - `Join` enabled joining a collection of templates together with a given separator template.

There are typically two types of logic directive, those that take a simple boolean condition (e.g. x == 1) and

those that take a `Predicate`s which are used into lambda form (e.g. x -> x == 1). The former is more concise but the

latter is more flexible.  

Additionally, the directives that accept a `Predicate` also require a `Function` to be provided. This

means the function that

returns the template has access to the value being tested which is very useful for adding to a template or

using `Function` defined elsewhere.

Examples

```java

// If Directive

HTML."""

  \{ If(zombieCount > 0, HTML."🙀Uh oh, there are zombies!") }

  """;

// If/Else Directive

HTML."""

  
\{ 

    If(brainsEaten < 10, 

      HTML."Need more 🧠s...", 

      HTML."Time for 🛏!") 

    }

  

  """;

// Switch Directive

HTML."""

  


    \{ color } is a nice color

  

""";

// For Directive

HTML."""

  


    \{ For(zombies, zombie -> HTML."\{ zombie.name }") }

  

""";

// Range Directive

HTML."""

  \{For(

      Range(10),

      i -> HTML."
Step \{i}"

  )}

""";

// Range Directive with step

HTML."""

  \{For(

      Range(2, 10, 2),

      i -> HTML."\{i}"

  )}

"""

```

### Using Undead Templates for "DeadViews" (i.e. traditional) HTML rendering

It is fine to use Undead Templates to render HTML outside of LiveViews so feel free to do so. You can use

the `Undead.HTML` processor

the same way and call `toString()` on it to get the rendered HTML.

## Javascript Commands

Undead provides a number of Javascript commands that can be used to show/hide elements, add/remove classes, dispatch

events, etc. These commands are

called JS Commands and can be part of the Undead Template you define in a `View`s `render` function. JS Commands are

loaded on the client-side

when the template is rendered and executed based on user interactions. JS Commands are a powerful way to manipulate the

DOM without having to write javascript.  

Below is a list of the commands:

* JS.addClass - Adds a class to an element

* JS.dispatch - Dispatches an event on an element

* JS.exec - Executes JS commands on an element's attribute

* JS.focus - Focuses an element

* JS.focusFirst - Focuses the first element in a selector

* JS.hide - Hides an element

* JS.navigate - Sends a navigation event to the server

* JS.patch - Sends a patch event to the server

* JS.popFocus - Pops the focus stack

* JS.push - Pushes an event to the server

* JS.pushFocus - Pushes the focus stack

* JS.removeAttr - Removes an attribute from an element

* JS.removeClass - Removes a class from an element

* JS.setAttr - Sets an attribute on an element

* JS.show - Shows an element

* JS.toggle - Toggles visibility of an element

* JS.transition - Applies css transitions to an element

See the JS Commands javadocs for more details on each command and its options.

## `Undead` Javascript

Like I said, you don't have to write javascript...and if javascript is too ghastly for you to write, you can continue

to use the `undead.js` as is (see the resources directory) and just make sure it is loaded on your page.  

However, if you want to wade into the gory details of the javascript, check out the `/js` directory. Inside is a simple

node project that uses [esbuild](https://esbuild.github.io/) to build the `undead.js` file from typescript

(i.e. `js/undead.ts`). Assuming you have npm installed, to run it:

```shell

cd js

npm install

npm run build

```

## Why did you write Undead?

LiveViews (a.k.a UndeadViews 🧟) are an enchanting, new paradigm for building bewitching front-end experiences and I

wanted to see if how hard it would be to implement them on the JVM. I poked around the existing templating libraries

and didn't find anything that was ideal but when I learned about String Templates I thought they might be a good fit

and waited for them to be released. Once they were released, it was just a matter of dusting off the ol' Java skills

(still very rusty - thank you very much).

It also helps that I've written (or co-written) LiveView libraries for [Javascript](https://liveviewjs.com)

and [Go](https://github.com/canopyclimate/golive) so know the

protocol fairly well at this point.

## TODO

Most of these are advanced features or internal details that you don't need to know about to use Undead.

~~This is very early / PoC stage / "nothing works".~~ The basics work:

- [x] Templating - `Undead.HTML`, `If`, `Switch`, `For`, `Range`, `Join` Directives

- [x] Message JSON parsing and generation

- [x] Basic Protocol `phx-join`, `heartbeat`, page events (`click`, `keyup`, `blur`, etc) and `form` events

- [x] Internal Events (i.e. InfoEvents)

- [x] Example Project - Javalin + Undead with examples: `UndeadCounter`, `UndeadUserForm`, `UndeadSalesDashnoard`

- [x] Parts Diffing

- [x] Push Events

- [ ] Live Patch / Navigation

- [ ] File Uploads

- [ ] UndeadComponents (i.e. LiveComponents)

- [x] Building Client Javascript

- [x] JS Commands

- [x] Pub/Sub

## What is a LiveView?

At a high level, a Live...err... an UndeadView, is a server process that receives events (clicks, form input, etc) from

the browser, updates

its state, and sends back diffs which are applied to the browser. You could say it makes "spooky action at a

distance"  very easy for developers ✨. `Undead` handles all the spine-chillingly difficult things; automatically routing

events, providing a clean API for devs, and rendering (and diffing) the HTML, and applying those diffs efficiently so

the

developers can just focus on enchanting their users.

LiveViews where invented and popularized by the [Phoenix Framework](https://www.phoenixframework.org/) which is written

in Elixir and

runs on the Erlang VM. Obviously, `Undead` is not Elixir or Erlang but it adheres to the LiveView protocol and reuses

the client-side

javascript from the Phoenix Framework.  (Suffice it to say, the Phoenix Framework is awesome and kudos to the

Elixir/Erlang community for

inventing LiveViews! 🙌)

## Feedback Welcome

I haven't written Java professionally in about 12 years so would love any feedback and/or PRs!

## Elixir / Erlang folks

Please don't [Greenspun's tenth rule](https://en.wikipedia.org/wiki/Greenspun%27s_tenth_rule) me about "the BEAM" 🙀😀.
Ecosyste.ms: Awesome

https://github.com/floodfx/undead

Awesome Lists containing this project

README

Count: \{ count }

Count: \{ count }

Hello, \{ name }!

Count:

\{ count }

Count:

\{ count }
