Creating an Application

If you’re here, you might have downloaded the Equo CLI and added it to your operating system path. If not, please take a look to that section first.

The easiest way to learn how to use Equo is to try things out yourself. As you read this guide, try to test each method. The goal is to use Equo’s SDK core features to create a modern desktop application with a web frontend. When you finish, you’ll know how to create a web UI based on the popular framework vue.js, add native menus, trigger events from the frontend to the backend, add event handlers both in Java and JavaScript, release and share your app.

Creating your First App

From the command line, execute the equo create command and the Equo CLI will manage the rest. The following command creates an Equo application:

equo create my-app

The above command generates an interactive command line to easily create an Equo application ready to be started and executed. Follow the steps below to create a Gradle-based Equo application with Vue.js in the frontend:

interactive equo create

It is also possible to create applications inline with the following command:

equo create my-app gradle-equo-app vue true

You can import and open it in your favorite IDE. This is a great starting point to start developing an application.

Once you created your first application, you can run and take a look at it by running:

equo run ./my-app

or by running the main class from your IDE.

Import your App in your IDE

To start building your application you need a text editor or an IDE. Import your application project in your favorite IDE. You can then open your app from the IDE by running the main class of your app, which is the one that implements the IEquoApplication interface.

On macOS systems, add -XstartOnFirstThread as a vm argument before running your app. This will allow the display to be created on the main thread and avoid Cocoa issues.

Inside the src/main/resources folder you will find an index.html file. This file represents the Web UI part of your Equo application. All the resources added inside of the resources folder will be available in your app. So, if you want to separate css, html and javascript code in different files, you can do it by adding them inside the resources folder and referencing them correctly.

Creating a Web UI with VueJS

Now, you already have an Equo application with a VueJS starter template. We will now develop a simple application using Vue.js and some of the core features of the Equo SDK.

Thanks to our default template, some of the main libraries of the Equo SDK are already included in your application, such as the communication module (aka comms). The comms module allows secure real-time communication between the frontend and the backend of your application.

Open the HelloWorld.vue file to verify that the communication library is already imported. Now, create an instance of the communication module as follows:

import { EquoCommService } from "@equo/comm"

Then, create a Vue.js method that will broadcast a message with an specific handler id using the comm API, something like this:

clickEvent() {
    EquoCommService.send("MyEventHandler", "Hi, I am a message from the frontend!")
}

The send() method calls a specific handler with a message. In this case the handler that will receive the message needs to be registered in your backend using the APIs of the Equo SDK.

The full code of the HelloWorld.vue file is available below:

<!-- HelloWorld.vue file -->
<template>
  <div class="hello">
    <h1>{{ msg }}</h1>
    <h3>JavaScript-Java interaction button</h3>
    <button class="spacing" @click="clickEvent">Click me</button>
    <div class="spacing">{{ message }}</div>
  </div>
</template>

<script>
import { EquoCommService } from "@equo/comm"

export default {
  name: "HelloWorld",
  props: {
    msg: String,
  },
  data() {
    return {
      message: "",
    }
  },
  mounted() {
    EquoCommService.on("MyJavaEvent", (res) => {
      console.log(res)
      this.message = res
    })
  },
  methods: {
    clickEvent() {
      EquoCommService.send("MyEventHandler", "Hi, I am a message from the frontend!")
    },
  },
}
</script>

<style scoped>
div.hello {
  text-align: center;
}
h3 {
  margin: 40px 0 0;
}

button {
  background-color: rgb(59, 182, 110);
  border: none;
  border-radius: 10px;
  padding: 15px;
}

button:hover {
background-color: rgb(144, 255, 190);
}

button:active {
  background-color: rgb(24, 124, 66);
}

.spacing {
margin: 20px;
}
</style>

Handling Events on the Java Side

We just created some content in our web-based UI and triggered an event that will happen when a button is clicked. Now we will handle that event in our Java backend.

Create a new Java class inside of src/main/java/samplename/MyEventHandler.java in the samplename package, as follows:

package samplename;

import java.util.Calendar;

import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;

import com.equo.comm.api.ICommService;
import com.equo.comm.api.actions.IActionHandler;
import com.equo.comm.api.annotations.EventName;

@Component
public class MyEventHandler implements IActionHandler {

	@Reference
	private ICommService commService;

	@EventName("MyEventHandler")
	public String myFirstEvent(String payload) {
		System.out.println("First event: " + payload);
		String date = Calendar.getInstance().getTime().toString();
		commService.send("MyJavaEvent", date);
		return payload;
	}
}

To know more about how to trigger and handle events in Java and JavaScript, check out the Java and JavaScript Communication documentation.

Handling Events on the JavaScript Side

Open the HelloWorld.vue file again and look for the following code:

EquoCommService.on("MyJavaEvent", (res) => {
  console.log(res)
  this.message = res
})

The code from above shows how easy is to handle events in JavaScript using the comms API.

Adding Native Menus

The Equo SDK provides two ways to add native menus to the top of the application window: using the JavaScript or the Java APIs. In this guide, we will add native menus using the JavaScript API - we will also show the communication between Java and JavaScript that we already saw previously.

To use the JavaScript API, you have to import the node package corresponding to the Menu API as follows:

yarn add @equo/equo-application-menu

After that you can create menus and menu items for your application:

Menu.create()
    .withMainMenu("File")
    .addMenuItem("Exit")
    .onClick(() => EquoCommService.send('exitevent'))
    .setApplicationMenu();

The JavaScript API allows you to define menus using a builder and a set of methods - you can define them by chaining methods one by one and finally calling the setApplicationMenu() function. We will create these menus inside the App.vue main component, located in the src folder. The full code of the App.vue file is available below:

<template>
  <div id="app">
    <img alt="Vue logo" src="./assets/logo.png" />
    <hello-word msg="Welcome to Your Vue.js App" />
  </div>
</template>

<script>
import HelloWorld from "./components/HelloWorld.vue";
import { Menu } from "@equo/equo-application-menu";
import { EquoCommService } from "@equo/comm";

const comm = EquoCommService.get();

export default {
  name: "App",
  components: {
    HelloWorld,
  },
  beforeMount() {
    Menu.create()
      .withMainMenu("File")
      .addMenuItem("Exit")
      .onClick(() => EquoCommService.send('exitevent'))
      .setApplicationMenu();
  },
};
</script>

<style scoped>
#app {
  text-align: center;
}
</style>

The Exit menu item we added has as an onClick event, which triggers an exit event that we will define on the Java side. Add the following method to the MyEventHandler class to handle the exit event:

@EventName("exitevent")
public void exitEvent(String payload) {
  System.out.println("Closing app...");
  System.exit(0);
}

This method closes the application when it is called.

For more information about how to build menus both in JavaScript and Java check out the related documentation.

Test your Changes

To test all your changes and to make the app development easier in general, you can use the hot reload feature provided by the SDK. With this feature you can make changes to the UI and instantly see those changes on your running application. To run your application in hot reload mode use the following command:

equo run ./sample-name --dev

To see real time changes you make while developing your Java backend you may run your application from your IDE using the debugging tool of your IDE.

Check out this section for more information about hot reloading, and this one for debugging.

Recap

To summarize all the steps we’ve done:

  • We bootstrapped an Equo application with a predefined VueJS template that helped us with the creation of a web-based UI.

  • We experimented how the real-time communication works between the different parts of an Equo application (frontend and backend), and we added and created event handlers to manage that communication.

  • We created native menus.

  • We review how to test our changes when developing our app.

Package and Distribute your Application

The fastest and easiest way to distribute your newly created app is using the Equo dashboard.

  1. Log in to Equo.

  2. Connect your application repository.

  3. Get your installer URL.

  4. Share it. That’s it. Simple. Fast.