Update doc

tlrx · tlrx · commit 04c9626f5583 · 2012-12-20T15:03:15.000+01:00
diff --git a/README.md b/README.md
@@ -1,12 +1,12 @@
-### Introducing the ElasticSearch View Plugin
+# Introducing the ElasticSearch View Plugin
 
-ElasticSearch fournit un moyen simple et rapide de récupérer un document indexé grâce à l'API Get. Jusqu'à présent, cette
-API ne permet de récupérer un document qu'au format JSON:
-
-````
+Elasticsearch provides a fast and simple way to retrieve a document with the [GET API](http://www.elasticsearch.org/guide/reference/api/get.html).
+```
 curl -XGET 'http://localhost:9200/catalog/product/1'
+```
 
-
+Until now, this API only allows to get the document in JSON format:
+```
 {
     "_index": "catalog",
     "_type": "product",
@@ -20,7 +20,11 @@ curl -XGET 'http://localhost:9200/catalog/product/1'
         ...
     }
 }
-````
+```
+
+Although this format is really useful, it is not directly presentable to a final user. It is more dedicated to
+applications which are in charge of the
+The goal of these applications is to generate a graphic result of one or more documents for instance on HTML page. They need a specific executive environment (...) which is necessary to install, configure and maintain. as well as regular deliveries of the application when the graphic content of one document is modified.
 
 Bien que très pratique, ce format n'est pas directement présentable à un utilisateur final. Il est plutot destiné à être
 exploité par des applications tierces dont le rôle est de générer un rendu graphique d'un ou plusieurs documents, par
@@ -50,22 +54,19 @@ scripts prédéfinis, ou encore de créer une vue sur-mesure pour afficher le r
 
 ## Installing the plugin
 
-|_. elasticsearch-view-plugin	|_. ElasticSearch|
-|   master (0.0.1)      |     0.20.1     |
-
-In order to install the plugin, simply run:
+The plugin can be installed as any other ElasticSearch's plugins:
 
 ```
 bin/plugin -install tlrx/elasticsearch-view-plugin/0.0.1
 
 ```
 
-And start your ElasticSearch cluster.
+The current version of the plugin is compatible with [ElasticSearch 0.20.1](http://www.elasticsearch.org/download/2012/12/07/0.20.1.html).
 
 
 ## Creating views for existing documents
 
-Let's imagine that we have a `catalog` index in which we indexed many documents of `product` type:
+Let's imagine that we have a `catalog` index and few documents of `product` type:
 ```
 curl -XPUT 'http://localhost:9200/catalog/product/1' -d '
 {
@@ -82,12 +83,13 @@ curl -XPUT 'http://localhost:9200/catalog/product/1' -d '
 ```
 
 ElasticSearch View Plugin uses the mapping's [meta data](http://www.elasticsearch.org/guide/reference/mapping/meta.html)
-to store all the views that are associated with a specific document type. Each view has a unique name, a template language
-and a template content.
+to store all the views that are associated with a specific document type. Each view has a unique name, a scripting language,
+a content and eventually a content type.
 
-Be careful, as the [Update API](http://www.elasticsearch.org/guide/reference/api/update.html), the `_source` field need to be enabled for this feature to work.
+Be careful, as the [Update API](http://www.elasticsearch.org/guide/reference/api/update.html), the `_source` field need
+to be enabled for this feature to work.
 
-Let's create a basic view using the [MVEL templating](http://mvel.codehaus.org/MVEL+2.0+Basic+Templating) language:
+First, we can create a basic view using the [MVEL templating](http://mvel.codehaus.org/MVEL+2.0+Basic+Templating) language:
 ```
 curl -XPUT 'http://localhost:9200/catalog/product/_mapping' -d '
 {
@@ -106,17 +108,23 @@ curl -XPUT 'http://localhost:9200/catalog/product/_mapping' -d '
 
 The previous command creates a view called `default`. The property `view_lang` can be used to specify the templating
 engine to use (default is `mvel`) whereas the `view` property holds the content of the view. When needed, a specific `content_type`
-can be set. The view named `default` will be used by default to render the documents of type `product`.
+can be set. Note that the view named `default` will be used by default to render the documents of type `product`.
+
+In MVEL, the coordinates of the document are available with `@{_id}`, `@{_type}` and `@{_index}` instructions. The original
+`_source` of the document can be accessed with `@{_source._x_}` where _x_ is a document property name.
+
+Now the view is created, opening the URL `http://localhost:9200/_view/catalog/product/1` in a web browser will trigger
+the rendering of document with id 1. The result looks like:
 
-Now the view is created, opening the URL `http://localhost:9200/_view/catalog/product/1` in a web browser will trigger the rendering of document with id 1.
+![Default view for product #1](https://raw.github.com/tlrx/elasticsearch-view-plugin/gh-pages/samples/render_default.png)
 
-The result looks like:
+Simple, no?
 
-imag render_default.png
 
 ### Using multiple views
 
-Many views can be defined for the same type of document, allowing differents renderings of the same document:
+In most use cases, a unique view is not sufficient. That's why the plugins allows to define many views for the same type of document,
+ allowing differents renderings of the same document:
 
 ```
 curl -XPUT 'http://localhost:9200/catalog/product/_mapping' -d '
@@ -140,9 +148,9 @@ curl -XPUT 'http://localhost:9200/catalog/product/_mapping' -d '
 ```
 
 
-The URL `http://localhost:9200/_view/catalog/product/1/xml` can be used to access to the XML view of document 1:
+This way the URL `http://localhost:9200/_view/catalog/product/1/xml` can be used to access to the XML view of document 1:
 
-image render_xml.png
+![XML view for product #1](https://raw.github.com/tlrx/elasticsearch-view-plugin/gh-pages/samples/render_xml.png)
 
 
 ### Rendering binary fields
@@ -167,12 +175,11 @@ curl -XPUT 'http://localhost:9200/catalog/product/1' -d '
 
 ```
 
-The picture field contains a base64 encoded image of Harley Davidson's logo.
+The picture field contains a base64 encoded image of the Harley Davidson's logo.
 
 We can now define two more views:
-* logo: which renders the picture as binary content
-* full: which renders the document as HTML content
-
+* **logo**: which renders the picture as binary content
+* **full**: which renders the document as  HTML block
 
 ```
 curl -XPUT 'http://localhost:9200/catalog/product/_mapping' -d '
@@ -206,26 +213,26 @@ curl -XPUT 'http://localhost:9200/catalog/product/_mapping' -d '
 The URL `http://localhost:9200/_view/catalog/product/1/logo` can be used to get the picture of the product, whereas
  `http://localhost:9200/_view/catalog/product/1/full` renders the full HTML view:
 
-image render_html.png
-
+![HTML view of document #1](https://raw.github.com/tlrx/elasticsearch-view-plugin/gh-pages/samples/render_html.png)
 
 
 ## Using preloaded templates
 
 Similar to the [scripting module](http://www.elasticsearch.org/guide/reference/modules/scripting.html), the ElasticSearch
 View Plugin supports predefined templates scripts.
 
-The scripts can be placed under the `config/views` directory and then referencing them by the script name. The way to
+The scripts must be placed under the `config/views` directory and then referencing them by the script name. The way to
 reference a script differs according to the view language.
 
 For example, we can create the file  `config/views/copyright.mv` with the following content:
 ```
 <p>© Copyright @{_source.brand}</p>
 ```
 
-The `.mv` extension indicates that the file contains a template in MVEL language.
+The `.mv` extension indicates that the file contains a template written in MVEL.
 
-After a cluster restart, we will be able to update the `full` view in order to use the preloaded template script:
+After a cluster restart, we will be able to update the `full` view in order to use the preloaded template script (note the
+@includeNamed{} instruction):
 ```
 ...
      "full": {
@@ -235,12 +242,14 @@ After a cluster restart, we will be able to update the `full` view in order to u
 ...
  ```
 
+Preloaded templates are great candidates for code o text that are used in mulitple views.
+
 ## Creating complete views from queries
 
 The plugin allows to create custom views from query hits. Everytime such a view is requested, a set of predefined queries
-are executed and the results are used to create the view.
+are executed and the results are used to create the view. Such views are stored in ElasticSearch as documents.
 
-This kind of view are really powerful and are a simple way to create complete web pages.
+This kind of view is really powerful and are a simple way to create complete web pages.
 
 First, let's create a more complex template called `list-of-products` and stored in the file `config/views/list-of-products.mv`:
 ```html
@@ -252,8 +261,6 @@ First, let's create a more complex template called `list-of-products` and stored
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta name="description" content="">
     <meta name="author" content="">
-
-    <!-- Le styles -->
     <link href="http://twitter.github.com/bootstrap/assets/css/bootstrap.css" rel="stylesheet">
     <style>
       body {
@@ -268,7 +275,6 @@ First, let's create a more complex template called `list-of-products` and stored
   </head>
 
   <body>
-
     <div class="navbar navbar-inverse navbar-fixed-top">
       <div class="navbar-inner">
         <div class="container">
@@ -286,7 +292,6 @@ First, let's create a more complex template called `list-of-products` and stored
         </div>
       </div>
     </div>
-
     <div class="container">
         <h1>List of products with scale 1:10</h1>
         <table class="table table-striped">
@@ -310,12 +315,11 @@ First, let's create a more complex template called `list-of-products` and stored
             </tbody>
         </table>
     </div>
-
   </body>
 </html>
 ```
 
-Next, we can create the view:
+Next, we can create a view:
 ```
 curl -XPUT "http://localhost:9200/catalog/list-of-products-by-size/1:10" -d "{
     \"views\":{
@@ -340,7 +344,8 @@ curl -XPUT "http://localhost:9200/catalog/list-of-products-by-size/1:10" -d "{
 }"
 ```
 
-This view is called `default` (but could have another name) and uses the `list-of-products` template to render a list
+Note that the view is indexed in `catalog` index with the `list-of-products-by-size` document type and id `1:10`. It defines
+a view called `default` (but could have another name) and uses the `list-of-products.mv` template to render a list
 of products.
 
 The list of products is defined by the `products_with_size_1_10` query in the `queries` field of the view. This query
@@ -364,9 +369,7 @@ final HTML page. Of course, multiple queries can be used in the same view.
 
 The result is available at `http://localhost:9200/_view/catalog/list-of-products-by-size/1:10` and looks like:
 
-img render_html_list.png
-
-These kind of view are indexed as normal ElasticSearch docs.
+![List of products with scale 1:10](https://raw.github.com/tlrx/elasticsearch-view-plugin/gh-pages/samples/render_html_list.png)
 
 
 ## Going further...
@@ -376,22 +379,27 @@ These kind of view are indexed as normal ElasticSearch docs.
 The plugin [elasticsearch-view-mustache-plugin](https://github.com/tlrx/elasticsearch-view-mustache-plugin) adds
 [Mustache](http://mustache.github.com/) as templating language for views.
 
-Mustache is a great templating engine that supports template encapsulation.
+Mustache is a great templating engine that supports template encapsulation. To defined views with Mustache template engine,
+use `"view_lang": "mustache"`.
+
+Some sample usage of this plugin can be found in the Github project.
 
-### Rewriting URL with Apache2
+### Rewriting URLs with Apache2
 
-Apache2 server with mod_proxy and mod_rewrite can be used to redirect ElasticSearch Views Plugin URLs with some configuration:
+Apache2 server with mod_proxy and mod_rewrite can be used to redirect ElasticSearch Views Plugin URLs to better looking URLs.
 
+The goal is to have nicer URLs like `http://www.domain.com/catalog/list-of-products-by-size/1:10` that points
+to internal `http://localhost:9200/_view/catalog/list-of-products-by-size/1:10`.
+
+Here is a basic sample of such URL rewriting:
 ```
 RewriteEngine on
 RewriteRule ^catalog/(.*)$ http://localhost:9200/_view/catalog/$1 [P,L]
 ```
 
-This way, the URL `http://www.domain.com/catalog/list-of-products-by-size/1:10` points to `http://localhost:9200/_view/catalog/list-of-products-by-size/1:10`.
-
 
 
-Hope this plugin will be as useful as it is for us :)
+We hope that this plugin will be as useful for you as it is for us, and we welcome your feedback and comments about this new plugin.
 
 
 
