Logo for jsDocs.io

@phosphor/application

  • Version 1.7.3
  • Published
  • 32.9 kB
  • 3 dependencies
  • BSD-3-Clause license

Install

npm i @phosphor/application
yarn add @phosphor/application
pnpm add @phosphor/application

Overview

PhosphorJS - Pluggable Application

Index

Classes

Interfaces

Namespaces

Classes

class Application

class Application<T extends Widget> {}

  • A class for creating pluggable applications.

    #### Notes The Application class is useful when creating large, complex UI applications with the ability to be safely extended by third party code via plugins.

constructor

constructor(options: Application.IOptions<T>);

  • Construct a new application.

    Parameter options

    The options for creating the application.

property commands

readonly commands: CommandRegistry;

  • The application command registry.

property contextMenu

readonly contextMenu: ContextMenu;

  • The application context menu.

property shell

readonly shell: Widget;

  • The application shell widget.

    #### Notes The shell widget is the root "container" widget for the entire application. It will typically expose an API which allows the application plugins to insert content in a variety of places.

property started

readonly started: Promise<void>;

  • A promise which resolves after the application has started.

    #### Notes This promise will resolve after the start() method is called, when all the bootstrapping and shell mounting work is complete.

method activatePlugin

activatePlugin: (id: string) => Promise<void>;

  • Activate the plugin with the given id.

    Parameter id

    The ID of the plugin of interest.

    Returns

    A promise which resolves when the plugin is activated or rejects with an error if it cannot be activated.

method addEventListeners

protected addEventListeners: () => void;

  • Add the application event listeners.

    #### Notes The default implementation of this method adds listeners for 'keydown' and 'resize' events.

    A subclass may reimplement this method as needed.

method attachShell

protected attachShell: (id: string) => void;

  • Attach the application shell to the DOM.

    Parameter id

    The id of the host node for the shell, or ''.

    #### Notes If the id is not provided, the document body will be the host.

    A subclass may reimplement this method as needed.

method evtContextMenu

protected evtContextMenu: (event: MouseEvent) => void;

  • A method invoked on a document 'contextmenu' event.

    #### Notes The default implementation of this method opens the application contextMenu at the current mouse position.

    If the application context menu has no matching content *or* if the shift key is pressed, the default browser context menu will be opened instead.

    A subclass may reimplement this method as needed.

method evtKeydown

protected evtKeydown: (event: KeyboardEvent) => void;

  • A method invoked on a document 'keydown' event.

    #### Notes The default implementation of this method invokes the key down processing method of the application command registry.

    A subclass may reimplement this method as needed.

method evtResize

protected evtResize: (event: Event) => void;

  • A method invoked on a window 'resize' event.

    #### Notes The default implementation of this method updates the shell.

    A subclass may reimplement this method as needed.

method handleEvent

handleEvent: (event: Event) => void;

  • Handle the DOM events for the application.

    Parameter event

    The DOM event sent to the application.

    #### Notes This method implements the DOM EventListener interface and is called in response to events registered for the application. It should not be called directly by user code.

method hasPlugin

hasPlugin: (id: string) => boolean;

  • Test whether a plugin is registered with the application.

    Parameter id

    The id of the plugin of interest.

    Returns

    true if the plugin is registered, false otherwise.

method listPlugins

listPlugins: () => string[];

  • List the IDs of the plugins registered with the application.

    Returns

    A new array of the registered plugin IDs.

method registerPlugin

registerPlugin: (plugin: IPlugin<this, any>) => void;

  • Register a plugin with the application.

    Parameter plugin

    The plugin to register.

    #### Notes An error will be thrown if a plugin with the same id is already registered, or if the plugin has a circular dependency.

    If the plugin provides a service which has already been provided by another plugin, the new service will override the old service.

method registerPlugins

registerPlugins: (plugins: IPlugin<this, any>[]) => void;

  • Register multiple plugins with the application.

    Parameter plugins

    The plugins to register.

    #### Notes This calls registerPlugin() for each of the given plugins.

method resolveOptionalService

resolveOptionalService: <U>(token: Token<U>) => Promise<U | null>;

  • Resolve an optional service of a given type.

    Parameter token

    The token for the service type of interest.

    Returns

    A promise which resolves to an instance of the requested service, or null if it cannot be resolved.

    #### Notes Services are singletons. The same instance will be returned each time a given service token is resolved.

    If the plugin which provides the service has not been activated, resolving the service will automatically activate the plugin.

    User code will not typically call this method directly. Instead, the optional services for the user's plugins will be resolved automatically when the plugin is activated.

method resolveRequiredService

resolveRequiredService: <U>(token: Token<U>) => Promise<U>;

  • Resolve a required service of a given type.

    Parameter token

    The token for the service type of interest.

    Returns

    A promise which resolves to an instance of the requested service, or rejects with an error if it cannot be resolved.

    #### Notes Services are singletons. The same instance will be returned each time a given service token is resolved.

    If the plugin which provides the service has not been activated, resolving the service will automatically activate the plugin.

    User code will not typically call this method directly. Instead, the required services for the user's plugins will be resolved automatically when the plugin is activated.

method start

start: (options?: Application.IStartOptions) => Promise<void>;

  • Start the application.

    Parameter options

    The options for starting the application.

    Returns

    A promise which resolves when all bootstrapping work is complete and the shell is mounted to the DOM.

    #### Notes This should be called once by the application creator after all initial plugins have been registered.

    If a plugin fails to the load, the error will be logged and the other valid plugins will continue to be loaded.

    Bootstrapping the application consists of the following steps: 1. Activate the startup plugins 2. Wait for those plugins to activate 3. Attach the shell widget to the DOM 4. Add the application event listeners

Interfaces

interface IPlugin

interface IPlugin<T, U> {}

  • A user-defined application plugin.

    #### Notes Plugins are the foundation for building an extensible application.

    Plugins consume and provide "services", which are nothing more than concrete implementations of interfaces and/or abstract types.

    Unlike regular imports and exports, which tie the service consumer to a particular implementation of the service, plugins decouple the service producer from the service consumer, allowing an application to be easily customized by third parties in a type-safe fashion.

property activate

activate: (app: T, ...args: any[]) => U | Promise<U>;

  • A function invoked to activate the plugin.

    Parameter app

    The application which owns the plugin.

    Parameter args

    The services specified by the requires property.

    Returns

    The provided service, or a promise to the service.

    #### Notes This function will be called whenever the plugin is manually activated, or when another plugin being activated requires the service it provides.

    This function will not be called unless all of its required services can be fulfilled.

property autoStart

autoStart?: boolean;

  • Whether the plugin should be activated on application start.

    #### Notes The default is false.

property id

id: string;

  • The human readable id of the plugin.

    #### Notes This must be unique within an application.

property optional

optional?: Token<any>[];

  • The types of optional services for the plugin, if any.

    #### Notes These tokens correspond to the services that can be used by the plugin if available, but are not necessarily required.

    The optional services will be passed to the activate() function following all required services. If an optional service cannot be resolved, null will be passed in its place.

property provides

provides?: Token<U>;

  • The type of service provided by the plugin, if any.

    #### Notes This token corresponds to the service exported by the plugin.

    When the plugin is activated, the return value of activate() is used as the concrete instance of the type.

property requires

requires?: Token<any>[];

  • The types of required services for the plugin, if any.

    #### Notes These tokens correspond to the services that are required by the plugin for correct operation.

    When the plugin is activated, a concrete instance of each type will be passed to the activate() function, in the order they are specified in the requires array.

Namespaces

namespace Application

namespace Application {}

  • The namespace for the Application class statics.

interface IOptions

interface IOptions<T extends Widget> {}

  • An options object for creating an application.

property contextMenuRenderer

contextMenuRenderer?: Menu.IRenderer;

  • A custom renderer for the context menu.

property shell

shell: T;

  • The shell widget to use for the application.

    This should be a newly created and initialized widget.

    The application will attach the widget to the DOM.

interface IStartOptions

interface IStartOptions {}

  • An options object for application startup.

property hostID

hostID?: string;

  • The ID of the DOM node to host the application shell.

    #### Notes If this is not provided, the document body will be the host.

property ignorePlugins

ignorePlugins?: string[];

  • The plugins to **not** activate on startup.

    #### Notes This will override startPlugins and any autoStart plugins.

property startPlugins

startPlugins?: string[];

  • The plugins to activate on startup.

    #### Notes These will be *in addition* to any autoStart plugins.

Package Files (1)

Dependencies (3)

Dev Dependencies (14)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@phosphor/application.

  • Markdown
    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@phosphor/application)
  • HTML
    <a href="https://www.jsdocs.io/package/@phosphor/application"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>