TopicTtree is subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.mozilla.org/MPL/. Alternatively, TopicTree may be used under the terms of either the GNU General Public License Version 2 or later (the "GPL"), or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"). See license agreement (Appendix A).
$ Date: 2004/1/28 $
Abstract
Simple bookmark management and general tree UI tool.
Table of Contents
TopicTree is a simple bookmark management and general tree UI tool. It supports keyboard navigation and can be used as a collaborative knowledge repository.
This manual is structured as follows: this section provides a brief introduction to TopicTree, Section 2 describes program structure and components. Section 3 covers installation and Section 4 covers utilization of the application. Finally, potential future work is discussed in Section 5.
There are lots of complex Personal Information Managers (PIMs) and simpler outlining tools available (for example, see John Redmood's Overview of Windows Outlining Programs). Also, there are many PHP- or JavaScript-based tree or directory tools around such as Morten Wang's JavaScript Tree Menu or Martin Mouritzen's NanoTree.
TopicTree tries to combine the best features of other tree- and outlining tools. It is most suitable for personal or small group usage, as a personal bookmark collection or a study project references list. It is designed to be fast and easy to use and deploy. With WWW user interface, it is accessible from any computer with Internet connection. It's by no means either unique or the most efficient implementation but for the author (and hopefully others, too), it has proven to be quite useful.
TopicTree grew from a personal information management need. The author had to study/work on several different computers using different operating systems. As maintaining a pure HTML link page turned out to be a clumsy solution and none of the tree tools available felt quite suitable for centralized fast bookmark management, a new tool was needed.
The main requirements for TopicTree were fast link adding and editing, keyboard navigation (again, for efficiency) and maintaining all links on one page, so they can be referenced on single look. Naturally the system should be accessible on most popular operating systems (Windows, Linux, MacOS) and modern browsers (Mozilla, IE, Opera).
Keyboard navigation with loose topic selection. TopicTree has easy-to-use and intuitive navigation UI. For detailed controls, see Section 4.1.
Simple storage format. Currently the data stored by TopicTree is plain text that can be updated using the web interface or manually on the server. The format allows subtopics that are shared by many ancestors, 0-N links in a topic or custom forms with one edit box.
Collaborative tool support. Since there is currently no user authentication, anyone can edit the contents of TopicTree (this presents a potential security risk, see Section 4.3). Also, TopicTrees from different web sites can be combined.
Topic Map output. TopicTree features an experimental and incomplete Topic Map (see TopicMaps.org) output. This way you can manipulate your TopicTree in a Topic Map browser like Omnigator (unfortunately conversion from Topic Maps to TopicTree is not possible with current TopicTree format). You can convert your local TopicTree to TopicMap with xtmcreate.php.
Program structure and components are described in this section.
Directory listing from source directory of TopicTree shows the following (the root directory contains only LICENSE file and documentation directory).
bash$ cd /dir/where/you/extracted/topictree bash$ cd src bash$ ls -la drwxr-xr-x 4 minurmin users 4096 Jan 26 17:05 . drwxr-xr-x 4 minurmin users 4096 Jan 26 12:37 .. drwxrwxrwx 2 minurmin users 4096 Jan 26 11:54 docs -rw-r--r-- 1 minurmin users 85 Dec 29 18:13 doctree.ini.php -rw-r--r-- 1 minurmin users 277 Jan 26 17:07 doctree_global.php -rw-r--r-- 1 minurmin users 3483 Jan 7 18:06 generic.php -rw-r--r-- 1 minurmin users 2086 Jan 7 18:06 htmllib.php drwxr-xr-x 2 minurmin users 4096 Jan 26 17:05 images -rw-r--r-- 1 minurmin users 8579 Jan 7 18:04 index.php -rw-r--r-- 1 minurmin users 855 Jan 27 14:46 key.php -rw-r--r-- 1 minurmin users 385 Dec 29 18:13 keyboard.js -rw-r--r-- 1 minurmin users 2669 Jan 7 18:05 refresh.php -rw-r--r-- 1 minurmin users 9488 Dec 29 18:13 tree.js -rw-r--r-- 1 minurmin users 3619 Jan 7 18:03 tree.php -rw-r--r-- 1 minurmin users 1147 Dec 29 18:13 treestyles.css -rw-r--r-- 1 minurmin users 4711 Jan 26 12:24 xtmcreate.php bash$ |
index.php is the user interface for TopicTree. Topic and link data is contained in docs/, bullet images reside in images/ (directories can be altered). doctree.ini and doctree.global are configuration files. key.php is a convenience file for detecting keyboard codes (in case you want to alter the default mapping). xtmcreate.php converts current local TopicTree to Topic Map and returns it to browser so it can be saved. Other files are system components.
Most of the functionality (and representation - bad code) is contained in index.php. When user updates data files with HTML forms, the result is sent to refresh.php that performs update and redirects itself back to index.php using META element. This is not a desirable implementation and should be implemented in a single file - perhaps in the next version...
tree.php, tree.js and treestyles.css are responsible for tree styles and JavaScript user inteface. With minor modifications they could be used with many kinds of pages (the essential data for determining tree structure is in CSS styles - not in actual HTML elements).
System setup and configuration is described in this section.
On client side (browser), JavaScript is used for convenience but is not an absolute requirement. TopicTree has been successfully tested with Mozilla 1.0, Mozilla Firebird 0.6, Netscape 6, Opera 7 and IE 5 (or later versions). Opera 5/6 can be also used but JavaScript-enabled code doesn't work right.
On server side, the main requirement is a web server with PHP4-scripting enabled. Note that the web server (or alternatively all users, but this is unsecure) must have access and write privileges to docs directory and all files therein. The package should work with PHP3 as well (at least with minimal modifications), but it hasn't been tested for current version.
TopicTree can be obtained from http://www.maths.jyu.fi/~minurmin/.
Extract the distribution package to your working directory. If you have GNU tar, extracting goes with command.
bash$ tar --extract --ungzip --file=topictree.tar.gz |
Copy the contents in src/ directory to a web directory.
Check that the web server has access and write privileges for docs/ directory and its files and correct them if required. For example, the owner/privilege data can be set like this on a Linux system with Apache web server (assuming you are in the src/ directory):
bash$ chown -r apache:apache docs bash$ chmod 700 docs bash$ chmod 600 docs/*.dat |
If you don't have the privileges to change file ownership, you can also set full read/write privileges for dat files (see chmod documentation). However, this is not recommended because then anyone could modify your files.
If you don't want your bookmarks to be public, you can protect your directory using web server authentication. For example, for Apache web server, see the documentation: Authentication, Authorization, and Access Control.
TopicTree can be configured by changing doctree.ini.php-script. Currently only document and image directory and root document name can be modified.
Keys for keyboard navigation can be modified by changing tree.js directly. This is a crude solution that should be replaced by configuring keys in ini-file and perhaps an UI for keyboard codes. At the current time, however, this is the only option. In the beginning of tree.js there are arrays press and keys. The first represents keycodes for keypress events and second is for keyup events. The order of array elements is: (up,left,down,right).
Note that keypress and keyup use different codes for keys. key.php can be used to check key codes for either event type.
The basic usage of TopicTree is for personal bookmark/note management. Whenever you encounter an interesting page or subject, you can add it's URL to your TopicTree. If there are more related pages on the same topic, you might create a new subtopic for it. If you keep your bookmarks public, other people can update your links as well.
The tree can be navigated (ie. moving around nodes, expanding and collapsing subtrees, selecting topics) with custom keys. Default keys are keypad arrows or keys / * - +. Loose topic selection means that you can select a topic or expand/collapse subtree with mouse by pointing to some relative horizontal position next to the topic (ie. don't click on the link but any area around the link). The selected topic/subtree is highlighted.
If you press the right key when a topic is selected, focus will automatically shift to the first link of current topic. Then you can jump to selected link or select next/previous link using the standard keyboard shortcuts provided by the browser.
You can update any topic in the tree by pressing the filename link next to the header for each topic. Then a small HTML form is opened and you can edit the selected topic. The rest of the TopicTree is still browseable, but you can edit only one topic at the time. The upper edit box contains topic header and larger textarea contains topic links along with notes. While editing a topic in web browser, you are editing an exact representation of the topic data file (apart the header, which is actually the first row of the data file). This is somewhat error-prone and unsafe, but it is also quite efficient solution if used correctly.
On each row in textarea, you have the following options:
On each row, there is a note text followed by |. Then there are link URLs separated by |-marks. There can be multiple links, although the textarea window might look a bit messy if excessive number of links are used. If there are no links, consider the row as a note text, as in an outlining tool. The note text must always be terminated by |-mark. For example:
my personal note| link to w3c|http://www.w3.org software|http://www.sourceforge.net/|http://www.freshmeat.net/ |
Note that URL:s must be written with protocol scheme included (eg. http://, https://, ftp://...).
Plain text with no | mark indicates reference to a topic file. By convention, topic files should be named with dat extension but this is not enforced in any way. You can reference the same file from multiple locations, thus forming a directed acyclic graph. You can even make loops, but this hangs the system, so don't. If the file you reference does not exist, the system creates it automatically for you. If the filename starts with http://, it is assumed to be an external TopicTree node that is combined with current tree (see Section 4.3).
subtopic.dat http://example.com/my/external/topic/tree/ext_topic.dat |
The most complicated components in TopicTree are custom Popup Forms. They can be used to reach external web service and control it using HTML form input. This is useful for direct access to search engines, for instance. Popup forms are marked by POPUP| followed by a note, base address and custom address, again separated with |-marks. Custom address must be terminated with | as well. The actual link is formed from user input appended to custom address. For example, the following line generates form for searching with Google search engine:
POPUP|Google|http://www.google.com/|http://www.google.com/search?q=| |
At the current point of development, TopicTree is extremely vulnerable to hostile to malicious users. When left in the public WWW anyone can edit your topic data or even clear the files or populate them with spam. Therefore, if you have important and/or sensitive data in TopicTree you should protect it with web server authentication or at least by placing the tree in a directory that has no incoming links and is protected by robots.txt so search engines won't index it.
Naturally, when used in non-hostile environment, TopicTree can be used as a simple collaborative environment like a small-scale wiki. TopicTree has no support for concurrent updates so if many people happen to update the same topic, the last update is saved.
Multiple topic trees can be combined in a single tree. External topic link can point to any http URL that contains a TopicTree dat file. The system fetches the whole tree from other site and presents it as if it were part of your tree. However, you can't edit external TopicTree nodes when combined to another tree.
User management and easier integration of different TopicTree sources, ability to publish TopicTree in a read-only HTML format.
UI-enhancements: ability to delete nodes (combined with user management) and to move topics around the tree.
A standard internal representation format, perhaps OPML or limited subset of Topic Maps.
Improved performance for large (>400 nodes) trees.
The essential code that lead to implementation of TopicTree software was published as a FAQTS.com entry by J V, Martin Honnen and Pat Friedl. Textarea autoresizing UI code is based on Paul Tuckey's javascript textarea sizer. Peter-Paul Koch's JavaScript Section (now called QuirksMode) has been a most important general JavaScript reference.
Version: MPL 1.1/GPL 2.0/LGPL 2.1
TopicTtree is subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.
The Original Code is TopicTree code.
The Initial Developer of the Original Code is Miika Nurminen. Portions created by Miika Nurminen are Copyright (C) Miika Nurminen. All Rights Reserved.
Contributor(s):
Alternatively, TopicTree may be used under the terms of either the GNU General Public License Version 2 or later (the "GPL"), or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), in which case the provisions of the GPL or the LGPL are applicable instead of those above. If you wish to allow use of your version of TopicTree only under the terms of either the GPL or the LGPL, and not to allow others to use your version of TopicTree under the terms of the MPL, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the GPL or the LGPL. If you do not delete the provisions above, a recipient may use your version of TopicTree under the terms of any one of the MPL, the GPL or the LGPL.