Development

Introduction

A large amount of RopeWiki development is accessible to users without any special permissions because it is done through MediaWiki and SemanticMediaWiki content. This page attempts to make the development process more accessible.

How RopeWiki works

RopeWiki is a set of software and data running on some servers in the cloud. When you navigate to ropewiki.com, your computer connects to one of the RopeWiki servers and asks it for a web page. The RopeWiki server is running a copy of MediaWiki, which is a program that serves web pages for wiki sites and was created as the basis of Wikipedia. To add additional functionality beyond the basic MediaWiki capabilities, there are also a number of "extensions" installed which are small pieces of software that work within MediaWiki to provide additional features -- the list of installed extensions can be found here. When the RopeWiki MediaWiki program receives a request for a web page, it retrieves the current version of the wikitext for the requested page and renders it into HTML, using appropriate extensions when necessary. The resulting HTML is sent back to your computer where your browser displays the HTML to you as the webpage you see.

Templates

Overview

Whenever you see double braces in wikitext, a "template" is being called. Instead of displaying the double-braced content on the page, the MediaWiki wikitext rendering engine will replace the double-braced content with the content generated by the template. The first word following the opening double braces is the name of the template. For instance, the wikitext below is referring to the "Condition" template:

{{Condition
|ReportedBy=Willie92708
|Location=Seven Teacups
|Date=2019/10/13
|Quality condition=5 - Amazing
|Water condition=5 - Moderate (class C1 = a4)
|Wetsuit condition=3 - Full wetsuit (5mm-6mm)
|Difficulty condition=2 - Normal
|Team time=6.5
|Team size=2
|Comments=Water level was right at the arch.  Water temp is definitely dropping, and combined with cooler air, made for a chilly trip.  I used a 2 piece full-body wetsuit with hood, 5mm socks and 5mm gloves and that was barely enough.  Maybe that's why we had the whole place to ourselves all day!  We also spent a lot of time just basking in the Sun to stay warm.


The toilet bowl hydraulic is easy enough to exit (without pack) on the surface, but it seems like the current no longer circulate like it did in the past.  Instead the current flows radially out from the falls on the surface, instead of circulating counter-clockwise.  Maybe more rock and or sediment has changed the pothole bottom.  BTW, the washing machine is working well (see pic)
|FileList=FILE-20191015164900.jpg,
}}

Everything following each | character is a "parameter" to the template (some people may also call these "arguments") -- basically, information that the template might need to know in order to display properly. In the case above, the "ReportedBy" parameter has the value "Willie92708", the "Quality condition" parameter has the value "5 - Amazing", etc. To see the actual template, navigate to ropewiki.com/Template:<name of template> -- in this case, http://ropewiki.com/Template:Condition The rendered page should display documentation on how to use the template, although many do not have the level of documentation needed to use the template. If you have to figure out yourself how a template works because its documentation is lacking, it would be greatly appreciated if you could improve the documentation for others as you learn what it does! To see the "code" of the template, you must edit it or view its source. The documentation should be in a noinclude tag, and the code should be in an includeonly tag. The code in many templates looks completely unapproachable and indeed, MediaWiki templates are right up there with regular expressions in terms of readability difficulty. But, the basic rules are fairly simple and applying them repeatedly should reveal what the template is doing.

Template rules

For a more detailed description of templates, please see the MediaWiki documentation. Note that we only want to use named parameters, not numbered or ordered parameters.

Any content inside the includeonly tag should be rendered ("transcluded") in the page

Try out a simple example to see what this means:

1. Go to http://ropewiki.com/Template:TestTemplate
2. If this page does not yet exist:
   1. Look near the upper right for a button that says "Create with form" and click it
   2. Next to "Output format" near the bottom, select "Plain text"
   3. Click Save page
   4. You've now created a template named TestTemplate
3. Click Edit in the upper right to edit the template
4. In between the opening and closing "includeonly" tags, add the text "Hello world"
5. Save the template page
6. Go to http://ropewiki.com/Test
7. Edit the page (or create it if it doesn't exist)
8. Replace any existing content with the content below and save the page:

The template TestTemplate says "{{TestTemplate}}"

Note that the page should show The template TestTemplate says "Hello world". This is because, when rendering the Test page, MediaWiki first rendered the TestTemplate template's content (which turned out to be "Hello world") and replaced the TestTemplate content in double braces with "Hello world".

Named parameters in triple braces are replaced with the value for that named parameter

For instance, if a template was called with:

{{MyTemplate|MyParameter1=Foo bar}}

...and the content of MyTemplate in between the includeonly tags were

The value is {{{MyParameter1}}}.

...then the template, as called, would render as The value is Foo bar.. If you see a | character when referring to a triple-braced parameter, the value following the | character is what value will be used if the parameter is not specified. For instance:

{{MyTemplate}}

...with the content of MyTemplate between the includeonly tags beign

The value is {{MyParameter1|not specified}}.

...then the template, as called, would render as The value is note specified.

Templates and parser functions are rendered exactly as they would be on a normal page

(Parser functions are like templates, but are defined in extensions rather than template pages, and their names are preceded with a # character, like {{#vardefine:MyVariable|My value}}).

This means that template content can reference other templates' content, and so on.

Example: Show most recent condition report

Users often miss the fact that condition reports exist when they are linked in the infobox on the right -- we want to try out putting a condition report right in the body content to see if that raises awareness. We'll use this as a practical example of working with templates: we want to make our own template that will show the most recent condition report for a particular page.

To start out, we'll get as close as we can to the content we want and then see how that content was generated. If we visit Seven Teacups and click on the condition report link, we'll get something like Conditions:Seven_Teacups-20191015164836 which has exactly what we want as the first row under "Reported Conditions". When we edit that page, we'll see that it calls the Condition template with some parameters. So, we'll go to the Condition template and edit it to see its code. Holy Moses, that's a lot of unreadable code, right? It's ok; we can break it down. Make sure you're looking at a rendered condition report along side the code. Note that the thing we want is just under the heading "Reported conditions", so let's search for "reported conditions" in the code. We find it in this snippet:

{{#ifeq:{{#urlget:action}}|render||=Reported conditions=
{{DisplayConditions|Page={{{Location|}}}}} }}
{{#semanticdependent:{{{Location|}}}}}
[[Category:Conditions]]
 
</includeonly>

The text we're looking for is inside the #ifeq directive. That's a parser function and using the documentation, we can read that line as "if {{#urlget:action}} = render, then render nothing. Otherwise, render =Reported conditions= {{DisplayConditions|Page={{{Location|}}}}}". If we count opening and closing braces, we'll see that the braces for the #ifeq directive are closed before we get to #semanticdependent.

The next question is what that #urlget thing is doing. I don't know, so let's search for mediawiki urlget. The first page is the best answer and it tells us that it gives us the value of any URL parameters. That means we would see this evaluate to "render" if the user navigated to, e.g., http://ropewiki.com/index.php?title=Conditions:Seven_Teacups-20191015164836&action=render If we look at our address bar, we see there's no "action=render" in the URL, so the DisplayConditions template is being rendered to get the content we want. To double-check ourselves here, let's see what the DisplayConditions template does when we provide it with the parameters we think it's getting eventually inside of our demo page. Go to a test page where you can add arbitrary content, and replace all content with this:

{{DisplayConditions|Page=Seven Teacups}}

...then either save the page or (pro tip) just click Show preview to render that wikitext. Great, this is what we want (plus all the other condition reports). So, now we need to investigate the DisplayConditions template. Here is the content in the includeonly tags:

{{#ask: [[Category:Conditions]]{{#if:{{{Page|}}}|[[Has condition location::{{{Page|}}}]]|}}
|?Has condition date=Date
|?Has condition quality=Quality
|?Has condition water=Waterflow
|?Has condition wetsuit=Wetsuit
|?Has condition difficulty=Difficulty
|?Has condition time=Time
|?Has team size=Size
|?Has team min experience=Min
|?Has team max experience=Max
|?Has reported by
|?Has condition comments
|?Has condition url
|?Has condition questionable
|?Has reported by url
|format=template
|template=DisplayConditionsLine
|introtemplate=DisplayConditionsHeader
|outrotemplate=DisplayConditionsFooter
|sort=Has condition date
|order=descending
|limit=15
|link=none
}}

That is a SMW query. We could investigate exactly how it works, but really the only difference we want is to display just one result instead of a bunch. So, let's add another parameter to the template which defaults to 15 to maintain backwards compatibility (have the template behave exactly the same if this new parameter isn't specified) and make sure to document it -- see here for changes. Once you have saved a change to a Template, it is very important to refresh a page that uses that template to make sure it still works since that template is likely used to display a large number of pages. In this case refreshing our reference page should let us double check. The expected behavior is for nothing to have changed. Now, to test our new feature, we want to replace the content in our test page with

{{DisplayConditions|Page=Seven Teacups|Count=1}}

Note again that we can just click Show preview to render this code (we don't have to save the page), but we do have to save the template page before trying this. The results look good, so we can insert this code in the desired page to print out the most recent condition report in its body. But, one more optimization we can make is that we don't want to have to manually update the Page parameter for each different page -- instead, we can use the magic word "{{PAGENAME}}" to make some code that can be copy-pasted to any canyon page and just work:

{{DisplayConditions|Page={{PAGENAME}}|Count=1}}

Scripting infrastructure

While most core RopeWiki functionality does not rely on Javascript, a large amount of functionality primarily added by Luca does rely on Javascript extensively. Development on this Javascript can be very difficult.

We have moved development of MediaWiki:Common.js to a dedicated GitHub repo so that development will be done on a local machine and only the "rendered" minified Javascript will be published on the Common.js page. Eventually, we want to work to minimize this Javascript codebase by moving the necessary Javascript into a custom MediaWiki extension.

Searching

Common.js is not the only Javascript on the site, however, and the standard MediaWiki search functionality does not return all instances of a desired search term. Currently, the most effective known method to perform a search on all RopeWiki page-based infrastructure is to download the entire current content of the Template and MediaWiki namespaces. This can be accomplished as follows:

1. Get a list of all pages in the desired namespace from Special:Allpages
2. Copy that list into a text editor and replace spaces with line breaks so that you have a page name per line
3. Export the content of all those pages using Special:Export
   1. Paste the name-per-line list of pages into the big text box
   2. Check the "Include only the current version" box
   3. Check the "Include templates" box
   4. Check the "Save as file" box

The result will be an XML file whose format should be fairly intuitive, and will contain the full text of all requested pages.