klient.js was created to illustrate JSON services in a browser as a form of documentation. To that end it detects
special CSS-classes on an html
<form> to model some kind of JSON request, and displays the response in a nicely
formatted modal containing some of the most important bits involved in the request.
Here's one pulled from the test page for immediate gratification. klient.js is all of the
<form action="https://api.github.com/search/code" class="klient-form-query"> <input type="text" name="q" class="klient-query"/> <input type="text" name="page" class="klient-query"/> <input type="text" name="per_page" class="klient-query"/> <input type="text" name="sort" class="klient-query"/> <input type="text" name="order" class="klient-query"/> <button type="submit">GitHub API: code search</button> </form>
Binding klient.js to a JSON form
klient.js supports two kinds of forms through
<form class=...> attribute.
- klient-form-query - for forms driving a JSON request with (or without) a querystring
klient-form-body - for forms driving a JSON request with JSON in the request body. The HTTP request will
Content-Type: application/json; charset=UTF-8, which is the only sane identifier that a JSON service should expect.
klient.js picks up the HTTP request URL and method from the
<form action="..." method="..."> attributes.
The page must invoke
Klient.bind(); to bind forms. This may be invoked only once. Matched form elements
will log to the console.
query string parameters
Form elements with the class klient-query will include this value in the query string keyed by that element's
attribute. Multiple form elements with the same name are supported and serialized into the request's query string in the
only correct way, e.g.
json request body
Up to one element may have the class klient-json-body to signify this form element's value will be placed in the request body. For these kinds of freeform JSON inputs, it is usually helpful to decorate them with editor functionality such as Ace or CodeMirror.
Format loose responses
Any jqXHR requests may still be displayed in the response modal without going through a klient.js form.
Klient.initialize()will (invisibly) add the response modal elements to the end of the page. This is a prerequisite to any rendering function.
Klient.bind()would have included this step, but if you are interested in just the modal, then you don't care about binding a klient.js-formatted form.
Klient.renderRequest(request)will populate the request attributes and hide any previous response. request is an object read for the properties: type, url, contentType, data
Klient.renderResponse(jqXHR)will show and populate the response attributes given the jQuery XMLHttpRequest.
Dependencies & Inclusion
bower install klient.js