App Basics

Once webforJ and its dependencies are set up in your project, you're ready to create the app structure. This article will walk through the key elements of a basic webforJ app, specifically focusing on the Application and HomeView classes, which are the foundational classes in the webforj-archetype-hello-world starter project.

Main app class: Application.java

The Application class serves as the entry point for your webforJ app, setting up essential configurations and routes. To start, notice the class's declaration and annotations.

This class extends the core App class from webforJ, making it recognizable as a webforJ app. Various annotations configure the app's theme, title, and routing.

@Routify(packages = "com.samples.views")
@AppTitle("webforJ Hello World")
@StyleSheet("ws://app.css")
public class Application extends App {
}

• @Routify: Specifies that webforJ should scan the com.samples.views package for route components.
• @AppTitle: Defines the title displayed on the app's browser tab.
• @StyleSheet: Links an external CSS file, app.css, allowing custom styling for the app.

The Application class doesn't contain any additional methods because the configurations are set through annotations, and webforJ handles the app initialization.

With Application.java set up, the app is now configured with a title and routes pointing to the views package. Next, an overview of the HomeView class gives insight into what's displayed when the app is run.

Discovering an App

A single App limit is enforced in webforJ, which shifts all error handling responsibilities to the Java side and gives developers full control over error management.

During the webforJ bootstrap process, all classes that extend com.webforj.App are scanned. If multiple apps are found, the system looks for the com.webforj.annotation.AppEntry annotation. If any of the discovered classes are annotated with @AppEntry, the first one encountered is considered the entry point.

• If a class is annotated with @AppEntry, that class is selected as the entry point.
• If multiple classes are annotated with @AppEntry, an exception is thrown, listing all the discovered classes.
• If no class is annotated and only one subclass of App is found, that class is selected as the entry point.
• If no class is annotated and multiple subclasses of App are found, an exception is thrown, detailing each subclass.

Error Handling

For more information on how errors are handled in webforJ, see this article.

Main view class: HomeView.java

The HomeView class defines a simple view component that serves as the homepage for the app. It displays a field and a button that to greet the user's typed name.

Class declaration and annotations

HomeView extends Composite<FlexLayout>, which allows it to act as a reusable component composed of a FlexLayout component. The @Route("/") makes this the root route of the app.

@Route("/")
public class HelloWorldView extends Composite<FlexLayout> {

  private FlexLayout self = getBoundComponent();
  private TextField hello = new TextField("What is your name?");
  private Button btn = new Button("Say Hello");

  public HelloWorldView(){
    self.setDirection(FlexDirection.COLUMN);
    self.setMaxWidth(300);
    self.setStyle("margin", "1em auto");

    btn.setTheme(ButtonTheme.PRIMARY)
        .addClickListener(e -> 
          Toast.show("Welcome to webforJ Starter " + hello.getValue() + "!", Theme.GRAY));

    self.add(hello, btn);
  }
}

Component initialization

Inside the class, several UI elements are initialized and declared:

private FlexLayout self = getBoundComponent();
private TextField hello = new TextField("What is your name?");
private Button btn = new Button("Say Hello");

• self: The main layout component using FlexLayout, configured as a container for the elements. This element uses the getBoundComponent() method to store the main FlexLayout the class contains.
• hello: A TextField labeled What is your name? for users to input their name.
• btn: A primary-styled Button labeled Say Hello.

Layout configuration

The layout (self) is configured with a few key style properties:

• FlexDirection.COLUMN stacks the elements vertically.
• setMaxWidth(300) restricts the width to 300 pixels for a compact layout.
• setStyle("margin", "1em auto") centers the layout with a margin around it.

Adding components to the layout

Finally, the hello text field and btn button are added to the FlexLayout container by calling self.add(hello, btn). This arrangement defines the view’s structure, making the form both interactive and visually centered.

Styling the app

The styles.css file provides custom styling for your webforJ app. This CSS file is referenced in the Application class using the @StyleSheet annotation, which allows the app to apply styles to components within the app.

This file is located in the resources/static directory of the project, and can be referenced using the web server URL ws://app.css.