Last modified: 2014-02-12 23:38:19 UTC
Right now, there are at least four ways to mark up tours, some of which can be combined. 1. (Extension-defined only) Use messages, and rely on jqueryMsg to parse them. The problem is this only supports certain features, notably excluding things like bold and italics. I have a patch in to support wikilinks. See https://bugzilla.wikimedia.org/show_bug.cgi?id=43498 and https://bugzilla.wikimedia.org/show_bug.cgi?id=43512 . 2. Use raw HTML. E.g. the guidedtour-tour-test-test-description does this. As a message, it goes through jqueryMsg, but that just preserves the existing bold. This can also be used for on-wiki tours. 3. Use parseDescription. This does an API call to the server for each step that uses it, which is a performance hit. However, it allows on-wiki tours (which can not currently use messages) to pass in wikitext and have it parsed. 4. Use getPageAsDescription. This also does an API call to the server, which may also require a database access. It allows embedding a separate page. However, given that each step is generally short, I don't know how useful this is. We should consider trying to simplify this picture as part of improving the API (https://bugzilla.wikimedia.org/show_bug.cgi?id=43530)
I wrote parseDescription() as more a test. I felt that editors who might be more comfortable writing a feature that might be complex (video embed, for example) would probably be more familiar with Wikitext so it'd be interesting to make it available. I wrote getPageAsDescription() because I thought that it'd make sense to open the tours themselves (without opening the javascript hardware which needs to be locked behind a higher access control) to the community at large to allow them to be improved. This way we adopt the same security protocol that has already been put in mediawiki itself. I believe that getPageAsDescription() while it generates a HTTP request to the server probably might be more efficient than parseDescription() in the long run since the parser cache should probably cache it avoiding the need of the parser to be triggered. We should probably thinking of migrating the guided tour to Ori's JSON schema or something. It's awfully close. Right now it has to be javascript because we don't know what sort of auto-advance/etc. that our guided tours will actually have. Once a library of common use cases are made, we could abstract this into a javascript generator and allow the tours to be created in JSON schema without allowing arbitrary javascript injection (and thus the need to protect the tours namespace).
