@jupyterlab/docmanager

@jupyterlab/docmanager

Version 4.1.6
Published 16 days ago
197 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.

variable IDocumentWidgetOpener

const IDocumentWidgetOpener: Token<IDocumentWidgetOpener>;

The document widget opener 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,
    context: DocumentRegistry.Context,
    translator?: ITranslator
) => Promise<void | 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 confirmClosingDocument

confirmClosingDocument: boolean;

Whether to ask confirmation to close a tab or not.

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 renameUntitledFileOnSave

renameUntitledFileOnSave: boolean;

Whether to ask the user to rename untitled file on first manual save.

property services

readonly services: ServiceManager.IManager;

The service manager used by the manager.

property stateChanged

readonly stateChanged: ISignal<IDocumentManager, IChangedArgs<any>>;

Signal triggered when an attribute changes.

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 duplicate

duplicate: (path: string) => Promise<Contents.IModel>;

Duplicate a file.
Parameter path
The full path to the file to be duplicated.
Returns
A promise which resolves when the file is duplicated.

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 confirmClosingDocument

confirmClosingDocument: boolean;

Whether to ask confirmation to close a tab or not.

property isDisposed

readonly isDisposed: boolean;

Test whether the document widget manager is disposed.

property stateChanged

readonly stateChanged: ISignal<DocumentWidgetManager, IChangedArgs<any>>;

Signal triggered when an attribute changes.

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 confirmClosingDocument

confirmClosingDocument: boolean;

Whether to ask confirmation to close a tab or not.

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 renameUntitledFileOnSave

renameUntitledFileOnSave: boolean;

Whether to ask the user to rename untitled file on first manual save.

property services

readonly services: ServiceManager.IManager;

The service manager used by the manager.

property stateChanged

readonly stateChanged: ISignal<IDocumentManager, IChangedArgs<any>>;

Signal triggered when an attribute changes.

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 duplicate

duplicate: (path: string) => Promise<Contents.IModel>;

Duplicate a file.
Parameter path
The full path to the file to be duplicated.
Returns
A promise which resolves when the file is duplicated.

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 IDocumentWidgetOpener

interface IDocumentWidgetOpener {}

The interface for a widget opener.

property opened

readonly opened: ISignal<IDocumentWidgetOpener, IDocumentWidget>;

A signal emitted when a widget is opened

method open

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

Open the given widget.

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 isConnectedCallback

isConnectedCallback?: () => boolean;

Autosaving should be paused while this callback function returns false. By default, it always returns true.

property manager

manager: ServiceManager.IManager;

A service manager instance.

property opener

opener: IDocumentWidgetOpener;

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.

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.

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 isConnectedCallback

isConnectedCallback?: () => boolean;

Autosaving should be paused while this callback function returns false. By default, it always returns true.

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.

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 (6)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto 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>

Updated 15 days ago.
Package analyzed in 4349 ms.
Missing or incorrect documentation? Open an issue for this package.

@jupyterlab/docmanager

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Namespaces

Variables

variable IDocumentManager

variable IDocumentWidgetOpener

Functions

function isValidFileName

function renameDialog

function renameFile

function shouldOverwrite

Classes

class DocumentManager

constructor

property activateRequested

property autosave

property autosaveInterval

property confirmClosingDocument

property isDisposed

property lastModifiedCheckMargin

property registry

property renameUntitledFileOnSave

property services

property stateChanged

property translator

method cloneWidget

Parameter widget

Returns

method closeAll

Returns

method closeFile

Parameter path

Returns

method contextForWidget

Parameter widget

Returns

method copy

Parameter fromFile

Parameter toDir

Returns

method createNew

Parameter path

Parameter widgetName

Parameter kernel

Returns

method deleteFile

Parameter path

Returns

method dispose

method duplicate

Parameter path

Returns

method findWidget

Parameter path

Parameter widgetName

Returns

method newUntitled

Parameter options

method open

Parameter path

Parameter widgetName

Parameter kernel

Returns

method openOrReveal

Parameter path

Parameter widgetName

Parameter kernel

Returns

method overwrite

Parameter oldPath

Parameter newPath

Returns

method rename

Parameter oldPath