Merge pull request #4494 from spenceralger/add_js_docs

JavaScript client docs

docs/community/clients.asciidoc

@@ -69,7 +69,9 @@ See the http://www.elasticsearch.org/guide/en/elasticsearch/client/ruby-api/curr
 
 
 [[community-javascript]]
-=== Javascript
+=== JavaScript
+
+See the http://www.elasticsearch.org/guide/en/elasticsearch/client/elasticsearch/index.html[official Elasticsearch JavaScript client].
 
 * https://github.com/fullscale/elastic.js[Elastic.js]:
   A JavaScript implementation of the ElasticSearch Query DSL and Core API.

docs/javascript/index.asciidoc

@@ -0,0 +1,138 @@
+= elasticsearch-js
+
+== Overview
+
+Official low-level client for Elasticsearch. Its goal is to provide common
+ground for all Elasticsearch-related code in JavaScript; because of this it tries
+to be opinion-free and very extendable.
+
+The full documentation is available at http://elasticsearch.github.io/elasticsearch-js
+
+
+=== Getting the Node.js module
+
+To install the module into an existing Node.js project use npm:
+
+[source,sh]
+------------------------------------
+npm install elasticsearch
+------------------------------------
+
+=== Getting the browser client
+
+For a browser-based projects, builds for modern browsers are available http://elasticsearch.github.io/elasticsearch-js#browser-builds[here]. Download one of the archives and extract it, inside you'll find three files, pick the one that best matches your environment:
+
+ * elasticsearch.jquery.js - for projects that already use jQuery
+ * elasticsearch.angular.js - for Angular projects
+ * elasticsearch.js - generic build for all other projects
+
+Each of the library specific builds tie into the AJAX and Promise creation facilities provided by their respective libraries. This is an example of how Elasticsearch.js can be extended to provide a more opinionated approach when appropriate.
+
+=== Setting up the client
+
+Now you are ready to get busy! First thing you'll need to do is create an instance of `elasticsearch.Client`. Here are several examples of configuration parameters you can use when creating that instance. For a full list of configuration options see http://elasticsearch.github.io/elasticsearch-js/index.html#configuration[the configuration docs].
+
+[source,javascript]
+------------------------------------
+var elasticsearch = require('elasticsearch');
+
+// Connect to localhost:9200 and use the default settings
+var client = new elasticsearch.Client();
+
+// Connect the client to two nodes, requests will be
+// load-balanced between them using round-robin
+var client = elasticsearch.Client({
+  hosts: [
+    'elasticsearch1:9200',
+    'elasticsearch2:9200'
+  ]
+});
+
+// Connect to the this host's cluster, sniff
+// for the rest of the cluster right away, and
+// again every 5 minutes
+var client = elasticsearch.Client({
+  host: 'elasticsearch1:9200',
+  sniffOnStart: true,
+  sniffInterval: 300000
+});
+
+// Connect to this host using https, basic auth,
+// a path prefix, and static query string values
+var client = new elasticsearch.Client({
+  host: 'https://user:password@elasticsearch1/search?app=blog'
+});
+------------------------------------
+
+
+=== Setting up the client in the browser
+
+The params accepted by the `Client` constructor are the same in the browser versions of the client, but how you access the Client constructor is different based on the build you are using. Below is an example of instantiating a client in each build.
+
+[source,javascript]
+------------------------------------
+// elasticsearch.js adds the elasticsearch namespace to the window
+var client = elasticsearch.Client({ ... });
+
+// elasticsearch.jquery.js adds the es namespace to the jQuery object
+var client = jQuery.es.Client({ ... });
+
+// elasticsearch.angular.js creates an elasticsearch
+// module, which provides an esFactory
+var app = angular.module('app', ['elasticsearch']);
+app.service('es', function (esFactory) {
+  return esFactory({ ... });
+});
+------------------------------------
+
+=== Using the client instance to make API calls.
+
+Once you create the client, making API calls is simple.
+
+[source,javascript]
+------------------------------------
+// get the current status of the entire cluster.
+// Note: params are always optional, you can just send a callback
+client.cluster.health(function (err, resp) {
+  if (err) {
+    console.error(err.message);
+  } else {
+    console.dir(resp);
+  }
+});
+
+// index a document
+client.index({
+  index: 'blog',
+  type: 'post',
+  id: 1,
+  body: {
+    title: 'JavaScript Everywhere!',
+    content: 'It all started when...',
+    date: '2013-12-17'
+  }
+}, function (err, resp) {
+  // ...
+});
+
+// search for documents (and also promises!!)
+client.search({
+  index: 'users',
+  size: 50,
+  body: {
+    query: {
+      match: {
+        profile: 'elasticsearch'
+      }
+    }
+  }
+}).then(function (resp) {
+  var hits = resp.body.hits;
+});
+------------------------------------
+
+== Copyright and License
+
+This software is Copyright (c) 2013 by Elasticsearch BV.
+
+This is free software, licensed under The Apache License Version 2.0.