overviewer/Minecraft-Overviewer — Issue #520: Configuring the javascript
Author: brownan
Created: 2011-10-27 03:09:16+00:00
State: open
Labels: Discussions

We had a good discussion on IRC on how best to expose an interface to configure javascript parameters. Here are the high level points.

People felt that we should have a more convenient interface than editing overviewerConfig.js in the web_assets folder or copying it and using the --web-assets option, both of which currently already work. I argued that editing web_assets should still be an option since we cannot predict every way people may want to edit the resulting static files, but agreed that there should be a more convenient way to edit common parameters.

The other point was that we felt that options going to the javascript should be separated from options that go to the overviewer renderer. Additionally, I felt that we should avoid adding a new command line option for every small configuration option and that there should be a better way to specify things like e.g. the default zoom level for the javascript than adding a --default-zoom command line option.

This led us to consider a single option for setting/overriding javascript variables in overviewerConfig.js. In settings.py a jsoptions dictionary can be used to override default values for various javascript variables. For example, jsoptions["defaultZoom"] = 3 would override the default of 0 and set it to 3 in the outputted overviewerConfig.js.

This led us further to the ambiguity of the "right" way to edit these configuration options. Right now, web_assets includes an overviewerConfig.js file that is actually a template (unlike every other file in web_assets, except for some comments in index.html looks like). Should people edit things in the overviewerConfig.js template? Should they do it with --web-assets? Should they change jsoptions in settings.py?

We all mostly agreed that it would be better to remove overviewerConfig.js from web_assets entirely and have it generated from scratch using python's json library. A hard-coded dictionary of defaults can be exposed to settings.py for the opportunity to override anything, and that can be outputted as overviewerConfig.js. This removes the ambiguity on the appropriate place to edit javascript configuration. It also has the advantage that the file can never get out of sync with custom edits, and the py code has more control over how it looks.

jsoptions can also be exposed to the command line through a single option: --jsoption=name:value or something like that. A single option like such is much better than adding a new option every time someone wants to customize a different value.

The problems with this approach is just that there is an option in overviewerConfig.js that is not currently JSON: there is one option that contains a function. I suggest a simple workaround where the function is moved to a different file, and being a slightly more complicated option, it can only be edited using the existing facilities (of editing web_assets directly or using --web-assets). overviewerConfig.js and the setting.py jsoptions will be reserved for simple configuration parameters that fit within JSON.