My first App
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.|
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:
Make sure you are in the directory in which you want your project to be created and run
enonic project create;
Use Up and Down to navigate between the options and chose the
Keep pressing Enter to continue with the default values for project name, destination folder and project version;
Make sure to select the previously created sandbox when asked;
Finally, you don’t need to open the starter docs for now, so type
Nand 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:
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.|
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.
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:
Change to the project directory:
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:
Building in sandbox 'tutorial'... Starting a Gradle Daemon (subsequent builds will be faster) BUILD SUCCESSFUL in 5s 3 actionable tasks: 3 executed
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 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
tutorial sandbox, we should expect that file to be on
|.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.
You’ve now successfully built and deployed your first Enonic XP 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
After those changes, redeploy your app and revisit your installed applications list:
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:
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.
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.|