LocDB Implementing Modules

From Wikivoyage Tech

Contents 1 Maintenance and application side 2 Modules on the maintenance side 2.1 The module data class 2.2 The module processing class 2.2.1 Constructor 2.2.2 Method saveToDb() 2.2.3 Method outSection() 2.2.4 Method outSynopsis() 2.2.5 Method save() 2.2.6 Method prepareDiff() 2.2.7 Method tryUndo() and saveUndo() 2.2.8 Method doMerge() 2.2.9 Method saveMerge()

[edit] Maintenance and application side

Usualy, modules will have a mainenance and an application part. Both shlould be implemented as MediaWiki extensions. The maintenance part has to be included in the LocalSettings.php of the maintenance interface, i.e. the ldb pseudo wiki, while the application part has to be included in the LocalSettings.php of the wikis that use the data from the location DB. Mostly, there also will be some part of the code that can be used on both sides, call it shared part.

[edit] Modules on the maintenance side

The framework of the maintenance interface provides an internal interface for modules. Thus, modules only have to care for the processing of the part of data they have to manage, but not for the interaction with the rest of the MediaWiki software.

Technicaly, a module consists of al least two PHP classes, the module data class and the module processing class. The module data class must be derived from the class LdbModData and the module processing class must be derived from the class LdbModule. Both classes are declared as abstract classes in Module.php.

Additionaly, a module needs to have a file tables.sql where all database tables needed by this module must be defined in SQL format. It is up to the module to update this tables when the data for a location has been modified.

[edit] The module data class

The module data class should only keep the data the module precessing class is working with. The data should be stored in a minimal form. Whenever the data of the module is modified, a complete instance of the module data class is stored in a DB table row in serialized form. Serialisation and stroage is done by the framework, but it's in the task of the module developer to keep the size of the module data class as small as possible.

The abstract method newFromDb() must be able to read the data of the current revision of a location from the tables maintained by the module.

[edit] The module processing class

This class is the actual working unit of the module. It interacts with the framework and maintaines the underlaying DB tables.

The abstract parent class LdbModule has several abstract methods that need to be overwritten by the module processing class. The framework calls this methods in order to communicate with hthe module.

A module must never write HTML code to wgOut or elsewhere. Instead, all HTML or JS output is lead to the framework and displayed from there.

Each module class inherits a LdbStatus member for sending messages to the user.

Here is an overview of important methods used to communicate with the framework.

[edit] Constructor

The constructor has to accept tree parameters from which the latter ones are optional. The first paramete is the location object the module operates on. The 2nd and 3rd parameters are LocRevision objects of either two revisions of the location given as first argument or one revision of the location and the other one is a revision from an other location.

[edit] Method saveToDb()

This abstract method has to be defined and must be able to write the current data of the module into the DB tables managed by the module.

[edit] Method outSection()

This method writes the HTML and JS code needed for the display on the location's page. Both are returned by writing into the corresponing arguments that are passed by reference. The HTML code must not contain any sread in JS parts. Instead, all JS has to be written into the JS vaiable. It is inserted directly after the HTML part by the framework.

[edit] Method outSynopsis()

Writes the HTML and JS code needed for displaying differences between revisions or merge conflicts. It is called with the some arguments as outSection().

[edit] Method save()

The part of HTTP post data controlled by the module is passed as argument. Method save() has to do a validity check for the user submitted data, to write status messages as needed and to save the data of the new revison in the tables managed by the module.

[edit] Method prepareDiff()

Calculate the difference of the data from the two LocRevisions given in the constructor and prepare the display. The actual output of the HTML and JS is done by outSynopsis().

[edit] Method tryUndo() and saveUndo()

Method tryUndo() tries to undo the modifications done from the old LocRevision to the new LocRevision. Both LocRevisions have been set in the constructor. After the difference has been calculated, the data from the current revision of the location has to be patched with it. Method tryUndo returns true if the patch is possible, false otherwise. After all modules have successfully tried their undos, the framework calls their saveUndo() methods which have to save the data of the new revision into the DB tables.

[edit] Method doMerge()

Interpretes the two LocRevisions as current revisions of two different locations and tries to merge them. Sets warn or error messages in the status as needed. If a merge conflict occures, it has to be displayed when outSynopsis() is called.

[edit] Method saveMerge()

Afte all modules have reported a successfull merge, the framework calls their saveMerge() methods. It saves the data of the merge revision into the tables managed by the module.