MediaWiki

From Jmol
Revision as of 13:38, 15 April 2006 by NicolasVervelle (talk | contribs) (wikiPageContents)
Jump to navigation Jump to search

Description

MediaWiki is an open source wiki engine licensed under the GNU General Public License. It is used by many websites, including this one.

The Jmol Mediawiki Extension enables the use of the Jmol applet inside of Mediawiki pages. This simple page demonstrates how to use the extension.

Note: The Jmol Mediawiki Extension is currently under development. It will go under several changes, different versions will probably be incompatible between each other


Wikis using the Jmol Extension

If you know a Wiki using the Jmol MediaWiki Extension, please add it in the following list:


How to use the Jmol Extension

Once the Jmol Extension is installed in the Wiki, you can start adding Jmol applets and controls.

This following documentation is subject to change since the Jmol Extension is currently under development

Simple usage

To add a Jmol applet to a MediaWiki page, just add the following: 

<jmol>
  <jmolApplet>
    <wikiPageContents>page of the wiki containing the molecular data</wikiPageContents>
  </jmolApplet>
</jmol>

or 

<jmol>
  <jmolApplet>
    <onlineContents>contents of the molecular file</onlineContents>
  </jmolApplet>
</jmol>

or 

<jmol>
  <jmolApplet>
    <urlContents>URL of the molecular file</urlContents>
  </jmolApplet>
</jmol>

To add buttons to send scripts to the applet, just add the following: 

<jmol>
  <jmolButton>
    <script>script to execute</script>
    <text>text of the button</text>
  </jmolButton>
</jmol>

Applets and buttons can be combined in a single <jmol> tag.

Reference

The <jmol> can contain the following:

  • <jmolApplet> : Jmol Applet.
    • <signed> (true, false) : On the first Jmol applet to use the signed or unsigned version of the applet. This attribute can be disabled by the Wiki administrator with the $wgJmolAuthorizeChoosingSignedApplet setting.
    • <color> : To change the background color of the Jmol applet.
    • <wikiPageContents> : Name of a page of this wiki containing the molecular data to load in the Jmol applet.
    • <urlContents> : URL of the molecular file to load. This attribute can be disabled by the Wiki administrator with the $wgJmolAuthorizeUrl setting.
    • <onlineContents> : molecular data to load in the Jmol applet.
    • <size> : Size of the applet.
    • <script> : Script to execute at startup.
    • <name> : Name of the Jmol applet (useful if you want to use several Jmol applets in the same page).
  • <jmolButton> : Button.
    • <script> : Jmol script to execute when the button is clicked.
    • <text> : Text of the button.
    • <name> : Name of the Jmol applet linked with the button (useful if you want to use severak Jmol applets in the same page).


Installation

Download Jmol and extract all the files in a temporary directory.

Create the directory Jmol in $mediawiki/extensions, and copy the following files in it:

  • File icon.gifCOPYRIGHT.txt
  • File icon.gifJmol.js
  • File icon.gifJmolApplet_i18n.jar and File icon.gifJmolApplet0.jar to File icon.gifJmolApplet6.jar
  • File icon.gifJmolAppletSigned_i18n.jar and File icon.gifJmolAppletSigned0.jar to File icon.gifJmolAppletSigned6.jar, if you want to be able to use the signed applet.
  • File icon.gifLICENSE.txt
  • File icon.gifREADME.txt


Add the following line to the end of File icon.gifLocalSettings.php: 

require_once('extensions/Jmol/JmolExtension.php');


You can configure the Jmol extension with several settings added after the above line (default value in bold):

  • $wgJmolAuthorizeUrl (true, false) : Authorize the use of <urlContents>.
  • $wgJmolAuthorizeChoosingSignedApplet (true, false) : Authorize users to choose between the unsigned and the signed Jmol applet.
  • $wgJmolDefaultAppletSize (400) : Size in pixels of the Jmol applet.
  • $wgJmolForceNameSpace : Force the NameSpace where the applet will go looking for wiki pages containing molecular data (using <wikiPageContents>).
  • $wgJmolUsingSignedAppletByDefault (true, false) : Choose if the signed Jmol applet will be used by default. Note: the signed Jmol applet is signed with a default certificat. If you want to use the signed Jmol applet in your wiki, I suggest resigning the Jmol applet with your own certificate.


Copy the following code and paste it into File icon.gifextensions/Jmol/JmolExtension.php: 

<?php

/*
 * Copyright (C) 2006 Nicolas Vervelle,  The Jmol Development Team
 *
 * Contact: nico@jmol.org, jmol-developers@lists.sf.net
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 */
 
if (defined('MEDIAWIKI')) {

global $wgJmolAuthorizeUrl;
global $wgJmolAuthorizeChoosingSignedApplet;
global $wgJmolDefaultAppletSize;
global $wgJmolUsingSignedAppletByDefault;

/* Global configuration parameters */
$wgJmolAuthorizeUrl = false;
$wgJmolAuthorizeChoosingSignedApplet = false;
$wgJmolDefaultAppletSize = "400";
$wgJmolUsingSignedAppletByDefault = false;

/* Class containing all the code for the Jmol Extension */
class JmolExtension {
  var $mOutput, $mDepth;
  var $mCurrentObject, $mCurrentTag;

  var $mValColor;
  var $mValName;
  var $mValOnlineContents;
  var $mValScript;
  var $mValSigned;
  var $mValSize;
  var $mValText;
  var $mValUrlContents;

  function JmolExtension() {
    $this->mOutput = "";
    $this->mDepth = 0;
    $this->resetValues();
  }

  function renderJmol($input) {
    $this->mOutput = "";
    $this->mDepth = 0;
    $xmlParser = xml_parser_create();
    xml_set_object($xmlParser, &$this);
    xml_set_element_handler($xmlParser, "startElement", "endElement");
    xml_set_character_data_handler($xmlParser, "characterData");
    $input = "<jmol>$input<jmol>";
    if (!xml_parse($xmlParser, $input)) {
      die(sprintf(
        "XML error: %s at line %d",
        xml_error_string(xml_get_error_code($xmlParser)),
        xml_get_current_line_number($xmlParser)));
    }
    xml_parser_free($xmlParser);
    return $this->mOutput;
  }

  function renderJmolApplet() {
    global $wgJmolAuthorizeUrl;
    
    $this->mValOnlineContents = trim($this->mValOnlineContents);
    $this->mValOnlineContents = preg_replace("/\t/", " ", $this->mValOnlineContents);
    $this->mValOnlineContents = preg_replace("/\n/", "\\n'+\n'", $this->mValOnlineContents);
    $this->mOutput .=
      "<script src='/extensions/Jmol/Jmol.js'></script>\n".
      "<script>\n";
    if ($this->mValSigned) {
      $this->mOutput .= "jmolInitialize('/extensions/Jmol', true);\n";
    } else {
      $this->mOutput .= "jmolInitialize('/extensions/Jmol', false);\n";
    }
    $this->mOutput .=
      "jmolCheckBrowser('popup', '/extensions/Jmol/browsercheck', 'onClick');\n".
      "jmolSetAppletColor('".$this->mValColor."');\n";
    if (($this->mValUrlContents != "") && ($wgJmolAuthorizeUrl == true)) {
      $this->mOutput .=
        "jmolApplet(".$this->mValSize.", \n".
                    "'load ".$this->mValUrlContents."; ".$this->mValScript."'";
    } else {
      $this->mOutput .=
        "jmolAppletInline(".$this->mValSize.", \n".
                          "'".$this->mValOnlineContents."', \n".
                          "'".$this->mValScript."'";
    }
    if ($this->mValName != "") {
      $this->mOutput .= ",\n'".$this->mValName."'";
    }
    $this->mOutput .=
      ");\n".
      "jmolBr();\n".
      "</script>\n";
  }

  function renderJmolButton() {
    $this->mOutput .= "<script>\n";
    if ($this->mValName != "") {
      $this->mOutput .= "jmolSetTarget('".$this->mValName."');\n";
    }
    $this->mOutput .=
      "jmolButton('".$this->mValScript."', '".$this->mValText."');\n".
      "</script>\n";
  }

  function startElement($parser, $name, $attrs) {
    $this->mDepth += 1;
    switch ($this->mDepth) {
    case 1:
      // JMOL tag itself
      $this->resetValues();
      break;
    case 2:
      // The interesting tags
      $this->resetValues();
      $this->mCurrentObject = $name;
      break;
    case 3:
      // Details of the interesting tags;
      $this->mCurrentTag = $name;
    }
  }

  function endElement($parser, $name) {
    switch ($this->mDepth) {
    case 1:
      // JMOL tag itself
      $this->resetValues();
      break;
    case 2:
      // The interesting tags
      switch ($this->mCurrentObject) {
      case "JMOLAPPLET":
        $this->renderJmolApplet();
        break;
      case "JMOLBUTTON":
        $this->renderJmolButton();
        break;
      }
      $this->resetValues();
      break;
    case 3:
      // Details of the interesting tags
      $this->mCurrentTag = "";
      break;
    }
    $this->mDepth -= 1;
  }

  function characterData($parser, $data) {
    global $wgJmolAuthorizeChoosingSignedApplet;
    
    switch ($this->mDepth) {
    case 3:
      // Details of the interesting tags
      switch ($this->mCurrentTag) {
      case "COLOR":
        $this->mValColor = $data;
        break;
      case "NAME":
        $this->mValName = $data;
        break;
      case "ONLINECONTENTS":
        $data = trim($data);
        if ($data != "") {
          $this->mValOnlineContents .= "\n" . $data;
        }
        break;
      case "SCRIPT":
        $this->mValScript = $data;
        break;
      case "SIGNED":
        if ($wgJmolAuthorizeChoosingSignedApplet) {
          $this->mValSigned = $data;
        }
        break;
      case "SIZE":
        $this->mValSize = $data;
        break;
      case "TEXT":
        $this->mValText = $data;
        break;
      case "URLCONTENTS":
        $this->mValUrlContents = $data;
        break;
      }
      break;
    }
  }

  function resetValues() {
    global $wgJmolDefaultAppletSize;
    global $wgJmolUsingSignedAppletByDefault;
    
    $this->mCurrentObject = "";
    $this->mCurrentTag = "";
    $this->mValColor = "black";
    $this->mValName = "";
    $this->mValOnlineContents = "";
    $this->mValScript = "";
    $this->mValSigned = $wgJmolUsingSignedAppletByDefault;
    $this->mValSize = $wgJmolDefaultAppletSize;
    $this->mValText = "";
    $this->mValUrlContents = "";
  }
};

$wgExtensionCredits['other'][] = array(
  'name'        => 'Jmol Extension for MediaWiki',
  'description' => 'adds the possibility to include Jmol applets in MediaWiki.',
  'author'      => 'Nicolas Vervelle, Jmol Development Team'
);

/* Test to modify between Dev and Release versions */
if (true) {
  $wgExtensionFunctions[] = "wfJmolExtension";

  $wgJmolExtension = new JmolExtension;

  function wfJmolExtension() {
    global $wgParser;
    $wgParser->setHook( "jmol", "wfRenderJmol" );
  }

  function wfRenderJmol($input) {
    global $wgJmolExtension;
    return $wgJmolExtension->renderJmol($input);
  }
} else {
  $wgExtensionFunctions[] = "wfJmolDevExtension";

  $wgJmolDevExtension = new JmolDevExtension;

  function wfJmolDevExtension() {
    global $wgParser;
    $wgParser->setHook( "jmolDev", "wfRenderJmolDev" );
  }

  function wfRenderJmolDev($input) {
    global $wgJmolDevExtension;
    return $wgJmolDevExtension->renderJmol($input);
  }
}

}
?>


External links

Contributors

AngelHerraez, NicolasVervelle, Rzepa, Mevans86, Ngreeves, Pimpim, SklogWiki, Jacksmind, EricMartz

Retrieved from "https://wiki.jmol.org/index.php?title=MediaWiki&oldid=2148"