This document describes the licensing terms for the Friki software, how to install it, and how to configure and tune it to your needs once it is installed.
This is the "free" version of Friki. It is copyright (c) 2002 Frank Carver, and licensed under the GNU Public License (GPL) version 2. If you wish to use the Friki software, in whole or in part, in an application or situation incompatible with the GPL, we are willing to consider other, less-restrictive, licensing terms. Note, however, that there may be a charge for this option. Please contact us at firstname.lastname@example.org to discuss your needs.
The latest version of Friki is available from http://www.efsol.com/. If you got this software or this document from another source, please check that you have the latest version.
Friki 2 comes in three builds, so it's important to make sure you have the right one for your system and your needs.
Both "OneDotFour" and "OneDotThree" support the full "classic" Wiki markup with the addition of the common "interwiki" syntax for linking to pages on other Wikis. They should immediately be comfortable for anyone who has used the original Wiki.
If you are in a hurry, Friki 2 can be installed as quickly as you can copy a file!.
You will need a working Servlet Container or Application Server which implements at least version 2.3 of the Java Servlet API. Friki 2 has been tested on Resin 2, and Tomcat 4, and sticks to the specification, so it should work on all other compliant servers. Please let me know if you find a server it won't work on, but remember to check that you are using the correct Friki build for your system first.
All you need to do is drop the file "friki.war" into the "webapps" directory of your servlet container. Most smart containers should recognize the new application automatically, but you may need to restart the container if yours gets confused. Once the container has recognized, deployed and initialized the web application (which may take a few minutes), you should be able to view a page by appending friki to the URL of your server. For example, if I have a server at http://tomcat.efsol.com/, I can access Friki at http://tomcat.efsol.com/friki, or if you have a server at http://localhost:8080/, you can access Friki at http://localhost:8080/friki. Now you can view the existing pages, search, edit and create new pages to your heart's content.
That was straightforward, wasn't it!
Warning! However, there is one thing to beware of if you run Friki this way. Any changes you make or new pages you create will be stored in the "temporary directory" provided by the servlet container as part of the servlet specification. It's the only way to make an application work "out-of-the-box" like this, but it can be a little dangerous. The servlet API specification is vague about what should happen to the contents of this "temporary directory" if you reload or modify a web application. I can't control how your container behaves in this respect, and I'd hate to see a lot of hard work and information inadvertently lost if you upgrade or reinstall later. By all means run Friki this way to check it out, and see how it works, but I strongly recommend that you configure your installed Friki to use a different, more permanent, directory for your files before you use it "for real".
All of the following configuration and customization instructions assume you have an "expanded" installation of the Friki web application "war" file. All files mentioned are relative to this expanded directory.
Almost all servlet containers expand each web application into its own directory when it is deployed. If your server doesn't automatically expand the deployed web application you will need to expand it yourself using something like "WinZip" or "jar". You should make sure that you expand the "war" to a subdirectory of a directory monitored by the server. Typically this will be the same "webapps" directory in which you placed the "war" file, so you could for example use jar xf friki.war friki.
Before you start modifying the expanded web application, you should remove the original "war" file from the webapps directory, to ensure you don't get any conflicts. This may require stopping the server.
Some servlet containers will automatically detect a change to web.xml or other files and reload the web application after your changes. For others you will need to restart the server.
One of the first "customizations" you should consider is where the pages are stored.
<init-param> <param-name>location</param-name> <param-value>*TMP*</param-value> </init-param>The *TMP* is a special token which tells Friki to use the container "temporary directory". Change it to the full path to your chosen directory, and save the file.
There is a small selection of pages supplied with Friki, but you are not limited to viewing and editing these pages. Creating new pages is very easy, and users should be encouraged do it in the normal course of using Friki..
Sometimes you need to delete a page. In a live system, used by many people, you should think very hard before doing it, as it might easily break links on other sites. If at all possible, just remove (or move) the content of the offending page, and replace it with a note explaining what happened. I provide no way for casual Friki users to delete a page. Deleting a page is considered an admin operation.
When you access friki without specifying the name of a page, it shows the configured "default page". As delivered, this is set to "FrontPage", which is a reasonable default for many uses, but might be inappropriate for yours.
<init-param> <param-name>dflPage</param-name> <param-value>FrontPage</param-value> </init-param>
Whenever Friki starts up, it checks that a minimum set of basic pages are present. For the great majority of Friki installations, these will probably pose no problem, but if you need to change which pages are treated this way, you can.
It's important to note, however, that there are two types of initial pages: those that are just example content, and can easily be changed (by default these are FrontPage, PageFormatting and SandBox); and those which are used by Friki itself for logging (by default these are ReadRequests and RecentChanges). Changing the "example content" pages is simple and is described here. Changing the Friki logging pages is a bit more complicated, and should only be considered if these page names are really abhorrent. See "To change the way Friki logs pages", below.
To change the example content pages
The next time Friki reinitializes, it will ensure that your real page store contains these initial pages.
I find it hard to imagine, but you may not want to offer an application called "friki" on your web site. If this is the case, you can call the application anything you like (within the limits of acceptable URL directory names).
If you wish to install more than one Friki on your web site (for example, one for staff use, and one for customer use, or one for each of your product areas), you can't call both of them "friki". Follow the process described above in "to change the name of the application", but copy the directory rather than moving it. Remember to configure each Friki instance to use a different directory for page storage, or things may get very confusing!
Using this technique will allow you to install as many Friki's as you want.
The default page style of Friki is functional but bland. You can easily change the page style, maybe to integrate with the "look and feel" of other pages on your site, or maybe just because you don't like it.
You can even alter the button text for the buttons "EDIT THIS PAGE", "SEARCH", "SEARCH AGAIN", and "COMMIT CHANGES". This is slightly more complex, and has two steps.
By default, each time anyone views or changes a page, Friki logs it. This is usually very useful, as it allows users and administrators to discover which pages are popular, and what topics are active. Like many other aspects of Friki, this behaviour is also configurable. If you don't wish Friki to log pages, or you wish to change the page that the access logs go to, you need to add a new "init-param" to override the default behaviour.
To disable logging of page reads:
<init-param> <param-name>logReads</param-name> <param-value>false</param-value> </init-param>
To disable logging of page changes:
<init-param> <param-name>logWrites</param-name> <param-value>false</param-value> </init-param>
To change the page used for logging of page reads:
<init-param> <param-name>readLogPage</param-name> <param-value>your new page name</param-value> </init-param>
To change the page used for logging of page changes:
<init-param> <param-name>writeLogPage</param-name> <param-value>your new page name</param-value> </init-param>
Once you have added any of these init parameters, I suggest you delete or rename the existing log pages. If Friki tries to log to a page which does not exist or which does not have the "content.prefix" attribute set to "<pre>" and the "content.suffix" attribute set to "</pre>" you may not get the behaviour you are expecting.
As your Friki installation becomes popular, you will notice the log pages growing ever longer. After a while they may also get irritatingly slow to load and browse.
Trimming long log pages is actually simpler than it might appear. Both the read and change logs are stored as regular Friki pages, so to trim them all you need to do is hit the "EDIT THIS PAGE" button, and delete a bunch of old lines.
As part of the build process, every time Friki is compiled the latest copy of the official intermap.txt file is downloaded and included in the application. After a while the copy with your Friki might become out of date. If this is the case you can simply edit the file WEB-INF/classes/intermap.txt yourself. Alternatively you can download the lastest version of the master list and copy it over the local file.
You will need to restart Friki after updating this file.
|Version 2.0.2||20 Nov 2002||Frank Carver|