dependencies.halbrowser.README.adoc Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of akka-http-hal_2.11 Show documentation
akka-http-hal
The newest version!
= HAL-browser

An API browser for the hal+json media type

== Example Usage

Here is an example of a hal+json API using the browser:

http://haltalk.herokuapp.com/explorer/browser.html[http://haltalk.herokuapp.com/explorer/browser.html]

== About HAL

HAL is a format based on json that establishes conventions for
representing links. For example:

[source,javascript]
----
{
    "_links": {
        "self": { "href": "/orders" },
        "next": { "href": "/orders?page=2" }
    }
}
----

More detail about HAL can be found at
http://stateless.co/hal_specification.html[http://stateless.co/hal_specification.html].

== Customizing the POST form

By default, the HAL Browser can't assume there is any metadata. When you click on the non-GET request button (to create a new resource), the user must enter the JSON document to submit. If your service includes metadata you can access, it's possible to plugin a custom view that makes use of it.

. Define your custom view.
+
Here is an example that leverages Spring Data REST's JSON Schema metadata found at */{entity}/schema*.
+
[source,javascript]
----
var CustomPostForm = Backbone.View.extend({
	initialize: function (opts) {
		this.href = opts.href.split('{')[0];
		this.vent = opts.vent;
		_.bindAll(this, 'createNewResource');
	},

	events: {
		'submit form': 'createNewResource'
	},

	className: 'modal fade',

	createNewResource: function (e) {
		e.preventDefault();

		var self = this;

		var data = {}
		Object.keys(this.schema.properties).forEach(function(property) {
			if (!("format" in self.schema.properties[property])) {
				data[property] = self.$('input[name=' + property + ']').val();
			}
		});

		var opts = {
			url: this.$('.url').val(),
			headers: HAL.parseHeaders(this.$('.headers').val()),
			method: this.$('.method').val(),
			data: JSON.stringify(data)
		};

		var request = HAL.client.request(opts);
		request.done(function (response) {
			self.vent.trigger('response', {resource: response, jqxhr: jqxhr});
		}).fail(function (response) {
			self.vent.trigger('fail-response', {jqxhr: jqxhr});
		}).always(function () {
			self.vent.trigger('response-headers', {jqxhr: jqxhr});
			window.location.hash = 'NON-GET:' + opts.url;
		});

		this.$el.modal('hide');
	},

	render: function (opts) {
		var headers = HAL.client.getHeaders();
		var headersString = '';

		_.each(headers, function (value, name) {
			headersString += name + ': ' + value + '\n';
		});

		var request = HAL.client.request({
			url: this.href + '/schema',
			method: 'GET'
		});

		var self = this;
		request.done(function (schema) {
			self.schema = schema;
			self.$el.html(self.template({
			    href: self.href,
			    schema: self.schema,
			    user_defined_headers: headersString}));
			self.$el.modal();
		});

		return this;
	},
	template: _.template($('#dynamic-request-template').html())
});
----
+
. Register it by assigning to `HAL.customPostForm`
+
[source,javascript]
----
HAL.customPostForm = CustomPostForm;
----
+
. Load your custom JavaScript component and define your custom HTML template.
+
[source,html,indent=0]
----

----

NOTE: To load a custom JavaScript module AND a custom HTML template, you will probably need to create a customized version of `browser.html`.

NOTE: The HAL Browser uses a global `HAL` object, so there is no need to deal with JavaScript packages.

== Usage Instructions

All you should need to do is copy the files into your webroot.
It is OK to put it in a subdirectory; it does not need to be in the root.

All the JS and CSS dependencies come included in the vendor directory.

== TODO

* Provide feedback to user when there are issues with response (missing
self link, wrong media type identifier)
* Give 'self' and 'curies' links special treatment