Home
Maintaining a semantic MediaWiki can be a lot of work, as any reasonably complex semantic wiki will require dozens of templates, forms and attribute pages. By separating the model from its implementation, it becomes easier to keep an overview of the semantic components used.
The first step to do this is to model the semantic relationships as an ontology, using a modelling tool such as Protege. Alternatively, simple ontologies can modelled visually using UML and then converted into RDF (see https://gitlab.com/alvarosaurus/UML-ODM-to-OWL-XML).
The second step is to convert the ontology into templates, forms and attributes pages in the wiki. This script takes an ontology file in RDF format as input and creates the necessary wiki pages using the MediaWiki API.
Follow the steps here: https://gitlab.com/alvarosaurus/RDF-to-MediaWiki/blob/master/README.md
I strongly suggest you add the following line to your MediaWiki LocalSettings.php:
# Open external links in new tab (useful when working with many forms)
$wgExternalLinkTarget = '_blank';
# Allow pages to customize the title
# (necessary for localization of imported ontologies).
$wgRestrictDisplayTitle = false;
# Allow using icons from wikipedia
$wgAllowExternalImagesFrom = "https://upload.wikimedia.org/";
This script uses the MediaWiki API to create Wiki content. As of MediaWiki 1.27, this requires that the session is initiated by a "bot" user.
Login to the Wiki and open the page Special:BotPasswords. On this page, you can create new bot passwords and manage existing ones. Clients using bot passwords can only access the API, not the normal web interface.
The new bot should be granted the following permissions:
(you can only grant the bot permissions that you already have).
- Basic rights
- Edit existing pages
- Create, edit, and move pages
- Delete pages, revisions, and log entries
Note down the bot's username (usually Your-User-Name@bot) and the bot password which was generated for you by MediaWiki. You will need these for the script configuration (see next).
Copy the file example/example.ini to example/config.ini.
Edit config.ini to suit your configuration (table 1).
Table 1: Script configuration options.
| Property | Description | Example |
|---|---|---|
| baseMwURL | Base URL of the MediaWiki installation | http://myurl.org/mw/ |
| username | Username of the MediaWiki API bot user | user@bot |
| password | Password of the MediaWiki API bot user | somepassword |
| tempDir | Local directory where the script will store temporary files | /tmp |
| tplDir | Path to xslt template files | templates |
An simple example ontology is included in the folder "example". This ontology, Calendar.rdf, models an event calendar, such as from thunderbird etc.
The ontology file is provided in two XML formats: Calendar.rdf (the file used for the remaining of this how-to) stores the ontology in RDF/XML format. The file Calendar.owl stores the file in OWL/RDF format. Both formats can be used with the script, but RDF is preferred.
If you wish to edit the example ontology, I recommend you use an ontology editor such as Protege (Figure 1).
Figure 1: The example ontology as shown in the Protege ontology editor (with VOWL Plug-in).
The elements of the ontology will be mapped to MediaWiki templates, forms, categories and attribute pages as shown in table 2.
Table 2: Ontology to MediaWiki elements mapping.
| Ontology element | MediaWiki markup | Example |
|---|---|---|
| Class | Template:Classname, Form:Classname, Category:Classname | The ontology class "Entry" is mapped to Template:Entry and Form:Entry |
| Datatype property | Property:propertyname, markup in the corresponding class' template. | The property "hasPriority" of the class "Entry" is mapped to the page Property:HasDetails and a snippet of markup is added to the page Template:Entry |
| Object property | The objects in the range are listed in the domain class. | The Calendar template has a semantic query that lists all the events. |
| rdfs:label | Labels shown in the templates and forms | The datatype property hasEndDate is rendered as a "Enddatum" on a German language site. |
| rdfs:comment | Comments are shown above the input fields and on property pages | The comments for each field, if available, are rendered in the language chosen during import. |
Make sure your Wiki is up and running, and that the Semantic MediaWiki and additional extensions are installed. You can list the extensions by opening the Special:Version page of your wiki.
To run the transformation, do:
./rdf2mw.sh -a import -i example/Calendar.rdf
Important: after that, ssh to your MediaWiki server and do:
cd /path/to/your/wiki/www/directory
php maintenance/runJobs.php
After the maintenance script has finished (the first time it takes a while):
- Open the page
Category:Entry - Create a new Entry using the form (figure 2), call it
My first Entry, add some values, save it. Do not worry about "hasLocation" for the moment. - Open the page
Category:Location - Create a new Location using the form. Add some values, save it.
- Open the page
Category:Entry. You should see the created Entry. Open it. - Click on the "Edit with form" button. If the button is not present, reload the page.
- Under the "hasLocation" header, select the newly created location and save the Entry.
Figure 2: The form for the entry class, as generated from the ontology.
To change the language of the wiki, first add labels and comments to the properties you want to customize, e.g. using Protege. Then run the transformation with the language parameter. For example, to create a German language wiki do:
./rdf2mw.sh -a import -i example/Calendar.rdf -l de
It may be necessary to customize the layout or to set the display order of the properties on a page. As the order of the properties is not considered relevant in ontologies, the display order has to be set in a custom template file. To import the ontology into a wiki using a custom template file:
- Copy the templates in
src/smw/templatesto a custom template directory - Customize the templates
- Set the path to the custom templates directory in your config.ini
- Run the rdf2mw as usual
This will remove the categories, templates, forms and properties of the ontology. It will not remove the content pages (the pages in the article namespace that used the templates, forms etc.)
./rdf2mw.sh -a remove -i example/Calendar.rdf
To run the tests, I recommend you install "green" and "coverage", which should be installed if you did pip3 install -r requirements.txt.
To run all the tests and get code coverage statistics:
cd test
bash test.sh
To run single test classes (without code coverage statistics), do:
cd test
export PYTHONPATH=${PYTHONPATH}:../src:.
python3 name_of_the_test_file.py
The tests run on a slightly more complex ontology, found here: https://gitlab.com/alvarosaurus/RDF-to-MediaWiki/blob/master/test/testdata/Test.rdf
The directory docs contains UML diagrams. These can be opened using ArgoUML (http://argouml.tigris.org).
- Problems while importing an RDF or OWL file
- If you are getting 'NoneType' errors during import, make sure all the datatype and object properties have a domain and a range.
- Problems with forms, templates queries or categories/
- Most of the time, problems with Semantic MediaWiki can be solved by running the '''maintenance script''' as explained above.
- Problems with the user interface
- If you are missing icons or are seeing links where icons should be, then please check that you have edited your wiki's LocalSettings.php as suggested under ''Installation''.
- Problems with tests
- If the tests fail with "permission denied" errors, check the ''Create a "bot" user'' section: have you created a bot account, does it have the necessary permissions, are username and password correct in config.ini?
API:Login (n.d.). In ''MediaWiki''. Accessed 8 Nov. 2017, https://www.mediawiki.org/wiki/API:Login/en