WebApp SDK

A small client SDK is provided to facilitate working with HTTP-requests and URLs.

requester

requester utilizes $.ajax to perform HTTP-requests. Use require('requester') in a client context to retrieve an instance of the requester.

requester.doGet(options)

Performs a GET-request. options extend base options.

// Base options GET
{type: 'get', dataType:'json'}

define(function(require) {
   'use strict';

   var
      requester = require('requester'),
      Component = require('Component');

   return Component.extend({
      ...      
      getSomething: function(options) {
         requester.doGet({
            url: options.url,
            context: this
         }).done(function(response) {
            ...
         }).fail(function(response) {
            ...
         }).always(function(response) {
            ...
         });
      }
   });
});

requester.doPut(options)

Performs a PUT-request. Options extend base options.

// Base options PUT
{type: 'put', dataType:'json', contentType: 'application/json; charset=utf-8'}

requester.doPut({
   url: options.url,
   data: {
      value: options.value
   },
   context: this
}).done(function(response) {
   ...
});

requester.doPost(options)

Performs a POST-request. Options extend base options.

// Base options POST
{type: 'post', dataType:'json', contentType: 'application/json; charset=utf-8'}

requester.doPost({
   url: options.url,
   data: {
      value: options.value
   },
   context: this
}).done(function(response) {
   ...
});

requester.doDelete(options)

Performs a DELETE-request. Options extend base options.

// Base options DELETE
{type: 'delete', dataType:'json', contentType: 'application/json; charset=utf-8'}

requester.doDelete({
   url: options.url,
   data: {
      value: options.value
   },
   context: this
}).done(function(response) {
   ...
});

Uploading files with the requester [@since 8]

You can upload files with the requester using post/put requests. In order to do this files should be passed as FormData according to this example and a fileUpload: true property should be added to the request. Setting fileUpload: true is a shortcut for setting contentType: false and processData: false which are properties handled by $.ajax.

var formData = new FormData();
formData.append('username', 'Chris');
formData.append('userpic', myFileInput.files[0], 'chris.jpg');

requester.doPost({
   url: options.url,
   data: formData,
   fileUpload: true,
   context: this
}).done(function(response) {
   ...
});

Want to know more about how you handle files on the serverside see this page.

router

Router provides methods to facilitate working with URLs. Use require('router') in a client context to retrieve an instance of the router.

router.getUrl(path [, queryStringParameters])

Returns a URL given a path. Provide queryStringParameters as an object to include query string parameters. The URL will match configured paths in index.js.

// index.js
(function() {
   'use strict';

   var router = require('router');

   router.post('/purchase', function(req, res) {
      res.json({});
   });
}());

// Component
define(function(require) {
   'use strict';

   var
      requester = require('requester'),
      router    = require('router'),
      Component = require('Component');

   return Component.extend({
      ...
      purchase: function(options) {
         requester.doPost({
            url: router.getUrl('/purchase'), // match '/purchase' in index.js
            data: options.data,
            context: this
         }).done(function(response) {
            ...
         });
      }
   });
});

router.getStandaloneUrl(path [, queryStringParameters]) [@since 4.5.5]

Returns a URL that will execute a route standalone, i.e. it will not be part of page rendering. This is very useful when you only want to target your route without any side effects. Typical use cases are delivering a file from a route or redirecting when a form has been posted.

Below is an example of the standalone URL format:

router.getStandaloneUrl('/file');
// /appresource/4.219dbc491694cbe49067b/12.6a36ac031697183395a4/file

Example of a standalone URL being used to execute a route:

//any template
// ...
<button class="env-button" data-get-json>Get JSON</button>
// ...

// anyComponent.js
// ...
events: {
	dom: {
		'click [data-get-json]': 'handleGetJson'
	}
},

handleGetJson: function(event) {
	requester.doGet({
		url: router.getStandaloneUrl('/json'),
	}).done(data => {
		console.log(data);
	});
}
// ...

// index.js
// ...
router.get('/json', (req, res) => {
	res.json({
		name: 'Grodan Boll',
		age: 33
	});
});
// ...

router.navigate(url [, options])

Updates the URL (History API) and triggers path and/or query changes. Defaults to pushState navigation. Set the replace option to true to perform a replaceState navigation. Pass a queryParams object in the options object to update query string parameters in the URL. See the events documentation for information on how to respond to URL changes.

define(function(require) {
   'use strict';

   var
      $         = require('jquery'),
      Component = require('Component'),
      router    = require('router');

   return Component.extend({
      ...
      goToPage: function(e) {
         e.preventDefault();
			
         // updates URL
         router.navigate($(e.currentTarget).attr('href'));
      }
   });
});

// replaceState
router.navigate($(e.currentTarget).attr('href'), {replace: true});

Pass an empty string as URL to update query string parameters while maintaining current path.

router.navigate('', {
   queryParams: {
      layout: options.layout
   }
});

router.parseQueryString() [@since 4.5.3]

Returns current query string (location.search) as an object. WebApp specific parameters (sv.target and sv.<portletId>.router) are omitted from the object.

//?sv.target=12.52ed0541665c9934cb5&sv.12.52ed0541665c9934cb5.route=/test&foo=bar
router.parseQueryString(); // {foo: "bar"}