Page MenuHomePhabricator

RFC: Decide the interface of the <mapframe>, <maplink>, and <mapdata> tags
Closed, ResolvedPublic


We can show map as:

  • static image - server generated PNG image -- very fast to load, optimal for slow connections / low power devices (e.g. mobile phones, desktops over dial-up)
  • dynamic - downloads leaflet js lib + tiles + geojson data -- very flexible, allows zooming & panning of the map
  • link (popup) -- map is shown as an href that shows the map when clicked. We could show it center of the screen or full screen
  • maximize/restore buttons -- for static & dynamic maps, show a button to make the map full screen or shrink it back to the original size
  • data (hidden) -- data only mode, nothing is shown

The question is how many of these modes should be editor controllable, and how many should be decided by the specifics of the user browser/connection.

The current proposal is documented at the extension page.

Event Timeline

Yurik raised the priority of this task from to High.
Yurik updated the task description. (Show Details)
Yurik added subscribers: Yurik, Esanders, MaxSem, TheDJ.
Restricted Application added a subscriber: Aklapper. · View Herald Transcript
  • mode=default is a bad idea, IMO, because we might want to make the default mode configurable per-wiki, making this syntax ambiguous.
  • mode=data should not exist, using a separate tag for that is much, much more clear.

So my proposal is:

  • <embedmap> - embed a map.
  • <maplink>
  • <mapdata> or whatever

@MaxSem, I like your idea - it removes the weirdness with the plural <maps>, and removes the mode. @Esanders, I think VE map editor should show identical interface for all 3 tags, with an ability to switch between tags.

Re <maplink>: Kartographer needs to generate an <a href=somelink>sometext</a> tag. How should we generate sometext? If <maplink> contains geojson data with a pushpin marker, and the marker's icon is set to -letter or -number, we should show the autogenerated letter/number in the color of the marker. For multiple pushpins, we could either show just the first one, or show all comma separated. If there are no autogenerated markers in geojson, the editors may want to show some wiki markup as a link.

Some ideas:

  • <maplink defaulttext=""> produces [42] (the generated marker) in colors of that marker, and if there are no automarkers in geojson, it uses defaulttext attribute or the word "map" if its not set. For multiple markers, it could either show the first one or comma separated all.
  • <maplink linkprefix="" linksuffix=""> produces[42] (no spacing added)
  • <maplink text="<mapmarker>"> produces[42] This approach allows us to have extra params for mapmarker, such as showall, separator, css, etc, but having a tag inside another tag's attribute seems weird.

What exactly is the functionality of <maplink>? If these tags are distinct enough in their behaviour to have separate tags they should have separate editing interfaces.

<maplink> would replace the <maps mode=link ...> -- a clickable anchor link generated by Kartographer extension based on geojson data. On click shows a fullscreen map.

The interface between the three tags is almost identical -- it should allow editing of map center (should we show the "map center" cross?), zoom, and the extra geojson. The difference is how these tags would show on the page - as a map <mapframe>, as a link <maplink>, or as nothing at all <mapdata>. VE editor should differ between them as follows:

  • <mapframe>: edit map size and optionally specify a comma separated list of groups (|\*|[a-z]+(,[a-z]+)*) - empty or * or list of strings
  • <maplink>: edit of the link extra options as described in T125686#1997481, plus the comma separated list of groups, same as above.
  • <mapdata>: edit the group name (any string lowercase [a-z]+)

Documentation for this functionality has been updated at the extension page.

Yurik renamed this task from RFC: Decide which modes <maps> tag should support to RFC: Decide the interface of the <mapframe>, <maplink>, and <mapdata> tags.Feb 11 2016, 5:36 AM

From IRC (lots about avoiding groups functionality):

<edsanders> yurik, I'm in favour of using one tag name
<yurik> edsanders, i understand, but it will allow us much more flexibility and interface (typing) cleanliness if we use different ones. They all have somwhat different set of attributes, even though their body is the same geojson
<edsanders> yurik, there are quite a few extensions like that, extensions rarely have more than one name AFAIK other than as an alias
<edsanders> yurik, plus we'd have to write more VE code to support it :)
<yurik> edsanders, we would have to write more code to support multiple sets of attributes (modes) regardless :(
<yurik> (for modes)
<edsanders> I mean handling multiple tag names and outputting the correct one
<RoanKattouw> Normally I would support <map mode=X> in favor of <Xmap>, but mode=data seems very different
<RoanKattouw> Why is there a data-only mode? Is that so that maps can be referred to from elsewhere? Why not make all maps work that way and version them separately?
<yurik> RoanKattouw, yes, they all are fairly different -- mode=embed is a regular map, mode=link is a clickable link that pops up the map. Both can have some geojson elements drawn on top of them. But often you might want to have additional data definined elsewhere on the page, and that's where we use mode=data
<Krinkle> edsanders: yurik: Creating three new tags seems like a mistake imho
<yurik> Krinkle and RoanKattouw, i am on the fence about it also - could you review what options we have discussed in -- there is a reason behind madness :)
<Krinkle> Though if you do, at least prefix it (are dashes allowed?). map-{embed,data,link}
<RoanKattouw> So it looks like it's not really three modes at all, and mode= doesn't really feel right
<RoanKattouw> You're either defining map data, or linking to a map, or embedding a map
<Krinkle> linkprefix/linksuffix attributes are bad idea too
<Krinkle> yurik: What kind of purpose are these tags? Do they relate to providing custom geo data, or relate to picking a place on a globe and zoom level etc.
<Krinkle> If the latter, I assume all three will use the same "pick a map position" editor
<Krinkle> or input widget, rather
<yurik> RoanKattouw, all three could define data, its just that wikivoyage (as a good example) wants to define each data point separately. Scroll down a bit from
<yurik> edsanders, back to the groups question - in VE, is it possible to run through all map tags and assemble all the dataZ
<yurik> so when drawing each map, we could do the same as done by the backend to assemble groups into one structure, but also to update all maps when one of the groups changes.
<RoanKattouw> yurik: That's basically how <ref> works. It's possible but it is laborious and a bit complicated
<yurik> RoanKattouw, what part are you refering to?
<RoanKattouw> "run through all map tags and assemble the data"
<RoanKattouw> That sounds like the same thing that <references> does, right?
<RoanKattouw> yurik: Speaking of, what does the Parsoid output for this map stuff look like?
<yurik> roan, interesting, thx. Re parsoid - no idea really - it is set up on, including the parsoid's api
<RoanKattouw> Well, I ask because we don't want to add more <ref>-like code to VE
<RoanKattouw> i.e. code that requires multiple passes
<James_F> Or Parsoid.
<RoanKattouw> Ideally, the <ref>-related logic would be moved into Parsoid
<RoanKattouw> (Ideally ideally, it wouldn't be that complicated)
<yurik> RoanKattouw, so the need for "state" storage is because the map features (pushpins, highlighted areas, ...) could be defied separately from the map itself
<yurik> see wikivoyage
<yurik> RoanKattouw, they have a link for each attraction on the page, and clicking each shows the map with that specific feature in the center. But they all also show up in the map on the side of the article.
<edsanders> yurik, RoanKattouw yeah tags with look ahead / grouping are a bit evil - they stop us doing things like section editing properly.
<yurik> edsanders, agree, but we don't have any alternatives at the moment. Ideas like multiple streams per article (per Daniel) have been floating, but nothing useful yet. It would be cool to store all this data in wikidata-like storage outside of the article
<James_F> I imagine Performance would veto anything with that getting deployed.
<yurik> i'm sure we could figure out performance aspect
<yurik> its not easy, i agree, but wikidata has managed to solve performance despite storing tiny data pieces in a separate storage
<edsanders> "at the moment" well yes, but once you go with the easy solution you can pretty much never go back
<yurik> edsanders, we already are in that solution - all of wikivoyage uses their magic template to generate some magical tags that get picked up by an external database and drawn. What we are doing is a big step forward
<edsanders> yeah but changing every invocation on wikivoyage is nothing compared to
<yurik> edsanders, even though I really really don't want to do this, we could make it conditional for WV only
<yurik> edsanders, actually, i think all wikis will want this - because this way you can define a map somewhere in the middle of the article, but you can also place a link at the very top (where we currently have GPS coordinates) to popup that same map.
<edsanders> yurik, I don't think it would be worth all the effort just to avoid duplicating a pair of coords once - especially as in some cases the embedded map won't want the target in the perfect centre - so the coordinates may not be identical
<yurik> edsanders, its not just the coordinates - take a look at the link and scroll down to the "See" section.
<yurik> the link is what describes each piece of data. I know it would be great to have another storage, but "nice" and "not available" are two different things - this feature is being implemented in the worst possible way - with an external labs-based service. This is bad, and should be fixed. Once we have more storage options, we can upgrade them all
<edsanders> yurik, the markers should be in the map
<edsanders> everything else is just a link to that map
<yurik> edsanders, baby steps - we should first match what already exists - users expectations. Afterwards, we may revisit this and shift the location of the data. Otherwise we once again try to dictate how things "should be" vs "how everyone expects them to be, and how they are now"
<yurik> we cannot just introduce a new system and expect everyone to break all the processes. We should introduce something matching, and than work on converting
<edsanders> I disagree - if you build the product to match how it was hacked together in the past that makes it much harder to change it in the future
<edsanders> nor do I think wikivoyage is a massive use case one needs to tip-toe around
<edsanders> if you come up with a sensible system for and get widespread adoption, WV will follow suite
<edsanders> especially if that's the only way to get the supported editing tools
<yurik> this is also a valid point. My opinion is that it is better to have this feature, as it will be useful in a number of cases. I might agree that we don't have to support groups in VE from the start.
<edsanders> yurik, that's not my point - we shouldn't design a system that requires document-wide context to render
<edsanders> nor make bad architectural decisions based on a tiny sister project's use case
<James_F> yurik: We did it once in 2003 when we didn't know better, and wouldn't ever allow it again.
<James_F> yurik: And yes, replacing the Cite extension is on the list.
<yurik> James_F, replacing with what? do you have any other mechanism at the moment to do something that has page-wide autocounting?
<yurik> i ran it by tim, and he was totally fine with our approach
<James_F> yurik: See ext.cite.
<James_F> yurik: CSS.
<yurik> CSS does not work for complex case like maps - i need to have those pre-generated
<yurik> geojson needs to be somehow constructed on both client and server side
<yurik> edsanders|away, i think the best course of action would be to enable VE maps editor just for the <embedmap>, and the two other tags (<maplink> and <mapdata>) only enable for wikivoyage, without VE support. This way we can move forward with the new functionality, while still supporting their existing environment
<edsanders> yurik, I don't see the obsession with wikivoyage - it represents 0.01% of our potential users and the most complex edge cases
<edsanders> we should focus on the needs of the Wikipedia sites
<yurik> edsanders, unless we heed at least to some of the requests from non en-wikipedia, we will never develop them. They are a good testbed for new functionality, they are much more flexible adapting new features, and much easier to work with
<edsanders> also as soon as you deploy that feature people will never let you turn it off if it requires them to migrate their content - they'll want the old way that "just works" even if it will never have VE spport
<edsanders> yurik, they're not the only place we can develop new features - we have tons of smaller wikis
<yurik> edsanders, i am ok with not enabling the link & data on the wikipedias just yet - until we have some semblance of an agreement
<yurik> i know, but they stand to benefit the most from the maps
<yurik> (in terms of impact per visitor)
<yurik> maps and wikivoyage are highly related
<yurik> wikipedias are not map-centric
<edsanders> but there are no visitors
<yurik> so should we close them?
<edsanders> *than
<edsanders> there are orders of magnitude more people who look at and edit maps on Wikipedia the WV
<edsanders> no, but we shouldn't focus our engineering efforts around them - nor cripple our software for their benefit
<yurik> ed, they are already doing it this way. Until we can provide an alternative, let them continue doing it - it is the core of their workflow. I am totally ok to discuss better approaches
<yurik> data is our biggest problem IMO
<edsanders> yes - they can continue to use whatever hacks they are using
<yurik> and we should address it, and once that's available, it should be trivial to write a script to copy stuff
<edsanders> but don't build those hacks into the extension
<yurik> we are not ok with them using external site (even if its wmflabs) for all visitors
<yurik> its a security issue
<yurik> we do not want to allow a DEFAULT (not-user-initiated) view of a page to hit external resources
<yurik> hence we need to provide a simple workaround. Without VE, this is a trivial code that will make their live much better
<yurik> i'm ok to not develop VE support for that extra feature
<yurik> but we need to migrate them regardless
<yurik> Ed, i know it sucks in the "grand scheme of things". We do need a better unified data storage, sharable between wikis, embedable into any map. We do want auto-counting of sorts, so that each embeded feature could have its own index (reference), etc. But we don't have any of that yet.
<yurik> so we have to fix what is majorly broken now with something that is "less broken". Lets try to fix things iteratively, not one giant leap at a time that takes years
<edsanders> yurik, what data is being pulled from wmflabs at the moment
<yurik> edsanders, -- pulls all the javascript to create the map, plus pulls the data to draw the marks
<yurik> the data comes from parsing wikimarkup of the page itself
<yurik> a roundtrip
<edsanders> you can migrate that code to the local wiki if wmflabs is all you're concerned about
<yurik> edsanders, that would be harder - the code is not written to our standards, and would have to be significantly rewritten to pass the security and quality. Plus we would have to run some magical additional services and databases to do all that. Not likely.

@Esanders, thanks for posting, I just showed that log to @MaxSem. Summing up:

Feature description

Allow editors to separately specify mapdata from the map tag itself. For example, a <maplink> tags would declare the GeoJSON data for one point of interest (POI) each (a pushpin for a museum, restaurant, etc). Somewhere else on the page, a <mapframe> tag would show the map with all those pushpins assembled together.

Why it is needed

We need this to do an in-place replacement of the existing hacky and insecure implementation. All of Wikivoyage heavily relies on this functionality - see demo. The POIs are added via a custom form via the "add listing" link (next to the header) as a template invocation {{see | ... }}. Code hosted at wmflabs server aggregates all declared POIs and shows them on the embedded map. Also, the {{see}} template shows as a link with the auto-numbered icon (using CSS hack, which the server attempts to match). The link opens the map full screen directly from wmflabs. These maps violate our security and privacy policy of embedding content from non-production servers on page load without user interaction.


This functionality requires full page parse before rendering the map. Thus it is not possible for VE to draw the <mapframe> correctly until it collects the data in all of the other <map*> tags. This is very similar to the citations, where each reference is declared in place, and later drawn together at the end of the page.

Solution ideas

TBD: Would a separate "side storage" located outside of the page content help?

fwiw, i think the time is worth spent on making this work for wikivoyage. They will benefit a lot and kartographer and the maps services will benefit from a lot of feedback and improvements, which likely will be useful for wikipedia.

@Yurik – Did you mean to tag this as TechCom-RFC or do you not want their input? Right now it's just generally tagged as #RfC, which essentially is merely "needs discussion".

The whole argument for this mapdata feature is based on the requirements of WikiVoyage. While it is great they are volunteering to let use test this extensions on their wiki, and it is frustrating that they are using the wmflabs hack, maps is not a WMF priority because of WikiVoyage. Wikipedia's account for millions times more traffic than WV, and there are orders of magnitude more maps on WP pages than all of WV.

Map editing is a naturally visual task, but deploying the extension as-is would hugely hamper any efforts to make it work with VE. That is of a considerably higher priority that the requirements of a such a small sister project.


This is very similar to the citations, where each reference is declared in place, and later drawn together at the end of the page.

We just about got references and ref lists working in VE but it took a disproportionate amount of effort and code. We don't want to voluntarily put ourselves in that position again.

The cases as different too: if I need to edit the position of a map marker that needs to be done in the context of the map. <ref>s, on the other hand, can be easily edited without caring about the reflist.

Update: @Esanders and I spoke today about the potential way forward. Our tentative agreement (Ed please correct) is that if we address these issues, the deployment may proceed as planned.

  • Kartographer will remove the <mapdata>, as it implies there is a page-level data scope vs tag-level. If needed, the same functionality can be achieved with the hidden <maplink> tag.
  • For T125301, Kartographer will for now implement the <mapframe> as right-aligned (left-aligned on RTL) by default. @Esanders will suggest the best way to specify alignment with the <mapframe ...> attributes for the future version.
  • Kartographer on Wikivoyage will run under a scary™ flag, e.g. $wgKartographerWikivoyageMode = true;
  • For non-Wikivoyage, we should have an additional, wider discussion. For now, non-Wikivoyage mode will not support cross-tag data sharing, so any data defined inside one mapframe or maplink will have no affect on any other map tags.
Yurik claimed this task.

Closing this issue as we have reached a tentative agreement on the way forward. Additional features such as groups will be discussed in separate tasks.

Update: @Esanders and I spoke today about the potential way forward. Our tentative agreement (Ed please correct) is that if we address these issues, the deployment may proceed as planned.

So have they all actually been addressed or you just have a plan to address them. This reads, and I agree with, that they must be addressed *first*.

@greg, these issues were addressed for WV, but not for WP. But we are not ready for WP regardless , so we are proceeding WV only for now. WP deployment will require considerably more servers, a new static service, etc, so this is probably another one or two quarters off.

Just waiting on the wikivoyage mode flag (is there a bug for that?)