1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
.. Copyright (c) Jupyter Development Team.
.. Distributed under the terms of the Modified BSD License.
.. _documents:
Documents
=========
JupyterLab can be extended in several ways:
- **Extensions (top level)**: Application extensions extend the
functionality of JupyterLab itself, and we cover them in the
:ref:`developer_extensions`.
- **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.
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).
Overview of document architecture
---------------------------------
A 'document' in JupyterLab is represented by a model instance implementing the
`IModel <../api/interfaces/docregistry.DocumentRegistry.IModel.html>`__ interface.
The model interface is intentionally fairly small, and concentrates on representing
the data in the document and signaling changes to that data. Each model has an
associated `context <../api/interfaces/docregistry.DocumentRegistry.IContext.html>`__
instance as well. The context for a model is the bridge between the internal data
of the document, stored in the model, and the file metadata and operations possible
on the file, such as save and revert. Since many objects will need both the context
and the model, the context contains a reference to the model as its `.model` attribute.
A single file path can have multiple different models (and hence different contexts)
representing the file. For example, a notebook can be opened with a notebook model
and with a text model. Different models for the same file path do not directly
communicate with each other.
Models contain an instance of `ISharedDocument <https://jupyter-ydoc.readthedocs.io/en/latest/api/interfaces/ISharedDocument.html>`_
that acts as data storage for the model's content. As of JupyterLab 4, the default data
storage implementation is a `YDocument <https://jupyter-ydoc.readthedocs.io/en/latest/api/classes/YDocument-1.html>`_
based on `Yjs <https://docs.yjs.dev>`_, a high-performance CRDT for building collaborative
applications. Both the interface and the implementation are provided by the package
`@jupyter/ydoc <https://github.com/jupyter-server/jupyter_ydoc>`_.
`Document widgets <../api/classes/docregistry.DocumentWidget-1.html>`__ represent
a view of a document model. There can be multiple document widgets associated with
a single document model, and they naturally stay in sync with each other since they
are views on the same underlying data model.
The `Document Registry <../api/classes/docregistry.DocumentRegistry-1.html>`__
is where document types and factories are registered. Plugins can
require a document registry instance and register their content types
and providers.
The `Document Manager <../api/classes/docmanager.DocumentManager-1.html>`__
uses the Document Registry to create models and widgets for documents.
The Document Manager handles the lifecycle of documents for the application.
Document Registry
-----------------
*Document widget extensions* in the JupyterLab application can register:
- file types
- model factories for specific file types
- widget factories for specific model factories
- widget extension factories
.. note::
We recommend you to look at the `document example <https://github.com/jupyterlab/extension-examples/tree/main/documents>`__
to help understanding a pratical case.
`Widget Factories <../api/classes/docregistry.DocumentRegistry-1.html#addWidgetFactory>`__
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create a widget for a given file.
*Example*
- The notebook widget factory that creates NotebookPanel widgets.
`Model Factories <../api/classes/docregistry.DocumentRegistry-1.html#addModelFactory>`__
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 Extension Factories <../api/classes/docregistry.DocumentRegistry-1.html#addWidgetExtension>`__
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Adds additional functionality to a widget type. An extension instance is
created for each widget instance, enabling the extension to add
functionality to each widget or observe the widget and/or its context.
*Examples*
- The ipywidgets extension that is created for NotebookPanel widgets.
- Adding a button to the toolbar of each NotebookPanel widget.
`File Types <../api/classes/docregistry.DocumentRegistry-1.html#addFileType>`__
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Adds a new file type to be understood through a mimetype and file extensions within JupyterLab.
`Document Models <../api/interfaces/docregistry.DocumentRegistry.IModel.html>`__
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Created by the model factories and passed to widget factories and widget
extension factories. Models are the way in which we interact with the
data of a document. For a simple text file, we typically only use the
``to/fromString()`` methods. A more complex document like a Notebook
contains more points of interaction like the Notebook metadata.
`Document Contexts <../api/interfaces/docregistry.DocumentRegistry.IContext.html>`__
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Created by the Document Manager and passed to widget factories and
widget extensions. The context contains the model as one of its
properties so that we can pass a single object around.
They are used to provide an abstracted interface to the session and
Contents API from ``@jupyterlab/services`` for the given model. They 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. Contexts are not meant to be subclassed or
re-implemented. Instead, the contexts are intended to be the glue
between the document model and the wider application.
Shared Models
-------------
The `@jupyter/ydoc` package contains an `ISharedNotebook
<https://jupyter-ydoc.readthedocs.io/en/latest/api/modules/ISharedNotebook.html>`_
and an `ISharedFile <https://jupyter-ydoc.readthedocs.io/en/latest/api/interfaces/ISharedFile.html>`_
which are the abstract interfaces to work against if you want to manipulate a notebook or a text file.
These models wrap a `Yjs document (Y.Doc) <https://docs.yjs.dev/api/y.doc>`_ which represents
a shared document between clients and hold multiple shared objects. They enable you
to share different `data types like text, Array, Map or set
<https://docs.yjs.dev/getting-started/working-with-shared-types>`_, to make different
types of collaborative applications.
In addition, a shared model has an `Awareness <https://docs.yjs.dev/getting-started/adding-awareness>`_
attribute. This attribute is linked to the *Y.Doc* which means there is one *Awareness* object per document and is
used for sharing cursor locations and presence information. The `Awareness` is an implementation detail of Yjs
and is not part of the `ISharedDocument` interface.
Please, check out the `@jupyter/ydoc documentation <https://jupyter-ydoc.readthedocs.io/en/latest>`_
to know more about this package.
Document Manager
----------------
The *Document Manager* handles:
- document models
- document contexts
The *File Browser* uses the *Document Manager* to open documents and
manage them.
|
