Configure document-title during updates

[stlehmann]

This PR addresses #856 and #732. It adds an update_title parameter to Dash.__init__()which can be set to a String or None. If this parameter is set to a String this will be the document title that is shown if Dash is updating. If update_title is set to None or "" the document title will not change at all. This is especially useful for applications with short update intervals to prevent flickering of the document title.

I have not yet added any tests because I didn't know where to put them. If you should request some tests I am more than willing to provide some :)

[alexcjohnson]

@stlehmann thanks, this looks great! Re tests: How about in test_loading_states.py? The same pattern we used there should work for this purpose, with Lock to pause the callback until you've seen what you want in the browser.

[stlehmann]

@alexcjohnson

How about in test_loading_states.py? The same pattern we used there should work for this purpose, with Lock to pause the callback until you've seen what you want in the browser.

Thanks for the hint. I'll get into it.

[stlehmann]

@alexcjohnson I added tests to test_loading_states.py. I tested for update_title being set to default, None, empty and a custom string. Hopefully the test implementation is acceptable. Otherwise just let me know :)

[alexcjohnson]

Very nice tests! One thing though: your callback will execute on page load, right? So holding the lock while starting the server means we're testing the title during the initialization sequence. That's a good thing to test, but I think in at least one of these tests (and maybe all of them) we should test:

• during startup, we see the correct updating title
• when the callback is done we see the regular title
• when the callback is triggered interactively we see the updating title again

Also rather than a simple assert, for robustness I think it'd be better to do a wait.until, in case things don't happen quite in the expected order:

from dash.testing.wait import until

until(lambda: dash_duo.driver.title == "Updating...", timeout=1)

And one last thing, if you're feeling adventurous: These test cases are nearly identical so they could be parametrized, something like:

import pytest

@pytest.mark.parametrize(
    "kwargs,page_updating_title",
    [
        ({}, "Updating..."),
        ({"updating_title": None}, "Dash"),
        ({"updating_title": ""}, "Dash"),
        ({"updating_title": "Hello World"}, "Hello World")
    ]
)
def test_rdls003_update_title_default(dash_duo, updating_title, page_updating_title)

[stlehmann]

I tried to implement your suggestions. I omitted an explicit test for the correct update title on startup because the callback should be called on startup afaik. I hope this is OK. The parametrize decorator is a great thing. Didn't know that until now, thanks :) Hope I did it all right with the locks. I'm not that sure about it.

[alexcjohnson]

Interesting... this appears to work but I'm kind of surprised it does - it might actually be waiting for the timeout period and then throwing an error silently. That's because the server and the browser side are running in different processes (hence the need for Lock).

I'd remove the title check inside the callback, and just put it at the very end of the test, after #button.click() (but still inside the with lock: block)

[stlehmann]

@alexcjohnson

I'd remove the title check inside the callback, and just put it at the very end of the test, after #button.click() (but still inside the with lock: block)

This was my first shot but that didn't work at that time because I missed the lock inside the callback. Now this works like a charm. I also added the check on startup again.

[alexcjohnson]

Beautiful! Thanks for the test updtes. I'm not sure what happened with the Percy run but that's not on your side, just something flaky - I'll sort it out. 💃

[stlehmann]

You are very welcome. Thanks again for the review and the great mentoring. 🙇

[alexcjohnson]

@Marc-Andre-Rivet as we were discussing the other day - the renderer no longer holds this default value at all. That means when the R and Julia implementations update to include this functionality in their renderer, they will need to add this option to the back end at the same time or the default behavior will change to no title changes ever.

[chriddyp]

Update to those passing through GitHub: This feature is now documented in http://dash.plotly.com/external-resources. Look for the title= and update_title=. See the "Customizing Dash's Document or Browser Tab Title", " Update the Document Title Dynamically based off of the URL or Tab", and "Customizing or Removing Dash's "Updating..." Message" sections.