Screen Builders¶

Screens are built for a state using the IBuildScreen interface that is required to be annotated with the State Beans patterns. Screen builders have access to all the variables that were saved to the state context during Action Handlers and Event Handlers.

Screens can also be altered without re-implementing the entire IBuildScreen implementation for the state that needs its screen altered. To alter the screen implement an IAfterBuildScreen, that uses the same State Beans patterns as the screen builders, that will take in the expected UIMessage for the screen that is being built and make the alterations.

In some cases there is a desire to show a different screen or dialog based on the last action that was processed. To create a screen builder after a specific action, the IBuildScreen implementation can be annotated with @ActionScreenBuilder. This will then prioritize this screen builder to be chosen when looking for the appropriate screen to build.

Best Practices¶

Keep IBuildScreen implementations simple.

Use the Return Early Pattern to check any state data and determine if the IBuildScreen or IAfterBuildScreen is meant to be used.

@State(name = "MyState")
public class BuildMyStateAlternateScreen implements IBuildScreen<MyStateUIMessage> {
  @In(scope = ScopeType.State)
  private String myVariable;

  public Optional<BuiltScreen<MyStateUIMessage>> buildScreen() {
    if("IgnoreWhenMyVariable".equals(myVariable)) {
      return Optional.empty();
    }
    ...
  }
}

Create helper components that can be injected into the IBuildScreen implementations when common functionality across multiple IBuildScreen is required or when the logic becomes more complex and would make testing easier.

@Component
@Scope("device")
public class MyStateScreenHelper {
  public SomeOtherObject buildCommonObject(SomeRequest request) {
    ...
  }
}

@State(name = "MyState")
@RequiredArgsConstructor
public class BuildFirstScreen implements IBuildScreen<MyStateUIMessage> {
  private final MyStateScreenHelper helper;

  public Optional<BuiltScreen<MyStateUIMessage>> buildScreen() {
    ...
  }
}

Anti-patterns¶

Try not to make heavy remote calls in the builders. They are typically called often and can affect performance.
Avoid using @Out or @InOut annotations within an IBuildScreen or IAfterBuildScreen as this can alter the states data without meaning to.