Getting JS to work in a notebook.

[thorwhalen]

Links

A Simple Pattern for Embedding Third Party Javascript Generated Graphics in Jupyter Notebooks

StackOverflow: How do I call a Javascript function from Python?

js2py

A GPT conversation about calling JS from a notebook

I had the oddest insane-making bug running some simple JS code in a notebook.
My function worked (behavior X) the first time it was called, but if I ran the exact same code again in a different cell, it didn't give me the same behavior (behavior Y). The first cell gave me systematically behavior X, but the second systematically behavior Y.

Some higher power was at play.

This is that story. A story where GPT-4 saved the day (but not immediately).

See the final, correct code, and how it behaves, in the "Calling JS mermaid from python, in a notebook" section of this notebook

html not even working

Me

I made an html file with the following content:

<pre class="mermaid">
    graph LR
        A --> B --> C
</pre>

<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({{ startOnLoad: true }});
</script>

I'm expecting to see an image of a diagram, generated by the mermaid script, but instead I'm just getting the text:

    graph LR
        A --> B --> C

Troubleshoot.

GPT-4

The issue here might be because of the incorrect usage of the mermaid.initialize function.

You should use it as mermaid.initialize({startOnLoad: true}); instead of mermaid.initialize({{ startOnLoad: true }});.

Also, to render the diagrams, you need to call mermaid.init after initializing.

Here is the corrected code:

<pre class="mermaid">
    graph LR
        A --> B --> C
</pre>

<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
    mermaid.init(undefined, document.querySelector('.mermaid'));
</script>

You can use mermaid.init to initialize a specific element or a collection of elements, by passing the element or collection as the second argument to mermaid.init. The undefined as the first argument to mermaid.init means that it uses the default configuration.

Please note that this script will not work if you open the HTML file directly in your browser due to CORS policy. You must serve your HTML file from a server. For local development, you can use a simple server like Python's built-in HTTP server. If you have Python installed, you can start a simple HTTP server by running python -m http.server in the directory containing your HTML file, and then access your file at http://localhost:8000/your-file.html.

IPython display function

Note that GPT-4's answer here wasn't really the problem, but it is good to know of the display function if you don't.

Me

I wrote this python code and executed in a jupyter notebook cell:

_mermaid_display_template = """
<script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({{ startOnLoad: true }});
    mermaid.init(undefined, document.querySelector('.mermaid'));
</script>

<pre class="mermaid">
    {code}
</pre>
"""

def mermaid(code: str, *, prefix='graph', suffix='', egress=None):
    if egress is None:
        egress = lambda x: x
    code_ = f"{prefix}\n{code}\n{suffix}"
    html = _mermaid_display_template.format(code=code_)
    return egress(html)

When I execute this in the next cell:

from IPython.display import HTML

code = "A --> B --> C"
mermaid(code, egress=HTML)

I see my graph image. The code has been rendered.

But when I copy that exact same code in the cell after that and execute, I do get the IPython.core.display.HTML object I'm expecting, but it is not rendered. I don't see the image.

Why?

GPT-4

The issue you're encountering is likely due to the way Jupyter Notebook renders output. When you execute a cell that returns an IPython.core.display.HTML object, the notebook will render the HTML content automatically. However, when you copy the same code to another cell and execute it, the HTML object is not automatically rendered. You need to explicitly display the HTML object using the display function from the IPython.display module.

Here's how you can modify your code to display the mermaid graph properly in both cases:

from IPython.display import display, HTML

code = "A --> B --> C"
graph_html = mermaid(code, egress=HTML)
display(graph_html)

Now, when you copy this code to another cell and execute it, the mermaid graph should be displayed as expected. The display function is used to explicitly display the HTML object, ensuring that the notebook renders the HTML content in both cases.

DOMContentLoaded

Again, GPT-4 didn't repair the problem with the following proposed solution, but it's included in the final solution. I've tried without it in the final solution, and it still works, but perhaps it's good to know about anyway, so including here.

Me

Actually, I still get the same effect here.
I still get my graph displayed in the first cell, but it renders the text in the second one.

GPT-4

Apologies for the confusion earlier. It seems that the issue is related to the execution order of the JavaScript code and the rendering of the HTML content in the Jupyter Notebook.

When the code runs for the first time, the JavaScript code is executed, and then the HTML content is rendered. However, when you run the code again in another cell, the JavaScript code might not have a chance to execute before the HTML content is displayed.

To fix this issue, you can modify the JavaScript code to use the DOMContentLoaded event. This ensures that the JavaScript code runs only after the HTML content has been fully loaded.

Here's the updated _mermaid_display_template:

_mermaid_display_template = """
<script type="module">
    async function initMermaid() {{
        const module = await import('https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs');
        const mermaid = module.default;
        mermaid.initialize({{ startOnLoad: true }});
        mermaid.init(undefined, document.querySelector('.mermaid'));
    }}
    
    if (document.readyState === 'loading') {{
        document.addEventListener('DOMContentLoaded', initMermaid);
    }} else {{
        initMermaid();
    }}
</script>

<pre class="mermaid">
    {code}
</pre>
"""

Now, when you run the following code in multiple cells, the mermaid graph should display correctly:

from IPython.display import display, HTML

code = "A --> B --> C"
graph_html = mermaid(code, egress=HTML)
display(graph_html)

The initMermaid function is defined as an async function and is called when the DOMContentLoaded event is triggered, or immediately if the document is already loaded. This ensures that the JavaScript code is executed after the HTML content has been rendered, which should resolve the issue you were experiencing.

unique identifiers

Me

It still doesn't work.

GPT-4

I apologize for the inconvenience. Upon further investigation, it seems that the issue is related to the fact that the Jupyter Notebook loads each cell's output into an iframe. The document.querySelector('.mermaid') in the JavaScript code may not select the correct element across different cells.

A solution to this issue is to use a unique identifier for each mermaid graph and update the JavaScript code to select the element using the unique identifier. Here's the updated code:

import uuid

_mermaid_display_template = """
<script type="module">
    async function initMermaid_{unique_id}() {{
        const module = await import('https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs');
        const mermaid = module.default;
        mermaid.initialize({{ startOnLoad: true }});
        mermaid.init(undefined, document.getElementById('mermaid_{unique_id}'));
    }}
    
    if (document.readyState === 'loading') {{
        document.addEventListener('DOMContentLoaded', initMermaid_{unique_id});
    }} else {{
        initMermaid_{unique_id}();
    }}
</script>

<pre class="mermaid" id="mermaid_{unique_id}">
    {code}
</pre>
"""

def mermaid(code: str, *, prefix='graph', suffix='', egress=None):
    if egress is None:
        egress = lambda x: x
    code_ = f"{prefix}\n{code}\n{suffix}"
    unique_id = str(uuid.uuid4()).replace("-", "")
    html = _mermaid_display_template.format(code=code_, unique_id=unique_id)
    return egress(html)

Now, when you run the following code in multiple cells, the mermaid graph should display correctly:

from IPython.display import display, HTML

code = "A --> B --> C"
graph_html = mermaid(code, egress=HTML)
display(graph_html)

The uuid.uuid4() function is used to generate a unique identifier for each mermaid graph, and the JavaScript code is updated to use this unique identifier when selecting the element to render the graph. This should resolve the issue you were experiencing with displaying the mermaid graph in multiple cells.