Moving from MediaWiki to SharePoint O365 - part 3

Now that you have the scripts in place, how do you make use of them?

Redirect

This one is simple. Write #REDIRECT[[pagename]] like you're used to doing it in MediaWiki. Just take care that you write it exactly as I did: in uppercase, without a space between # and REDIRECT or between REDIRECT and [[. My script is not dummy-proofed like MediaWiki is.

Math and source code

As we're making use of third party scripts (MathJax and SyntaxHighlighter), you should refer to the corresponding websites for documentation. In short, you can do the following:
For inline math, use the delimiters \​​( to start and \​​) to end your math, eg \(a \ne 0\)​.​ For display equations you can use either a double dollar sign to start and end your math ​($​$)​ or use \​[ to start and \​​] to end, eg

$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$​​

If you're wondering about the syntax being used, then you haven't used math on your MediaWiki website either. In that case, here's a basic tutorial and here's a bunch of additional samples to get you started.


For source code, put your code in a pre-block and give it the appropriate class to call the corresponding brush for the language of your code, e.g. js for JavaScript. If you have something with < or > (like HTML or XML), you need to use the <script> tag and a ![CDATA[ escape. More information on the SyntaxHighlighter website.

1
2
3
4
5
6
<pre class="brush: js;">​
function helloSyntaxHighlighter()
{
 return 'hi!';
}
</pre>


Templates

Templates are not as powerful as they are on MediaWiki. Most important to understand is that my script does not handle chaining of templates (i.e. calling a template from within a template). No doubt that's perfectly possible, but for now I can make do without it, and so I haven't put it in. If anybody out there improves on the code to make it possible, please share it back to me!

Calling a template works the same way as on MediaWiki: use double curly brackets.
{{templateName}} will include the page with name template_templateName.aspx 
{{templateName
|var1 = variable 1
|var2 = some other variable
}}
will include the page with name template_templateName.aspx and pass it the variables mentioned. The template page can display them with {{{var1}}} and {{{var2}}} as named variables, or {{{1}}} and {{{2}}} in the order as they are mentioned on the calling page.
On the template page you can include a default value like {{{var1|default value}}}. An empty default value is rendered correctly, just do {{{var1|}}}. If you do not specify a default value, the name of the variable will be used as default.

I'm using the template_templateName as filename as naming convention, seeing there's no namespaces in SharePoint wikis (that I'm aware of). That doesn't mean you can only include pages prefixed with template_! You can include any page (eg {{pageName}}), but the script will always first look for template_pageName.aspx and only if it can't find that as a page will it try pageName.aspx itself.

Because there's no decent way to put functionality in a template like with the ParserFunctions on MediaWiki, and you might want your template to be more powerful, I've added some hooks. For a template called aaa and stored on a page with name template_aaa.aspx, you can create a script like shown below, call it template_aaa.js and upload it to the Documents library. 


 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
function template_aaa_preprocessor(templateContent, variables){
    /* Do your template specific logic here by updating the string 'templateContent'.
     * The variables given by the template caller are available in 'variables' as variables['variableName']
     * At this point, the string templateContent holds the raw code of your template. 
     * Variables like {{{variableName}}} have not yet been replaced.
     */
     
    //...
     
    //ALWAYS return the result, even if you didn't use this function or do anything with it
    return templateContent;
}
 
function template_aaa_postprocessor(templateContent, variables){
    /* Do your template specific logic here by updating the string 'templateContent'.
     * The variables given by the template caller are available in 'variables' as variables['variableName']
     * At this point, the string templateContent holds the updated code of your template, with variables 
     * like {{{variableName}}} replaced by their given value or default value and any other changes made by 
     * your preprocessor.
     */
     
    //...
     
    //ALWAYS return the result, even if you didn't use this function or do anything with it
    return templateContent;
}
 
//include the below line for better debugging in Google Chrome
//@ sourceURL=https://yourInstallation.sharepoint.com/sites/yourSitenumber/Shared%20Documents/template_aaa.js


In these functions, you have all the power of JavaScript and jQuery at your fingertips. There is little you and your users will not be able to do. Assuming they know their way around JavaScript.
Important: if you make a template-specific script, always have both functions present, even if you're only using one of them.


One more extra thrown in for good measure: you remember the <noinclude></noinlude> tags from MediaWiki, right? They allow you to put content on a page which will not be included when the page is called as a template. Very handy place to put your template documentation: if you look at the template page itself, you'll see it, if you call the template from another page, it won't be included.
Of course, SharePoint does not allow you to put a <noinlude> tag in your content. It will helpfully strip that out for you. The bastard.
So my script allows you to use {noinclude} and {\noinclude} instead.


Next up

So, now that we've gotten some functionality upgrades in SharePoint O365, we can (finally) get started on moving our MediaWiki content over. That will be happening with a number of PHP scripts and some PowerShell.