|
@@ -1,56 +1,91 @@
|
|
|
# Documents
|
|
|
-The [Document Registry](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html) is the default mechanism for interacting with
|
|
|
-files in JupyterLab. The [Document Manager](http://jupyter.org/jupyterlab/classes/_docmanager_manager_.documentmanager.html) uses it to create models and
|
|
|
-widgets for documents. The [File Browser](http://jupyter.org/jupyterlab/classes/_filebrowser_browser_.filebrowserwidget.html) uses the Document Manager when
|
|
|
-creating and opening files.
|
|
|
|
|
|
-The Document Manager handles models, contexts, and widgets for documents
|
|
|
-and manages their life cycle.
|
|
|
+JupyterLab can be extended in two ways via:
|
|
|
|
|
|
-Extensions in the JupyterLab application can register widget factories,
|
|
|
-model factories, widget extensions, file types, and file creators.
|
|
|
+- application plugins (top level): Application plugins extend the
|
|
|
+ functionality of JupyterLab itself, and and we cover them in the
|
|
|
+ "Extensions" tutorial focuses.
|
|
|
+- **document widget extensions (lower level):** Document widget extensions extend
|
|
|
+ the functionality of document widgets added to the application, and we cover
|
|
|
+ them in this section.
|
|
|
|
|
|
-## [Widget Factories](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registerwidgetfactory)
|
|
|
-Create a widget for a given file. An example is the notebook widget
|
|
|
-factory that creates NotebookPanel widgets.
|
|
|
+For this section, the term, 'document', refers to any visual thing that is
|
|
|
+backed by a file stored on disk (i.e. uses Contents API).
|
|
|
|
|
|
-## [Model Factories](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registermodelfactory)
|
|
|
-Create a model for a given file. Models are generally differentiated by
|
|
|
-the contents options used to fetch the model (e.g. text, base64, notebook).
|
|
|
+The [Document Manager](http://jupyter.org/jupyterlab/classes/_docmanager_manager_.documentmanager.html)
|
|
|
+uses the Document Registry to create models and widgets for documents.
|
|
|
|
|
|
-## [Widget Extensions](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registerextension)
|
|
|
-Add additional functionality to a widget type. An extension instance is
|
|
|
-created for each widget instance. An example is the ipywidgets extension
|
|
|
-that is created for NotebookPanel widgets. Another example would be to add a
|
|
|
-button to the toolbar of each NotebookPanel widget.
|
|
|
+The [File Browser](http://jupyter.org/jupyterlab/classes/_filebrowser_browser_.filebrowserwidget.html)
|
|
|
+uses the Document Manager when creating and opening files.
|
|
|
|
|
|
-## [File Types](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registerfiletype)
|
|
|
-Intended to be used in a "Create New" dialog, providing a list of known
|
|
|
-file types.
|
|
|
+The [Document Registry](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html)
|
|
|
+is the default mechanism for interacting with files in JupyterLab.
|
|
|
|
|
|
-## [File Creators](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registercreator)
|
|
|
-Intended for create quick launch file creators. The default use will be for
|
|
|
-the "create new" dropdown in the file browser, giving list of items that can
|
|
|
-be created with default options (e.g. "Python 3 Notebook").
|
|
|
+## Document Manager
|
|
|
+
|
|
|
+The Document Manager handles:
|
|
|
+
|
|
|
+- models
|
|
|
+- contexts
|
|
|
+- widgets
|
|
|
|
|
|
-## [Document Models](http://jupyter.org/jupyterlab/interfaces/_docregistry_interfaces_.idocumentmodel.html)
|
|
|
-Created by the model factories and passed to widget factories and widget
|
|
|
+for documents and manages their life cycle.
|
|
|
+
|
|
|
+### [Document Models](http://jupyter.org/jupyterlab/interfaces/_docregistry_interfaces_.idocumentmodel.html)
|
|
|
+
|
|
|
+Created by the model factories and passed to widget factories and widget
|
|
|
extensions.
|
|
|
|
|
|
-## [Document Contexts](http://jupyter.org/jupyterlab/interfaces/_docregistry_interfaces_.idocumentcontext.html)
|
|
|
+### [Document Contexts](http://jupyter.org/jupyterlab/interfaces/_docregistry_interfaces_.idocumentcontext.html)
|
|
|
+
|
|
|
Created by the Document Manager and passed to widget factories and
|
|
|
widget extensions. They are used to provide an abstracted interface
|
|
|
-to the session and contents API from jupyter-js-services for the
|
|
|
+to the session and contents API from jupyter-js-services for the
|
|
|
given model. They are tied to a model and can be shared between widgets.
|
|
|
The reason for a separate context and model is so that it is easy to create
|
|
|
model factories and the heavy lifting of the context is left to the Document
|
|
|
Manager.
|
|
|
|
|
|
-## [Document Wrappers](http://jupyter.org/jupyterlab/classes/_docmanager_manager_.documentwrapper.html)
|
|
|
-The top level widget created by the Document Manager that wraps the widget
|
|
|
+### [Document Wrappers](http://jupyter.org/jupyterlab/classes/_docmanager_manager_.documentwrapper.html)
|
|
|
+
|
|
|
+The top level widget created by the Document Manager that wraps the widget
|
|
|
returned by the widget factory. They are used because they can be
|
|
|
created synchronously, while the widgets created using the widget
|
|
|
factory are created asynchronously after potentially loading data
|
|
|
from disk. Some interfaces (like drag and drop) require a widget to be
|
|
|
returned synchronously.
|
|
|
|
|
|
+## Registry
|
|
|
+
|
|
|
+Extensions in the JupyterLab application can register:
|
|
|
+
|
|
|
+- widget factories
|
|
|
+- model factories
|
|
|
+- widget extensions
|
|
|
+- file types
|
|
|
+- file creators
|
|
|
+
|
|
|
+### [Widget Factories](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registerwidgetfactory)
|
|
|
+
|
|
|
+Create a widget for a given file. An example is the notebook widget
|
|
|
+factory that creates NotebookPanel widgets.
|
|
|
+
|
|
|
+### [Model Factories](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registermodelfactory)
|
|
|
+
|
|
|
+Create a model for a given file. Models are generally differentiated by
|
|
|
+the contents options used to fetch the model (e.g. text, base64, notebook).
|
|
|
+
|
|
|
+### [Widget Extensions](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registerextension)
|
|
|
+
|
|
|
+Add additional functionality to a widget type. An extension instance is
|
|
|
+created for each widget instance. An example is the ipywidgets extension
|
|
|
+that is created for NotebookPanel widgets. Another example would be to add a
|
|
|
+button to the toolbar of each NotebookPanel widget.
|
|
|
+
|
|
|
+### [File Types](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registerfiletype)
|
|
|
+Intended to be used in a "Create New" dialog, providing a list of known
|
|
|
+
|
|
|
+## [File Creators](http://jupyter.org/jupyterlab/classes/_docregistry_registry_.documentregistry.html#registercreator)
|
|
|
+Intended for create quick launch file creators. The default use will be for
|
|
|
+the "create new" dropdown in the file browser, giving list of items that can
|
|
|
+be created with default options (e.g. "Python 3 Notebook").
|