The js/css override mechanism is not well explained in the docs

[JeffAbrahamson]

Describe the bug It is unclear from the docs (and from the code) how to override javascript and css that folium emits. There's some very old discussion in (closed) issue #192 and (open) issues #1479 and #1482 on this subject. The issue #1479 is particularly striking: it's nice to update folium to use bootstrap 4, but is the only way to do this to change folium? What if I use folium on two sites and the sites use different versions of bootstrap for some historical reason? This seems like it should be customisable, and #192 suggests it is. And yet code such as

figure.header.add_child(
    JavascriptLink('https://example.com/bootstrap/400.5.0/css/bootstrap.min.css'),
    name="bootstrap_css")

doesn't have the desired effect of changing the output html. (Bootstrap 400 doesn't exist, of course, I want to make clear that I'm trying to change the default, even if the default is quite different when this issue is read by someone many years hence, as happens.)

It appears from #1479 that a different version of folium would solve my underlying issue (of wanting to use bootstrap 4), but it wouldn't address the issue that the docs don't tell me how to modify what version it uses. And #1482 anyway hasn't been merged.

To Reproduce

As I'm trying to make this go in a django context, I've written a minimal reproducible example in django. The (hopefully) only relevant bit is the code in this view function. That project can be cloned and run and it will provide two pages: an index page and a map page. The map page is slightly borked because of the bootstrap mismatch.

I've asked this question on the leaflet google group with a fair bit of (by now slightly rambling) documentation of things I've tried to do and code I've looked at to try to understand it. I've since realised this is probably more appropriate for folium than for leaflet, but that was less clear when I started.

Expected behavior This is a documenation bug, not a code functionality bug, so the expected behaviour is that I'd be able to learn how to make folium use my bootstrap version by reading the docs.

Environment (please complete the following information):

• Browser = firefox
• django
• Python version = 3.9.5 : sys.version_info(major=3, minor=9, micro=5, releaselevel='final', serial=0)
• folium version = 0.12.1
• branca version = 0.4.2

Additional context Add any other context about the problem here.

Possible solutions List any solutions you may have come up with.

folium is maintained by volunteers. Can you help making a fix for this issue?

I'm happy to help, but at the moment I don't know how to do so.

[Conengmo]

[update: this comment is outdated. See https://github.com/python-visualization/folium/issues/1519#issuecomment-2037113318 for recent info.]

You are right that the documentation is lacking in this aspect. Help with that is welcome!

I can say here that all static Javascript and CSS links are exposed in the various classes. They are included as lists called default_js and default_css. You can overwrite them. For backwards compatibility we didn't change the structure though, so unfortunately they are lists of tuples.

I'll give an example of how to replace a specific link by using an intermediary dictionary:

m = Map()
css_links = dict(m.default_css)
css_links['bootstrap'] = 'https://www.example.com'
m.default_css = list(css_links.items())

Maybe we should have this as a method on the JSCSSMixin class...

But for now just adding this to the documentation would be helpful!

[deji725]

Hi, I also ran into this issue. It took me a while to find this thread. Has the contents of your comment been uploaded to the documentation?

[Conengmo]

We just merged a PR that improves overriding js/css and adds documentation, see https://python-visualization.github.io/folium/latest/advanced_guide/customize_javascript_and_css.html. This new feature will be available in the upcoming Folium v.0.17.0 release.