Gadget kitchen/January 2012 training

Gadget tutorial Brion practicing 19 Jan 2012 These notes are very messy and will be cleaned up in time for the 21 January hackathon tutorials.

You can customize the software to do what you want. MW is FLOSS but runs on a server so you can't change it directly MW is two programs You can modify that!! Think like, Greasemonkey extension for Firefox. That extension lets you write clientside JavaScript which will be loaded after the website finishes loading, thus allowing you to alter it. But you don't need browser additions to add JavaScript customizations because we have provided a facility in MediaWiki itself for you to plug things in. User scripts and Gadgets!
 * serverside in PHP
 * clientside in HTML/JS

mediawiki.org has a page on User Scripts - http://www.mediawiki.org/wiki/Gadget_kitchen

Gadget Kitchen intro page for gadgets DEFINITIONS: A gadget is shared among multiple users. Obvious example: built-in. https://www.mediawiki.org/wiki/Gadget_kitchen pull up mediawiki:tutorial-quickrc.js http://www.mediawiki.org/wiki/MediaWiki:Tutorial-QuickRC.js This is a tutorial user script that has been sitting around for a while. Question: scope of where US go. Some US runs automatically for logged in users. Brion should have mentioned SiteJS Three ways to insert additional JavaScript into sys from user end of things. 1) Admin of the site can edit common.js page. MediaWiki:Common.js Affects everyone. Restricted as to who can edit it. Example: sidebar ... a lot of ime, extra tools in here and extra tabs are because of common.js. 2) Gadgets are selectable as user preferences, have to be created by admins though. 3) User JavaScript : just for yourself. Sometimes 1 and 2 will get prototyped as 3. Explain here that all these things are just executing JavaScript on the client side. All ways of doing the same thing. Question: Can I write a gadget and make that run, on my wiki, for anon logged in users? yes, but it is not as simple as it should be. You have to include the code for that gadget in the global site JS.  But Gadgets is being rewritten. /////// Those need screeeshots :p  ////// Log in to mediawiki.org create a user account Go to your preferences click the Gadgets tab Let's turn on Code Editor, which Brion wrote. Now, go to Appearance tab in preferences Shared CSS/JS for all skins, click the link for Custom JavaScript. Now you are editing User:You/common.js This is just a wiki page like any other. We turned on code editor gadget, so we have line numbers, syntax highlighting. LET'S PROVIDE A SAMPLE THING TO TYPE IN. alert("Hello world"); or change title or background color just hit save and then that thing would happen. we have jQuery! Brion to provide jQuery/JS to type in (sample) In Gadget Kitchen, do these steps: https://www.mediawiki.org/wiki/Gadget_kitchen#I_want_to_try.21 We still have the border on the page. Refresh. Border is gone. Sample code adds a link to the toolbox section on sidebar. Click it and it pops up dialog box with list of recently changed pages. Does several things: adds to UI, makes interactive, uses MediaWiki REST API. Shows several things! mw.loader.using these functions are what MW itself uses and you can use them too. anything in mw.* namespace should be reliable for future versions. Now, tells our JS module system, have you loaded jquery.ui.dialog plugin to make dialogs. please load it. to find out what modules are available, there may not be a good list. point to web viewable browsable sourcecode resources.php in the resources directory within phase3 dir within trunk DKinzler: would be awesome if mw.* would be self-descriptive. mw.help .... or documentation! Look on Gadget Kitchen docs page, and on mediawiki page for ResourceLoader. Also look at web service API documentations. Hope you like closures! You're gonna use them a lot! list of modules to load, function to run when it's loaded. You don't have to worry about module load order. We have straightforward code in here - jQuery, jqueryui dialog plugin, tell it string & size, contents, it makes a dialog. jQuery.getJSON loads things from our web api standard jQuery functions for doing http fetch of JSON data we use a little mw.util function called wikiscript that gives us location of API endpoint (there are easier ways to do this in 1.19 coming up that encapsulate API access stuff.) MW 1.19 will be out in March probably some parameters function returns yr data go through that, build some stuff. now, look at web API help start with https://www.mediawiki.org/wiki/API:Main_page then: https://en.wikipedia.org/w/api.php gives you all the modules, parameters, sample links. Also the query sandbox: https://en.wikipedia.org/wiki/Special:ApiSandbox Tells you what an API call would look like. Idea: query, fetch all pages. Hit Make Request button. This is the JSON we get back. (Coded by Max Semenik) "I wanna do some query that pulls this data, not sure how to do it." At the end here is our ready function. jQuery's .ready waits to do stuff until the page is fully initialized. THEN go through and add links. utility function: mw.util.addPortletLink kind of cryptic, but documented (hopefully) over on ResourceLoader/Default modules (Doesn't tell you which portals exist). TODO: improve Default modules docs. Standard jQuery code at the end of the new common.js ... add an event that calls our code. Ideas for exercises: More elaborate: try to localise this! (idea: localise? because what about cross-loading JS?  too advanced for this) change the query re the sidebar popup. Make it a tab! Stephen: looks at custom JS. How do I make a tab? Look in the default modules. AddPortletLink. On line 75 of common.js. addPortletLink call - changed destination parameter -- Change from the toolbar (p-tb) to a tab (p.cactions) Hit Save. "quick changelog" now shows up in dropdown near the searchbox. Use Firebug! or dev tools in chrome or safari. now let's try p-views. hit Save and now it is a tab near the Edit etc. Exercise idea: Can we add another web API call? Page history of the page you're on. Back to API sandbox. format=json is what you always want. action=query prop=revisions rvprop = comment titles=Main Page     ## example So let's go back to our code in common.js change the query we make line 47, 'prop': 'revisions'; rvprop is comment 'titles': mw.config.get('wgPageName'); ### should be documented somewhere in here. separate plurals by vertical bar If you have a JS console like firebug, run the little snippets! instead of query=recentchanges, we now have query=changes (change line 54 as well) array is indexed by pageid,so you need to find the pageid to get the other ones. Next: Show how to turn this into a gadget look at Special:Gadgets page this is a list of gadgets. Look at definitions. Anyone can see this page. You have to be an admin to edit it. On our wikis, you have to be an admin to edit this. There is a defn file that is a little list. You can define mult sections. Each line is a single item. example: CodeEditor. Name, compat with RL, needs to load this module, and then actual page file. Go to Gadget-Codeeditor.js loads it from Toolserver where actual code lives. To turn your US into a gadget: you find admins, say you want to set something up as a gadget. They can copy your gadget into a gadget definition. What's the protocol for turning my US into an en.wp gadget? look at https://en.wikipedia.org/wiki/Wikipedia:Gadget "Proposal" is active, "Evaluation" is not. Tell Sumana so she can help you move forward in the process. Should we make suggestions for stuff they could hack on? Do more typing, less copy-pasting! Take the basic bits in part by part. include the reference link though
 * A user script just belongs to you as a user
 * We let you do anything you want.
 * Anything you can do in JS
 * No security concerns. Only runs as you.
 * No one else automatically gets that script.
 * "you can XSS yourself"
 * Pull up the Gadget Kitchen page*
 * Ask Roan outside this room about future of gadgets, will make certain things easier.
 * TODO: Brion to pretest this particular change.