klient.js

Created: 2014-05-19 18:34
Updated: 2016-11-25 06:52

README.md

klient.js

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.

live demo

Sample

Here's one pulled from the test page for immediate gratification. klient.js is all of the klient-* classes.

<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>

The test page has some more examples. rawgit.com link for live demo.

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 include header 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 name 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. ?key=value1&key=value2&key=value3.

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

are captured in the module's bower.json: Bootstrap (for modal support) and jQuery. This repository is registered with bower. Be sure to include bootstrap.js and jquery.js before klient.js

bower install klient.js
Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more