Preparing Android Projects for Liferay Screens

To use Liferay Screens, you must install it in your Android project and then configure it to communicate with your Liferay instance. Note that Screens is released as an AAR file hosted in jCenter.

There are three different ways to install Screens. This tutorial shows you each:

  1. With Gradle: Gradle is the build system Android Studio uses to build Android projects. We therefore recommend that you use it to install Screens.

  2. With Maven

  3. Manually


Liferay Screens for Android includes the Component Library (the Screenlets) and a sample project. It requires the following software:

  • Android Studio 2.0 or above.
  • Android SDK 4.0 (API Level 15) or above. Its AppCompat library (v7:23.0.1) implements the recycler view and offers older devices a material look and feel.
  • Liferay Portal 6.2 CE/EE, 7.0 CE, Liferay DXP.
  • Liferay Screens Compatibility Plugin (CE or EE, depending on your portal edition). This app is preinstalled in Liferay 7.0 CE and Liferay DXP bundles.
  • Liferay Screens source code.

Liferay Screens for Android uses EventBus internally.

Securing JSON Web Services

Each Screenlet in Liferay Screens calls one or more of Liferay Portal’s JSON web services, which are enabled by default. The Screenlet reference documentation lists the web services that each Screenlet calls. To use a Screenlet, its web services must be enabled in the portal. It’s possible, however, to disable the web services needed by Screenlets you’re not using. For instructions on this, see the tutorial Portal Configuration of JSON Web Services.

Using Gradle to Install Liferay Screens

To use Gradle to install Liferay Screens in your Android Studio project, you must edit your app’s build.gradle file. Note that your project has two build.gradle files: one for the project and another for the app module. You can find them under Gradle Scripts in your Android Studio project. This screenshot highlights the app module’s build.gradle file:

Figure 1: The app modules build.gradle file.

Figure 1: The app module's `build.gradle` file.

In the app module’s build.gradle file, add the following line of code inside the dependencies element:

compile ''

Note that the + symbol tells Gradle to install the newest version of Screens. If your app relies on a specific version of Screens, you can replace the + symbol with that version.

If you’re not sure where to add the above lines, see the below screenshot.

Once you edit build.gradle, a message appears at the top of the file that asks you to sync your app with its Gradle files. Syncing the Gradle files incorporates the changes you make to them. Syncing also downloads and installs any new dependencies, like the Liferay Screens dependency that you just added. Sync the Gradle files now by clicking the Sync Now link in the message. The following screenshot shows the top of an edited build.gradle file with the Sync Now link highlighted by a red box:

Figure 2: After editing the app modules build.gradle file, click Sync Now to incorporate the changes in your app.

Figure 2: After editing the app module's `build.gradle` file, click *Sync Now* to incorporate the changes in your app.

In the case of conflict with the appcompat-v7 or other support libraries (,, you have several options:

  • Explicitly add the versions of the conflicting libraries you want to use. For example:

    implementation ''
    implementation ''
    implementation ''
  • Remove the dependency from your project and use the one embedded in Liferay Screens.

  • Exclude the problematic library from Liferay Screens. For example:

    implementation ('') {
        exclude group: '', module: 'design'
  • Ignore the inspection, adding a comment like this:

    //noinspection GradleCompatible
  • Ignore the warning–Liferay Screens will work without problems.

Although we strongly recommend that you use Gradle to install Screens, the following section shows you how to install Screens with Maven.

Using Maven to Install Liferay Screens

Note that we strongly recommend that you use Gradle to install Screens. It’s possible though to use Maven to install Screens. Follow these steps to configure Liferay Screens in a Maven project:

  1. Add the following dependency to your pom.xml:

  2. Force a Maven update to download all the dependencies.

If Maven doesn’t automatically locate the artifact, you must add jCenter as a new repository in your maven settings (e.g., .m2/settings.xml file):


Nice work!

Manual Configuration in Gradle

Although we strongly recommend that you use Gradle to install Screens automatically, it’s possible to use Gradle to install Screens manually. Follow these steps to use Gradle to install Screens and its dependencies manually in your Android project:

  1. Download the latest version of Liferay Screens for Android.

  2. Copy the contents of Android/library into a folder outside your project.

  3. In your project, configure a settings.gradle file with the paths to the library folders:

     include ':core'
     project(':core').projectDir = new File(settingsDir, '../../library/core')
     project(':core').name = 'liferay-screens'
  4. Include the required dependencies in your build.gradle file:

     compile project(':liferay-screens')

You can also configure the .aar binary files (in Android/dist) as local .aar file dependencies. You can download all necessary files from jCenter.

To check your configuration, you can compile and execute a blank activity and import a Liferay Screens class (like Login Screenlet).

Next, you’ll set up communication with Liferay.

Configuring Communication with Liferay

Before using Liferay Screens, you must configure it to communicate with your Liferay instance. To do this, you must provide Screens the following information:

  • Your Liferay instance’s ID

  • The ID of the site your app needs to communicate with

  • Your Liferay instance’s version

  • Any other information required by specific Screenlets

Fortunately, this is straightforward. In your Android project’s res/values folder, create a new file called server_context.xml. Add the following code to the new file:

<?xml version="1.0" encoding="utf-8"?>

    <!-- Change these values for your Liferay Portal installation -->

    <string name="liferay_server"></string>

    <string name="liferay_company_id">10155</string>
    <string name="liferay_group_id">10182</string>
    <integer name="liferay_portal_version">62</integer>


As the above comment indicates, make sure to change these values to match your Liferay instance. The server address is suitable for testing with Android Studio’s emulator, because it corresponds to localhost:8080 through the emulator. If you’re using the Genymotion emulator, you should, however, use address instead of localhost.

The liferay_company_id value is your Liferay instance’s ID. You can find it in the Control PanelConfigurationPortal Instances menu. Your Liferay instance’s ID is in the Instance ID column. Copy and paste this value from your portal to the liferay_company_id value in server_context.xml.

The liferay_group_id value is the ID of the site your app needs to communicate with. Since the app needs to communicate with the Guestbook portlet, navigate to the site you put the Guestbook portlet on. Then select AdminSite AdministrationConfiguration from the Dockbar. The site ID is listed on the Site Settings tab. Copy and paste this value from your portal to the liferay_group_id value in server_context.xml.

If you’re using version 7.0 of Liferay Portal CE or Liferay DXP, you must also set the liferay_portal_version attribute in your server_context.xml to 70. Supported values for this attribute are 62 for Liferay Portal 6.2, and 70 for Liferay Portal CE 7.0 or Liferay DXP 7.0. If you don’t set this attribute, it defaults to 62.

You can also configure Screenlet properties in your server_context.xml file. The example properties listed below, liferay_recordset_id and liferay_recordset_fields, enable DDL Form Screenlet and DDL List Screenlet to interact with a Liferay instance’s DDLs. You can see an additional example server_context.xml file here.

<!-- Change these values for your Liferay Portal installation -->

<string name="liferay_recordset_id">20935</string>
<string name="liferay_recordset_fields">Title</string>

Super! Your Android project’s ready for Liferay Screens.

Example Apps

As you use Screens to develop your apps, you may want to refer to some example apps that also use it. There are two demo applications available:

  • test-app: A showcase app containing all the currently available Screenlets.
  • Westeros Bank: An example app that uses Screenlets to manage technical issues for the Westeros Bank. It’s also available in Google Play.

Great! Now you’re ready to put Screens to use. The following tutorials show you how to do this.

Using Screenlets in Android Apps

Using Views in Android Screenlets

Preparing iOS Projects for Liferay Screens

« Introduction to Android Apps with Liferay ScreensUsing Screenlets in Android Apps »
Was this article helpful?
0 out of 0 found this helpful