- Maven Central
- Code examples
- Routing
- HTML markup Java DSL
- DOM events
- SPAs, plain pages head tag
- Page HTTP status code and HTTP headers
- UI components
- How to use components
- How to implement a stateful component
- Evaluating code on the client-side
- Web server's configuration
- Logging
Admin Server Components core is a Java web Server Side Rendering (SSR) framework for building real-time admin UIs as server-side applications with minimum dependencies.
<dependency>
<groupId>io.github.vadimv</groupId>
<artifactId>rsp</artifactId>
<version>2.0.0</version>
</dependency>This project requires Java version 17 or newer.
ASC core provides a Java internal domain-specific language to define HTML templates as a composition of functions.
For example, the HTML fragment:
<!DOCTYPE html>
<html>
<body>
<h1>This is a heading</h1>
<div class="par">
<p>This is a paragraph</p>
<p>Some dynamic text</p>
</div>
</body>
</html> to be represented in the Java DSL as the code fragment below:
import static rsp.html.HtmlDsl.*;
...
final View<State> view = state -> html(
body(
h1("This is a heading"),
div(attr("class", "par"),
p("This is a paragraph"),
p(state.text)) // adds a paragraph with a text from the state object
)
);where:
- HTML tags are the
rsp.html.HtmlDslclass' methods with same names, e.g.<div></div>translates todiv() - HTML attributes are the
rsp.html.HtmlDsl.attr(name, value)function, e.g.class="par"translates toattr("class", "par") - Text nodes are represented either by tags methods' String parameter or by the
rsp.html.HtmlDsl.text(string)wrapper
The of() DSL function takes a Stream<T> of objects, e.g. a sequence of tags, or a table rows:
import static rsp.html.HtmlDsl.*;
...
state -> ul(of(state.items.stream().map(item -> li(item.name))))An overloaded variant of of() accepts a CompletableFuture<S>:
final Function<Long, CompletableFuture<String>> lookupService = userDetailsByIdService();
...
// consider that at this moment we know the current user's Id
state -> stateUpdate -> div(of(lookupService.apply(state.user.id).map(str -> text(str))))another overloaded of() function takes a Supplier<S> as its argument and allows inserting code fragments.
import static rsp.html.HtmlDsl.*;
...
state -> of(() -> {
if (state.showInfo) {
return p(state.info);
} else {
return p("none");
}
})The when() DSL function conditionally renders (or not) an element:
state -> when(state.showLabel, span("This is a label"))To respond to browser events, register a DOM event handler by adding an on(eventType, handler) on an HTML element:
final ComponentView<State> view = state -> stateUpdate ->
a("#", "Click me", on("click",
ctx-> {
System.out.println("Clicked " + state.counter() + " times");
stateUpdate.setState(new State(s.counter() + 1));
}));
record State(int counter) {}Some types of browser events, like a mouse move, may fire a lot of events' invocations. Sending all these notifications over the network and processing them on the server side may cause the system's overload.
To filter the events use the following event object methods:
throttle(int timeFrameMs)debounce(int waitMs, boolean immediate)
window().on("scroll", ctx -> {
System.out.println("A throtteld page scroll event");
}).throttle(500)The ctx.eventObject() method provides its event's object as a JSON data structure:
form(on("submit", ctx -> {
// Prints the submitted form's input field value
System.out.println(ctx.eventObject());
}),
input(attr("type", "text"), attr("name", "val")),
input(attr("type", "button"), attr("value", "Submit"))
)To send a custom event use the ctx.dispatchEvent() method:
on("custom-event",
ctx -> {
System.out.println("Custom event object: " + ctx.eventObject());
})
...
on("click",
ctx -> ctx.dispatchEvent(new CustomEvent("custom-event",
JsonDataType.Object.EMPTY.put("key",
new JsonDataType.String("value")))))A custom event is bubbled from a child element and can be handled by its ancestor's event handler.
The window().on(eventType, handler) DSL function registers an event handler on the browser's window object:
html(window().on("click", ctx -> {
System.out.println("window clicked");
})
...
)ASC core framework supports two types of web pages:
- server-side single-page applications (SPAs), written in Java, e.g. for an admin UI
- plain server-rendered detached HTML pages
The page's <head> tag DSL determines if this page is an interactive Single-Page-Application or a plain HTML page.
The head(...) or head(PageType.SPA, ...) function creates an HTML page <head> tag for an SPA.
If the head() is not present in the page's markup, the simple SPA-type header is added automatically.
This type of head injects a script, which establishes a WebSocket connection between the browser's page and the server
and enables reacting to the browser events.
head(HeadType.PLAIN, ...) renders the markup with the <head> tag without injecting of init script
to establish a connection with server and enable server side events handling for SPA.
This results in rendering of a plain detached HTML page.
statusCode()method sets result response HTTP status code.addHeaders()method adds response headers.
For example:
__ -> html(
head(HeadType.PLAIN, title("404 page not found")),
body(
div(
p("404 page not found")
)
)
).statusCode(404);A web page's components tree HTML generation consists of two phases:
- a routing function maps an incoming HTTP request to the root component state
- the root component and its descendants render this state to HTML markup
To define a routing of an incoming request, create a Routing and provide it as a parameter:
import static rsp.html.RoutingDsl.*;
...
final App<State> app = new App<>(routes(), render());
...
private static Routing<HttpRequest, State> routes() {
final var db = new Database();
return routing(concat(get("/articles", req -> db.getArticles().thenApply(articles -> State.ofArticles(articles))),
get("/articles/:id", (__, id) -> db.getArticle(id).thenApply(article -> State.ofArticle(article))),
get("/users/:id", (__, id) -> db.getUser(id).thenApply(user -> State.ofUser(user))),
post("/users/:id(^\\d+$)", (req, id) -> db.setUser(id, req.queryParam("name")).thenApply(result -> State.userWriteSuccess(result)))),
NotFound.INSTANCE);
}During a dispatch, the routes are verified individually for a matching HTTP method and a path pattern.
Route path patterns can include zero, one, or two path-extracting variables, possibly combined with regexes and the wildcard symbol "*"
The matched variable values become available as the correspondent handlers' parameters alongside the request details object.
The route's handler function should return a CompletableFuture of the page's state:
get("/users/*", req -> CompletableFuture.completedFuture(State.ofUsers(List.of(user1, user2))))If needed, extract a paths-specific routing section:
final Routing<HttpRequest, State> routing = routing(get(__ -> paths()),
State.pageNotFound());
private static PathRoutes<State> paths() {
return concat(path("/articles", db.getArticles().thenApply(articles -> State.ofArticles(articles))),
path("/articles/:id", id -> db.getArticle(id).thenApply(article -> State.ofArticle(article)));
}Use match() DSL function routing to implement custom matching logic, for example:
match(req -> req.queryParam("name").isPresent(), req -> CompletableFuture.completedFuture(State.of(req.queryParam("name"))))The any() route matches every request.
Pages are composed of components of two types:
- views or stateless components
- stateful components
A view is a pure function from an input state to a DOM fragment's definition.
public static View<State> appView = state ->
switch (state) {
case NotFoundState nf -> statelessComponent(nf, notFoundStatelessView);
case UserState user -> component(user, userComponentView);
case UsersState users -> component(users, usersComponentView);
}
appView.apply(new UserState("Username"));A stateful component has its associated current state snapshot, an object of an immutable class or a record , which is managed by the framework.
A state is set:
- on a component's initialization during its first render
- on an update as a result of an event, triggered by browser events or asynchronous events, e.g. timers
A component state update is initiated by invoking of a ComponentView<S> parameter's StateUpdate interface methods, e.g. setState(newState).
Include a new instance of component definition class to the DSL alongside HTML definition tags.
div(span("Two counters"),
new Counter(1),
new Counter(2))Note that a component's code is executed on the server, use only components you trust.
- extend from one of the subclasses of the base component definition class
StatefulComponentDefinition<S> - for simple cases use
ComponentDslhelper methods
The propertiesByRef() method of a DOM event context object provides access to the client-side elements properties.
final ElementRef inputRef = createElementRef();
...
input(elementId(inputRef),
attr("type", "text")),
a("#", "Click me", on("click", ctx -> {
var props = ctx.propertiesByRef(inputRef);
props.getString("value").thenAccept(value -> {
System.out.println("Input element's value: " + value);
props.setState("value", "new text");
});
}))A reference to an object can be created on-the-fly using RefDefinition.withKey() method.
There is also the special window().ref() reference for the page's window object.
To invoke arbitrary EcmaScript code in the browser use the ctx.evalJs() method.
evalJs() sends a code fragment to the client and returns its evaluation result as a CompletableFuture<JsonDataType>.
...
button(attr("type", "button"),
text("Alert"),
on("click",
ctx -> ctx.evalJs("alert('Hello from the server')"))),
button(attr("type", "button"),
text("Calculate"),
on("click",
ctx -> ctx.evalJs("1+1").whenComplete((r,e) -> System.out.println("1+1=" + r)))
...The rsp.jetty.WebServer class constructor accepts extra parameters like an optional static resources' handler
and a TLS/SSL configuration:
final var staticResources = new StaticResources(new File("src/main/java/rsp/tetris"), "/res/*");
final var sslConfig = SslConfiguration("/keysore/path", "changeit");
final var server = new WebServer(8080, app, staticResources, sslConfig);
server.start();
server.join();This project's uses System.Logger for server-side logging.
On the client-side, to enable detailed diagnostic data exchange logging, enter in the browser console:
RSP.setProtocolDebugEnabled(true)