@@ -20,7 +20,7 @@ This can be accomplished in different ways for different reasons:
20
20
* - :ref: `Dynamically Install Javascript ` (requires NPM _)
21
21
- You want to **quickly experiment ** with IDOM and the Javascript ecosystem.
22
22
23
- * - :ref: `Import Javascript Source `
23
+ * - :ref: `Import Javascript Bundles `
24
24
- You want to create polished software that can be **easily shared ** with others.
25
25
26
26
@@ -32,19 +32,16 @@ Dynamically Install Javascript
32
32
Before continuing `install NPM `_.
33
33
34
34
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:
41
38
42
39
.. code-block :: bash
43
40
44
41
idom install @material-ui/core
45
42
46
43
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):
48
45
49
46
.. code-block ::
50
47
@@ -73,33 +70,53 @@ add an ``onClick`` handler to the element:
73
70
.. example :: material_ui_button_on_click
74
71
75
72
76
- Import Javascript Source
77
- ------------------------
73
+ Import Javascript Bundles
74
+ -------------------------
78
75
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:
80
83
81
- This does not require NPM _ to be installed.
84
+ .. code-block ::
82
85
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")
93
88
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.
95
105
96
106
.. example :: super_simple_chart
97
107
98
108
99
109
Alternate Client Implementations
100
110
--------------------------------
101
111
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:
103
120
104
121
105
122
.. Links
0 commit comments