Custom UI via an HTML Frame Overlaying Map View

If you have an idea for a new feature, please discuss it in the main MapTool forum first, then post a summary of the discussion here. Use the first Sticky as a template.

Moderators: dorpond, trevor, Azhrei, giliath, jay, Mr.Ice

Post Reply
User avatar
digiacom
Cave Troll
Posts: 44
Joined: Thu Sep 27, 2018 3:00 am

Custom UI via an HTML Frame Overlaying Map View

Post by digiacom »

I would really like to see a way to overlay HTML elements directly onto the Map View that have access to impersonated & selected token properties and macros on a per-client basis. Imagine Diablo-style UIs for maptool, dynamically updated upon token change. Here is a vision for what it could look like with good CSS: (flagrantly from Diablo):

Image

For instance, imagine a 'Custom UI' tab in the campaign properties where you could define assets, styles, and markup for a simple widget to display your impersonated token's HP with a 'Update HP' macrolink in the top left corner, based on a dynamically applied body class maptool would apply when I impersonate a token:

Code: Select all

<style>
.my-hp { display: none; color: white; background: black; }
body.mt-token-impersonated .hp { display: block; }
</style>

<div class="my-hp"> 
   [getProperty( HP, getImpersonated() )]/[getProperty( MaxHP, getImpersonated() )]<br>
   <a href="[r:macroLinkText('ChangeHP@CAMPAIGN', 'none', '', getImpersonated())]">Update HP</a>   
</div>
UI 'modes' would be accomplished by attaching CSS classes to the body, and CSS selectors could be used to style modal UI combinations. The classes could be built-in, dynamically applied classes on a predefined set of events (a token is selected, multiple tokens are selected, a token is impersonated, current map name, GM/Player status, an object with notes/portrait is clicked on). Eventually, additional UI classes could be manually applied by event macros by a new function, something like 'toggleMapViewClass('class-name')'. This could also create effects like a 'YOU DIED' screen that covers the entire map view for a player, or a 'Intermission Curtain' that you could obscure the map with for players while you fix something during a game.

For dedicated framework builders, this could allow frameworks to move some or all of their functionality from the Selection/Impersonation/Campaign panels directly into the Map View UI for players, freeing up a lot of space and making the game more immersive. So many possibilities!

Considerations / Concerns
  • UI Shouldn't interfere with Map View. I of course don't want HTML content that isn't clickable to interfere with normal use of the Map View. The Layer and Drawing Tools modal should hover above any HTML UI, like it does now above the map view. Since it is not visible to players using the pointer tool, it wouldn't interfere much with UI and wouldn't need to be configured.
  • Port the 'Stat Sheet' to this overlay system in new campaigns. The hover-activated 'Stat Sheet' & 'Notes View' that appears when you click on an objects should be targetable via CSS. Perhaps it could be re-implemented via this new system by default to serve as a basis for frameworks to expand upon. Apart from that possibility, it should just sit directly over any HTML layer to preserve backwards compatibility.
  • Maybe wait for Javascript? This idea might be better done once some method of getting properties with Javascript is implemented, as MT Script might not be a great choice for such a UI overlay frame in terms of performance. Hopeful some devs have some thoughts on that.
  • UI must appear to update in real-time to be useful. Currently, frames (including the hover-stat sheet) must be reloaded manually/via macro to update their value. I would want this UI to be more dynamic, firing a refresh upon changes on selected/impersonated tokens, and perhaps other designated 'watched' tokens. I would want the experience for most people to be that the UI updating would 'just work' and wouldn't require emitting update events from other macros, for instance.
  • UI should be toggleable. A menu item or toolbar button could simply turn the UI on or off if it is affecting performance or glitching out.
  • Custom UI should be defined in Campaign properties. I wouldn't mind if a Macro or Library Token could load it or change it with macros, but I would prefer if it was core functionality in 'Campaign Properties', including special graphical assets used just for the UI.
  • Including a Frontend Javascript Library..? Making this approach compatible with front end frameworks like vuejs would be.. uh, amazing? They are very performant, cross-browser, and compact, so being able to make a VueJS app and somehow 'drop' it into a campaign as a UI would be just incredible - though I admit I have no idea how this stuff would work under the hood.
I hope I've clearly explained my thoughts here. I feel like this might be, at least in some basic version, a huge opportunity for custom UI that would set MapTool even further apart from other VTTs. I'm really excited about the idea, and am curious what others think. :)
a.k.a. Melek on Discord.
Check out my Simple 5e Framework!

Merudo
Giant
Posts: 228
Joined: Wed Jun 05, 2019 7:06 am

Re: Custom UI via an HTML Frame Overlaying Map View

Post by Merudo »

Thank you so much for sharing this! I do agree full fledged overlays would be wonderful to have in MapTool.

Currently, it is possible to some extend to have overlays by using dialog with the noframe=1 option. The main issue is that the background cannot be set to transparent. This pretty much restricts us to rectangular overlays.

Ideally I'd like to add an option to dialogs so they can be transparent, and work as flexible overlays. I tried to set it up but I couldn't get the transparency to work for WebView, the class used to display HTML by dialog5. Also, forwarding the clicks to the Swing components behind the overlay would be tricky given that dialog5 is a JavaFX component embedded in Swing.

Hopefully the feature will be easier to implement once we switch from Swing to JavaFX for our own UI.
Last edited by Merudo on Sat Mar 28, 2020 2:15 am, edited 3 times in total.

User avatar
digiacom
Cave Troll
Posts: 44
Joined: Thu Sep 27, 2018 3:00 am

Re: Custom UI via an HTML Frame Overlaying Map View

Post by digiacom »

I'm so glad the idea has some traction! Any incarnation of custom UI over the Map view would be a big feature to bring MapTool forward. Transparent borderless panels would be nearly just as good for many UI patterns, and that would be a great start!

I know websites like Google Maps sometimes use an HTML canvas element in the background of a website to display their map, then widgets similar to what I'm proposing serve as the UI.

It is a pretty huge change, but would it be possible to implement an experimental 'HTML5 Mapview' that re-implements the map view as a background in an HTML 5 frame? Then it would be pretty trivial to add more markup on top of that (in my mind).
a.k.a. Melek on Discord.
Check out my Simple 5e Framework!

Merudo
Giant
Posts: 228
Joined: Wed Jun 05, 2019 7:06 am

Re: Custom UI via an HTML Frame Overlaying Map View

Post by Merudo »

digiacom wrote:
Sat Mar 28, 2020 1:11 am
It is a pretty huge change, but would it be possible to implement an experimental 'HTML5 Mapview' that re-implements the map view as a background in an HTML 5 frame? Then it would be pretty trivial to add more markup on top of that (in my mind).
I think it would be doable through a StackPane. However, to do so we first need to switch over to JavaFX.

Merudo
Giant
Posts: 228
Joined: Wed Jun 05, 2019 7:06 am

Re: Custom UI via an HTML Frame Overlaying Map View

Post by Merudo »

I gave it more thoughts and I believe HTML 3.2 overlays are currently implementable. I opened up a Github feature request here.

The implementation details that are find tricky are:

1) how to position the overlay. It needs to be on a relative part of the map (in your example, bottom & top left corner), with an adjustable offset
2) how to manually close the overlay. The user probably needs a way to close an overlay if things go awry. Maybe some keyboard shortcut to close an overlay, or a button could should up on mouse over?

User avatar
digiacom
Cave Troll
Posts: 44
Joined: Thu Sep 27, 2018 3:00 am

Re: Custom UI via an HTML Frame Overlaying Map View

Post by digiacom »

I think all overlays should be toggleable at once from the 'Window' menu, a checkable option called something like 'Custom UI Overlays'.

Assuming a click pass-through method works, I've made a JSFiddle to demonstrate a possible positioning and offset scheme:
https://jsfiddle.net/digiacom/dvu1h4bo/

This fiddle demonstrates a possible method for registered overlays to be positioned within a single HTML overlay frame, since I think having one HTML document is easy to cache (though it may be more expensive to update unless AJAX is used), probably better performance wise, and then logic in the HTML/CSS/JS would be automatically unified in a single document.

Anyway, I'm mostly continuing this in Github from here, so anyone reading might want to pop over to the issue in Merudo's last comment :)
a.k.a. Melek on Discord.
Check out my Simple 5e Framework!

Post Reply

Return to “Feature Requests”