This is an old revision of the document!
Table of Contents
NetLogo Plugin
Compatible with DokuWiki
Angua, Adora Belle, Weatherwax
This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.
Similar to applet
NetLogo is a multi-agent programmable modeling environment. It is used by tens of thousands of students, teachers and researchers worldwide. It is authored by Uri Wilensky and developed at the CCL. You can download it free of charge.
The NetLogo plugin for DokuWiki allows wiki editors to embed NetLogo applets in their pages. When NetLogo files (with extension .nlogo
) are uploaded to the server and included in a page as media this plugin executes the file in the NetLogo Java applet.1)
Installation
This plugin will embed .nlogo
files uploaded to your DokuWiki server. To allow upload you must add the following line to conf/mime.local.conf
nlogo !application/octet-stream
External requirements: This plugin requires that the user has Java installed to run the applet.
Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.
Examples/Usage
See an implementation of Conway's Game of Life for a demonstration of this plugin in action.
Syntax
Basic syntax
You can include uploaded .nlogo
files with curly brackets, similar to internal images. Optionally you can specify the size of them. If a user has uploaded applet.nlogo
to the current namespace, the following are valid syntax:
Real size: {{applet.nlogo}} Resize to given width: {{applet.nlogo?500}} Resize to given width and height: {{applet.nlogo?800x500}}
Note that NetLogo applets may not present properly if resized to smaller than their default size.
By using left or right whitespaces you can choose the alignment.
Right: {{ applet.png}} Left: {{applet.png }} Center: {{ applet.png }}
Only files on the current server, uploaded to the DokuWiki media folder are permitted. The NetLogo plugin respects ACLs: an applet will only be executed if the viewer has permission to read the file. Otherwise an error message is displayed.
Unlike images and other media files, titles are not allowed. If a title is included a download link will be presented instead:
{{applet.nlogo|Click to download applet}}
An empty title is allowed, however, for compatibility with the default format of the “Add Images and other files” toolbar button. For example,
{{applet.nlogo|}}
will execute the applet.
Advanced syntax
Instead of adding a title to create a download link, you may add a ?do=download
parameter to the link, such as
{{applet.nlogo?do=download}}
By default the .nlogo
file determines the version of NetLogo executed. You may override this behaviour by specifying your own version as a parameter in the link:
Centered without version: {{ applet.nlogo }} Centered with version: {{ applet.nlogo?version=5.0.3 }} Centered with size and version: {{ applet.nlogo?800x500&version=5.0.3 }}
You may want to present the source code to the file directly in the wiki page. To do so add ?do=code
to the link:
{{applet.nlogo?do=code}}
Currently, the raw code is simply wrapped in a code block. The author hopes to enable syntax highlighting in the future.
NetLogo allows extra information to be added in a “Info” tab. To present this information in a wiki page add ?do=info
to the link:
{{applet.nlogo?do=info}}
The text is presented without any formatting. To render so that headers, links, and other formatting are displayed correctly install the plugin:markdownextra plugin and use ?do=mdinfo
instead:
{{applet.nlogo?do=mdinfo}}
Configuration and Settings
None at this time.
Development
How it works
ACL
The first challenge I had in developing this plugin was figuring out how to handle security. I couldn't just allow the NetLogo applet to access the .nlogo file directly because:
- It wouldn't work on most DokuWiki installs (direct file access is usually disabled), and
- It wouldn't respect DokuWiki access permissions.
A user should only be able to run the file if he/she has permission to read it. How to let the Java applet know if DokuWiki grants permission? The applet only runs after the page has finished loading. I tried using DokuWiki's built-in fetch.php
to pass along the file to the applet but that didn't work because the applet didn't have access to the user's session info (cookies and such) so it would get rejected. In the end I decided on the following:
- The plugin creates a token containing the .nlogo filename and an expiration time. The token is encrypted with a secret hash.
- The page is constructed containing a link to
servefile.php
with the .nlogo filename, expiration time, and token included as parameters. - When the page is loaded the Java applet tries to load the .nlogo file from the
servefile.php
link. Only ifservefile.php
is able to recreate the same token from the same information (filename, expiration time, and secret hash) does it send the file to the applet.
I think this gives good security (respecting DokuWiki's ACL) but would appreciate feedback in case there are any serious vulnerabilities or a simpler approach.
Applet version
In order to work this plugin requires the NetLogoLite.jar
Java applet be installed on the server. Every new release of NetLogo comes with a new jar file and every .nlogo
file works best with the version it was designed for. So any new .nlogo
file uploaded may require its own NetLogoLite.jar
. It would be tedious and confusing to ask the user or the administrator to install each one manually.
Instead, the plugin reads the .nlogo
file and checks the version against the already installed jars. If the right version isn't on the server yet the plugin downloads it from http://ccl.northwestern.edu/netlogo/ before presenting the page. So the plugin is always ready for NetLogo updates. It works for me but please let me know if you have any problems.
Applet size
How big should the applet be on the page? The user can specify with parameters but if not specified it reads the .nlogo
file and finds the positions of all the interface elements. It reserves space to fit them all. This might not work if you have unusual zoom settings in your browser. Then you may want to manually set the size using the size parameters (see Basic Syntax).
Change Log
- switched to https (secure) netlogoweb.org (2018-07-28 07:21)
- update plugin.info.txt (2017-01-22 05:00)
- Merge pull request #1 from splitbrain-forks/php7-signature (2016-12-17 06:42)
- fix: remove urlencode() (2016-11-28 06:47)
- fix: remove resolve_mediaid() (2016-11-28 06:45)
- only remote .nlogo files supported (2016-11-28 06:41)
Known Bugs and Issues
See issues on GitHub.
ToDo/Wish List
This plugin is intended only as a proof-of-concept. Others are encouraged to fork this plugin and develop it further. Please send a pull request to the master branch on significant improvements.
Here are some improvements the author hopes to see implemented:
- The
?do=code
option should apply syntax highlighting. - Options (such as the applet download url) are hard-coded. Should be moved to configuration.
- Is it possible (and a good idea?) to automatically modify
conf/mime.local.conf
so the administrator doesn't have to fiddle with code to get this plugin working?