Skip to content

Commit 834e87d

Browse files
ericsnekbytesfcollonvalkrassowski
authored
Added jupyterlab-toparea-text widget example. (#240)
* Added jupyterlab-toparea-text widget example. * Added README updates and preview image. * Updated README with toparea-text-widget links. * Removed unnecessary files, updated metadata/examples lists. * Added Jeremy's video tutorial link. * Remove empty types in tsconfig * Removed junk file. * Added guide link. * Updated README for the example. * Update README. * Update README. * Revise README. * Update README. * Update root README with improved description. * Fixed links. * Updated title. * Added basic playwright test. * Changed license metadata. * Added suppression to kebab case for styles, formatting. * Updated ESLint ignore entries in the example's package.json. * Update toparea-text-widget/README.md Co-authored-by: Michał Krassowski <[email protected]> * Update example --------- Co-authored-by: Frédéric Collonval <[email protected]> Co-authored-by: Michał Krassowski <[email protected]> Co-authored-by: Frédéric Collonval <[email protected]>
1 parent cf1efca commit 834e87d

25 files changed

+776
-1
lines changed

‎.github/workflows/main.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ jobs:
3636
- signals
3737
- state
3838
- toolbar-button
39+
- toparea-text-widget
3940
- widgets
4041
os: [ubuntu-latest, macos-latest, windows-latest]
4142

‎README.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
1. [Signals](#signals)
3030
1. [State](#state)
3131
1. [Toolbar Item](#toolbar-item)
32+
1. [Top Area Text Widget](#top-area-text-widget)
3233
1. [Widgets](#widgets)
3334
1. [Prerequisites](#prerequisites)
3435
1. [Develop and Use the Examples](#develop-and-use-the-examples)
@@ -116,6 +117,7 @@ Start with the [Hello World](hello-world) and then jump to the topic you are int
116117
- [Signals](signals)
117118
- [State](state)
118119
- [Toolbar item](toolbar-button)
120+
- [Top Area Text Widget](toparea-text-widget)
119121
- [Widgets](widgets)
120122

121123
You can expect from each example:
@@ -225,7 +227,7 @@ Add user interface to edit cell or notebook metadata.
225227

226228
[![Metadata Form](metadata-form/preview.gif)](metadata-form)
227229

228-
## [MIME Renderer](mimerenderer)
230+
### [MIME Renderer](mimerenderer)
229231

230232
Add a MIME renderer for mp4 content to the application.
231233

@@ -273,6 +275,13 @@ Add a new button to the notebook toolbar.
273275

274276
[![Toolbar button](toolbar-button/preview.gif)](toolbar-button)
275277

278+
### [Top Area Text Widget](toparea-text-widget)
279+
280+
A very simple example that adds a basic text widget to the top area. See [related video.](https://www.youtube.com/watch?v=mqotG1MkHa4).
281+
This example is part of the [Extension Dual Compatibility Guide](https://jupyterlab.readthedocs.io/en/latest/extension_dual_compatibility.html).
282+
283+
[![Top Area Text Widget](toparea-text-widget/preview.jpg)](toparea-text-widget)
284+
276285
### [Widgets](widgets)
277286

278287
Add a new Widget element to the main window.

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@
4141
"signals",
4242
"state",
4343
"toolbar-button",
44+
"toparea-text-widget",
4445
"widgets"
4546
],
4647
"devDependencies": {

‎toparea-text-widget/.copier-answers.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
2+
_commit: v4.2.4
3+
_src_path: https://github.com/jupyterlab/extension-template
4+
author_email: ''
5+
author_name: Project Jupyter Contributors
6+
data_format: string
7+
file_extension: ''
8+
has_binder: true
9+
has_settings: false
10+
kind: frontend
11+
labextension_name: '@jupyterlab-examples/toparea'
12+
mimetype: ''
13+
mimetype_name: ''
14+
project_short_description: A JupyterLab extension to add text in the top area.
15+
python_name: jupyterlab_examples_toparea
16+
repository: https://github.com/jupyterlab/extension-examples
17+
test: false
18+
viewer_name: ''
19+

‎toparea-text-widget/.gitignore‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
*.bundle.*
2+
lib/
3+
node_modules/
4+
*.log
5+
.eslintcache
6+
.stylelintcache
7+
*.egg-info/
8+
.ipynb_checkpoints
9+
*.tsbuildinfo
10+
jupyterlab_examples_toparea/labextension
11+
# Version file is handled by hatchling
12+
jupyterlab_examples_toparea/_version.py
13+
14+
# Created by https://www.gitignore.io/api/python
15+
# Edit at https://www.gitignore.io/?templates=python
16+
17+
### Python ###
18+
# Byte-compiled / optimized / DLL files
19+
__pycache__/
20+
*.py[cod]
21+
*$py.class
22+
23+
# C extensions
24+
*.so
25+
26+
# Distribution / packaging
27+
.Python
28+
build/
29+
develop-eggs/
30+
dist/
31+
downloads/
32+
eggs/
33+
.eggs/
34+
lib/
35+
lib64/
36+
parts/
37+
sdist/
38+
var/
39+
wheels/
40+
pip-wheel-metadata/
41+
share/python-wheels/
42+
.installed.cfg
43+
*.egg
44+
MANIFEST
45+
46+
# PyInstaller
47+
# Usually these files are written by a python script from a template
48+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
49+
*.manifest
50+
*.spec
51+
52+
# Installer logs
53+
pip-log.txt
54+
pip-delete-this-directory.txt
55+
56+
# Unit test / coverage reports
57+
htmlcov/
58+
.tox/
59+
.nox/
60+
.coverage
61+
.coverage.*
62+
.cache
63+
nosetests.xml
64+
coverage/
65+
coverage.xml
66+
*.cover
67+
.hypothesis/
68+
.pytest_cache/
69+
70+
# Translations
71+
*.mo
72+
*.pot
73+
74+
# Scrapy stuff:
75+
.scrapy
76+
77+
# Sphinx documentation
78+
docs/_build/
79+
80+
# PyBuilder
81+
target/
82+
83+
# pyenv
84+
.python-version
85+
86+
# celery beat schedule file
87+
celerybeat-schedule
88+
89+
# SageMath parsed files
90+
*.sage.py
91+
92+
# Spyder project settings
93+
.spyderproject
94+
.spyproject
95+
96+
# Rope project settings
97+
.ropeproject
98+
99+
# Mr Developer
100+
.mr.developer.cfg
101+
.project
102+
.pydevproject
103+
104+
# mkdocs documentation
105+
/site
106+
107+
# mypy
108+
.mypy_cache/
109+
.dmypy.json
110+
dmypy.json
111+
112+
# Pyre type checker
113+
.pyre/
114+
115+
# End of https://www.gitignore.io/api/python
116+
117+
# OSX files
118+
.DS_Store
119+
120+
# Yarn cache
121+
.yarn/

‎toparea-text-widget/.prettierignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
node_modules
2+
**/node_modules
3+
**/lib
4+
**/package.json
5+
!/package.json
6+
jupyterlab_examples_toparea

‎toparea-text-widget/.yarnrc.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
nodeLinker: node-modules

‎toparea-text-widget/README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Top area widget (cross compatible extension)
2+
3+
This example defines an extension that adds a single self-contained text widget
4+
to the top bar of the UI.
5+
6+
![preview](./preview.jpg)
7+
8+
## Jupyter Notebook / JupyterLab compatibility
9+
10+
As Jupyter Notebook 7+ is built with components from JupyterLab, and since
11+
both use the same building blocks, that means your extension can work
12+
on both (or any other frontend built with JupyterLab components) with
13+
little or no modification depending on its design.
14+
15+
This extension doesn't need to do anything at all to be compatible
16+
with both JupyterLab and Notebook 7+ (both apps have a top area that can hold the
17+
widget, so it will be visible in both JupyterLab and Notebook 7+ upon install and
18+
after launch). This will be the case if your extension only uses features
19+
that both applications have.
20+
21+
## Adding a widget to the top area
22+
23+
You can add a widget to the top area by calling the following
24+
method of the application shell:
25+
26+
```ts
27+
// src/index.ts#L34-L34
28+
29+
app.shell.add(widget, 'top', { rank: 1000 });
30+
```
31+
32+
The _rank_ is used to order the widget within the top area.
33+
34+
## Where to Go Next
35+
36+
If your extension is using features that are not common to both interfaces,
37+
special steps needs to be taken. You can have a look at the [Shout button example](../shout-button-message)
38+
that uses a feature available in JupyterLab but not in Notebook 7+.
39+
40+
You can have more information about this in the
41+
[Extension Dual Compatibility Guide](https://jupyterlab.readthedocs.io/en/latest/extension_dual_compatibility.html).

‎toparea-text-widget/install.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"packageManager": "python",
3+
"packageName": "jupyterlab_examples_toparea",
4+
"uninstallInstructions": "Use your Python package manager (pip, conda, etc.) to uninstall the package jupyterlab_examples_toparea"
5+
}

‎toparea-text-widget/jupyterlab_examples_toparea/__init__.py‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
try:
2+
from ._version import __version__
3+
except ImportError:
4+
# Fallback when using the package in dev mode without installing
5+
# in editable mode with pip. It is highly recommended to install
6+
# the package from a stable release or in editable mode: https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs
7+
import warnings
8+
warnings.warn("Importing 'jupyterlab_examples_toparea' outside a proper installation.")
9+
__version__ = "dev"
10+
11+
12+
def _jupyter_labextension_paths():
13+
return [{
14+
"src": "labextension",
15+
"dest": "@jupyterlab-examples/toparea"
16+
}]

0 commit comments

Comments
 (0)