Skip to content

Commit 66c9b5f

Browse files
committedDec 22, 2020
imrove docs
1 parent f109d4a commit 66c9b5f

File tree

2 files changed

+43
-26
lines changed

2 files changed

+43
-26
lines changed
 

‎docs/source/javascript-modules.rst

+41-24
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ This can be accomplished in different ways for different reasons:
2020
* - :ref:`Dynamically Install Javascript` (requires NPM_)
2121
- You want to **quickly experiment** with IDOM and the Javascript ecosystem.
2222

23-
* - :ref:`Import Javascript Source`
23+
* - :ref:`Import Javascript Bundles`
2424
- You want to create polished software that can be **easily shared** with others.
2525

2626

@@ -32,19 +32,16 @@ Dynamically Install Javascript
3232
Before continuing `install NPM`_.
3333

3434
IDOM makes it easy to draft your code when you're in the early stages of development by
35-
using NPM_ to directly install Javascript packages into IDOM on the fly. Ultimately
36-
though, this approach isn't recommended if you
37-
:ref:`Import Javascript Source`.
38-
39-
Experimenting with IDOM it can be useful to quickly In this example we'll be using the ubiquitous React-based UI framework `Material UI`_
40-
which can be easily installed using the ``idom`` CLI:
35+
using NPM_ to directly install Javascript packages on the fly. In this example we'll be
36+
using the ubiquitous React-based UI framework `Material UI`_ which can be installed
37+
using the ``idom`` CLI:
4138

4239
.. code-block:: bash
4340
4441
idom install @material-ui/core
4542
4643
Or at runtime with :func:`idom.client.module.install` (this is useful if you're working
47-
in a REPL or a Jupyter Notebook):
44+
in a REPL or Jupyter Notebook):
4845

4946
.. code-block::
5047
@@ -73,33 +70,53 @@ add an ``onClick`` handler to the element:
7370
.. example:: material_ui_button_on_click
7471

7572

76-
Import Javascript Source
77-
------------------------
73+
Import Javascript Bundles
74+
-------------------------
7875

79-
.. note::
76+
For projects that will be shared with others we recommend bundling your Javascript with
77+
`rollup <https://rollupjs.org/guide/en/>`__ or `webpack <https://webpack.js.org/>`__
78+
into a
79+
`web module <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules>`__.
80+
Once you've done this, you can distribute bundled javascript in your Python package and
81+
integrate it into IDOM by defining :class:`~idom.client.module.Module` objects that
82+
load them from source:
8083

81-
This does not require NPM_ to be installed.
84+
.. code-block::
8285
83-
While it's probably best to create
84-
`a real package <https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry>`__
85-
for your Javascript, if you're just experimenting it might be easiest to quickly
86-
hook in a module of your own making on the fly. As before, we'll be using a
87-
:class:`~idom.client.module.Module`, however this time we'll pass it a ``source``
88-
parameter which is a file-like object. In the following example we'll use Victory again,
89-
but this time we'll add a callback to it. Unfortunately we can't just pass it in
90-
:ref:`like we did before <Passing Props To Javascript>` because Victory's
91-
event API is a bit more complex so we've implemented a quick wrapper for it in a file
92-
``chart.js`` which we can read in as a ``source`` to :class:`~idom.client.module.Module`:
86+
import idom
87+
my_js_package = idom.Module("my-js-package", source_file="/path/to/my/bundle.js")
9388
94-
Click the bars to trigger an event 👇
89+
The core benefit of loading Javascript in this way is that users of your code won't need
90+
NPM_. Rather, they can use ``pip`` to install your Python package without any other build
91+
steps because the bundled Javascript you distributed with it will be symlinked into the
92+
IDOM client at runtime.
93+
94+
.. note::
95+
96+
In the future IDOM will come with tools to help author Python packages with bundled
97+
Javascript
98+
99+
With that said, if you just want to see how this all works it might be easiest to
100+
hook in simple a hand-crafted Javascript module. In the example to follow we'll create
101+
a very basic SVG line chart. The catch though is that we are limited to using Javascript
102+
that can run directly in the browser. This means we can't use fancy syntax like
103+
`JSX <https://reactjs.org/docs/introducing-jsx.html>`__ and instead will use
104+
`htm <https://github.com/developit/htm>`__ to simulate JSX in plain Javascript.
95105

96106
.. example:: super_simple_chart
97107

98108

99109
Alternate Client Implementations
100110
--------------------------------
101111

102-
under construction...
112+
While it's possible to implement a whole-sale replacement for IDOM's built-in client by
113+
adhering to IDOM's :ref:`API <Package API>` and :ref:`Specifications`, the easiest way
114+
to implement a custom client is to create an object that adheres to the
115+
:class:`~idom.client.protocol.ClientImplementation` protocol and update the ``current``
116+
value of the :attr:`~idom.client.protocol.client_implementation` ref.
117+
118+
.. autoclass:: idom.client.protocol.ClientImplementation
119+
:noindex:
103120

104121

105122
.. Links

‎idom/client/protocol.py

+2-2
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010

1111
class ClientImplementation(Protocol):
12-
"""A minimal set of functions required to use :class:`idom.widget.module.Module`"""
12+
"""A minimal set of functions required to use :class:`~idom.client.module.Module`"""
1313

1414
def web_module_url(self, package_name: str) -> str:
1515
"""Return the URL to import the module with the given name."""
@@ -33,4 +33,4 @@ def add_web_module(self, package_name: str, source: Union[Path, str]) -> str:
3333
client_implementation: Ref[ClientImplementation] = Ref(
3434
cast(ClientImplementation, manage)
3535
)
36-
"""The current client implementation used by :class:`idom.widgets.module.Module`"""
36+
"""The current client implementation used by :class:`~idom.client.module.Module`"""

0 commit comments

Comments
 (0)
Please sign in to comment.