Extension:ZWIMaker

From mediawiki.org
MediaWiki extensions manual
OOjs UI icon advanced-invert.svg
ZWIMaker
Release status: stable
Implementation Parser function
Author(s) Sergei V. Chekanov (KSFencyclospheretalk)
Latest version 1.3 (2022-02-12)
MediaWiki 1.34+
PHP 7.2+
Database changes No
License GNU Lesser General Public License 3.0
Download
Example handwiki (for registered users)
$wgMzwiName, $wgMzwiTab, $wgMzwiSubmit, $wgMzwiPassword, $wgMzwiAuthorApprove, $wgMzwiSubmitUrl,$wgMzwiLicense

Check usage and version matrix.

ZWIMaker extension exports MediaWiki articles to the ZWI file format (version 1.3) used by the Encyclosphere project of the Knowledge Standards Foundation (KSF). It allows downloading ZWI files with MediawWiki articles, as well as it can be used for automatic submissions of such files to the Encyclosphere network.

After installation, the button "ZWI export" should appear. It is located at the top-right side of the edit area (in the Timeless skin). If you click this button, you will see the menu that allows you to download the ZWI file with the Mediawiki article. One can also use this menu to submit this ZWI file to the Encyclosphere network.

This plugin requires a password for submission to Encyclosphere, i.e. the network should authorize the MediaWiki installation. This password can be obtained from the KSF. For testing purposes, one can use the password "0123456789" for submission of articles to "sandbox" (in this case $wgMzwiName="sandbox"; should be set).

Download[edit]

Go to the MediaWiki install directory, and then go to the directory "extensions".

cd extensions
git clone https://gitlab.com/ks_found/ZWIMaker.git

You will see the directory "ZWIMaker". You should make sure that the web server can write into the directory "ZWIMaker/tmp". If you run Apache under Linux, make sure the owner and group is "www-data".

cd ZWIMaker 
chown www-data tmp
chgrp www-data tmp
chmod 755 tmp

To use this extension, make sure the php-zip module is installed (here is Ubuntu example for PHP 7.0):

sudo apt-get install php7.0-zip
service apache2 restart

Installation[edit]

  • Download and place the file(s) in a directory called ZWIMaker in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    wfLoadExtension( 'ZWIMaker' );
    
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration[edit]

The extension requires several parameters. Add these lines at the bottom of LocalSettings.php of your MediaWiki configuration file:

# What is the name of your Wiki 
# This corresponds to the network "Publisher" name. In the example below, the publisher is the name of the site.
# You can change it to any name.
$wgMzwiName=$wgSitename;
# action tab to make "Export to ZWI"
$wgMzwiTab=true;
# if you set this parameter to 0 it will trigger download of ZWI file 
$wgMzwiSubmit=0;
#
# if $wgMzwiSubmit>0, you should specify the password for network submissions.
# Usually, this is 10-character password obtained from KSF.
# You can also use the password "0123456789" for submissions to the "sandbox" of the network. 
# In this case, set $wgMzwiName="sandbox".
$wgMzwiPassword='10 character password from KSF'; 
#
# should the author (contributors) approve the submission? 
# if false, then everyone after login can submit ZWI file to the Encyclosphere network.
$wgMzwiAuthorApprove=true;
#
# what about the license? This info will be included inside ZWI file.
$wgMzwiLicense='CC BY-SA 3.0';
#
# Encyclosphere submission URL 
$wgMzwiSubmitUrl="https://encycloreader.org/upload/";

You will see an additional button "ZWI export" above the edit area (this depends on the MediaWiki skin).

Generally, $wgMzwiName can be set to any name that represents a "publisher". But you will need to obtain the correct password from the KSF in order to associate this name with a password. You should set the license of the articles to the variable $wgMzwiLicense. This information will be included inside the metadata of the ZWI files.

In the case if you use the default password "0123456789", you should always set $wgMzwiName="sandbox";. This means that your article will appear in the directory "sandbox" of the Encyclosphere network. Note it can be overwritten by other installations with the same "sandbox" name.

Here are other parameters:

  • $wgMzwiSubmit=0 - ZWI file will be downloaded (it will not be submitted to the Encyclosphere network).
  • $wgMzwiSubmit=1 - the ZWI file will be submitted to the Encyclosphere network. Note only the authors who contributed to the text of this article can submit it to the Encyclosphere. Also you need to be properly registered and login on this MediaWiki. In addition, you will need to specify the password that will allow to submit the article to the network. The password can be obtained from the KSF.
  • $wgMzwiSubmit=2 - the article will be created in the directory "extensions/ZWIMaker/tmp/" without any further actions. It will be removed after new request.

The option 2 should never be used for public MediaWiki installations. This option is only useful for publishers who want to create ZWI files locally. One can trigger ZWI file creation using "wget". For example, this command:

If $wgMzwiAuthorApprove is set to false, any user (after login) can submit an article to Encyclosphere. If this parameter is set to true, only authors (contributors) can do the submission.

Image configuration[edit]

This ZWI builder works only if you configure MediaWiki such that all images are cached inside the "/thumb/". If you do not do this, only images that have been uploaded to MediaWiki will be included. Any external images from Wikimedia Commons will be ignored. In order to include external images, please add these lines to "LocalSettings.php ":

 # InstantCommons allows wiki to use images from <nowiki>https://commons.wikimedia.org</nowiki>
 $wgUseInstantCommons = true;
 # This is importnat to build ZWI files with external images. 
 $wgForeignFileRepos[] = [
         'class' => 'ForeignAPIRepo',
         'name' => 'imagescommonswiki', // Must be a distinct name
         'apibase' => 'https://commons.wikimedia.org/w/api.php',
         'hashLevels' => 2,
         'fetchDescription' => true, // Optional
         'descriptionCacheExpiry' => 8640000, // 24*100 hours, optional (values are seconds)
         'apiThumbCacheExpiry' => 8640000, // 24*100 hours, optional, but required for local thumb caching
 ];
 # not found? Use english wikipedia
 $wgForeignFileRepos[] = [
         'class' => 'ForeignAPIRepo',
         'name' => 'imagesenwiki',
         'apibase' => 'https://en.wikipedia.org/w/api.php',
         'hashLevels' => 2,
         'fetchDescription' => true,
         'descriptionCacheExpiry' => 8640000,  // 24*100 hours, optional (values are seconds)
         'apiThumbCacheExpiry' => 8640000, // 24*100 hours, optional, but required for local thumb caching
 ];

Protecting from non-registered users[edit]

You can remove the "ZWI export" button from non-registered users. For the Timeless skin, just add these lines in LocalSetting.php:

function efAddSkinStyles(OutputPage &$out, Skin &$skin) {
      if ($skin->getSkinName() == 'timeless') {
          $out->addInlineStyle('#other-languages { display:none; }');
      }
      if(!$skin->getUser()->isLoggedIn()) {
       if ($skin->getSkinName() == 'timeless') {
               $out->addInlineStyle('#ca-mzwi {display:none; }');
       }
   }
   return true;
}
$wgHooks['BeforePageDisplay'][] = 'efAddSkinStyles';