Skip to content

Commit 0738393

Browse files
rmorshearmorshea
committed
update readme
1 parent a6f16ac commit 0738393

File tree

2 files changed

+107
-97
lines changed

2 files changed

+107
-97
lines changed

‎README.md

Lines changed: 82 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,90 @@
11
# idom-jupyter
22

3-
A client for IDOM implemented using Jupyter widgets
3+
A client for [IDOM](https://github.com/idom-team/idom) implemented using Jupyter widgets
44

5-
## Installation
5+
## Try It Now!
66

7-
To install use pip:
7+
Check out some live examples by clicking the badge below:
88

9-
$ pip install idom_jupyter
9+
<a href="https://mybinder.org/v2/gh/idom-team/idom-jupyter/main?filepath=notebooks%2Fintroduction.ipynb">
10+
<img alt="Binder" height="25px" src="https://mybinder.org/badge_logo.svg" />
11+
</a>
12+
13+
## Getting Started
14+
15+
To install use `pip`:
16+
17+
```
18+
pip install idom_jupyter
19+
```
20+
21+
Then, before anything else, do one of the following:
22+
23+
1. At the top of your notebook run
24+
25+
```python
26+
import idom_jupyter
27+
```
28+
29+
2. Register `idom_jupyter` as a permanant IPython extension in [your config file](https://ipython.readthedocs.io/en/stable/config/intro.html#introduction-to-ipython-configuration):
30+
31+
```python
32+
c.InteractiveShellApp.extensions = [
33+
'idom_jupyter'
34+
]
35+
```
36+
37+
## Usage
38+
39+
Once you're done [getting started](#getting-started), you can author and display IDOM
40+
layouts natively in your Jupyter Notebook:
41+
42+
```python
43+
import idom
44+
45+
@idom.component
46+
def ClickCount():
47+
count, set_count = idom.hooks.use_state(0)
48+
return idom.html.button(
49+
{"onClick": lambda event: set_count(count + 1)},
50+
[f"Click count: {count}"],
51+
)
52+
53+
ClickCount()
54+
```
55+
56+
You can also turn an `idom` element constructor into one that returns an `ipywidget` with
57+
the `idom_juptyer.widgetize` function. This is useful if you wish to use IDOM in combination
58+
with other Jupyter Widgets as in the following example:
59+
60+
```python
61+
ClickCountWidget = idom_jupyter.widgetize(ClickCount)
62+
ipywidgets.Box(
63+
[
64+
ClickCountWidget(),
65+
ClickCountWidget(),
66+
]
67+
)
68+
```
69+
70+
Alternatively just wrap an `idom` element instance in an `idom_jupyter.LayoutWidget`:
71+
72+
```python
73+
ipywidgets.Box(
74+
[
75+
idom_jupyter.LayoutWidget(ClickCount()),
76+
idom_jupyter.LayoutWidget(ClickCount()),
77+
]
78+
)
79+
```
80+
81+
For a more detailed introduction check out this live demo here:
82+
83+
<a href="https://mybinder.org/v2/gh/idom-team/idom-jupyter/main?filepath=notebooks%2Fintroduction.ipynb">
84+
<img alt="Binder" height="25px" src="https://mybinder.org/badge_logo.svg" />
85+
</a>
86+
87+
## Development Installation
1088

1189
For a development installation (requires [Node.js](https://nodejs.org) and [Yarn version 1](https://classic.yarnpkg.com/)),
1290

‎notebooks/introduction.ipynb

Lines changed: 25 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,26 @@
1616
"\n",
1717
"# Getting Started\n",
1818
"\n",
19-
"The first thing we need must do in order to run IDOM in a Jupyter Notebook is `import idom_jupyter`. After that, you'll be able to use IDOM components like any other [Jupyter Widget](https://ipywidgets.readthedocs.io/en/latest/#)."
19+
"Then, before anything else, do one of the following:\n",
20+
"\n",
21+
"1. At the top of your notebook run\n",
22+
"\n",
23+
" ```python\n",
24+
" import idom_jupyter\n",
25+
" ```\n",
26+
"\n",
27+
"2. Register `idom_jupyter` as a permanant IPython extension in [your config file](https://ipython.readthedocs.io/en/stable/config/intro.html#introduction-to-ipython-configuration):\n",
28+
"\n",
29+
" ```python\n",
30+
" c.InteractiveShellApp.extensions = ['idom_jupyter']\n",
31+
" ```\n",
32+
"\n",
33+
"For the purposes of this tutorial, you'll want to do the first:"
2034
]
2135
},
2236
{
2337
"cell_type": "code",
24-
"execution_count": 2,
38+
"execution_count": null,
2539
"metadata": {},
2640
"outputs": [],
2741
"source": [
@@ -39,34 +53,9 @@
3953
},
4054
{
4155
"cell_type": "code",
42-
"execution_count": 3,
56+
"execution_count": null,
4357
"metadata": {},
44-
"outputs": [
45-
{
46-
"data": {
47-
"text/plain": [
48-
"App(7fb016a9afe0)"
49-
]
50-
},
51-
"execution_count": 3,
52-
"metadata": {},
53-
"output_type": "execute_result"
54-
},
55-
{
56-
"data": {
57-
"application/vnd.jupyter.widget-view+json": {
58-
"model_id": "7a9d9d0847d94e71b53ee3e9b22566d9",
59-
"version_major": 2,
60-
"version_minor": 0
61-
},
62-
"text/plain": [
63-
"LayoutWidget(Layout(App(7fb016a9afe0)))"
64-
]
65-
},
66-
"metadata": {},
67-
"output_type": "display_data"
68-
}
69-
],
58+
"outputs": [],
7059
"source": [
7160
"from idom import component, html, run\n",
7261
"\n",
@@ -143,34 +132,9 @@
143132
},
144133
{
145134
"cell_type": "code",
146-
"execution_count": 8,
135+
"execution_count": null,
147136
"metadata": {},
148-
"outputs": [
149-
{
150-
"data": {
151-
"text/plain": [
152-
"Gallery(7fb017f937c0)"
153-
]
154-
},
155-
"execution_count": 8,
156-
"metadata": {},
157-
"output_type": "execute_result"
158-
},
159-
{
160-
"data": {
161-
"application/vnd.jupyter.widget-view+json": {
162-
"model_id": "dd0ea39fb8164a12a6e3b495296b9ea3",
163-
"version_major": 2,
164-
"version_minor": 0
165-
},
166-
"text/plain": [
167-
"LayoutWidget(Layout(Gallery(7fb017f937c0)))"
168-
]
169-
},
170-
"metadata": {},
171-
"output_type": "display_data"
172-
}
173-
],
137+
"outputs": [],
174138
"source": [
175139
"import json\n",
176140
"from pathlib import Path\n",
@@ -221,7 +185,7 @@
221185
},
222186
{
223187
"cell_type": "code",
224-
"execution_count": 14,
188+
"execution_count": null,
225189
"metadata": {},
226190
"outputs": [],
227191
"source": [
@@ -256,25 +220,9 @@
256220
},
257221
{
258222
"cell_type": "code",
259-
"execution_count": 15,
223+
"execution_count": null,
260224
"metadata": {},
261-
"outputs": [
262-
{
263-
"data": {
264-
"application/vnd.jupyter.widget-view+json": {
265-
"model_id": "4ce3c50a8f1e4c6ca7c290cee10a89af",
266-
"version_major": 2,
267-
"version_minor": 0
268-
},
269-
"text/plain": [
270-
"Box(children=(IntSlider(value=0, readout=False), LayoutWidget(Layout(SliderObserver(7fb01611ed40, slider=IntSl…"
271-
]
272-
},
273-
"execution_count": 15,
274-
"metadata": {},
275-
"output_type": "execute_result"
276-
}
277-
],
225+
"outputs": [],
278226
"source": [
279227
"from ipywidgets import Box, IntSlider\n",
280228
"from idom_jupyter import LayoutWidget\n",
@@ -295,25 +243,9 @@
295243
},
296244
{
297245
"cell_type": "code",
298-
"execution_count": 16,
246+
"execution_count": null,
299247
"metadata": {},
300-
"outputs": [
301-
{
302-
"data": {
303-
"application/vnd.jupyter.widget-view+json": {
304-
"model_id": "b1797d7cf50f4b1eb9d5cfe34ef87663",
305-
"version_major": 2,
306-
"version_minor": 0
307-
},
308-
"text/plain": [
309-
"Box(children=(IntSlider(value=0, readout=False), LayoutWidget(Layout(SliderObserver(7fb01611fa00, slider=IntSl…"
310-
]
311-
},
312-
"execution_count": 16,
313-
"metadata": {},
314-
"output_type": "execute_result"
315-
}
316-
],
248+
"outputs": [],
317249
"source": [
318250
"from idom_jupyter import widgetize\n",
319251
"\n",

0 commit comments

Comments
 (0)