Liferay projects for front-end developers

Entering a project that is on going

Are you a front-end developer entering a project that has being going on for a while? This mini tutorial will show you how to get started as quickly as possible so you can work on your designs.

This particular tutorial will be directed to front-end developers that have never worked with Liferay before and seek to understand how they can use their skills and experience gathered from previous assignments in a Liferay project.

First of all, you need to prepare your spirit to something that is possibly new and essential in Liferay projects: working in a polyglot project where its size and number of used technologies may be overwhelming at first. Interaction between front-end and back-end developers is a most, and the perception that one does not need to fully understand all parts of the project is what will free your mind to apply your skills to collaborate with the team.

When you pulled that big project from your team’s git repository, you will most likely have what is called a Liferay workspace in front of you. This is a well known structure used to host everything produced for a project. This includes back-end and front-end. You will find several Java modules, elements written in JSP, FreeMarker, Groovy… and the list goes on and on.

Do not let this intimidate you, focus, the project may contain pieces of code for the front-end around, but the ideal place to start is the themes folder. There you will find the heart of your project’s style and where you will create most of your code to improve your project's look and feel. Sure you will have assignments in other places, but that folder will be your home.

You should examine the src folder first, where the code lives. This folder will probably and minimally contain the following sub-directories: css, images, templates.  The css folder will be the host for many SCSS files that will define the portal’s overall style. The templates folder is the house of FreeMarker components that are there to provide structure in the form of templates. Templates are used to generate pages, and you will not create pages yourself. Liferay will use the templates to create pages by combining the templates with the content configured for each page.

Some teams have the styling and templates assigned to different people, but you benefit from being able to read templates even if your team is divided like that. After all, you will quickly see that this is a place where you can include HTML code, and apply the classes you need. Bootstrap 4, in Liferay 7.1, is available for you and you can include all classes you may require inside the template files. If you know HTML, CSS and friends, you can collaborate to build templates even if you do not know how to write FreeMarker code. In this case, your team will probably have someone to help you when you need. This is very much like working with a team that uses JSPs, in case you have done this kind of work before.

Do not worry at this point about how the pieces get together. Liferay does a lot of work bringing JQuery, Bootstrap, Senna, and all the elements it requires along with your customization into the pages, they will be there. What you need to know when you start is that you do not have full control over the basic elements and initial style. It is all about building the difference from the initial elements to get the final result. This means that elements will come with some style, but instead of manipulating that style you will seek to create the code that when it is applied to the original brings the final result to the form you want. You can think of this as the style Browsers apply by their own account and you just live with it.

Ok, we want to be fast here, let’s talk about how you build the project to use it in Liferay. Depending on your team, you might have an IDE that is able to understand Gradle projects, Gradle is the tool used to build everything. If your IDE is one of those, you will probably get a button to execute a task named build, the task is simply, as the name suggest, a task for Gradle. IntelliJ and Eclipse are both good ideas.

If you do not have such IDE, you will likely have one with a terminal (you can also use your system’s terminal). From the project’s root folder use ./gradlew build, or ./gradlew.bat build on windows, Gradle is likely installed inside your project for you. Some teams may not like that and require that you install Gradle on your computer as a regular program, or inside the project in the form of a wrapper. Gradle installation is beyond the scope of this tutorial, just know you need it and if it is not there, ask your tech lead to advise you.

One thing to notice is that you cannot just click and execute the gradlew files, you need to pass the build argument and to avoid having to go through extra configuration steps you can use a terminal and type the command from the project root directory.

If everything goes well, inside your theme directory you will now see two new directories: build and dist. Your theme will be inside dist, as a .war file, ready to be installed on Liferay.

The build folder is a bit interesting, even though you should never work inside that folder, probably everything you do there will be lost, as the next build will override the files. It is interesting because you will see that Liferay complements your theme with elements it provides as base that your theme did not override with a custom one. So you might see extra templates, SCSS components you did not had in your theme and even the final CSS. It is nice to poke around that folder to see parts of the theme that were not in your code but you want to override, so you can see the original.

In the workspace, you will have a Liferay installed for you, inside the bundles directory, and when you ask Gradle to deploy, the theme will be installed. If you have a shared server for development, and access to the Control Panel > Apps > App manager, then you will be able to navigate to that place and use the three dots at the top of the page on your right to upload the file created at the dist directory. It normally takes some seconds for the deployment to finish, and you will be able to see the new theme you have just deployed a little after the success message.

Please note that a lot can vary from team to team, and you should ask your colleagues about how your project works. But the ideas we described here are more or less the same for projects created in a workspace for current versions of Liferay. We described everything in an informal way, using loosely defined terms, but the goal here is to get you to work fast, and hopefully make the next text you read easier to understand.

More Blog Entries