extending and updating documentation for visualize (#14441)

* extending and updating documentation for visualize

* updating based on review

docs/development/visualize/development-create-visualization.asciidoc

@@ -22,6 +22,7 @@ source code and the existing visualizations provided with it.
 * <<development-custom-response-handler>>
 - <<development-vis-object>>
 * <<development-vis-timefilter>>
+- <<development-aggconfig>>
 
 [[development-visualization-factory]]
 === Visualization Factory
@@ -30,7 +31,7 @@ Use the `VisualizationFactory` to create a new visualization.
 The creation-methods create a new visualization tied to the underlying rendering technology.
 You should also register the visualization with `VisTypesRegistryProvider`.
 
-["source","html"]
+["source","js"]
 -----------
 import { CATEGORY } from 'ui/vis/vis_category';
 import { VisFactoryProvider } from 'ui/vis/vis_factory';
@@ -335,7 +336,36 @@ This response matches the visData property of the <visualization> directive.
 
 [[development-default-response-handler]]
 ==== default response handler
-Default response handler will convert pure elasticsearch response to tabular format.
+The default response handler converts pure elasticsearch responses into a tabular format. 
+It is the recommended responseHandler. The response object contains a table property, 
+which is an array of all the tables in the response. Each of the table objects has two properties:
+
+- `columns`: array of column objects, where each column object has a title property and an aggConfig property
+- `rows`: array of rows, where each row is an array of non formatted cell values
+
+Here is an example of a response with 1 table, 3 columns and 2 rows:
+
+["source","js"]
+-----------
+{
+  tables: [{
+    columns: [{
+      title: 'column1',
+      aggConfig: ...
+    },{
+      title: 'column2',
+      aggConfig: ...
+    },{
+      title: 'column3',
+      aggConfig: ...
+    }],
+    rows: [
+      [ '404', 1262, 12.5 ]
+      [ '200', 343546, 60.1 ]
+    ]
+  }];
+}
+-----------
 
 [[development-none-response-handler]]
 ==== none response handler
@@ -387,6 +417,10 @@ The `vis` object holds the visualization state and is the window into kibana:
 - *vis.uiStateVal(name, val)*: updates a property in UI state
 - *vis.isEditorMode()*: returns true if in editor mode
 - *vis.API.timeFilter*: allows you to access time picker
+- *vis.API.queryFilter*: gives you access to queryFilter
+- *vis.API.queryManager*: gives you access to add filters to the filter bar
+- *vis.API.filterManager*: gives you access to filterManager
+- *vis.API.kuery*: gives you access to the experimental `keury`-language filter bar
 - *vis.API.events.click*: default click handler
 - *vis.API.events.brush*: default brush handler
 
@@ -404,10 +438,32 @@ You can access filter bar and time picker through the objects defined on `vis.AP
 ==== timeFilter
 
 Update the timefilter time values and call update() method on it to update time picker
+
 ["source","js"]
 -----------
    timefilter.time.from = moment(ranges.xaxis.from);
    timefilter.time.to = moment(ranges.xaxis.to);
    timefilter.time.mode = 'absolute';
    timefilter.update();
------------
+-----------
+
+
+[[development-aggconfig]]
+=== AggConfig object
+ 
+The AggConfig object represents an aggregation search to Elasticsearch, 
+plus some additional functionality to manage data-values that belong to this aggregation. 
+This is primarily used internally in Kibana, but you may find you have a need for it 
+when writing your own visualization. Here we provide short description of some of the methods on it, 
+however the best reference would be to actually check the source code.
+ 
+  
+- *fieldFormatter(<type>)* : returns a function which will format your value according to field formatters defined on
+the field. The type can be either 'text' or 'html'.
+- *makeLabel()* : gets the label for the aggregation
+- *isFilterable()* : return true if aggregation is filterable (you can then call createFilter)
+- *createFilter(bucketKey)* : creates a filter for specific bucket key
+- *getValue(bucket)* : gets value for a specific bucket
+- *getField()* : gets the field used for this aggregation
+- *getFieldDisplayName()* : gets field display name
+- *getAggParams()* : gets the arguments to the aggregation

docs/development/visualize/development-embedding-visualizations.asciidoc

@@ -5,6 +5,23 @@ There are two different angular directives you can use to insert a visualization
 To display an already saved visualization, use the `<visualize>` directive. 
 To reuse an existing Visualization implementation for a more custom purpose, use the `<visualization>` directive instead.
 
+==== VisualizeLoader
+The `VisualizeLoader` class i the easiest way to embed a visualization into your plugin. It exposes
+two methods:
+
+- `getVisualizationList()`: which returns promise which gets resolved with list of saved visualizations
+- `embedVisualizationWithId(container, savedId, params)`: which embeds visualization by id
+- `embedVisualizationWithSavedObject(container, savedObject, params)`: which embeds visualization from saved object
+
+`container` should be a dom element to which visualization should be embedded
+`params` is a parameter object where the following properties can be defined:
+
+- `timeRange`: time range to pass to `<visualize>` directive
+- `uiState`: uiState to pass to `<visualize>` directive
+- `appState`: appState to pass to `<visualize>` directive
+- `showSpyPanel`: showSpyPanel property to pass to `<visualize>` directive
+
+
 ==== `<visualize>` directive
 The `<visualize>` directive takes care of loading data, parsing data, rendering the editor 
 (if the Visualization is in edit mode) and rendering the visualization.