adding documentation for visualization development #12755
Conversation
ppisljar
added
Feature:Visualizations
|
We seem to have mixed conventions right now whether to write kibana upper or lowercase. A quick search showed, that we tend to write it uppercase (Kibana) currently within text in the docs. Is there any rule we currently try to stick to? |
There was a problem hiding this comment.
I've reviewed the docs (not checked whether the asciidoc syntax is valid, but focused on the content).
Made some suggestions about wording and typos (since I am not a native speaker, please feel free to ignore whatever you want from this).
Also made some suggestions where we might explain stuff in a bit more detail.
I think this would be a great starting point for the documentation which we might extend over time and I guess several of the mentioned suggestions could also be incorporated over time. That's why I won't mark it as "request changes needed" (but neither as "approved") :-)
Update: I think that some "a" or "the" might be missing in the text, but as a non-native I wasn't sure enough to mark all the places 🤐
| === Using Visualizations | ||
|
|
||
| There are two ways to insert visualization in your page. Using `<visualize>` directive or using `<visualization>` directive. | ||
| The following assumes you are using angular in your plugin. |
There was a problem hiding this comment.
angular is more often written uppercase and I guess even more often referenced as AngularJS
|
|
||
| ==== `<visualize>` directive | ||
| `<visualize>` directive takes a savedVis object and it takes care of loading data, parsing data, | ||
| rendering editor (if in edit mode) and rendering the visualization. Its the easiest way to add visualization to your |
There was a problem hiding this comment.
"rendering the editor"? (sorry, I am not a native speaker, so please ignore comments that just sounds wrong in English)
"Its" -> "It's"
There was a problem hiding this comment.
i am not a native speaker either as you probably noticed ;)
|
|
||
| `<visualize saved-obj='savedVis' app-state='appState' ui-state='uiState' editor-mode='false'></visualize>` where | ||
|
|
||
| `savedVis` is an instance of savedVisualization object, which can be retrieved using `savedVisualizations` service. |
There was a problem hiding this comment.
Maybe add: "which can be retrieved using the savedVisualizations service which is explained later in this documentation."
|
|
||
| `savedVis` is an instance of savedVisualization object, which can be retrieved using `savedVisualizations` service. | ||
|
|
||
| `appState` is an instance of `AppState`. visualize is expecting two parameters defined on it: |
There was a problem hiding this comment.
"visualize is expecting.." -> "appState is expecting..."?
Also maybe: "x is expecting to have two keys defined.."
|
|
||
| if not provided <visualize> will still work, just without monitoring the AppState. | ||
|
|
||
| `uiState` should be an instance of `PersistedState`. if not provided visualize will generate one, but you will have no access to it. |
There was a problem hiding this comment.
Maybe add a a short sentence, wherefore uiState will be used.
|
|
||
| [[development-none-request-handler]] | ||
| ==== `none` request handler | ||
| Using 'none' as your request handles means your visualization does not require search. |
There was a problem hiding this comment.
Maybe make clear, that "search" means "data from ES" in that case.
| Using 'none' as your request handles means your visualization does not require search. | ||
|
|
||
| [[development-custom-request-handler]] | ||
| ==== custom request handler |
There was a problem hiding this comment.
I think we would need a bit more explanation about what this function does, or make it clear in the docs, that this is kind of an internal thing, and you have to lookup in code how that function works (maybe with link to current implementation).
| [[development-visualization-response-handlers]] | ||
| === Visualization Response Handlers | ||
| Response handler will receive the data from request handler and an instance of Vis object. Its job is to convert the data to a format visualization can use. | ||
| by default 'none' request handler is used which just passes the data it receives back, but can be changed to 'basic' (which VislibVisTypeFactory uses) or to a custom one. |
There was a problem hiding this comment.
What exactly will be done with the return value of this function? To what (scope) variable/prop will it be assigned?
|
|
||
| Visualization gets all its parameters in `vis.params` (defaults merged with the current state). If it wants to update them it should update them in this object and then call `vis.updateState()` which will inform <visualize> about the change, which will call request and response handler and then your visualizations render method. | ||
|
|
||
| For the parameters that should not be saved with visualization you should use UI state (such as current state: popup open/closed, custom colors applied to the series etc) |
There was a problem hiding this comment.
Should custom colors applied to series, really not be saved with the visualization? It sounds like something, that would make sense to store in the visualization.
There was a problem hiding this comment.
colors are viewer specific (when you put it on dashboard you allow every person to customize them) thats why they are stored in uiState.
|
|
||
| For the parameters that should not be saved with visualization you should use UI state (such as current state: popup open/closed, custom colors applied to the series etc) | ||
|
|
||
| You can access filter bar and time picker thru the objects defined on `vis.API` |
There was a problem hiding this comment.
thru -> through (for less colloquial language)?
|
thanks a lot Tim! i'll go over all the comments tomorrow |
| [[development-visualization-request-handlers]] | ||
| === Visualization Request Handlers | ||
| Request handler gets called when one of the following keys on AppState change: | ||
| `vis`, `query`, `filters` or `uiState`. This sums up to pretty much every change to visualization. On top |
There was a problem hiding this comment.
What about aggs and time. Don't those cause requests as well?
| which just passes the data it received back. The data object will then be passed to visualization. | ||
|
|
||
| [[development-default-response-handler]] | ||
| ==== default response handler |
There was a problem hiding this comment.
Why is this called the default response handler when the above paragraph states that "By default 'none' request handler is used". Maybe this should be called the 'tabular' response handler?
There was a problem hiding this comment.
actually the default should be default, none should be possible but unadvised.
with 'none' visualization gets pure es data in which:
- is hard to work with
- might change in the future
- locks visualization to being used with es responses only
|
jenkins, test this |
There was a problem hiding this comment.
submitting, because i dont want to lose my notes (#14252). ill move these to the new one. That new PR and my notes crossed eachother.
|
|
||
| Easiest way to add new visualizations to kibana or to show existing kibana visualizations in your plugin is using | ||
| Visualize Plugin. This part of documentation is split into two parts. First part will tell you all you need to know to | ||
| use existing kibana visualization in your plugin and second step will focus on creating your own custom visualization. |
There was a problem hiding this comment.
Consider slight rewrite wrt language:
Kibana Visualizations are the easiest way to add additional functionality to Kibana. This part of documentation is split into two parts. The first part tells you all you need to know on how to embed existing Kibana Visualizations in your plugin. The second step explains how to create your own custom visualization.
There was a problem hiding this comment.
I'd add a short hedge. This is not public API (yet).
These pages document internal APIs and are not guaranteed to be supported across future versions of Kibana. However, these docs will be kept up-to-date to reflect the current implementation of Visualization plugins in Kibana.
| [[development-using-visualizations]] | ||
| === Using Visualizations | ||
|
|
||
| There are two ways to insert visualization in your page. Using `<visualize>` directive or using `<visualization>` directive. |
There was a problem hiding this comment.
Consider:
There are two different angular directives you can use to insert a visualization in your page. 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.
| @@ -0,0 +1,90 @@ | |||
| [[development-using-visualizations]] | |||
| === Using Visualizations | |||
There was a problem hiding this comment.
Consider Embedding Visualizations
| `<visualize>` directive takes a savedVis object and it takes care of loading data, parsing data, | ||
| rendering the editor (if in edit mode) and rendering the visualization. Its the easiest way to add visualization to your | ||
| page under the assumption that the visualization you are trying to display is saved in kibana. If that is not the case | ||
| take a look at using <visualization> directive. |
There was a problem hiding this comment.
small language typos:
The
<visualize>directive takes care of loading data, parsing data, rendering the editor (if the Visualization is in edit mode) and rendering the visualization. The directive takes a savedVis object for its configuration. It is the easiest way to add visualization to your page under the assumption that the visualization you are trying to display is saved in kibana. If that is not the case, take a look at using<visualization>directive.
| page under the assumption that the visualization you are trying to display is saved in kibana. If that is not the case | ||
| take a look at using <visualization> directive. | ||
|
|
||
| Once <visualize> is done rendering the element will emit `renderComplete` event. |
There was a problem hiding this comment.
Remove. Already explained at end of this section.
|
|
||
| [[development-vis-object]] | ||
| === Vis object | ||
| Vis object holds the visualization state and is the window into kibana: |
There was a problem hiding this comment.
The
visobject holds the visualization state and is the window into Kibana:
| - *vis.API.events.click*: default click handler | ||
| - *vis.API.events.brush*: default brush handler | ||
|
|
||
| Visualization gets all its parameters in `vis.params` (defaults merged with the current state). |
There was a problem hiding this comment.
The visualization gets all its parameters in vis.params, which are default values merged with the current state.
| - *vis.API.events.brush*: default brush handler | ||
|
|
||
| Visualization gets all its parameters in `vis.params` (defaults merged with the current state). | ||
| If it wants to update them it should update them in this object and then call `vis.updateState()` |
There was a problem hiding this comment.
If the visualization needs to update the current state, it should update the vis.params ...
| Visualization gets all its parameters in `vis.params` (defaults merged with the current state). | ||
| If it wants to update them it should update them in this object and then call `vis.updateState()` | ||
| which will inform <visualize> about the change, which will call request and response handler and then your | ||
| visualizations render method. |
| which will inform <visualize> about the change, which will call request and response handler and then your | ||
| visualizations render method. | ||
|
|
||
| For the parameters that should not be saved with visualization (are viewer specific) you should use UI state |
There was a problem hiding this comment.
For the parameters that should not be saved with the visualization you should use the UI state. These hold viewer-specific state, such as ...
adding docs for visualize development (after visualize refactor)