Quickstart

How to start using Medusa in your code

Last updated 3 years ago

Quickstart

How to start using Medusa in your code

Add dependencies (Maven)

Add the medusa-ui dependency, and make sure you have spring-boot-starter-webflux included in your pom.xml

		<dependency>
			<groupId>io.getmedusa</groupId>
			<artifactId>medusa-ui</artifactId>
			<version>...</version>
		</dependency>
		
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-webflux</artifactId>
		</dependency>

Always check for the latest release before using a version:

Create an HTML page

Under/src/main/resources, create a folder called pages

Under this folder, add a hello-world.html

<!DOCTYPE html>
<html lang="en"
      xmlns:m="https://medusa-ui.dev" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="https://medusa-ui.dev https://raw.githubusercontent.com/medusa-ui/medusa/poc/xml-parser/medusa-ui.xsd">
<head>
    <meta charset="UTF-8">
    <title>Hello Medusa</title>    
</head>
<body>
<h1>🦑 Hello Medusa</h1>
<p>Some example text.</p>
</body>
</html>

Create an event handler

Comfortable with Spring Controllers? This will feel very familiar.

Create a classHelloWorldEventHandlerin an appropriate package (for example com.sample.medusa.eventhandler).

Annotate it with@UIEventPageand point it to the right page and path.

import io.getmedusa.medusa.core.annotation.UIEventPage;

@UIEventPage(path = "/hello", file = "pages/hello-world.html")
public class HelloWorldEventHandler {

}

Add initial variables

If you will be using variables within your page, you'll want to define an initial value for them. This value can be different per request. You do this by adding a setupAttributes method.

This step is often wanted, but not required. It is possible to simply create an @UIEventPage that can only execute actions.

import io.getmedusa.medusa.core.annotation.PageAttributes;
import io.getmedusa.medusa.core.annotation.UIEventPage;
import io.getmedusa.medusa.core.annotation.UIEventWithAttributes;
import io.getmedusa.medusa.core.util.SecurityContext;
import org.springframework.web.reactive.function.server.ServerRequest;

@UIEventPage(path = "/hello", file = "pages/hello-world.html")
public class HelloWorldEventHandler {

    public PageAttributes setupAttributes(ServerRequest request, SecurityContext securityContext) {
        return new PageAttributes().with("name", "Maria");
    }

}

This method also gives you access to the current request information and, in case you are using Spring Security, the security context. That said, neither the request nor the securityContextis required, and both can be used as parameters in any order. So the following is also valid:

public PageAttributes setupAttributes() { ...

OR

public PageAttributes setupAttributes(ServerRequest request) { ...

OR

public PageAttributes setupAttributes(SecurityContext securityContext) { ...

OR

public PageAttributes setupAttributes(SecurityContext securityContext, ServerRequest request) { ...

And you can even define a custom setup method by adding it as a parameter to @UIEventPage, as such:

@UIEventPage(path = "/", file = "hello.html", setup = "customSetup")
public class HelloWorldEventHandler {

    public PageAttributes customSetup() {
        return new PageAttributes().with("name", "Maria");
    }

}

You can visualize the variable in your HTML page as a label within text, or as part of an attribute.

Labels are represented as such: <m:text item="name-of-the-variable" />

As an example, this is what your hello-world.html could look like. Notice you can also use it in something like the page title.

<!DOCTYPE html>
<html lang="en" ...>
<head>
    <meta charset="UTF-8">
    <title m:item="name"></title>
</head>
<body>
<h1>🦑 Hello <m:text item="name" /></h1>
<p>Some example text.</p>
</body>
</html>

Add interactivity

In HTML

Interactivity is handled through so-called medusa expressions and attributes. They're nothing more than extensions to HTML.

For now, let's add a very simple example: A text label showing a number and a button. You press the button, the number in the text label increases.

We already saw how to add variables within HTML in the previous section.

Additionally, there are attributes available that can be added to HTML elements. One of those is m-click

So we change our hello-world.htmlto something like this:

<!DOCTYPE html>
<html lang="en" ...>
<head>
    <meta charset="UTF-8">
    <title m:item="name"></title>   
</head>
<body>
<h1>🦑 Hello <m:text item="name" /></h1>

<p>Counter: <m:text item="my-counter" /></p>
<button m:click="increase(1)">Increase the value of the counter</button>

</body>
</html>

In Java

Now we should make the Java code aware of themy-countervariable and theincreasemethod.

The action you can do, increase() , just becomes a method in your UIEventController. This method returns DOMChanges. We just add key/value pairs that need any changes on the level of the DOM.

@UIEventPage(path = "/hello", file = "pages/documentation-test.html")
public class HelloWorldEventHandler {

    private int count = 0;

    @Override
    public PageAttributes setupAttributes(ServerRequest request, SecurityContext securityContext) {
        return new PageAttributes()
            .with("name", "Maria")
            .with("my-counter", count)
    }

    public DOMChanges increase(int increaseByThisMuch) {
        count += increaseByThisMuch;
        return DOMChanges.of("my-counter", count);
    }
}

That's it! Run the application and you'll see that you have direct integration with your backend.

PreviousConcept NextExpressions