Experimental extended deck

Glossary

• Interactive map - SVG canvas of a world (or other region) map that responds to user manipulations (i.e. dragging, scrolling, swiping), aiding the user in visual region recognition.

Overview

The sole intention of the deck is "incubating" the idea of interactive map for various note templates (currently Country - Map only).

Note, that logic behind interactive map:

• was developed with flexibility in mind, meaning that it is highly customizable (see Configuration section).
• follows robustness principle, meaning any misconfiguration, script loading failure or other error will not lead to the deck becoming unusable, but rather will make the deck default to the behaviour of extended version up until the initial issue is resolved.

File structure

• _ug-jsvectormap.js, _ug-jsvectormap.min.css - the code and styling of the underlying library using which the interactive map is implemented.
• _ug-world.js - definition of SVG map in the library-compatible format.
• _ug-interactive_map_config.js - various configurations used by the program.
• _ug-interactive_map_init.js - the basis of the logic where preparatory steps and interactive map initialization take place.

Note that _ug-interactive_map_init.js file is written with readability in mind (i.e. self-documented function and variable names, function docs), thus rendering any additional documentation useless due to providing essentially no supplementary information.

Configuration

Customizable configuration is defined as an object inside of a script element of "Country - Map" front card template:

<script>
  sessionStorage.setItem("userConfig",
    JSON.stringify({
      commonFeatures: {
        ...
      },
      commonColors: {
        ...
      }
    }));
</script>

The configuration consists of 2 self-descriptive parts:

• commonFeatures:
  • interactiveEnabled - switch to set interactive map on/off. May be used in case of critical bugs discovery to roll back to extended deck version behaviour.
  • interactiveMobileEnabled - switch to control interactive map mode for mobile (both AnkiDroid and Anki Mobile). Note that when interactiveEnabled is false the option is ignored.
  • autoAnswerEnabled - switch to define whether a card is automatically swapped to answer side after the user selects a region.
  • toolTipEnabled - a tooltip showing region name on answer card side on hover. Note that by default the feature is disabled as it is unclear of its consequences on remembering process - user might use it as a hint to show region name represented by a card further in the review queue.
• commonColors
  • region, selectedRegion, incorrectRegionHighlight, correctRegionHighlight - region colors in various states.
  • background - map background that is by default blue to create appearance of water mass.
  • border - region border color.
  • tooltipBackground, tooltipText - tooltip colors.

Note that any misconfiguration of the aforementioned properties will lead to the program defaulting to initial values. For example fasle string for any of the commonFeatures properties or red for any of commonColors.

Note that any unrelated to property values change of code (e.g. removal of JSON.stringify({ line or addition of comma) may break the program, causing it to default to generic globe SVG on the front card side and static fallback image on the back.

AnkiDroid notice

When using interactive map on AnkiDroid be sure to either:

• Disable gestures when reviewing the note templates including the map (e.g. disabling gestures and using filtered deck to review the cards).
• Disable interactive map on mobile via interactiveMobileEnabled option in the configuration.

Note that enabled gestures do not in any way break interactive map logic, so if the user finds a way of working with both enabled, then there should not be any issues. The recommendation is written purely for practical reasons as usage of the one feature may lead to accidental interaction with the other.

Implementation decision notices

• At the time of writing the program relies on jsvectormap library version 1.6.0. This might change in the future as there are certain library issues to be resolved either by maintainer or via including a fork of the project.
• _ug-interactive_map_init.js script is wrapped around IIFE (Immediately Invoked Function Expression) due to Anki web view being persistent for card reviews meaning that writing let a = 1 in global scope leads to failure due to redeclaration of the variable (and using var is generally considered a bad practice due to polluting the global namespace, though succeeding to work).
• value--image element in note template corresponding to the static map fallback is intentionally left unchanged while value--map (corresponding to interactive map) is initially set to display: none in order to accommodate scripts loading failure situations.
• swapToBackSide() function that performs automatic swap to answer card side heavily relies on Anki APIs support for which may be removed at any moment. Thus, such feature might not be considered reliable and in the worst case scenario its existence might be deprecated while interactive map still working as usual, simply without it.