Home

Welcome to the scenario wiki!

Why Scenario?

Each time when we write the CLI application on Java, we have to answer the following questions and then implement the corresponding logic:

• design the menu system:
• which menu should be displayed first?
• which items (choices) should each menu contain?
• which menu should be displayed when user chooses the action or types some text?
• how to prevent the user from typing incorrect value?
• how to call the needed business logic when some action is chosen?
• how to be sure that menu won't fall into never-ending cycle (user won't be able to exit the app)?
  ... and many others.

It leads to nested if or switch statements, input control classes and other boilerplate code.

The main purpose of the scenario library is to delegate all the CLI menu handling to it, so it will act as a service.

---

Quick Start Guide

Add the Dependency

Add the following dependency to your project's pom.xml:

⚠️ WARNING! The release version is not published yet and will be ready when this wiki page is complete.

<dependency>
    <groupId>com.github.prifiz</groupId>
    <artifactId>scenario</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

Menu Configuration

Okay, you've just added the needed dependency to your project. What's next?
It's time to forget that you're developer and start designing the menu.
It is really easy. You can even ask someone without any programming skills to configure it. The only required thing to know here is YAML syntax.
Now let's create a simple menu configuration:

1. Create an empty yaml-file with any name you want, e.g. myfirstmenu.yml
2. The root element should be "menuSystem:".
3. Create a menu by specifying its name and text.
   The name should be unique for referencing this menu by the others, the text value will be displayed in your command line app.
   The simplest menu configuration will look like this:

menuSystem:
 # Home Menu
  - name: "home"
    text: |
          Welcome to my awesome app.
          It was quite easy to configure it!

This is still not actually a menu system because it doesn't provide any options to choose. Let's add a couple.

menuSystem:
 # Home Menu
  - name: "home"
    text: |
          Welcome to my awesome app.
          It was quite easy to configure it!
    items:
      - name: "option1"
        text: "Option One"

      - name: "option2"
        text: "Option Two"

What happened here:

• our menu will display the welcome text specified in "text" attribute,
• next, the two options will be displayed:
  • Option One
  • Option Two

But... it is still not a menu system because it can't go to the chosen menu.
To do this, let's add two other menus and link the items with them by "gotoMenu" attribute:

menuSystem:
  # Home Menu
  - name: "home"
    text: |
          Welcome to my awesome app.
          It was quite easy to configure it!
    items:
      - name: "option1"
        text: "Option One"
        gotoMenu: "menuOne"

      - name: "option2"
        text: "Option Two"
        gotoMenu: "menuTwo"
  
  # Menu One
  - name: "menuOne"
    text: "Welcome to Menu One!"

  # Menu Two
  - name: "menuTwo"
    text: "Welcome to Menu Two!"

Well done!
Save the myfirstmenu.yml file somewhere to the project resources.

Running the Menu System

Now we are finally ready for returning to Java code to enable the menu.
Open the class of your app where you want the menu to be called.

import org.prifizapps.walkers.MenuWalkerInitiator;
import java.io.IOException;
import java.io.InputStream;

public class MyFirstMenuClass {

    public void runMenuSystem() throws IOException {
        InputStream inputStream = this.getClass().getResourceAsStream("myfirstmenu.yml");
        MenuWalkerInitiator.initMenu(inputStream).run();
    }

}

That's it! You've just added a CLI menu system to your application by typing only 2 lines of java code!
Now you can run your app and type "Option One" for going to Menu One or "Option Two" for going to Menu Two.

Interaction With the Client Code

Well, now you're able to configure the menu system and run it from your Java app.
But the menu system should interact with application's business logic.
To do this, the adapters should be used.