JDance applications are built from Java components. Pages are composed using layouts, requests are handled by actions, and the resulting component tree is rendered to the browser.

The goal is to keep both the user interface and server interaction inside a small and consistent Java API.

Requirements

To get started you need:

- Java 17 or later.

- A servlet container such as Apache Tomcat.

- The JDance library available to your application.

- A standard Java web application project.

Application structure

A small JDance application normally consists of three main parts:

- A controller that maps incoming requests.

- Actions that handle requests.

- Components or pages that render the user interface.

A simple project might look like this:

CODE

src/main/java/
    com/example/web/
        HttpControl.java
        actions/
            ViewHome.java
        pages/
            HomePage.java

Create the controller

The HTTP controller receives requests and maps them to JDance actions.

HttpControl.java

CODE

package com.example.web;

import jakarta.servlet.annotation.WebServlet;
import org.jdance.basic.http.HttpController;

@WebServlet(urlPatterns = {"/app/*"},loadOnStartup = 1)
public class HttpControl extends HttpController{

    public static HttpControl instance;

    @Override
    public void init(){
        super.init();
        instance = this;
    }

}

The controller is loaded by the servlet container and provides the action mapper used by the application's HTTP actions.

Create an action

Actions handle requests and return components.

A simple action can return a page component.

ViewHome.java

CODE

package com.example.web.actions;

import org.jdance.Component;
import org.jdance.basic.http.HttpAction;
import org.jdance.basic.http.HttpContext;
import com.example.web.HttpControl;
import com.example.web.pages.HomePage;

public class ViewHome extends HttpAction{

    @Override
    public void init(){
        setActionMapper(HttpControl.instance.getActionMapper());
    }

    @Override
    public Component perform(HttpContext context) throws Exception{
        return new HomePage();
    }

}

The action itself stays small. Its job is to handle the request and decide what component should be returned.

Create a page

Pages are ordinary JDance components.

The page below creates a small vertical layout with a heading, some text and a button.

HomePage.java

CODE

package com.example.web.pages;

import java.io.Writer;
import org.jdance.basic.gui.BasicLayout;
import org.jdance.basic.gui.Button;
import org.jdance.basic.gui.Font;
import org.jdance.basic.gui.GuiComponent;
import org.jdance.basic.gui.Text;

public class HomePage extends GuiComponent{

    @Override
    public void render(Writer out) throws Exception{
        Text title = new Text("Hello, JDance!");
        title.setFont(new Font().setSize(24).setBold(true));

        Text description = new Text(
            "This page is built entirely from Java components."
        );

        Button button = new Button("Continue");

        BasicLayout layout = new BasicLayout(BasicLayout.Direction.VERTICAL);
        layout.setGap(12);
        layout.setPadding(30);
        layout.add(title);
        layout.add(description);
        layout.add(button);

        layout.setContext(context).render(out);
    }

}

Layouts

Layouts are used to compose components and control their position and size.

BasicLayout is the main layout primitive.

It can arrange components vertically:

CODE

BasicLayout layout = new BasicLayout(BasicLayout.Direction.VERTICAL);
layout.setGap(10);

layout.add(new Text("First"));
layout.add(new Text("Second"));
layout.add(new Text("Third"));

or horizontally:

CODE

BasicLayout layout = new BasicLayout(BasicLayout.Direction.HORIZONTAL);
layout.setGap(10);

layout.add(new Text("Left"));
layout.add(new Text("Center"));
layout.add(new Text("Right"));

Layouts can also be nested to build more complex pages.

Sizing

Components and layout cells can be given fixed or relative sizes.

CODE

BasicLayout layout = new BasicLayout(BasicLayout.Direction.HORIZONTAL);
layout.setRelativeWidth(100);

layout.add(new Text("Sidebar")).setRelativeWidth(25);
layout.add(new Text("Content")).setRelativeWidth(75);

This makes the layout responsive to the available width.

Spacing

Layouts provide padding and gaps without requiring handwritten CSS.

CODE

BasicLayout layout = new BasicLayout(BasicLayout.Direction.VERTICAL);
layout.setPadding(20);
layout.setGap(10);

Padding controls the space inside the layout.

Gap controls the distance between its cells.

Alignment

Components can be aligned inside their layout cells.

CODE

layout.add(new Text("Centered")).setHAlign(Align.CENTER);
layout.add(new Text("Right")).setHAlign(Align.RIGHT);

Horizontal and vertical alignment can be configured independently where needed.

Styling

Common visual properties are represented by Java objects.

For example:

CODE

Text title = new Text("Welcome");

title.setFont(
    new Font()
        .setSize(22)
        .setBold(true)
        .setColor(new Color("#222222"))
);

A layout can be styled in the same way:

CODE

BasicLayout panel = new BasicLayout(BasicLayout.Direction.VERTICAL);
panel.setPadding(20);
panel.setGap(10);
panel.setBackgroundColor(new Color("#F7F7F7"));
panel.setBorder(
    new Border()
        .setWidth(1)
        .setRadius(8)
        .setColor(new Color("#DEDEDE"))
);

Responsive layouts

JDance supports media-dependent component properties.

Create a Media rule:

CODE

Media mobile = new Media(0,700);

and apply different layout properties for that screen width:

CODE

BasicLayout layout = new BasicLayout(BasicLayout.Direction.HORIZONTAL);

layout.setDirection(
    mobile,
    BasicLayout.Direction.VERTICAL
);

The same component tree can therefore adapt to different screen sizes without maintaining separate pages.

Actions

Actions connect the interface to application behavior.

A normal HttpAction performs standard HTTP navigation.

For example, a button can execute another action:

CODE

Button button = new Button("Open page");
button.onClick(new ViewHome());

JDance generates the required browser-side behavior from the action.

Forms

Forms combine fields with a FormPanel.

A basic form starts with ordinary components:

CODE

InputField name = new InputField();
name.setName("name");

Button submit = new Button("Submit");

BasicLayout layout = new BasicLayout(BasicLayout.Direction.VERTICAL);
layout.setGap(10);
layout.add(name);
layout.add(submit);

The layout can then be placed inside a FormPanel and connected to an action.

Separating actions and pages

For larger applications, keep request handling and user interface code separate.

Actions should normally contain request and application logic:

CODE

@Override
public Component perform(HttpContext context) throws Exception{
    return new AccountPage();
}

while the page component contains the user interface:

CODE

public class AccountPage extends GuiComponent{

    @Override
    public void render(Writer out) throws Exception{
        BasicLayout layout = new BasicLayout(BasicLayout.Direction.VERTICAL);

        layout.add(new Text("Account"));
        layout.add(new Text("Welcome back"));

        layout.setContext(context).render(out);
    }

}

This keeps both sides small and easy to understand.

A slightly larger example

The following example shows a simple page with a header, sidebar and main content area.

CODE

Text logo = new Text("My Application");
logo.setFont(new Font().setSize(20).setBold(true));

BasicLayout header = new BasicLayout(BasicLayout.Direction.HORIZONTAL);
header.setPadding(15);
header.add(logo);

BasicLayout sidebar = new BasicLayout(BasicLayout.Direction.VERTICAL);
sidebar.setGap(8);
sidebar.setPadding(20);
sidebar.add(new Text("Home"));
sidebar.add(new Text("Projects"));
sidebar.add(new Text("Settings"));

BasicLayout content = new BasicLayout(BasicLayout.Direction.VERTICAL);
content.setGap(12);
content.setPadding(20);
content.add(new Text("Dashboard"));
content.add(new Text("Your application content goes here."));

BasicLayout body = new BasicLayout(BasicLayout.Direction.HORIZONTAL);
body.setRelativeWidth(100);
body.add(sidebar).setRelativeWidth(25);
body.add(content).setRelativeWidth(75);

BasicLayout page = new BasicLayout(BasicLayout.Direction.VERTICAL);
page.setRelativeWidth(100);
page.add(header);
page.add(body);

Even this structure is still just a tree of ordinary Java components.

Where to go next

You now have the basic structure of a JDance application:

- HttpController receives requests.

- HttpAction handles request behavior.

- GuiComponent represents pages and reusable interface components.

- BasicLayout composes components.

- Java objects control styling and responsive behavior.

Use the navigation on the left to continue through the API reference.

The GUI Components section covers layouts, components, fields and panels.

Actions covers HTTP and server interaction.

Styling covers fonts, colors, borders, sizing, alignment and responsive media rules.