Servers Build a MediaWiki
Jamie Munro shows you how to make the most of your MediaWiki site with semantic extensions, which we won’t argue over.
Jamie Munro reveals how to make the most of your MediaWiki site with a semantic extension turbo boost. Give it some welly!
Wikis can be powerful tools, but with great power comes the responsibility for the unholy, unstructured mess your users will inevitably create. This is especially true if, as is often the case, your wiki will contain pages that share a common information structure and should be displayed in a similar structure.
If you ask 10 people to create a wiki page about a Linux distribution of their choice, chances are you’ll end up with 10 different variations containing information that’s relevant and 10 different ways of displaying it. If you also wanted to have a separate summary 10 distributions, and details of release version numbers then you would need to maintain a separate table, or page, and manually append new distributions as they’re added to your wiki. This isn’t the ideal situation because many users may forget or simply not know about the summary. Luckily, there are some excellent MediaWiki extensions available which can help.
This tutorial will show you how to use the Semantic MediaWiki, Page Forms and Semantic Results Format extensions to impose a degree of structure to wiki pages and make useful content more versatile by building the basic outline of a wiki to track Linux distributions. By the end you’ll have a set of properties, templates and forms that can be used to capture, and present information about distributions and their releases in a consistent way. We’ll also show you how to write simple queries that can be used on pages directly or embedded into templates to display a summary of distributions and their releases, a timeline of a distribution’s releases and a bar graph showing the number of downloads by release.
Get your wiki on
For this tutorial you’ll need to have MediaWiki installed and have the appropriate level of access to a terminal session (following the usual lecture from your friendly neighbourhood system administrator) on the server running MediWiki.
Composer is generally the preferred method to install extensions in MediaWiki. You may need to install Composer from your distribution’s repositories or by following the instructions at https://getcomposer.org/download.
Before installing any extensions you’ll need to know where your base MediaWiki directory is located. If you’re not sure where it is, find it by searching for the LocalSettings.php file, which contains all of your key MediaWiki configuration settings (and which we’ll need to edit later on). $ sudo find / -name LocalSettings.php /var/www/html/LocalSettings.php
To install the Semantic MediaWiki extension open a terminal, navigate to the directory where you found LocalSettings.php and type (replacing “~2.5.4” with the latest version):
$ --update-no-devcomposer require mediawiki/semantic-media-wiki “~2.5.4” Composer will download and install a number of dependencies and finally the Semantic MediaWiki extension. From the same base directory run the MediaWiki maintenance script: $ php maintenance/update.php
This will check and initialise the database tables. If you don’t have access to the terminal then you can run this script from the special page: www.your-wiki.com/Special:SemanticMediaWiki. Finally, you’ll need to enable semantic processing on your wiki by editing your LocalSettings.php file and add the following lines to the end of the file, replacing www.your-wiki.com with the domain name of your wiki: $ sudo nano LocalSettings.php enableSemantics( ‘www.your-wiki.com’ );
The Semantic Results Format extension isn’t needed to start using Semantic properties and queries on your wiki, but it does provide a number of ways to show the results of your queries. These include mathematical operations such as average, sum and product as well as tag clouds, pie charts and timelines. Again, Composer is the best way to install the extension, replacing “2.5.2” with the latest version: $ composer require mediawiki/semantic-result-formats “2.5.2” The Page Forms extension provides user-friendly forms to prompt users for template parameters. The developers suggest that Composer can be used to install the extension but it’s not recommended. To manually install Page Forms you need to download (or clone from git) the latest version of it and extract it to the extensions sub-directory in your base MediaWiki directory. To enable the extension you’ll need to edit LocalSettings.php and at the bottom of the file add the following lines: #Enable the Page Forms extension wfLoadExtension( ‘PageForms’ ); To check if the extensions have been installed properly and enabled you can browse to http://www.your-wiki.com/Special:Version and you should be able to see all three listed along with the correct version numbers.
And to business!
Before creating anything else in MediaWiki it’s important to give some thought to how information about Linux distributions might be modelled. Cats being skinned is a gruesome metaphor, but apparently there are many ways to do it. There are as many, albeit slightly less-gruesome ways you could structure information about Linux distributions and you need to consider whether you wish to capture things as pages, categories or properties embedded on a particular page. For this example we’ll have a page for each distribution and a page for each release. We’ll then use a property to link each release to its distribution. We’ll also have a property that enables one distribution page to be linked to another distribution page to indicate lineage. For each release we’ll also capture details of version numbers, release and end of life dates, the number of downloads.
We’ll also include a property to link releases to multiple pages for default software packages. For now we’ll capture the creators of distributions as simple text properties on each distribution, although there’s obviously a strong case for creating these as separate wiki pages, to capture more detail about each creator – in which case you’d need an additional template, form and category. The world is a rabbit hole, and how far you choose to take your wiki down that rabbit hole is entirely up to you.
What’s my properties?!
Properties provide the semantic glue that will hold your wiki pages together and are the first thing we need to create. Properties enable you to easily create, and interact with something akin to a field. Properties are stored in the Property namespace and, like fields, can be defined as specific types, for example, dates, numbers, text and pages.
To create a property browse to www.your-wiki.com/Special:CreateProperty, type in the name of the property, Has Distribution and select page for the type. Do the same
for each of the following properties: Has Version (Text), Has Release Date (Date), Has End Date (Date), Has Downloads (Number), Has Default Packages (Page), Based On (Page) and Created By (Text). You can see a full list of properties at www.your-wiki.com/Special:Properties or, to see or edit a specific property you can browse directly to it, for example www.your-wiki.com/Property:Has_Distribution. It’s possible to use these new properties directly in your wiki pages by simply adding them into any page as [[Has Distribution::Ubuntu]]. However, this relies on a robust knowledge of the structure and content of the wiki.
<insert template here>
Templates are part of MediaWiki and can be used to provide consistency across a wiki. They also help to make a wiki more manageable, by enabling you to edit a single template to update any instances of that template. Templates make it possible for you to group sets of properties together and provide a canvas to control how those properties are displayed on a page.
The next step is to create two templates: one for distribution and one for release. The easiest way to get started is to use the special page provided by the Page Forms extension for creating templates. This will generate the full template with all the necessary syntactic elements. To make changes to a template later you’ll need to edit the template manually by browsing to the full list of templates at www. your-wiki.com:Special:Templates or directly to a specific template: www.your-wiki.com/Template:Release.
The Release template will be the simpler of the two templates and will have several fields used to display the values collected from the related Release form.
Browse to www.your-wiki.com/Special:SpecialPages and then scroll down to www.your-wiki.com/Special:CreateTemplate. Complete the fields for the Release template as follows: Template Name: ‘Release’ Category defined by template (optional): ‘Releases’
Populate the field names, display labels and associated Semantic properties for each of the following, noting that Packages is the only field that holds a list of values: • field_Distribution, Distribution, Has Distribution • field_Version, Version, Has Version • field_Release_Date, Release Date, Has Release Date • field_End _Date, End Date, Has End Date • field_Downloads, Downloads, Has Downloads • field_Packages, Packages, Has Default Packages Leave aggregation blank. Select ‘Table’ as the output format and save the page. The Distribution template will be more complex and will include a few queries to dynamically display the number of total downloads of related releases as a number and a bar chart, a table of all related releases and a timeline showing their support periods. Create the template in the same way you created the Release template with the following values: Template Name: ‘Distribution’ Category defined by template (optional): ‘Distributions’
Populate the field names, display labels and associated Semantic properties for each of the following, noting that Packages is the only field that holds a list of values: • field_Distribution, Distribution, Has Distributions • field_Version, Version, Has Version Again, select table as the output format, leave the aggregation properties blank and save the page. We’ll add some queries to the template later.
Filling in Forms
The Page Forms extension provides you with a number of form components that you can group together and pass their values to a specified template as parameters. This means that each distribution and release page is more likely to be consistent, because as every user is prompted to provide the same information.
Browse to www.your-wiki.com/Special:CreateForm and type in Release for the form name. Select the Release template from the Add elements section and click Add. This will automatically pull in the fields from the chosen template and give you a choice of input type for each field. Change the date fields from the date (default) input type to datepicker and you’ll need to edit each of the Form labels to display as you’d like the user to see them (for example, change Field_ Distribution to Distribution).
Each field also has a section for ‘other parameters’, which includes settings for making a field mandatory or for limiting autocompletion to a particular namespace or category. Expand this section for the Distribution field and type Distributions into the Values from category. Save the page. Then create a form for Distributions. This is a smaller form with only two fields and other than renaming the Form labels, there’s no need to set any other parameters.
Falling into Categories
The Page Forms extension also gives you a page to create Categories and link them to a form. Browse to www.your-wiki. com/Special:CreateCategory and enter Releases for the category name and choose the Release form from the dropdown list. Leave the subcategory field empty and save the page. In addition, create the Distributions category and select the Distribution form. The category page will now have a link to create a new page in that category, using the default form.
Each page in the category will also have an Edit with Form option at the top right, which will enable users to easily edit the values in the template using the correct form.
You can now browse to www.your-wiki.com/ Category:Distributions and use the form link to create a few Distributions. You can do the same with www.your-wiki.com/ Category:Releases You should see the distributions you created appear in the autocomplete field.
Our example uses two defined categories: Category:Distributions and Category:Releases. It might seem tempting to use the names of distros, (for example, Ubuntu or Debian) as categories to group their releases, but this would lead to potential confusion and duplication because our example will have normal wiki pages for Ubuntu and Debian based on the Distribution template. The built-in grouping provided by MediaWiki’s Categories functionality presents the user with a simple, alphabetically sorted list of pages names in each category.
In contrast, we can do much more with an #ask: query that we can build into the distribution template, which will select, group and display related releases with far more granularity. Indeed, the real power of the Semantic MediaWiki extension is the ability to query for any property, page or category and to display the results with a high degree of control.
We’ll add several queries into the Distribution template, which will make the page a bit more dynamic and have more visual elements. We’ll also use #forminput to create a new related release directly from a distribution page, passing the name of the page to the form to pre-populate the Has Distribution property. Browse to www.your-wiki.com/ Template:Distribution and edit the page.
Delete the closing |} from the wikitable section and add the following lines underneath the Based On field and above [[Category:Distributions]]: |!Derivatives of {{PAGENAME}} |{{#ask:[[Based On::{{PAGENAME}}]] OR [[Based On.Based On::{{PAGENAME}}]]}} |!{{#ask:[[Has Distribution::{{PAGENAME}}]] |?Has Downloads |format=sum }} {{PAGENAME}} Downloads |{{#ask:[[Has Distribution::{{PAGENAME}}]] |?Has Downloads=Downloads |sort=Has Release Date |order=desc |format=jqplotchart |charttype=bar |distribution=no |min=0 |height=200|width=20% }} |} =={{PAGENAME}} Releases== {{#ask:[[Has Distribution::{{PAGENAME}}]] |?Has Version=Version |?Has Release Date=Release Date |?Has End Date=End Date |?Has Downloads=#Downloads |sort=Has Release Date |order=desc |format=broadtable }} {{#forminput:form=Release|button text=Add a new release|query string=Release[field_ Distribution]={{PAGENAME}}|no autofocus}} ==Timeline of {{PAGENAME}} Releases== {{#ask:[[Has Distribution::{{PAGENAME}}]] |?Has Version=Version |?Has Release Date=Release Date |?Has End Date=End Date |?Has Downloads=#Downloads |timelinesize=200px |format=timeline }}
Save the page and refresh any of the distribution pages you created to see the changes. If you created related releases then the tables, timelines, bar chart and number of downloads should automatically be populated.
Finally, to create a simple summary of Distributions and their releases, create a new page called Distributions by browsing to www.your-wiki.com/Summary and add the following ask query to the page: {{#ask:[[Has Distribution::+]] | ?Has Distribution | ?Has Version= | sort=Has Release Date | order=desc | format=outline | outlineproperties=Has Distribution }} Drop the team a line to let them know how you get on!