Ferret (Frame and JavaScript Enhanced Wiki)

Wikis are ideally suited to collect and manage individual information — ideas, logbook entries, career information, reference material, a good wiki can take it all — allowing you to easily enter and mange this information. However, Wikis were not build for convenience, entering information and creating new pages is tedious. The following modification uses frames to make a Wiki much easier to handle, facilitating the creation of new pages, tagging, updating entry listings, and much more.

I use DokuWiki as WikiEngine, since it uses .txt files to store the entered text information instead of a database, making backup and access of data without a webserver possible (e.g. quick text entry via Quicksilver + TextWrangler). The modifications would also work with a database-based Wiki (like MediaWiki), however, the commands would need to be changed.

Using Frames

A Wiki that is used with a Webbrowser can — in most cases — be opened in a frame window. A second frame (toolframe) can display tools to facilitate data entry in the Wiki. The Tool Frame can be used in different ways:

• by opening a page in the Wiki Frame with a specific URL
  • to “create” a page by opening a non-existing page in edit mode (in DokuWiki via the “&do=edit” command in the URL, as in: “DOKUWIKIPATH/doku.php?id=PAGENAME&do=edit&rev=”)
  • to “edit” an existing page by opening an existing page in edit mode (in DokuWiki via the “&do=edit” command in the URL, as in: “DOKUWIKIPATH/doku.php?id=PAGENAME&do=edit&rev=”)
  • to display a specific page (e.g. as additional navigation menu or to display all entries tagged with “artworks” with the “&do=showtag&tag=TAGNAME” command in the URL, as in: “DOKUWIKIPATH/doku.php?id=ferretonewordsearch&do=showtag&tag=cat_artworks” (“ferretonewordsearch” is the name of a non-existing page where the results are displayed))
• by using JavaScript to access specific pages
  • to open a page with the current day in the name by reloading the Wiki Frame with a link that includes JavaScript date/time information
• by using JavaScript to access the content of the text area (where the text is entered in the Wiki)
  • to use a Template by replacing the content of the textarea with the template code (e.g. ====== ” + titlenameheader + ” ======\n\n\n\n{{tag>” + firsttag + “}}\n====== eof ======, where “titlenameheader” is the page name entered in the form and “firsttag” is the tag of the category the page is created in (Note: These commands should only be allowed if the text are is empty. Otherwise it will overwrite the existing information.)
  • to enter tags by searching for the tag-code “{{tag>…}}” and replacing its contents by the existing contents + the new tag (Note: this should only be executed if the tag does not already exist on this page, i.e. if a search result for the to-be-assigned tag in the tag-code was “not found”.)
  • to enter Wiki page commands by reading the content of the text area and replacing it with itself + the new command at the end (or any place that can be defined), e.g. the DokuWiki commands “~~NOTOC~~” (no table of contents) and “~~NOCACHE~~” (do not cache this page) are notoriously tedious to write (“~” requires alt + n followed by Space)
  • to enter date or time specific information by using the JavaScript date/time commands, e.g. to create a page with the data as name or a new entry with the current time (great for diary writing)
• by using PHP to do maintenance tasks the WikiEngine is not capable of
  • to update the indexes (Searchindex, Tagindex, etc.) by opening every page of the Wiki in the WikiFrame automatically one after the other for about one second (think “time for a coffee”)
  • to automatically update link lists to pages in the wiki by overwriting the existing page with links to all files in the specific directory (Note: DokuWiki saves the page content in .txt files and allows subdirectories. PHP scans the subdirectory, e.g. “\ideas”, for the file names of its content and creates a .txt file with the results as links in the DokuWiki Syntax, e.g. for a file called “first_idea.txt” the entry [[First Idea]]. Since the created .txt-file is already linked in the Wiki it can easily be accessed.)
  • to display all used tags/keywords to get a complete tag-list and find out which tags were used how often

Example

Overview

I used these modifications with my own Wiki which I no longer open without the Tool Frame (called Keyword Encapsulator-Frame because it all started with searching for an easy way to assign tags). The keyenc.htm file opens my Wiki in the left-hand frame (wikiframe) and the Tool Frame in the right hand frame (toolframe).

Page Creation, Templates, and Maintenance

This page in the toolframe allows the easy creation of new pages, the assignment of Templates and often used DokuWiki commands like ~~NOTOC~~ (no table of contents) and ~~NOCACHE~~ (do not cache page). It also has links to PHP files that rebuild the indexes by opening every page of the wiki for about a second, rebuild a link list to all entries in the “ideas” directory (as 27 pages in the Wiki, one for each letter of the alphabet and one for all numbers), and display all used keywords/tags in the Wiki.

On the left hand side is the Wiki, the yellow page is the toolframe.

1. Links to other pages that are opened in the toolframe. It is easier to dedicate specific .html pages to specific functions (like assigning keywords, logbook entry helps, templates (and creation of new pages and maintenance), and watchlist (essentially an easy-to-edit navigation menu) than to scroll one long html page). Without any modifier links are opened in the same frame, so the links are simple html links like “<a href=”keywords.htm”>Keywords</a>“.
2. Textfield for the name of the page that should be created. The page will be created with DokuWiki, meaning that ” ” becomes “_”, etc.
3. The directory the file should be created in. DokuWiki allows subdirectories which I use for ideas, references, logbook (diary), projects, and career (job related).
4. Create New uses a JavaScript function to first check if the Wiki is not in Edit Mode (otherwise unsaved changes would be discarded) and then reloads the Wiki Frame with the directory name and page name that was entered (page name) or selected (directory name) in Edit Mode. The command is top.wikiframe.location.href = ‘PATHTODOKUWIKI/doku.php?id=’ + checked_box(‘directorytitle’) + “:” + newpagename + “&do=edit&rev=”;
5. Displays the link to the page that was created. If the page should be linked from somewhere else this allows easy copy and paste to avoid having to type the link.
6. Layout-Templates and common commands. If a template is used the textarea of the Wiki is accessed via content = top.wikiframe.document.forms[0].wikitext.value; (forms[0] can depend on the DokuWiki template used, in my monobook version it is [0], the DokuWiki default template is [4]). If the content is not empty, the template is not assigned. This prevents accidental overwriting of the textarea where unsaved entries would be lost.
   NOTOC and NOCACHE append two DokuWiki commands to the textarea. They replace the (always used) code “===== Tags =====\n{{tag>” with either “~~NOTOC~~\n” or “~~NOCACHE~~” and “===== Tags =====\n{{tag>”. I would be possible to simply write the commands at the end of the content of the textarea but I wanted it at a specific place (immediately before the tags). The commands are only added if they are not already used.
7. Rebuild opens every page of the Wiki in the wikiframe for about a second, done via PHP and JavaScript: “echo ‘<script language=”JavaScript”>top.wikiframe.location.href = “PATHTODOKUWIKI/doku.php?id=’.wikidir($directory).”:”.nameonly($files[$i]).'”</script>’; flush(); sleep(1);” (see code section below). This takes a very long time (can be done overnight) but I found that it works better than DokuWikis “Searchindex Manager” or “Tagindex Manager” which are supposed to do the same but do not seem to work correctly in my wiki installation.
8. Search Keywords shows me all the tags/keywords used in the Wiki. Originally written for a colleague of mine who needed such a function to analyze tags it creates a .txt file in my ferretscripts directory where it first writes down all tags and then the name of each page and which of the tags are used (as a table, 0 = not used, 1 = used, tab-separated). The file can be loaded into SPSS (statistics package) to analyze which tags are used how often and in which files, which occur together, etc.

Assigning Keywords/Tags

The idea of using Frames started when I was trying to assign tags, which was tedious: not only did I have to remember the correct names of the tags but I had to type the same text over and over again. The file in the toolframe/Keyword-Encapsulator-Frame allows easy assignment of tags.

1. Same navigation links as in any file in the toolframe.
2. Links that use a JavaScript function via “<a href=”javascript:transfer(‘cat_technical’)”>Technical</a>” or “<a href=”javascript:transfer(‘idea_own_work cat_project cat_articles cat_psychology cat_research cat_career’)”>ΨForschungsidee</a>” for multiple tags with one click. The function “transfer” checks if the page in the wikiframe is in edit mode (top.wikiframe.document.URL includes “do=edit”) and if so, it checks if the tag is already assigned (gets the {{tag>…}} part and searches for the ” ” + tagname + ” ” and ” ” + tagname + “}}”, this prevents accidental false hits, e.g. when searching for the tag “technical” which is included in “non_technical_solutions”). If the tag is not found, it replaces “}}” of the tag-code with “tagname + }}”, thereby appending the tags with the new tag. To allow for easy searching of individual tags a click on the tags while the wikiframe page is not in edit mode searches for this tag, with the command “targetlink = “DOKUWIKIPATH/doku.php?id=ferretonewordsearch&do=showtag&tag=” + tagline; top.wikiframe.location.href = targetlink;“.
   This way tags can easily be assigned to a page as long as it includes the {{tag>…}} code (comes with every template I use). I can quickly scroll the list to see which tags fit. I do not have to remember which tags I have already assigned as an accidental double assignment of an already existing tag is not possible (one future idea is to scan the tag code and mark the tags that are already assigned). If I have assigned the wrong tag, a double click on the tag in the textarea and pressing delete removes it.

Logbook Entries (Diary)

This solution can be very helpful for diary entries. Here it is used in combination with the JavaScript DATE/TIME functions.

• New Entry
  Uses JavaScript to search for “===== Tags =====\n{{tag>.*}}” (which is included in each Logbook Template I use) and replaces it with “—-\n\n” + givemeTime() + “\n\n” + itself, thereby inserting a new entry with the current time.
• Edit Today
  Opens the logbook file for the current date in the wikiframe via “top.wikiframe.location.href = ‘http://localhost/~ipsych/ipsychwiki/doku.php?id=logbook:’ + givemePureDate() + “&do=edit&rev=”;” if the wikiframe is not in Edit Mode (“if(top.wikiframe.location.href.search(/edit&rev/g) == “-1”)” is true).
• Logbook Template
  Transfers the template I use for logbooks, consisting of the date in the title of the page, a first entry with the current time, the tag-code and an end-of-file marker. Done via “tagline = “====== ” + givemePureDate() + ” ======\n\n” + givemeTime() + “\n\n===== Tags =====\n{{tag>logbook}}\n====== eof ======”;” if the textarea is empty (“inhalt = top.wikiframe.document.forms[0].wikitext.value;” => “inhalt.length == 0” is true.

Watchlist (Easy-to-edit Navigation Menu)

An other link in the toolframe leads to the watchlist. It is an extra navigation menu where the currently “hot” articles are listed.

To allow easy editing of the list, the list itself is a page in the wiki that is read with PHP. The PHP file translates the DokuWiki links in HTML-Links (e.g. “[[wiki_control|watchlist]]” to “<a href=”DOKUWIKIPATH/doku.php?id=wiki_control:watchlist”>wiki_control:watchlist</a>“.

The Code

The code is in the following files (zipped) as ferret_0-7.zip. This gives you an idea how this solution was programmed. You will have to search for DOKUWIKIPATH and replace it with the absolute link to your DOKUWIKI folder. If you use an other template than the monobook template, you probably have to exchange the forms-number in “top.wikiframe.document.forms[0].wikitext.value” (4 for the default DokuWiki template).

Important Notice: I do not take any responsibility nor do I offer any warranty that the files work as intended. These files were written in my spare time (and I am psychologist, not computer scientist), so do so at your own risk.

Note 2: Check the comments to this page. You find hints on using this files from someone who tried it out.

The files contain some remarks and variables in German. When I have the time, I rewrite it in English, for now this must be sufficient. I know that the programming is atrocious, feedback for improvement is appreciated.

ferretscripts_0-7

Files with description

• keyenc.htm (opens Wiki and the Tools in frame windows)
• keywords.htm (Assigning Keywords)
• keywords_logbook.htm (Logbook/Diary functions)
• templates.htm (Create New Page, Templates, Maintenance)
• rebuild.php (opens every page in the Wiki for one second, one after the other => rebuilds indexes)
• searchkeywords.php (exports all keywords and a list of all files of the wiki with the information if the keyword was used or not)

File location

Create a new folder in the dokuwiki directory (on the same level as bin, conf, data, inc, lib, etc.) called “ferretscripts” and place the files into this directory. It is possible that you have to change the read/write permissions, since searchkeywords creates a .txt file called output.txt in that directory.

Further Ideas

I have some ideas what to implement when I have the time (i.e. between the next time I feel the need to create and never):

• Optical changes (increases usability)
  • Using images/image-maps in the toolframe (e.g. for assigning tags, etc.)
• Tagging
  • showing which tags are already assigned (highlighted), click on highlighted tag removes it
  • search for multiple tags at the same time by clicking on tags on a search page
  • PHP script that searches for all entries with (a) given tag(s) and exports the content in a combined file
  • PHP script to tag a page without having to open it
  • information which keywords are assigned how often, if more than one keyword is selected the number of pages where both keywords are used is listed (if combined with “+”) and the number of pages where the first keyword is listed but not the second (if combined with “-“), etc. for more than two keywords
  • PHP script that shows the untagged files and allows easy tagging
  • finding similar pages that have nearly the same tags assigned
  • complex search functions with +, -, etc. for tags
  • replace keyword with other keyword (e.g. used “idea” and “ideas”, should only be “ideas”, solved it with TextWrangler but would be nice to include such a function)
• Maintenance
  • PHP script that compares the images in the media directory with the images already used in the wiki, shows which image references in the wiki are broken (missing images) and which images are not used (missing links)
  • PHP script that connects all diary entries with each other be including links to the previous entry (and not the previous day) and the next day (should improve navigation through logfile entries)
• TextArea Modifications
  • Tidy Up Code => checks the code for unnecessary characters (e.g. line ends with ” “) and gives warnings if the blank spaces in listings are not divisible through 2 (in DokuWiki a listing is ” ” + ” ” + “*”.
• Editing or Insert Commands/Code
  • Textfield with filename and link that inserts the code for videos (via file linking)
  • more complex writing tools
  • formating the content after it was inserted from another program (e.g. Circus Ponies Notebook Outline) into DokuWiki Code
  • Increasing or decreasing the headers one level
• Navigation
  • Instead of opening every page for one second the script could wait for a click (e.g. on “next”) to allow simple skimming through the contents of the Wiki, a page at a time. “Previous/next page” buttons and an index to chose from would also be nice.

Other Applications

Besides using this Frame-solution for individual Wikis, the following uses are also possible

• Allowing collaborative tagging with a predefined tagging list
• Giving additional writers’ tools for editing Wiki(pedia?) articles, e.g.:
  • a search field where you can look for the names of Wiki(pedia) pages you want to link to
  • Links to hints/rules/etc.
  • Copying often used commands that are not covered by the edit bar
  • textarea with a preview button to preview small pieces of Wiki(pedia) syntax instead of having to preview the whole section/page
  • a page with a complex formula editor (think Microsoft Word Formular Editor)
• using PHP to display pages that were not already tagged or only tagged by one colleague (to get at least two people to tag a page)
• etc.

Why Ferret?

I called the solution “Ferret” because I value the speed with which it can be used and the animal (and the Wing Commander II fighter) symbolizes this for me. Compared to fully-fledged CMS-like WikiEngines, DokuWiki is rather simple (or better: “sleek”), making it very fast. Ferret enhances DokuWiki with some (needed) functionality and makes data entry much, much faster.

Update:

I forgot to mention — if anyone wants to work on the files and put them online — go for it. 🙂
I made Ferret for myself, because I use my Wiki every day and it was tedious to enter data, which Ferret pretty much solved (for me). As different users of a Wiki have different demands, feel free to modify and distribute it (a citation/reference to this page — http://www.organizingcreativity.com/2009/09/ferret-frame-and-javascript-enhanced-wiki/ — would be nice).

More about this topic

• DokuWiki Adjustments
• Some Major DokuWiki Adjustments