@jupyterlab/docmanager

  • Version 3.4.2
  • Published
  • 118 kB
  • 15 dependencies
  • BSD-3-Clause license

Install

npm i @jupyterlab/docmanager
yarn add @jupyterlab/docmanager
pnpm add @jupyterlab/docmanager

Overview

docmanager

Index

Variables

variable IDocumentManager

const IDocumentManager: Token<IDocumentManager>;
  • The document registry token.

Functions

function isValidFileName

isValidFileName: (name: string) => boolean;
  • Test whether a name is a valid file name

    Disallows "/", "", and ":" in file names, as well as names with zero length.

function renameDialog

renameDialog: (
manager: IDocumentManager,
oldPath: string,
translator?: ITranslator
) => Promise<Contents.IModel | null>;
  • Rename a file with a dialog.

function renameFile

renameFile: (
manager: IDocumentManager,
oldPath: string,
newPath: string
) => Promise<Contents.IModel | null>;
  • Rename a file, asking for confirmation if it is overwriting another.

function shouldOverwrite

shouldOverwrite: (path: string, translator?: ITranslator) => Promise<boolean>;
  • Ask the user whether to overwrite a file.

Classes

class DocumentManager

class DocumentManager implements IDocumentManager {}
  • The document manager.

    #### Notes The document manager is used to register model and widget creators, and the file browser uses the document manager to create widgets. The document manager maintains a context for each path and model type that is open, and a list of widgets for each context. The document manager is in control of the proper closing and disposal of the widgets and contexts.

constructor

constructor(options: DocumentManager.IOptions);
  • Construct a new document manager.

property activateRequested

readonly activateRequested: ISignal<this, string>;
  • A signal emitted when one of the documents is activated.

property autosave

autosave: boolean;
  • Whether to autosave documents.

property autosaveInterval

autosaveInterval: number;
  • Determines the time interval for autosave in seconds.

property isDisposed

readonly isDisposed: boolean;
  • Get whether the document manager has been disposed.

property lastModifiedCheckMargin

lastModifiedCheckMargin: number;
  • Defines max acceptable difference, in milliseconds, between last modified timestamps on disk and client

property registry

readonly registry: DocumentRegistry;
  • The registry used by the manager.

property services

readonly services: ServiceManager.IManager;
  • The service manager used by the manager.

property translator

protected translator: ITranslator;

    method cloneWidget

    cloneWidget: (widget: Widget) => IDocumentWidget | undefined;
    • Clone a widget.

      Parameter widget

      The source widget.

      Returns

      A new widget or undefined.

      #### Notes Uses the same widget factory and context as the source, or returns undefined if the source widget is not managed by this manager.

    method closeAll

    closeAll: () => Promise<void>;
    • Close all of the open documents.

      Returns

      A promise resolving when the widgets are closed.

    method closeFile

    closeFile: (path: string) => Promise<void>;
    • Close the widgets associated with a given path.

      Parameter path

      The target path.

      Returns

      A promise resolving when the widgets are closed.

    method contextForWidget

    contextForWidget: (widget: Widget) => DocumentRegistry.Context | undefined;
    • Get the document context for a widget.

      Parameter widget

      The widget of interest.

      Returns

      The context associated with the widget, or undefined if no such context exists.

    method copy

    copy: (fromFile: string, toDir: string) => Promise<Contents.IModel>;
    • Copy a file.

      Parameter fromFile

      The full path of the original file.

      Parameter toDir

      The full path to the target directory.

      Returns

      A promise which resolves to the contents of the file.

    method createNew

    createNew: (
    path: string,
    widgetName?: string,
    kernel?: Kernel.IModel
    ) => Widget | undefined;
    • Create a new file and return the widget used to view it.

      Parameter path

      The file path to create.

      Parameter widgetName

      The name of the widget factory to use. 'default' will use the default widget.

      Parameter kernel

      An optional kernel name/id to override the default.

      Returns

      The created widget, or undefined.

      #### Notes This function will return undefined if a valid widget factory cannot be found.

    method deleteFile

    deleteFile: (path: string) => Promise<void>;
    • Delete a file.

      Parameter path

      The full path to the file to be deleted.

      Returns

      A promise which resolves when the file is deleted.

      #### Notes If there is a running session associated with the file and no other sessions are using the kernel, the session will be shut down.

    method dispose

    dispose: () => void;
    • Dispose of the resources held by the document manager.

    method findWidget

    findWidget: (
    path: string,
    widgetName?: string | null
    ) => IDocumentWidget | undefined;
    • See if a widget already exists for the given path and widget name.

      Parameter path

      The file path to use.

      Parameter widgetName

      The name of the widget factory to use. 'default' will use the default widget.

      Returns

      The found widget, or undefined.

      #### Notes This can be used to find an existing widget instead of opening a new widget.

    method newUntitled

    newUntitled: (options: Contents.ICreateOptions) => Promise<Contents.IModel>;
    • Create a new untitled file.

      Parameter options

      The file content creation options.

    method open

    open: (
    path: string,
    widgetName?: string,
    kernel?: Kernel.IModel,
    options?: DocumentRegistry.IOpenOptions
    ) => IDocumentWidget | undefined;
    • Open a file and return the widget used to view it.

      Parameter path

      The file path to open.

      Parameter widgetName

      The name of the widget factory to use. 'default' will use the default widget.

      Parameter kernel

      An optional kernel name/id to override the default.

      Returns

      The created widget, or undefined.

      #### Notes This function will return undefined if a valid widget factory cannot be found.

    method openOrReveal

    openOrReveal: (
    path: string,
    widgetName?: string,
    kernel?: Kernel.IModel,
    options?: DocumentRegistry.IOpenOptions
    ) => IDocumentWidget | undefined;
    • Open a file and return the widget used to view it. Reveals an already existing editor.

      Parameter path

      The file path to open.

      Parameter widgetName

      The name of the widget factory to use. 'default' will use the default widget.

      Parameter kernel

      An optional kernel name/id to override the default.

      Returns

      The created widget, or undefined.

      #### Notes This function will return undefined if a valid widget factory cannot be found.

    method overwrite

    overwrite: (oldPath: string, newPath: string) => Promise<Contents.IModel>;
    • Overwrite a file.

      Parameter oldPath

      The full path to the original file.

      Parameter newPath

      The full path to the new file.

      Returns

      A promise containing the new file contents model.

    method rename

    rename: (oldPath: string, newPath: string) => Promise<Contents.IModel>;
    • Rename a file or directory.

      Parameter oldPath

      The full path to the original file.

      Parameter newPath

      The full path to the new file.

      Returns

      A promise containing the new file contents model. The promise will reject if the newPath already exists. Use [[overwrite]] to overwrite a file.

    class DocumentWidgetManager

    class DocumentWidgetManager implements IDisposable {}
    • A class that maintains the lifecycle of file-backed widgets.

    constructor

    constructor(options: DocumentWidgetManager.IOptions);
    • Construct a new document widget manager.

    property activateRequested

    readonly activateRequested: ISignal<this, string>;
    • A signal emitted when one of the documents is activated.

    property isDisposed

    readonly isDisposed: boolean;
    • Test whether the document widget manager is disposed.

    property translator

    protected translator: ITranslator;

      method adoptWidget

      adoptWidget: (
      context: DocumentRegistry.Context,
      widget: IDocumentWidget
      ) => void;
      • Install the message hook for the widget and add to list of known widgets.

        Parameter context

        The document context object.

        Parameter widget

        The widget to adopt.

      method cloneWidget

      cloneWidget: (widget: Widget) => IDocumentWidget | undefined;
      • Clone a widget.

        Parameter widget

        The source widget.

        Returns

        A new widget or undefined.

        #### Notes Uses the same widget factory and context as the source, or throws if the source widget is not managed by this manager.

      method closeWidgets

      closeWidgets: (context: DocumentRegistry.Context) => Promise<void>;
      • Close the widgets associated with a given context.

        Parameter context

        The document context object.

      method contextForWidget

      contextForWidget: (widget: Widget) => DocumentRegistry.Context | undefined;
      • Get the document context for a widget.

        Parameter widget

        The widget of interest.

        Returns

        The context associated with the widget, or undefined.

      method createWidget

      createWidget: (
      factory: DocumentRegistry.WidgetFactory,
      context: DocumentRegistry.Context
      ) => IDocumentWidget;
      • Create a widget for a document and handle its lifecycle.

        Parameter factory

        The widget factory.

        Parameter context

        The document context object.

        Returns

        A widget created by the factory.

        Throws

        If the factory is not registered.

      method deleteWidgets

      deleteWidgets: (context: DocumentRegistry.Context) => Promise<void>;
      • Dispose of the widgets associated with a given context regardless of the widget's dirty state.

        Parameter context

        The document context object.

      method dispose

      dispose: () => void;
      • Dispose of the resources used by the widget manager.

      method findWidget

      findWidget: (
      context: DocumentRegistry.Context,
      widgetName: string
      ) => IDocumentWidget | undefined;
      • See if a widget already exists for the given context and widget name.

        Parameter context

        The document context object.

        Returns

        The found widget, or undefined.

        #### Notes This can be used to use an existing widget instead of opening a new widget.

      method messageHook

      messageHook: (handler: IMessageHandler, msg: Message) => boolean;
      • Filter a message sent to a message handler.

        Parameter handler

        The target handler of the message.

        Parameter msg

        The message dispatched to the handler.

        Returns

        false if the message should be filtered, of true if the message should be dispatched to the handler as normal.

      method onClose

      protected onClose: (widget: Widget) => Promise<boolean>;
      • Handle 'close-request' messages.

        Parameter widget

        The target widget.

        Returns

        A promise that resolves with whether the widget was closed.

      method onDelete

      protected onDelete: (widget: Widget) => Promise<void>;
      • Dispose of widget regardless of widget's dirty state.

        Parameter widget

        The target widget.

      method setCaption

      protected setCaption: (widget: Widget) => Promise<void>;
      • Set the caption for widget title.

        Parameter widget

        The target widget.

      class PathStatus

      class PathStatus extends VDomRenderer<PathStatus.Model> {}
      • A status bar item for the current file path (or activity name).

      constructor

      constructor(opts: PathStatus.IOptions);
      • Construct a new PathStatus status item.

      method render

      render: () => JSX.Element;
      • Render the status item.

      class SaveHandler

      class SaveHandler implements IDisposable {}
      • A class that manages the auto saving of a document.

        #### Notes Implements https://github.com/ipython/ipython/wiki/IPEP-15:-Autosaving-the-IPython-Notebook.

      constructor

      constructor(options: SaveHandler.IOptions);
      • Construct a new save handler.

      property isActive

      readonly isActive: boolean;
      • Get whether the handler is active.

      property isDisposed

      readonly isDisposed: boolean;
      • Get whether the save handler is disposed.

      property saveInterval

      saveInterval: number;
      • The save interval used by the timer (in seconds).

      method dispose

      dispose: () => void;
      • Dispose of the resources used by the save handler.

      method start

      start: () => void;
      • Start the autosaver.

      method stop

      stop: () => void;
      • Stop the autosaver.

      class SavingStatus

      class SavingStatus extends VDomRenderer<SavingStatus.Model> {}
      • A VDomRenderer for a saving status item.

      constructor

      constructor(opts: SavingStatus.IOptions);
      • Create a new SavingStatus item.

      method render

      render: () => JSX.Element | null;
      • Render the SavingStatus item.

      Interfaces

      interface IDocumentManager

      interface IDocumentManager extends IDisposable {}
      • The interface for a document manager.

      property activateRequested

      readonly activateRequested: ISignal<this, string>;
      • A signal emitted when one of the documents is activated.

      property autosave

      autosave: boolean;
      • Whether to autosave documents.

      property autosaveInterval

      autosaveInterval: number;
      • Determines the time interval for autosave in seconds.

      property registry

      readonly registry: DocumentRegistry;
      • The registry used by the manager.

      property services

      readonly services: ServiceManager.IManager;
      • The service manager used by the manager.

      method cloneWidget

      cloneWidget: (widget: Widget) => IDocumentWidget | undefined;
      • Clone a widget.

        Parameter widget

        The source widget.

        Returns

        A new widget or undefined.

        #### Notes Uses the same widget factory and context as the source, or returns undefined if the source widget is not managed by this manager.

      method closeAll

      closeAll: () => Promise<void>;
      • Close all of the open documents.

        Returns

        A promise resolving when the widgets are closed.

      method closeFile

      closeFile: (path: string) => Promise<void>;
      • Close the widgets associated with a given path.

        Parameter path

        The target path.

        Returns

        A promise resolving when the widgets are closed.

      method contextForWidget

      contextForWidget: (widget: Widget) => DocumentRegistry.Context | undefined;
      • Get the document context for a widget.

        Parameter widget

        The widget of interest.

        Returns

        The context associated with the widget, or undefined if no such context exists.

      method copy

      copy: (fromFile: string, toDir: string) => Promise<Contents.IModel>;
      • Copy a file.

        Parameter fromFile

        The full path of the original file.

        Parameter toDir

        The full path to the target directory.

        Returns

        A promise which resolves to the contents of the file.

      method createNew

      createNew: (
      path: string,
      widgetName?: string,
      kernel?: Kernel.IModel
      ) => Widget | undefined;
      • Create a new file and return the widget used to view it.

        Parameter path

        The file path to create.

        Parameter widgetName

        The name of the widget factory to use. 'default' will use the default widget.

        Parameter kernel

        An optional kernel name/id to override the default.

        Returns

        The created widget, or undefined.

        #### Notes This function will return undefined if a valid widget factory cannot be found.

      method deleteFile

      deleteFile: (path: string) => Promise<void>;
      • Delete a file.

        Parameter path

        The full path to the file to be deleted.

        Returns

        A promise which resolves when the file is deleted.

        #### Notes If there is a running session associated with the file and no other sessions are using the kernel, the session will be shut down.

      method findWidget

      findWidget: (
      path: string,
      widgetName?: string | null
      ) => IDocumentWidget | undefined;
      • See if a widget already exists for the given path and widget name.

        Parameter path

        The file path to use.

        Parameter widgetName

        The name of the widget factory to use. 'default' will use the default widget.

        Returns

        The found widget, or undefined.

        #### Notes This can be used to find an existing widget instead of opening a new widget.

      method newUntitled

      newUntitled: (options: Contents.ICreateOptions) => Promise<Contents.IModel>;
      • Create a new untitled file.

        Parameter options

        The file content creation options.

      method open

      open: (
      path: string,
      widgetName?: string,
      kernel?: Kernel.IModel,
      options?: DocumentRegistry.IOpenOptions
      ) => IDocumentWidget | undefined;
      • Open a file and return the widget used to view it.

        Parameter path

        The file path to open.

        Parameter widgetName

        The name of the widget factory to use. 'default' will use the default widget.

        Parameter kernel

        An optional kernel name/id to override the default.

        Returns

        The created widget, or undefined.

        #### Notes This function will return undefined if a valid widget factory cannot be found.

      method openOrReveal

      openOrReveal: (
      path: string,
      widgetName?: string,
      kernel?: Kernel.IModel,
      options?: DocumentRegistry.IOpenOptions
      ) => IDocumentWidget | undefined;
      • Open a file and return the widget used to view it. Reveals an already existing editor.

        Parameter path

        The file path to open.

        Parameter widgetName

        The name of the widget factory to use. 'default' will use the default widget.

        Parameter kernel

        An optional kernel name/id to override the default.

        Returns

        The created widget, or undefined.

        #### Notes This function will return undefined if a valid widget factory cannot be found.

      method overwrite

      overwrite: (oldPath: string, newPath: string) => Promise<Contents.IModel>;
      • Overwrite a file.

        Parameter oldPath

        The full path to the original file.

        Parameter newPath

        The full path to the new file.

        Returns

        A promise containing the new file contents model.

      method rename

      rename: (oldPath: string, newPath: string) => Promise<Contents.IModel>;
      • Rename a file or directory.

        Parameter oldPath

        The full path to the original file.

        Parameter newPath

        The full path to the new file.

        Returns

        A promise containing the new file contents model. The promise will reject if the newPath already exists. Use [[overwrite]] to overwrite a file.

      interface IFileContainer

      interface IFileContainer extends JSONObject {}
      • A stripped-down interface for a file container.

      property items

      items: string[];
      • The list of item names in the current working directory.

      property path

      path: string;
      • The current working directory of the file container.

      Namespaces

      namespace DocumentManager

      namespace DocumentManager {}
      • A namespace for document manager statics.

      interface IOptions

      interface IOptions {}
      • The options used to initialize a document manager.

      property collaborative

      collaborative?: boolean;
      • Whether the context should be collaborative. If true, the context will connect through yjs_ws_server to share information if possible.

      property docProviderFactory

      docProviderFactory?: IDocumentProviderFactory;
      • A factory method for the document provider.

      property manager

      manager: ServiceManager.IManager;
      • A service manager instance.

      property opener

      opener: IWidgetOpener;
      • A widget opener for sibling widgets.

      property registry

      registry: DocumentRegistry;
      • A document registry instance.

      property sessionDialogs

      sessionDialogs?: ISessionContext.IDialogs;
      • The provider for session dialogs.

      property setBusy

      setBusy?: () => IDisposable;
      • A function called when a kernel is busy.

      property translator

      translator?: ITranslator;
      • The application language translator.

      property when

      when?: Promise<void>;
      • A promise for when to start using the manager.

      interface IWidgetOpener

      interface IWidgetOpener {}
      • An interface for a widget opener.

      method open

      open: (widget: IDocumentWidget, options?: DocumentRegistry.IOpenOptions) => void;
      • Open the given widget.

      namespace DocumentWidgetManager

      namespace DocumentWidgetManager {}
      • A namespace for document widget manager statics.

      interface IOptions

      interface IOptions {}
      • The options used to initialize a document widget manager.

      property registry

      registry: DocumentRegistry;
      • A document registry instance.

      property translator

      translator?: ITranslator;
      • The application language translator.

      namespace PathStatus

      namespace PathStatus {}
      • A namespace for PathStatus statics.

      class Model

      class Model extends VDomModel {}
      • A VDomModel for rendering the PathStatus status item.

      constructor

      constructor(docManager: IDocumentManager);
      • Construct a new model.

        Parameter docManager

        : the application document manager. Used to check whether the current widget is a document.

      property name

      readonly name: string;
      • The name of the current activity.

      property path

      readonly path: string;
      • The current path for the application.

      property widget

      widget: any;
      • The current widget for the application.

      interface IOptions

      interface IOptions {}
      • Options for creating the PathStatus widget.

      property docManager

      docManager: IDocumentManager;
      • The application document manager.

      namespace SaveHandler

      namespace SaveHandler {}
      • A namespace for SaveHandler statics.

      interface IOptions

      interface IOptions {}
      • The options used to create a save handler.

      property context

      context: DocumentRegistry.Context;
      • The context associated with the file.

      property saveInterval

      saveInterval?: number;
      • The minimum save interval in seconds (default is two minutes).

      namespace SavingStatus

      namespace SavingStatus {}
      • A namespace for SavingStatus statics.

      class Model

      class Model extends VDomModel {}
      • A VDomModel for the SavingStatus item.

      constructor

      constructor(docManager: IDocumentManager);
      • Create a new SavingStatus model.

      property status

      readonly status: any;
      • The current status of the model.

      property widget

      widget: any;
      • The current widget for the model. Any widget can be assigned, but it only has any effect if the widget is an IDocument widget known to the application document manager.

      interface IOptions

      interface IOptions {}
      • Options for creating a new SaveStatus item

      property docManager

      docManager: IDocumentManager;
      • The application document manager.

      property translator

      translator?: ITranslator;
      • The application language translator.

      Package Files (8)

      Dependencies (15)

      Dev Dependencies (7)

      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/@jupyterlab/docmanager.

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