Liferay Portal provides many web services out-of-the-box to you. These services include retrieving data and information about various assets, creating new assets, and even editing existing assets.

To see a comprehensive list of the available web services, start up a bundle and navigate to http://localhost:8080/api/jsonws. This list includes any custom web services that have been deployed to the bundle. These services are useful for creating single page applications, and can even be used to create custom front-ends, both inside and outside of Liferay Portal.

This tutorial explains how to invoke these web services using JavaScript.

Go ahead and get started.

Invoking Web Services via JavaScript

Liferay Portal CE 7.0 contains a global JavaScript object called Liferay that has many useful utilities. One method is Liferay.Service, which is used for invoking JSON web services.

The Liferay.Service method takes four possible arguments:

service {string|object}: Either the service name, or an object with the keys as the service to call, and the value as the service configuration object. (Required)

data {object|node|string}: The data to send to the service. If the object passed is the ID of a form or a form element, the form fields will be serialized and used as the data.

successCallback {function}: A function to execute when the server returns a response. It receives a JSON object as it’s first parameter.

exceptionCallback {function}: A function to execute when the response from the server contains a service exception. It receives an exception message as it’s first parameter.

One of the major benefits of using the Liferay.Service method versus using a standard AJAX request is that it handles the authentication for you.

Below is an example configuration of the Liferay.Service method:

Liferay.Service(
        '/user/get-user-by-email-address',
        {
                companyId: Liferay.ThemeDisplay.getCompanyId(),
                emailAddress: '[email protected]'
        },
        function(obj) {
                console.log(obj);
        }
);

The example above retrieves information about a user by passing in the companyId and emailAddress of the user in question. The response data resembles the following JSON object:

{
        "agreedToTermsOfUse": true,
        "comments": "",
        "companyId": "20116",
        "contactId": "20157",
        "createDate": 1471990639779,
        "defaultUser": false,
        "emailAddress": "[email protected]",
        "emailAddressVerified": true,
        "facebookId": "0",
        "failedLoginAttempts": 0,
        "firstName": "Test",
        "googleUserId": "",
        "graceLoginCount": 0,
        "greeting": "Welcome Test Test!",
        "jobTitle": "",
        "languageId": "en_US",
        "lastFailedLoginDate": null,
        "lastLoginDate": 1471996720765,
        "lastLoginIP": "127.0.0.1",
        "lastName": "Test",
        "ldapServerId": "-1",
        "lockout": false,
        "lockoutDate": null,
        "loginDate": 1472077523149,
        "loginIP": "127.0.0.1",
        "middleName": "",
        "modifiedDate": 1472077523149,
        "mvccVersion": "7",
        "openId": "",
        "portraitId": "0",
        "reminderQueryAnswer": "test",
        "reminderQueryQuestion": "what-is-your-father's-middle-name",
        "screenName": "test",
        "status": 0,
        "timeZoneId": "UTC",
        "userId": "20156",
        "uuid": "c641a7c9-5acb-aa68-b3ea-5575e1845d2f"
}

Now that you know how to send an individual request, you’re ready to run batch requests.

Batching Requests

Another format for invoking the Liferay.Service method is by passing an object with the keys as the service to call and the value as the service configuration object.

Below is an example configuration for a batch request:

Liferay.Service(
        {
                '/user/get-user-by-email-address': {
                        companyId: Liferay.ThemeDisplay.getCompanyId(),
                        emailAddress: '[email protected]'
                }
        },
        function(obj) {
                console.log(obj);
        }
);

You can use this format to invoke multiple services with the same request by passing in an array of service objects. Here’s an example:

Liferay.Service(
        [
                {
                        '/user/get-user-by-email-address': {
                                companyId: Liferay.ThemeDisplay.getCompanyId(),
                                emailAddress: '[email protected]'
                        }
                },
                {
                        '/role/get-user-roles': {
                                userId: Liferay.ThemeDisplay.getUserId()
                        }
                }
        ],
        function(obj) {
                // obj is now an array of response objects
                // obj[0] == /user/get-user-by-email-address data
                // obj[1] == /role/get-user-roles data

                console.log(obj);
        }
);

Next you can learn how to nest your requests.

Nesting Requests

Nested service calls allow you to bind information from related objects together in a JSON object. You can call other services in the same HTTP request and conveniently nest returned objects.

You can use variables to reference objects returned from service calls. Variable names must start with a dollar sign ($).

The example in this section retrieves user data with /user/get-user-by-id, and uses the contactId returned from that service to then invoke /contact/get-contact in the same request.

Below is an example configuration that demonstrates the concepts covered in this section:

Liferay.Service(
        {
                "$user = /user/get-user-by-id": {
                        "userId": Liferay.ThemeDisplay.getUserId(),
                        "$contact = /contact/get-contact": {
                                "@contactId": "$user.contactId"
                        }
                }
        },
        function(obj) {
                console.log(obj);
        }
);

Here is what the response data would look like for the request above:

{
        "agreedToTermsOfUse": true,
        "comments": "",
        "companyId": "20116",
        "contactId": "20157",
        "createDate": 1471990639779,
        "defaultUser": false,
        "emailAddress": "[email protected]",
        "emailAddressVerified": true,
        "facebookId": "0",
        "failedLoginAttempts": 0,
        "firstName": "Test",
        "googleUserId": "",
        "graceLoginCount": 0,
        "greeting": "Welcome Test Test!",
        "jobTitle": "",
        "languageId": "en_US",
        "lastFailedLoginDate": null,
        "lastLoginDate": 1472231639378,
        "lastLoginIP": "127.0.0.1",
        [...]
        "screenName": "test",
        "status": 0,
        "timeZoneId": "UTC",
        "userId": "20156",
        "uuid": "c641a7c9-5acb-aa68-b3ea-5575e1845d2f",
        "contact": {
                "accountId": "20118",
                "birthday": 0,
                [...]
                "createDate": 1471990639779,
                "emailAddress": "[email protected]",
                "employeeNumber": "",
                "employeeStatusId": "",
                "facebookSn": "",
                "firstName": "Test",
                "lastName": "Test",
                "male": true,
                "middleName": "",
                "modifiedDate": 1471990639779,
                [...]
                "userName": ""
        }
}

Now that you know how to process requests, you can learn how to filter the results next.

Filtering Results

If you don’t want all the properties returned by a service, you can define a whitelist of properties. This returns only the specific properties you request in the object.

Below is an example of whitelisting properties:

Liferay.Service(
        {
                '$user[emailAddress,firstName] = /user/get-user-by-id': {
                        userId: Liferay.ThemeDisplay.getUserId()
                }
        },
        function(obj) {
                console.log(obj);
        }
);

To specify whitelist properties, place the properties in square brackets (e.g., [whiteList]) immediately following the name of your variable. The example above requests only the emailAddress and firstName of the user.

Below is the filtered response:

{
        "firstName": "Test",
        "emailAddress": "[email protected]"
}

Next you can learn how to populate the inner parameters of the request.

Inner Parameters

When you pass in an object parameter, you’ll often need to populate its inner parameters (i.e., fields).

Consider a default parameter serviceContext of type ServiceContext. To make an appropriate call to JSON web services you might need to set serviceContext fields such asscopeGroupId, as shown below:

Liferay.Service(
        '/example/some-web-service',
        {
                serviceContext: {
                        scopeGroupId: 123
                }
        },
        function(obj) {
                console.log(obj);
        }
);

Now you know how to invoke Liferay services!

Related Topics

Liferay JavaScript APIs

0 (0 Votos)
Liferay Portal JavaScript Utilities Anterior