Docs Developer Site
Developer 1013 - App development

My first App

Contents

Applications is the defacto way of adding functionality Enonic XP. Almost everything you’ll be using and interacting with in Enonic is an app.

For instance, if you’ve followed along, you already have two apps installed and accessible through XP admin menu on the dashboard.

Not all installed apps will show on XP admin menu, this is something that is configured on app level.

To clarify on the previous claims, here are some examples of XP apps…​ if you want have analytics, you can install google analytics app. If you want to use Enonic XP CMS in a headless way, you can install guillotine app, and access the created content through a GraphQL API. At the same time, your project idea will most likely be an app.

In the end, apps are compiled to .jar files (build processes) which are then deployed to XP instances to be executed.

The tasks and examples in this chapter are based on work done in previous chapters (starting with the sandboxes chapter). If you want to follow along with the examples, make sure you’re all caught up.

Starters

Creating a project from scratch can be a daunting task for any system you’re not familiar with. To make things easier for you, Enonic provides a range of different templates (known as starters). We’ll make use of these throughout this tutorial.

The complete list of starters can be found on the Enonic Market.

For your first project, we’ll use the "Vanilla" starter. This starter contains the bare minimum. We’ll use this to familiarize ourselves with how an XP app is structured and how to deploy it on your sandbox.

Here’s how to use the CLI to create your first app:

  1. Make sure you are in the directory in which you want your project to be created and run enonic project create;

  2. Use Up and Down to navigate between the options and chose the Vanilla starter;

  3. Keep pressing Enter to continue with the default values for project name, destination folder and project version;

  4. Make sure to select the previously created sandbox when asked;

  5. Finally, you don’t need to open the starter docs for now, so type N and press Enter.

Project names matter. XP does not support running two apps with the same name within a single instance.

If you used the default values as specified in the steps, a directory named myproject/ should have been created during the process. If you used a different project name or project directory name, your directory will have a different name.

The project directory contains a fairly minimal XP application. The most relevant parts of the directory are:

Essential XP project structure 
build.gradle (1)
gradle.properties (2)
src/
  main/
    resources/ (3)
1 The main build file for defining dependencies and more build-related details.
2 Contains the standard project settings, as defined by the CLI.
3 The main project folder. JavaScript code and assets are placed here.

Each XP project is linked to one and only one sandbox. If you want to change the sandbox that a project is linked to, make sure to be in the root directory of your project and run the following command:

enonic project sandbox

And then select the desired sandbox.

Building your app

Now that we’ve set up a project, let’s see how we build (or compile) the project and then how we deploy it to the sandbox. Again, the CLI is key to making this process as smooth as possible.

Here are the steps we need to take:

  1. Change to the project directory:

    cd myproject

  2. Start the build with Enonic CLI:

    enonic project build

While building your project, the CLI will print what it’s doing to your terminal. It will look something like this:

Sample output from build process 
Building in sandbox 'tutorial'...
Starting a Gradle Daemon (subsequent builds will be faster)

BUILD SUCCESSFUL in 5s
3 actionable tasks: 3 executed
Gradle got you worried? Enonic uses Gradle to support other programming languages and tools beyond JavaScript. Just stay calm and continue the journey!

After the build has finished, you’ll have a new file in your project directory, located under the build/libs subdirectory. Assuming you have used the default name, it’ll be located at build/libs/myproject.jar when at the project root. This file is the executable file that contains your application.

Deploying to sandbox

deploying is the term used when an app is made available to a specific XP instance, so if you made app "A" available to the XP instance "I", you could say that you have deployed app "A" to the instance "I". If the app and the instance can be inferred by context, you could just say that you have deployed.

To deploy your app to the sandbox, use the CLI again. Keep the server running or run it with enonic sandbox start --dev, if it is not running.

Now, in a different terminal, you can run the following command from the recently created project root folder, to deploy:

enonic project deploy

This copies the application .jar file to your sandbox’s home/deploy/ folder. Since in this case we deployed myproject.jar into tutorial sandbox, we should expect that file to be on ~/.enonic/sandboxes/tutorial/home/deploy.

.enonic is the folder used by CLI to manage your sandboxes and Enonic XP distributions.

XP picks up on this automatically and starts the app for you. The enonic project deploy command will build your project if you have made changes since the last build or haven’t built yet. It will also ask whether you want to start the appropriate sandbox if it isn’t already running.

To confirm that your application was started correctly, you can look at the logs in the sandbox’s terminal window. They should say something like this:

[...] - Local application [com.example.myproject] installed successfully
[...] - Application [com.example.myproject] started successfully

You can also verify that the application was installed correctly by using the admin console (http://localhost:8080): open the "Applications" app from the main launcher panel and look for your application in the list.

The applications list with a few applications installed. Also shows application details, such as content install time, version, and required XP system version for the selected application.
Figure 1. The applications list with the vanilla starter installed

You’ve now successfully built and deployed your first Enonic XP application!

Changing the display name of an application

You might have noticed that the application we created was listed as "Vanilla Example" in the applications list above. What if you wanted to change that to something more descriptive? To do that, we can head to the gradle.properties file in the project’s root directory. Change the appDisplayName to whatever you want it to display.

Similarly, you can change your application’s description to something more appropriate at the file src/main/resources/application.xml by replacing the stock text inside of the description element.

After those changes, redeploy your app and revisit your installed applications list:

The applications list with the recently installed vanilla started containing modifications on its display name and description.
Figure 2. Applications list with vanilla started updated

What if the application doesn’t show up?

If the application doesn’t show up under the Applications tab in XP after you’ve run enonic project deploy, check the logs (for the build first, and then for XP) for errors. The build might have failed or something may have gone wrong when deploying.

If the build works, but nothing shows up in the Applications tab, make sure you’re running the right sandbox. The CLI deploys to the sandbox specified during the project creation, and that’s stored in the project’s .enonic file, which is placed in the project directory root. This has to match the name of the sandbox that’s running:

.enonic file on the project root showing to which sandbox the project should be deployed to.

If the sandbox name on that file is not the one in which you wanted to deploy the project, you can directly change the sandbox name on that file and redeploy, or you can run enonic project sandbox in a terminal on the project root directory, to reconfigure the sandbox in which the project should be deploted to.

Manual deploying

If you’ve checked that you’re running the right sandbox and that the deploy succeeded, but you’re still not seeing the application, you can do a manual deploy.

The project build result is available in the build/libs directory of the project. You can copy this .jar file to the sandbox’s home/deploy directory. This will make XP pick it up. If you’ve used the suggested names in the steps above (and the default directories for XP configuration), this command will move the file for you on Unix systems when run from the project root:

mv build/libs/myproject.jar ~/.enonic/sandboxes/tutorial/home/deploy/
If you had to deploy manually when going through this tutorial, please get in touch on the community slack so we can improve the documentation and the process.

Contents