Definition of done for a feature:
server.basePath
configuredTypeScript
React
jest
& FTR
All OpenSearch Dashboards plugins should follow the same structure.
my_plugin/
├── opensearch_dashboards.json
├── public
│ ├── applications
│ │ ├── my_app
│ │ │ └── index.ts
│ │ └── index.ts
│ ├── services
│ │ ├── my_service
│ │ │ └── index.ts
│ │ └── index.ts
│ ├── index.ts
│ └── plugin.ts
└── server
├── routes
│ └── index.ts
├── collectors
│ └── register.ts
├── saved_objects
│ ├── index.ts
│ └── my_type.ts
├── services
│ ├── my_service
│ │ └── index.ts
│ └── index.ts
├── index.ts
└── plugin.ts
server
and public
should have an index.ts
and a plugin.ts
file:
index.ts
should only contain:
plugin
exportconfig
export (server only, optional)plugin.ts
should only export a single class that implements the Plugin
interface (more details below)applications
directory.
renderApp
function.application
that exports the renderApp
function.services
subdirectory.
server/routes
directory.
server/collectors/
directory.// my_plugin/public/index.ts
import { PluginInitializer } from '../../src/core/public';
import { MyPlugin, MyPluginSetup, MyPluginStart } from './plugin';
export const plugin: PluginInitializer<MyPluginSetup, MyPluginStart> = () => new MyPlugin();
export {
MyPluginSetup,
MyPluginStart
}
// my_plugin/public/plugin.ts
import { CoreSetup, CoreStart, Plugin } from '../../src/core/public';
import { OtherPluginSetup, OtherPluginStart } from '../other_plugin';
import { ThirdPluginSetup, ThirdPluginStart } from '../third_plugin';
export interface MyPluginSetup {
registerThing(...);
}
export interface MyPluginStart {
getThing(): Thing;
}
export interface MyPluginSetupDeps {
otherPlugin: OtherPluginSetup;
thirdPlugin?: ThirdPluginSetup; // Optional dependency
}
export interface MyPluginStartDeps {
otherPlugin: OtherPluginStart;
thirdPlugin?: ThirdPluginStart; // Optional dependency
}
export class MyPlugin implements Plugin<
// All of these types are optional. If your plugin does not expose anything
// or depend on other plugins, these can be omitted.
MyPluginSetup,
MyPluginStart,
MyPluginSetupDeps,
MyPluginStartDeps,
> {
public setup(core: CoreSetup, plugins: MyPluginSetupDeps) {
// should return a value that matches `MyPluginSetup`
}
public start(core: CoreStart, plugins: MyPluginStartDeps) {
// should return a value that matches `MyPluginStart`
}
public stop() { ... }
}
Difference between setup
and start
:
setup
is reserved for "registration" workstart
is where any "running" logic for your plugin would live. This only applies if you need to start listening for
outside events (polling for work, listening on a port, etc.)The bulk of your plugin logic will most likely live inside handlers registered during setup
.
It's important that UI code is not included in the main bundle for your plugin. Our webpack configuration supports dynamic async imports to split out imports into a separate bundle. Every app's rendering logic and UI code should leverage this pattern.
// my_plugin/public/applications/my_app.ts
import React from 'react';
import ReactDOM from 'react-dom';
import { CoreStart, AppMountParameters } from 'src/core/public';
import { MyAppRoot } from './components/app.ts';
/**
* This module will be loaded asynchronously to reduce the bundle size of your plugin's main bundle.
*/
export const renderApp = (
core: CoreStart,
deps: MyPluginStartDeps,
{ element, history }: AppMountParameters
) => {
ReactDOM.render(<MyAppRoot core={core} deps={deps} routerHistory={history} />, element);
return () => ReactDOM.unmountComponentAtNode(element);
};
// my_plugin/public/plugin.ts
import { Plugin, CoreSetup } from '../../src/core/public';
export class MyPlugin implements Plugin {
public setup(core: CoreSetup<MyPluginStartDeps>) {
core.application.register({
id: 'my-app',
async mount(params) {
// Load application bundle
const { renderApp } = await import('./application/my_app');
// Get start services
const [coreStart, depsStart] = core.getStartServices();
return renderApp(coreStart, depsStart, params);
}
});
}
}
Prefer the pattern shown above, using core.getStartServices()
, rather than store local references retrieved from start
.
Bad:
export class MyPlugin implements Plugin {
// Anti pattern
private coreStart?: CoreStart;
private depsStart?: DepsStart;
public setup(core) {
core.application.register({
id: 'my-app',
async mount(params) {
const { renderApp } = await import('./application/my_app');
// Anti pattern - use `core.getStartServices()` instead!
return renderApp(this.coreStart, this.depsStart, params);
}
});
}
public start(core, deps) {
// Anti pattern
this.coreStart = core;
this.depsStart = deps;
}
}
The main reason to prefer the provided async accessor, is that it doesn't requires the developer to understand and reason about when that function can be called. Having an API that fails sometimes isn't a good API design, and it makes accurately testing this difficult.
Service structure should mirror the plugin lifecycle to make reasoning about how the service is executed more clear.
// my_plugin/public/services/my_service.ts
export class MyService {
private readonly strings$ = new BehaviorSubject<string[]>();
public setup() {
return {
registerStrings: (newString: string) =>
this.strings$.next([...this.strings$.value, newString]);
}
}
public start() {
this.strings$.complete();
return {
strings: this.strings$.value
};
}
}
Constructing and interacting with this service becomes very simple from the top-level Plugin class:
// my_plugin/public/plugin.ts
import { MyService } from './services';
export class Plugin {
private readonly myService = new MyService();
public setup() {
return {
myService: myService.setup();
}
}
public start() {
return {
myService: myService.start();
}
}
}
For creating and registering a Usage Collector. Collectors should be defined in a separate directory server/collectors/
. You can read more about usage collectors on src/plugins/usage_collection/README.md
.
// server/collectors/register.ts
import { UsageCollectionSetup } from 'src/plugins/usage_collection/server';
import { CallCluster } from 'src/legacy/core_plugins/opensearch';
export function registerMyPluginUsageCollector(usageCollection?: UsageCollectionSetup): void {
// usageCollection is an optional dependency, so make sure to return if it is not registered.
if (!usageCollection) {
return;
}
// create usage collector
const myCollector = usageCollection.makeUsageCollector({
type: MY_USAGE_TYPE,
fetch: async (callCluster: CallCluster) => {
// query OpenSearch and get some data
// summarize the data into a model
// return the modeled object that includes whatever you want to track
return {
my_objects: {
total: SOME_NUMBER
}
};
},
});
// register usage collector
usageCollection.registerCollector(myCollector);
}
Saved object type definitions should be defined in their own server/saved_objects
directory.
The folder should contain a file per type, named after the snake_case name of the type, and an index.ts
file exporting all the types.
// src/plugins/my-plugin/server/saved_objects/my_type.ts
import { SavedObjectsType } from 'src/core/server';
export const myType: SavedObjectsType = {
name: 'my-type',
hidden: false,
namespaceType: 'single',
mappings: {
properties: {
someField: {
type: 'text',
},
anotherField: {
type: 'text',
},
},
},
migrations: {
'1.0.0': migrateFirstTypeToV1,
'2.0.0': migrateFirstTypeToV2,
},
};
// src/plugins/my-plugin/server/saved_objects/index.ts
export { myType } from './my_type';
Migration example from the legacy format is available in src/core/MIGRATION_EXAMPLES.md#saved-objects-types
Export start and setup contracts as MyPluginStart
and MyPluginSetup
.
This avoids naming clashes, if everyone exported them simply as Start
and Setup
.
Вы можете оставить комментарий после Вход в систему
Неприемлемый контент может быть отображен здесь и не будет показан на странице. Вы можете проверить и изменить его с помощью соответствующей функции редактирования.
Если вы подтверждаете, что содержание не содержит непристойной лексики/перенаправления на рекламу/насилия/вульгарной порнографии/нарушений/пиратства/ложного/незначительного или незаконного контента, связанного с национальными законами и предписаниями, вы можете нажать «Отправить» для подачи апелляции, и мы обработаем ее как можно скорее.
Опубликовать ( 0 )