Skip to content

Latest commit

 

History

History
57 lines (38 loc) · 5.29 KB

ConvertingToResourceLoader.org

File metadata and controls

57 lines (38 loc) · 5.29 KB

== How to adapt current CSS and JS to MediaWiki’s ResourceLoader ==

In the years since WikiPathways was set up, MediaWiki has created some good tools for managing CSS and JS assets. There are documents like [https://www.mediawiki.org/wiki/ResourceLoader/Migration_guide_for_extension_developers the migration guide for extension developers] and [https://www.mediawiki.org/wiki/ResourceLoader/Writing_a_MobileFrontend_friendly_ResourceLoader_module the instructions for writing a MobileFrontend-friendly ResourceLoader module] in addition to the [https://www.mediawiki.org/wiki/ResourceLoader top-level ResourceLoader page on MediaWiki.org] that be essential resources.

This document does not replace the above resources, but it walks through the work I did to adapt the AuthorInfo pieces into MediaWiki 1.29 for the 2017 work I did on the WikiPathways upgrade.

=== AuthorInfo: what it does ===

AuthorInfo is what WikiPathways uses to present the most relevant authors to people who are browsing pathways on the site. It also provides a [https://www.mediawiki.org/wiki/Manual:Tag_extensions tag parser] that exposes the feature so that it can be used in wikitext.

Initially, [https://github.com/wikipathways/wikipathways.org/blob/master/wpi/extensions/AuthorInfo/AuthorInfo.php AuthorInfo.php] was a monolithic php file containing all of the logic, CSS and Javascript to implement this feature.

=== Modernisation ===

I decided to make it part of a new GPML extension that I created to manage to the display of doc/GPMLContentHandler.mediawiki|pages containing pathway information.

I broke the Javascript and CSS into two files: [https://github.com/wikipathways/mediawiki-extensions-WikiPathways-GPML/blob/da7f215b6463bef98ecd74b8fc17418964567f62/modules/AuthorInfo.css Author.css] and [https://github.com/wikipathways/mediawiki-extensions-WikiPathways-GPML/blob/da7f215b6463bef98ecd74b8fc17418964567f62/modules/AuthorInfo.js Author.js].

To load these files, I added a section to [https://github.com/wikipathways/mediawiki-extensions-WikiPathways-GPML/blob/da7f215b6463bef98ecd74b8fc17418964567f62/extension.json#L49 GPML’s extension.json] that specified their location and a module name (“wpi.AuthorInfo”) that can be included via <tt>[https://doc.wikimedia.org/mediawiki-core/master/php/classParserOutput.html#acd540e0cc85127e4159668a96853811c ParserOutput::addModules()]<tt>: <source lang=”php”> $output->addModules( [ “wpi.AuthorInfo” ] ); </source>

Finally, to avoid hard-coding HTML into the PHP code (where it can be very difficult to modify) I’ve put the div for displaying this into a message that is described in the next section.

=== ResourceLoader and Localisation (ab)use ===

In the new release of WikiPathways, because ResourceLoader is used, the javascript that provides AuthorInfo is loaded in the <tt>&lt;head></tt> instead of embedded in the HTML body. Previously, WikiPathways used a JS call like the following embedded in a <tt>&lt;script></tt> tag: <source lang=”javascript”> AuthorInfo.init(‘authorInfoContainer’, ‘14229’, ‘4’, ”); </source>

This is replaced with [https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes data attributes] on an <tt>&lt;div></tt> element: <source lang=”html”> <div id=”authorInfoContainer” data-pageid=”14229” data-limit=”4” data-showbots=”“></div> </source>

The JQuery [https://api.jquery.com/ready/ <code>$(document).ready()</code>] is used [https://github.com/wikipathways/mediawiki-extensions-WikiPathways-GPML/blob/da7f215b6463bef98ecd74b8fc17418964567f62/modules/AuthorInfo.js#L1 in the <tt>wpi.AuthorInfo</tt> module] to find this <tt>&lt;div></tt> and populate it: <source lang=”javascript”> $(document).ready(function() {AuthorInfo.init(“authorInfoContainer”);}); </source>

Since the Pathway namespace is handled by the GPML content handler, it uses [https://www.mediawiki.org/wiki/Localisation MediaWiki’s Localisation system] to handle the HTML structure (where appropriate) that is sent to the browser. To find the right message to modify, add “<code>?uselang=qqx</code>” to the url being displayed. For example, doing this on “[http://vm1.wikipathways.org/Pathway:WP2586?uselang=qqx Aryl Hydrocarbon Receptor (Homo Sapiens)]” shows <pre> (wp-gpml-authorinfo: 33306, 5, ) </pre> as the first item on the page. This shows you that three parameters (“33306”, “5”, and “”) are passed to the the MediaWiki message <tt>wp-gpml-authorinfo</tt> which you can [http://vm1.wikipathways.org/index.php?title=MediaWiki:Wp-gpml-authorinfo&action=edit edit on the wiki]. (All links are to the dev server vm1 here.)

Parameters of the message are identified by location. So, for the first parameter, <tt>$1</tt> is used; for the second, <tt>$2</tt is used; and so on.

To get the HTML element with the data attributes descirbe above, this message currently contains <source lang=”html> <div id=’authorInfoContainer’ data-pageId=’$1’ data-limit=’$2’ data-showBots=’$3’></div> </source>

Note that ResourceLoader works asynchronously, so, to avoid a “[https://en.wikipedia.org/wiki/Flash_of_unstyled_content flash of unstyled content]”, I’ve left some styling on the elements themselves. All HTML or other directly displayed text has been moved into [https://www.mediawiki.org/wiki/Localisation MediaWiki’s Localisation system] which makes them available for editing on-wiki by people with appropriate permissions.