From 96df97ed50f5fb775f2ba6d998afee9c3fe10d45 Mon Sep 17 00:00:00 2001 From: Stefan Dirix Date: Thu, 24 Sep 2020 09:07:48 +0200 Subject: [PATCH] Add API documentation to '@theia/preview' * Document preview-handler.ts * Add custom preview guide to README.md Signed-off-by: Stefan Dirix Contributed on behalf of STMicroelectronics --- packages/preview/README.md | 14 ++++ .../preview/src/browser/preview-handler.ts | 81 ++++++++++++++++++- 2 files changed, 94 insertions(+), 1 deletion(-) diff --git a/packages/preview/README.md b/packages/preview/README.md index 431999c2b44b6..c0012f0e3bed4 100644 --- a/packages/preview/README.md +++ b/packages/preview/README.md @@ -15,6 +15,20 @@ The `@theia/preview` extension adds the ability to display rendered previews of supported resources.\ The extension comes with built-in support for rendering `markdown` files. +## Contribute Custom Previews + +To provide custom previews implement and bind the `PreviewHandler` interface, e.g. + +```typescript +@injectable +class MyPreviewHandler implements PreviewHandler { + ... +} +// in container +bind(MyPreviewHandler).toSelf().inSingletonScope(); +bind(PreviewHandler).toService(MyPreviewHandler); +``` + ## Additional Information - [API documentation for `@theia/preview`](https://eclipse-theia.github.io/theia/docs/next/modules/preview.html) diff --git a/packages/preview/src/browser/preview-handler.ts b/packages/preview/src/browser/preview-handler.ts index 84594cb62e628..572bb1431c3e3 100644 --- a/packages/preview/src/browser/preview-handler.ts +++ b/packages/preview/src/browser/preview-handler.ts @@ -20,8 +20,17 @@ import { ContributionProvider, MaybePromise, Prioritizeable } from '@theia/core' export const PreviewHandler = Symbol('PreviewHandler'); +/** + * The parameters given to the preview handler to render the preview content. + */ export interface RenderContentParams { + /** + * Textual content of the resource. + */ content: string; + /** + * URI identifying the source resource. + */ originUri: URI; } @@ -31,15 +40,72 @@ export namespace RenderContentParams { } } +/** + * A PreviewHandler manages the integration of one or more previews. + * + * It indicates whether a preview shall be rendered for a given resource URI and, if yes, renders the content. + * Additionally it optionally provides methods with which the scroll state of the preview and corresponding + * editor can be managed. + * + * See {@link MarkdownPreviewHandler} for an example implementation. + */ export interface PreviewHandler { + /** + * One or more classes which specify the preview widget icon. + */ readonly iconClass?: string; + /** + * Indicates whether and with which priority (larger is better) this preview handler is responsible for the resource identified by the given URI. + * If multiple handlers return the same priority it's undefined which one will be used. + * + * @param uri the URI identifying a resource. + * + * @returns a number larger than 0 if the handler is applicable, 0 or a negative number otherwise. + */ canHandle(uri: URI): number; + /** + * Render the preview content by returning appropriate HTML. + * + * @param params information for the handler to render its content. + * + * @returns the HTMLElement which will be attached to the preview widget. + */ renderContent(params: RenderContentParams): MaybePromise; + /** + * Search and return the HTMLElement which corresponds to the given fragment. + * This is used to initially reveal elements identified via the URI fragment. + * + * @param content the preview widget element containing the content previously rendered by {@link PreviewHandler.renderContent}. + * @param fragment the URI fragment for which the corresponding element shall be returned + * + * @returns the HTMLElement which is part of content and corresponds to the given fragment, undefined otherwise. + */ findElementForFragment?(content: HTMLElement, fragment: string): HTMLElement | undefined; + /** + * Search and return the HTMLElement which corresponds to the given line number. + * This is used to scroll the preview when the source editor scrolls. + * + * @param content the preview widget element containing the previously rendered by {@link PreviewHandler.renderContent}. + * @param sourceLine the line number for which the corresponding element shall be returned. + * + * @returns the HTMLElement which is part of content and corresponds to the given line number, undefined otherwise. + */ findElementForSourceLine?(content: HTMLElement, sourceLine: number): HTMLElement | undefined; + /** + * Returns the line number which corresponds to the preview element at the given offset. + * This is used to scroll the source editor when the preview scrolls. + * + * @param content the preview widget element containing the previously rendered by {@link PreviewHandler.renderContent}. + * @param offset the total amount by which the preview widget is scrolled. + * + * @returns the source line number which corresponds to the preview element at the given offset, undefined otherwise. + */ getSourceLineForOffset?(content: HTMLElement, offset: number): number | undefined; } +/** + * Provider managing the available PreviewHandlers. + */ @injectable() export class PreviewHandlerProvider { @@ -48,6 +114,13 @@ export class PreviewHandlerProvider { protected readonly previewHandlerContributions: ContributionProvider ) { } + /** + * Find PreviewHandlers for the given resource identifier. + * + * @param uri the URI identifying a resource. + * + * @returns the list of all supported `PreviewHandlers` sorted by their priority. + */ findContribution(uri: URI): PreviewHandler[] { const prioritized = Prioritizeable.prioritizeAllSync(this.previewHandlerContributions.getContributions(), contrib => contrib.canHandle(uri) @@ -55,8 +128,14 @@ export class PreviewHandlerProvider { return prioritized.map(c => c.value); } + /** + * Indicates whether any PreviewHandler can process the resource identified by the given URI. + * + * @param uri the URI identifying a resource. + * + * @returns `true` when a PreviewHandler can process the resource, `false` otherwise. + */ canHandle(uri: URI): boolean { return this.findContribution(uri).length > 0; } - }