New component - Typescript/Javascript code - workflow?

Hi,
I am new to Bokeh and I enjoy it very much! But I want to extend Bokeh with a graphical widget of my own. I have seen the examples, but a few questions remain

  • Is there a reference for the Javascript/Typescript code to write? I can understand more or less from the examples what to do but I have not seen a documented API
  • The typescript file imports things from “core/properties” and “core/dom”… and my linter goes bonkers because it can’t find them (even if it works), what do you do when you write that file to make that a nice experience with your IDE?
  • How stable this API is supposed to be? What is the likelihood of my widget stopping to work after a software update?

Thanks!!

cc @mateusz

Hi @sharikone for a fairly long time BokehJS was a a hidden implementation detail, and only more recently become (somewhat) more user facing with the possibility of extensions, etc. But it still has not received as much attention, re: documentation, as the Python side has. This is actually a current topic of interest, so if you have experience or expertise you can share, please chime in on this dev discussion: Adopt JSDoc to document TypeScript code · bokeh/bokeh · Discussion #11309 · GitHub

Pretty much all the documentation there currently is on extending Bokeh is located in the user’s guide chapter:

https://docs.bokeh.org/en/latest/docs/user_guide/extensions.html

BokehJS is still under active development, but I would not expect the property types in core/properties to change much, or the DOM helps in core/dom either. (But note that you don’t have to use core/dom at all, you could just create DOM objects manually)

and my linter goes bonkers because it can’t find them (even if it works), what do you do when you write that file to make that a nice experience with your IDE?

I don’t know the answer to this, perhaps @mateusz can chime in and then we can create an issue to document whatever the correct configuration is.

Thank you very very much!

You confirmed my impression that BokehJS is still lacking in its documentation.

I managed to get a satisfiable work environment (and to get linting: the secret is using the “paths” and “include” properties of tsconfig.json).

If you or @mateusz have a tip for creating a debugging environment too it would be wonderful and save me much time. As I see now the bokeh compiler produces a very big javascript bundle that includes all the modules, included the external ones, and includes it in the html file. If there was, say, a way to put breakpoints in the original typescript file that is fed to the compiler and use Chrome developer tools to debug the code it would really improve productivity. I am not nearly skilled enough in frontend development for coming up with a solution on my own, sadly.

Anyway, I am creating a graphic module to show quantum states in a Bloch sphere rendered using Three.js. If all goes well I will shamelessly showcase it here.

1 Like

You confirmed my impression that BokehJS is still lacking in its documentation.

It is however, probably worth mentioning one caveat. Most of the work in Bokeh boils down to “setting property values on objects”. This is definitely true on the Python side, and still mostly true for CustomJS code. The Python and JS properties are maintained under test to be in complete agreement. In that sense, the existing reference guide for bokeh.models, although it is technically based on the Python codebase, is completely applicable to the JS side as well:

Every model and property listed there exists on both the Python and JS sides, with the same default values.

Now, all that said, things are a little more involved when discussing custom extensions, because that is the one area where there is more possibility of needing to use actual function/method APIs, and those are what are not documented especially well yet. But even there, I think the existing examples cover the a good chunk of common needs at least by way of demonstration (which methods might need to be defined, how to utilize screen mappers, etc).

If all goes well I will shamelessly showcase it here.

Looking forward to seeing it!

Oh wow, yes looking forward to that showcase and following this thread closely. I’ve been dreaming of extending bokeh to three.js for quite some time! Just to put it out there based on what I’ve looked into, you might want to check out the ipyvolume source code (GitHub - maartenbreddels/ipyvolume: 3d plotting for Python in the Jupyter notebook based on IPython widgets using WebGL). I know three.js is used in the backend for this, AND there are some functions that are supposed to allow linking to bokeh ( ipyvolume & bokeh — ipyvolume 0.6.0-alpha.10 documentation ), however I cannot get it to work ( Bokeh-->Ipyvolume connection.. Can't get basic example working · Issue #396 · maartenbreddels/ipyvolume · GitHub ) and have had to more less park this for other higher priority work tasks etc. Good luck!

1 Like

@gmerritt123 have you seen this example for wrapping JavaScript libraries? May point you in the right direction for extending to three.js

1 Like

Yes! This is totally where I’d “start.” I’ve even messed around with this example with geologic layer data (aka “my” data… it got insanely laggy heheh). I just need a weekend (or three) to take a real hard run at it and build up my understanding of how all this can be tied together. But good lord the potential there is just scary.

While we’re on this dream topic, the other algorithm I’d like to incorporate is fast marching cubes → check this out: fhtr: Fast marching cubes in JavaScript (see the demo to slice a volume and or isosurface that renders on the fly). If I had a 3d figure canvas extension and the right 3d model extensions to tie this type of thing back to the bokeh world… oh boy…