DATAREST-624 - Added reference documentations for Spring Data REST HAL Browser.

Original pull request: #193.

src/main/asciidoc/index.adoc

@@ -28,6 +28,7 @@ include::validation.adoc[leveloffset=+1]
 include::events.adoc[leveloffset=+1]
 include::metadata.adoc[leveloffset=+1]
 include::security.adoc[leveloffset=+1]
+include::tools.adoc[leveloffset=+1]
 include::customizing-sdr.adoc[leveloffset=+1]
 
 [[appendix]]

src/main/asciidoc/tools.adoc

@@ -0,0 +1,52 @@
+[[tools]]
+= Tools
+:spring-data-rest-root: ../../..
+
+== The HAL Browser
+
+The developer of the http://stateless.co/hal_specification.html[HAL spec] has a useful application: https://github.com/mikekelly/hal-browser[the HAL Browser]. It's a web app that stirs in a little HAL-powered JavaScript. You can point it at any Spring Data REST API and use it to navigate the app and create new resources.
+
+Instead of pulling down the files, embedding them in your application, and crafting a Spring MVC controller to serve them up, all you need to do is add a single dependency.
+
+In Maven:
+
+[source,xml]
+----
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.data</groupId>
+        <artifactId>spring-data-rest-hal-browser</artifactId>
+    </dependency>
+</dependencies>
+----
+
+In Gradle:
+
+[source,groovy]
+----
+dependencies {
+    compile 'org.springframework.data:spring-data-rest-hal-browser'
+}
+----
+
+NOTE: If you use Spring Boot or the Spring Data BOM (bill of materials), you don't need to specify the version.
+
+This dependency will autoconfigure the HAL Browser to be served up when you visit your application's root URI in a browser. (NOTE: http://localhost:8080 was plugged into the browser, and it redirect to the URL shown below.)
+
+image::hal-browser-1.png[]
+
+The screen shot above shows the root path of the API. On the right side are details from the response including headers and the body (a HAL document).
+
+The HAL Browser reads the links from the response and puts them on a list on the left side. You can either click on the *GET* button and navigate to one of the collections, or click on the *non-GET* option to make changes.
+
+The HAL Browser speaks *URI Template*. You may notice up above the *GET* button next to *persons* has a question mark icon. An expansion dialog will pop-up if you choose to navigate to it like this:
+
+image::hal-browser-3.png[]
+
+If you click *Follow URI* without entering anything, the variables will essentially be ignored. For situations like <<projections-excerpts>> or <<paging-and-sorting>>, this can be useful.
+
+When you click on a *non-GET* button, a pop-up dialog appears. By default, it shows *POST*. This field can be adjusted to either *PUT* or *PATCH*. The headers are filled out to properly to submit a new JSON document.
+
+Below the URI, method, and headers are the fields. These are automatically supplied based on the metadata of the resources, automatically generated by Spring Data REST. Update your domain objects, and the pop-up will reflect it.
+
+image::hal-browser-2.png[height="150"]