mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 17:28:26 -04:00
Add developer documentation about the building blocks we offer plugin developers (#92743)
* Create building_blocks.mdx * Update dev_docs/building_blocks.mdx Co-authored-by: Brandon Kobel <brandon.kobel@gmail.com> * Update dev_docs/building_blocks.mdx Co-authored-by: Brandon Kobel <brandon.kobel@gmail.com> * Update dev_docs/building_blocks.mdx Co-authored-by: Brandon Kobel <brandon.kobel@gmail.com> * add description to Lens embeddable Co-authored-by: Brandon Kobel <brandon.kobel@gmail.com> Co-authored-by: Joe Reuter <johannes.reuter@elastic.co> Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
This commit is contained in:
Stacey Gammon
GitHub
parent
356d4609e8
commit
3d54379da6
1 changed files with 138 additions and 0 deletions
138
dev_docs/building_blocks.mdx
Normal file
138
dev_docs/building_blocks.mdx
Normal file
|
|
@ -0,0 +1,138 @@
|
|||
---
|
||||
id: kibBuildingBlocks
|
||||
slug: /kibana-dev-docs/building-blocks
|
||||
title: Building blocks
|
||||
summary: Consider these building blocks when developing your plugin.
|
||||
date: 2021-02-24
|
||||
tags: ['kibana','onboarding', 'dev', 'architecture']
|
||||
---
|
||||
|
||||
When building a plugin in Kibana, there are a handful of architectural "building blocks" you can use. Some of these building blocks are "higher-level",
|
||||
and some are "lower-level". High-level building blocks come
|
||||
with many built-in capabilities, require less maintenance, and evolve new feature sets over time with little to no
|
||||
impact on consumers. When developers use high-level building blocks, new features are exposed consistently, across all of Kibana, at the same time.
|
||||
On the downside, they are not as flexible as our low-level building blocks.
|
||||
|
||||
Low-level building blocks
|
||||
provide greater flexibility, but require more code to stitch them together into a meaningful UX. This results in higher maintenance cost for consumers and greater UI/UX variability
|
||||
across Kibana.
|
||||
|
||||
For example, if an application is using <DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Patterns"/> and
|
||||
<DocLink id="kibBuildingBlocks" section="search-source" text="Search Source"/>,
|
||||
their application would automatically support runtime fields. If the app is instead using the
|
||||
lower-level <DocLink id="kibBuildingBlocks" section="search-strategy" text="Search Strategy"/>, additional work would be required.
|
||||
|
||||
Armed with this knowledge, you can choose what works best for your use case!
|
||||
|
||||
# Application building blocks
|
||||
|
||||
## UI components
|
||||
|
||||
The following high-level building blocks can be rendered directly into your application UI.
|
||||
|
||||
### Query Bar
|
||||
|
||||
The <DocLink id="kibDataPlugin" text="Data plugin"/> provides a high-level Query Bar component that comes with support for Lucene, KQL, Saved Queries,
|
||||
and <DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Patterns"/>.
|
||||
|
||||
If you would like to expose the ability to search and filter on Elasticsearch data, the Query Bar provided by the
|
||||
<DocLink id="kibDataPlugin" text="Data plugin"/>
|
||||
is your go-to building block.
|
||||
|
||||
**Github labels**: `Team:AppServices`, `Feature:QueryBar`
|
||||
|
||||
### Dashboard Embeddable
|
||||
|
||||
Add a Dashboard Embeddable directly inside your application to provide users with a set of visualizations and graphs that work seamlessly
|
||||
with the <DocLink id="kibBuildingBlocks" section="query-bar" text="Query Bar"/>. Every feature that is added to a registered
|
||||
<DocLink id="kibBuildingBlocks" section="embeddables" text="Embeddable"/>
|
||||
(Lens, Maps, Saved Searches and more) will be available automatically, as well as any
|
||||
<DocLink id="kibBuildingBlocks" section="ui-actions--triggers" text="UI Actions"/> that are
|
||||
added to the Embeddable context menu panel (for example, drilldowns, custom panel time ranges, and "share to" features).
|
||||
|
||||
The Dashboard Embeddable is one of the highest-level UI components you can add to your application.
|
||||
|
||||
**Github labels**: `Team:Presentation`, `Feature:Dashboard`
|
||||
|
||||
### Lens Embeddable
|
||||
|
||||
Check out the Lens Embeddable if you wish to show users visualizations based on Elasticsearch data without worrying about query building and chart rendering. It's built on top of the
|
||||
<DocLink id="kibBuildingBlocks" section="expressions" text="Expression language"/>, and integrates with
|
||||
<DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Patterns"/>
|
||||
and <DocLink id="kibBuildingBlocks" section="ui-actions--triggers" text="UI Actions"/>. Using the same configuration, it's also possible to link to
|
||||
a prefilled Lens editor, allowing the user to drill deeper and explore their data.
|
||||
|
||||
**Github labels**: `Team:KibanaApp`, `Feature:Lens`
|
||||
|
||||
### Map Embeddable
|
||||
|
||||
Check out the Map Embeddable if you wish to embed a map in your application.
|
||||
|
||||
**Github labels**: `Team:Geo`
|
||||
|
||||
## Searching
|
||||
|
||||
### Index Patterns
|
||||
|
||||
<DocLink id="kibDataPlugin" section="index-patterns-api" text="Index Patterns"/> are a high-level, space-aware abstraction layer that sits
|
||||
above Data Streams and Elasticsearch indices. Index Patterns provide users the
|
||||
ability to define and customize the data they wish to search and filter on, on a per-space basis. For example, users can specify a set of indices,
|
||||
and they can customize the field list with runtime fields, formatting options and custom labels.
|
||||
|
||||
Index Patterns are used in many other high-level building blocks so we highly recommend you consider this building block for your search needs.
|
||||
|
||||
**Github labels**: `Team:AppServices`, `Feature:Index Patterns`
|
||||
|
||||
### Search Source
|
||||
|
||||
<DocLink id="kibDataPlugin" section="searchsource" text="Search Source"/> is a high-level search service offered by the
|
||||
<DocLink id="kibDataPlugin" section="searchsource" text="Data plugin"/>. It requires an
|
||||
<DocLink id="kibBuildingBlocks" section="index-patterns" text="Index Pattern"/>, and abstracts away the raw ES DSL and search endpoint. Internally
|
||||
it uses the ES <DocLink id="kibBuildingBlocks" section="search-strategies" text="Search Strategy"/>. Use Search Source if you need to query data
|
||||
from Elasticsearch, and you aren't already using one of the high-level UI Components that handles this internally.
|
||||
|
||||
**Github labels**: `Team:AppServices`, `Feature:Search`
|
||||
|
||||
### Search Strategies
|
||||
|
||||
Search Strategies are a low-level building block that abstracts away search details, like what REST endpoint is being called. The ES Search Strategy
|
||||
is a very lightweight abstraction layer that sits just above querying ES with the elasticsearch-js client. Other search stragies are offered for other
|
||||
languages, like EQL and SQL. These are very low-level building blocks so expect a lot of glue work to make these work with the higher-level abstractions.
|
||||
|
||||
**Github labels**: `Team:AppServices`, `Feature:Search`
|
||||
|
||||
### Expressions
|
||||
|
||||
Expressions are a low-level building block that can be used if you have advanced search needs that requiring piping results into additional functionality, like
|
||||
joining and manipulating data. Lens and Canvas are built on top of Expressions. Most developers should be able to use
|
||||
<DocLink id="kibBuildingBlocks" section="lens-embeddable" text="Lens"/> or
|
||||
<DocLink id="kibBuildingBlocks" section="search-source" text="Search Source"/>, rather than need to access the Expression language directly.
|
||||
|
||||
**Github labels**: `Team:AppServices`, `Feature:ExpressionLanguage`
|
||||
|
||||
## Saved Objects
|
||||
|
||||
<DocLink id="kibDevDocsSavedObjectsIntro" text="Saved Objects" /> should be used if you need to persist application-level information. If you were building a TODO
|
||||
application, each TODO item would be a `Saved Object`. Saved objects come pre-wired with support for bulk export/import, security features like space sharing and
|
||||
space isolation, and tags.
|
||||
|
||||
**Github labels**: `Team:Core`, `Feature:Saved Objects`
|
||||
|
||||
# Integration building blocks
|
||||
|
||||
Use the following building blocks to create an inter-connected, cross-application, holistic Kibana experience. These building blocks allow you to expose functionality
|
||||
that promotes your own application into other applications, as well as help developers of other applications integrate into your app.
|
||||
|
||||
## UI Actions & Triggers
|
||||
|
||||
Integrate custom actions into other applications by registering UI Actions attached to existing triggers. For example, the Maps
|
||||
application could register a UI Action called "View in Maps" to appear any time the user clicked a geo field to filter on.
|
||||
|
||||
**Github labels**: `Team:AppServices`, `Feature:UIActions`
|
||||
|
||||
## Embeddables
|
||||
|
||||
Embeddables help you integrate your application with the Dashboard application. Register your custom UI Widget as an Embeddable and users will
|
||||
be able to add it as a panel on a Dashboard. With a little extra work, it can also be exposed in Canvas workpads.
|
||||
|
||||
**Github labels**: `Team:AppServices`, `Feature:Embeddables`
|
||||
Loading…
Add table
Add a link
Reference in a new issue