---
---+ Koala Skin Version 1.18 - Instructions

By Colas Nahaboo. http://colas.nahaboo.net
	* Graphical design by Thierry Kormann, http://koala.ilog.fr/tkormann
	* Koala Skin Distribution: 
	  http://twiki.org/cgi-bin/view/Plugins/KoalaSkin
	  (Download at the end of the topic)
	* Discussion, support: 
		* http://twiki.org/cgi-bin/view/Plugins/KoalaSkinDev
		* koalaskin@koala.ilog.fr is the mailing list for people 
		  wanting to follow closely discussions on TWiki:Plugins/KoalaSkinDev
		  Topics discussed on the list will be summarized on the wiki
		  topic, and new developments on the topic will be announced 
		  there.
		  See: http://koala.ilog.fr/mailman/listinfo/koalaskin
		* koalaskin-announce@koala.ilog.fr is where announces (and 
		  nothing else) of new koalaskin version will be posted. If
		  you use koalaskin, *please susbcribe to this list!*.
		  See: http://koala.ilog.fr/mailman/listinfo/koalaskin-announce
	* Exemple of public sites using it: 
		* http://koala.ilog.fr/wiki
		* http://www-sop.inria.fr/wiki/bin/view
		* http://wiki.enst.fr/

*Contents:*
%TOC{depth="2"}%

---++ Design goals

This skin has been designed to be able to use TWiki to replace an
internal web site, with potentially a large number of webs (48 now) and
users. The goal was to provide a look and feel close to well known web
sites, but not hiding too much the Wiki-ness of it. We wanted also to
do it in clean HTML+CSS code, with as less images as possible.
It should be both simple to the novice and close enough to traditional wikis
for the expert. 
We emphasised the coherence of the look and the runtime efficiency over ease
of modification by anyone from the web.

Although this is freeware code, and there is no formal support, as this skin
is in use daily at vital sites for our company, it will be maintained
actively.

This implementation also keeps a lot of the templates structure of the
original TWiki templates. 
	* A wiki page Main.WebList is written to describe the web 
	  pseudo-hierarchy.
	* A shell (bash) script generates the TWiki templates from this 
	  description.
	* This is developped on unix only, 
	  but it works on windows with cygwin (with the gcc devel package 
	  installed) since version 1.8.
	  Note that templates can be generated on a unix machines (on each
	  new web creation), and then uploaded to a non-unix web server
	  running the TWiki system.

*Features of the skin:*
	* a navigation bar on top with tabs for web names provides a
	  pseudo-hierarchy and allows handling many webs
	* there is one level of hierarchy: a web can have sub-webs
	  (the system could be expansed easily for any depth)
	* only level-1 webs ("group webs") have specific colors. This is
	  to reduce the "rainbow effect" plaguing big TWikis. Subwebs use 
	  the same color scheme as their group leader
	* user only give the hue of the webs and common page background color,
	  rest of is deduced
	* hierarchy is flexible: a web can be in several groups
	* editing saves directly without going through preview. Note that 
	  convenient buttons are provided to also from the edit view, in 
	  one click:
		* *Save* Save topic and return to normal view
		* *QuietSave* Save but will not trigger email notification 
		  to people monitoring the page (same as checking the 
		  "Minor changes" checkbox) 
		* *Checkpoint* Save, and re-edit immediately
		* *Preview* The old behavior: Do not save yet, but show 
		  what the topic would look if saved
		* *Cancel* Discard changes and return to view mode, release
		  lock
	  Note that these buttons are also available from the Preview view,
	  with a convenient *Back* button to get back to the Edit view.
	* a search menu provides a quick familliar central point to search,
	  go to and create topics
	* one can search easily all the webs in the group by the search  menu
	* nearly nothing is used from the web preferences, for ease of 
	  management of a big number of webs. 
	  Everything is defined in a single wiki topic
	  Main.WebList. A script then generates (compiles) templates 
	  from this information, lowering runtime overhead.
	  Note that this will generate about 120k of templates per web.
	* We tried to use CSS for defining the looks, rather than the
	   =%<nop>XXX%= twiki variables, but staying within a subset of CSS 
	  understood by most browsers.  
	* New WebPreferences variables:
		* =%<nop>TOPICS%= can hold a web-specific list of interesting 
		  topics for the web, to place in the left menu
	* a site map (similar to the <nop>WikiWebTable) is generated.
	* skin is easily upgradable: just untar a new distrib in the wiki dir.
	  Distributed files should not be customized: customization happens
	  in other files for which the distributed script can generate an 
	  initial form. For instance this file is distributed as an
	  attachement that is included in the locally-modified topic. Thus 
	  upgrading will overwrite the attachement but not the local text.

*Known Problems*
	* Normal use works on Netscape 4.x. Bugs in this browser will show
	  easily for some user constructs due to the use of nested tables.
	  (blockquotes with long lines)
	  I provide an ugly hack for this, FixForNS4Blockquote.patch 
	  on TWiki:Plugins/KoalaSkinDev
	* Generation of templates is straightforward if you have shell access.
	  If not (hosted sites), you will have to generate locally the 
	  templates and upload them.     

---++ Quick Start

For the impatient, here is what to do to use it:

*For a new install:*

	1 Go into your wiki dir
	2 Uncompress the distrib there
	3 Edit the =DIR= variable in the script =bin/koalaskin-generate=
	  (not necessary if you run it from the twiki install dir).
	  to the directory where TWiki is installed.
	  If the data and templates dirs are not in the default location
	  (just in DIR), change also the =data= and =templates= vars 
	  underneath.
	  Edit the main variable to the web you put WebList if not Main,
	  i.e. if you redefined %<nop>MAINWEB%          
	4 Set in your global web preferences:
	  <br> _6 spaces_ * Set SKIN = koala
	  <br> _6 spaces_ * Set TOPICS = 
	  <br> _6 spaces_ * Set EDITBOXSTYLE = width: 99%
	5 Apply the following fixes if they are not already on your system:
		1 TWiki:Codev/ThisWebNameMultiple
		2 TWiki:Codev/PostfixArgToParentMeta
		  (the <nop>ParentSuffix.patch, since v1.5, *not* the
		  the <nop>ParentPostfix.patch !)
		3 in bin/view, add after the line 76: 
		<br>&nbsp;&nbsp; =my $skin = ...=
		<br>the 2 lines:
		<br>&nbsp;&nbsp; =my $viewMeta = $query->param( "meta" ) || "";=
		<br>&nbsp;&nbsp; =if ($viewMeta) { $viewRaw = "debug"; }=
		4 TWiki:Codev/RefreshEditPage
		5 TWiki:Codev/TerserSignature
		6 TWiki:Codev/SkinParamOnAllTemplateReads
	6 In bin/.htaccess, say that savemulti needs valid-user, i.e. add:
		<br> =&lt;Files "savemulti">
		<br> &nbsp;&nbsp; =require valid-user=
		<br> &lt;/Files>
	7 Create a topic Main.WebList (or %<nop>MAINWEB%.WebList if
	  you changed the name of the Main web)
		* Fill it with the output of the script 
		  =bin/koalaskin-generate -i=
		  This will give you help on usage.
		* Edit and Complete it by the list of your webs. 
		  See for instance:
		  http://koala.ilog.fr/wiki/bin/view/Main/WebList
	8 Create a topic Plugins.KoalaSkin. In it put any text you want
	  to describe your local explanations if needed, and this line
	  that will include this readme:
	  <br>&nbsp;&nbsp; =%<nop>INCLUDE{%<nop>ATTACHURL%/TWikiKoalaSkin.txt}%=
	9 Execute the shell (bash) script =bin/koalaskin-generate=
	  You must have write access to the templates/ subdirectory
	10 Subscribe to koalaskin-announce@koala.ilog.fr, 
	  See: http://koala.ilog.fr/mailman/listinfo/koalaskin-announce
	  to be kept informed of new versions

---++ Detailed info

*For upgrading a previous <nop>KoalaSkin install:*
	1 Go into your wiki dir
	2 Uncompress the distrib there
	3 (optional) edit the variables at the top of script 
	  =bin/koalaskin-generate= : DIR, data, templates, main
	4 check history at the end for new features, things to do,
	  patches to apply since the previous version.
	  *items prefixed by [!]* indicates actions you *must* perform.
	5 re-generate templates by running =bin/koalaskin-generate=

*To change layout:*
	1 edit Main.WebList under TWiki
	2 re-run =bin/koalaskin-generate= in shell

*Options of the =bin/koalaskin-generate= script*
	* <b>-i</b> outputs a template of what should be the WebList topic,
	  ready to cut and paste, with description of the available options
	* <b>-d</b> generates a tar/gzip distribution in /tmp

*To add per-web specific topics:*
(to the Topic menu on the left), define the
TOPIC variable in the web WebPreferences topic, as a list of topics
separated by &lt;br> (line breaks) 

You may want to allow for redefining per web  some of the globally-defined
variables such as:
	* KSCOLORBG the color of the page background 
	* KSCOLORUNSEL color of tabs of unselected web groups
	* KSCOLORSEL color of the text of the selected tab
	* KSICON upper-left wiki icon IMG tag, with dims. If you want it 
	  to appear in mailed changes, do:
		* use full URLs, like %<nop>PUBURL% 
		* put two spaces between =img= and =src= in the tag to fool
		  the image-removal code of TWiki
	* KSLMARGIN left margin (default 150)
	* KSTABWIDTH minimum width of web tabs (default 80)
	* KSNOICONS if set to true (actually any non-empty string)
	  generates templates not using any images for the row of
	  buttons on the upper right: Home/Edit/Attach/Sitemap/Help
	* KSHELP the url the user gets to when clicking the Help icon
	  defaults to: %SCRIPTURLPATH%/view%SCRIPTSUFFIX%/TWiki/WelcomeGuest
	* KSNOEXPAND if set to something else than "false", will not
	  expanse templates at generation time, saving space (for a 18-web
	  wiki, makes templates dir use 2.3M instead of 5.7M, compared to
	  0.4M without KoalaSkin). Expansion saves disk access on each 
	  web request, though.
To do this, set in Main.WebList the variable to a %-var, that you will
have to define the default in the site preferences in TWiki.TWikiPreferences,
that then can be used to define things per web. For instance, in
Main.WebList, with the following declaration you will be able to use
%=%<nop>TOPICON%= to redefine the upper left icon per web.
		* =Set KSICON = %<nop>TOPICON%=

*Customizations:*
If you change the distributed templates, please provide feed back so we can
see if we can change the skin to get your changes as configuration tweaks in
Main.WebList, to ease your future upgrades. The goal is to provide variables
in Main.WebList to specify your customizations, so you only have to call the
generate script without remembering to add options or patch things afterwards.

*Notes:*
	* If you have in your bin/.htaccess the script "save" declared,
	  repeat the same declaration for "savemulti"

*To enable generation of templates via the web*

You must allow the UID under which runs the web server (nobody, www-data...)
able to modify, if they exist already:
	* templates
	* templates/styleneutral.koala.tmpl
	* templates/sitemapwebs.koala.tmpl
	* templates/*/*.koala.tmpl
You can do for instance (once will suffice) a:

chmod a+rw templates templates/styleneutral.koala.tmpl \
  templates/sitemapwebs.koala.tmpl templates/*/*.koala.tmpl

Then, add to the <nop>WebList topic the following HTML code:
<pre>
After editing this topic, you must click on this link:
&lt;a href=%<nop>SCRIPTURL%/koalaskin-generate>Regenerate templates&lt;/a>
to commit your changes.
</pre>

Then, after editing the topic, clicking on the above link will re-generate the
templates. But once you do this, you may not be able to re-generate from the
shell from a non-root account.

---
---++ Implementation

---+++ Files in distribution

	* =pub/Plugins/KoalaSkin/TWikiKoalaSkin.txt=
	  This readme. Should become the Wiki page describing it once complete.
	* =bin/searchmulti=
	  CGI script to implement the multipurpose search menu.
	* =bin/savemulti=
	  CGI script to implement save/checkpoint/cancel/preview choices 
	  in edit templates. 
	* =bin/koalaskin-generate=
	  Shell script to compile per-web templates from the main ones.
	* =templates/sitemap.koala.tmpl=
	  Stub template for the site map of all webs.
	* =templates/style.koala.tmpl=
	  Stub CSS stylesheet.
	* =templates/twiki.koala.tmpl=
	  Main template definitions
	* =templates/view.koala.tmp=
	  =templates/edit.koala.tmpl=
	  =templates/preview.koala.tmpl=
	  =templates/attach.koala.tmpl=
	  =templates/changeform.koala.tmpl=
	  =templates/moveattachment.koala.tmpl=
	  =templates/oopsmore.koala.tmpl=
	  =templates/renamebase.koala.tmpl=
	  =templates/rdiff.koala.tmpl=
	  =templates/search.koala.tmpl=
	  =templates/searchbookview.koala.tmpl=
	  =templates/searchformat.koala.tmpl=
	  =templates/searchmeta.koala.tmpl=
	  =templates/searchrenameview.koala.tmpl=
	* =templates/changes.koala.tmpl= 
	  Emailed template on WebNotify
	* =templates/ks_leftbar.koala.tmpl=
	  Template modules, prefixed by ks_ to differentiate from full
	  standalone templates
	* =pub/Plugins/KoalaSkin/home.gif=
	  =pub/Plugins/KoalaSkin/edit.gif=
	  =pub/Plugins/KoalaSkin/attach.gif=
	  =pub/Plugins/KoalaSkin/help.gif=
	  =pub/Plugins/KoalaSkin/print.gif=
	  =pub/Plugins/KoalaSkin/sitemap.gif=
	  Icons used in the view templates.

---+++ Generated files by shell script
For each web =Foo=, the script create a template dir =templates/Foo= and 
generates in it the files:
	* =attach.koala.tmpl=
	* =changeform.koala.tmpl=
	* =edit.koala.tmpl=
	* =moveattachment.koala.tmpl=
	* =oopsmove.koala.tmpl=
	* =rdiff.koala.tmpl=
	* =renamebase.koala.tmpl=
	* =search.koala.tmpl=
	* =searchbookview.koala.tmpl=
	* =searchformat.koala.tmpl=
	* =searchmeta.koala.tmpl=
	* =searchrenameview.koala.tmpl=
	* =sitemap.koala.tmpl= General outline of the sitemap pages
	* =sitemapwebs.koala.tmpl= The actual sitemap seen from this web
	  (current web is higlighted for a "you are here" effect)
	* =style.koala.tmpl= The CSS definitions for this web
	* =twiki.koala.tmpl= Definitions used in other templates
	* =view.koala.tmpl= The most used template: viewing pages
	* =websbar.koala.tmpl=
	  The navigation bar on top of page with web names in tabs

Generates also the common templates in templates dir:
	* =styleneutral.koala.tmpl=
	  The common part of the CSS style (without per-web colors) to use
	  for the sitemap
	* =sitemapwebs.koala.tmpl=
	  The template stub for the actual per-web sitemap templates

---+++ Templates changes from standard TWiki ones
Most templates changes consist in adding 
	* a CSS style: 
	  =&lt;style type="text/css">%<nop>TMPL:INCLUDE{"style"}%&lt;/style>=
	* a backgound color: =&lt;body bgcolor="%<nop>KSCOLORBG%">=
	* a header definition =%<nop>TMPL:DEF{"heading"}%...%<nop>TMPL:END%=

---++ Misc
	* Quoting =%<nop>WEB%= in templates is done by: =%<nop>&lt;WEB>%= 
	  (for search templates, which use the =%<nop>REPEAT%= construct)
	* The colors of webs are defined as CSS classes:
		* bg1-%WEB% for the darker color
		* bg2-%WEB% for the lighter color

---++ TODO
May be be done for next version:
	* top/bottom links
	* menu entry for an external search engine
	* make templates for the TWiki:Codev/SimpleTableEntryUsingForms
	* "web service": way to get/lock/store raw contents from http
	* search group for topic name (menu / search page?)
	* factorize CSS in external URLs (one per group)
	* allow use of (web/site?) local stylesheets
	* offer some embeddabe macros
May be done in the future, no guarantee.
	* access keys as per  http://twiki.org/cgi-bin/view/Codev/AccessKeys
	* tabs to external webs
	* rewrite in a more standard language (ruby, perl?)
	* index / topics names are confusing
	* be able to include a groupmap in any topic
	* use a favicon: <link rel="icon" href="icon-path.png"
	  type="image/png"> (must check that it works under IE)

---
---++ History of revisions
*Warning:* 
*[!]* denotes actions you MUST perform when upgrading from previous version
	* *1.18* _23 Aug 2002_
		* bugfix: navigation bar was badly generated in some cases
	* *1.17* _21 Aug 2002_
		* *[!]* add the line to your Site Prefs
		  (TWiki.TWikiPreferences), to be forward-compatible with the
		  upcoming TWiki release.
		  <br> _6 spaces_ * Set EDITBOXSTYLE = width: 99%
		* bugfix: names like WebHome have been replaced by their
		  "meta" name, (e.g.: %<nop>HOMETOPIC%)
		* bugfix: sitemaps were broken in 1.16 (bad html comment
		  syntax: -- is forbidden in comments, but browsers didnt mind
		  before...)
		* bugfix: search result pages header colors were broken since
		  1.14  
	* *1.16* _09 Aug 2002_
		* bugfix: CSS was misplaced on some views (search, diff...)
		  (bug introduced in 1.14 found by Jon Reid)
		* bugfix: some garbage could be seen in some views in the
		  parents field on some pages.
		* bugfix: cleaning pass on html to pass W3C validator
		  http://validator.w3.org/ .
		  Tested: view, diffs, changes.
		  Work remains to do for other scripts (edit), but may imply
		  more fixes to TWiki itself.
		* for validation, you may want to apply also this patch:
		  http://twiki.org/cgi-bin/view/Codev/InvalidHtmlFixRdiff
	* *1.15* _08 Aug 2002_
		* new option variable KSNOEXPAND for space-tight people, to
		  use the same template/ space as 1.14 and before.
		  (no need to upgrade if you do not need this option)
	* *1.14* _07 Aug 2002_
		* *[!]* bugfix: when saving with the bottom save button from
		  the preview view, parent field was overwritten by garbage
		  with %TOPICPARENT%. You must repair the damage done to
		  some pages, see:
		  http://twiki.org/cgi-bin/view/Plugins/KoalaSkinDev#topicparent
		  You can either:
			* edit by hand the pages showing %TOPICPARENT%
			  strings, if some exist on your site.
			* use the automatic shell script:
			  http://twiki.org/p/pub/Plugins/KoalaSkinDev/repair-topicparent
		* mail template redesigned. 
		* Hints for writing KSICON
		* Tests /tmp/hsv2rgbhex & /tmp/rgb2hsvhex before using them
		* new %KSHELP% variable
		* %TMPL:INCLUDES are now expansed at generation time. Much
		  slower at generation, but cuts disks access at runtime.
	* *1.13* _18 Jun 2002_
		* *[!]* you may want to apply the patch to Dec 2001 version:
		  TWiki:Codev/SkinParamOnAllTemplateReads
		  (but nothing serious will happen if you dont)
		* A way to re-generate templates from the web added
		* bugfix: the WebList template outputted with -i was buggy
		  (the * EMPTY line was mistaken for a web declaration)
		* bugfix: when previewing a page containing html forms
		  (such as the registration page), save buttons were inoperant
		  Bug found by Samuel Tardieu.
		* bugfix: Internet Explorer rendered badly the sitemaps,
		  workaround for this IE bug.
		* doc: which patches to apply are more explicit
		* announcements of the koalaskin@koala.ilog.fr and 
		  koalaskin-announce@koala.ilog.fr mailing lists
	* *1.12* _05 Jun 2002_
		* *[!]* Terser signature patch used, but you *must* apply
		  the TWiki:Codev/TerserSignature
		  patch to bin/edit
		* empty groups by declaration. Suggestion of  Matt Wilkie.
		  Put the word EMPTY at the start of the Web description.
		* cosmetic: attachements table left-aligned in view mode
		* %<nop>MAINWEB% everywhere, instead of Main.
		  variable main settable in the script also. 
		* Wiki Name syntax is checked on create topic by menu
		* CSS declarations trimmed (and bugfixed) to be smaller.
		  Simple pages went from 50k to 13k.
		* new KSNOICONS variable for the Web List topic
		* non-clickable links are now not white to differentiate
		  them visually from clickable web tabs
	* *1.11* _11 Apr 2002_
		* bugfix: was not working well if your directory structure
		  differred from the distribution.
		<br> *Note:* No need to upgrade if you had no problem
		  installing the 1.10 version 
	* *1.10* _28 Mar 2002_
		* bugfix: editing failed (javascript error) on old versions
		  (5.0) of IE. 
	* *1.9* _18 Mar 2002_
		* *[!]* Forgot to mention that the <nop>RefreshEditPage patch 
		  should be applied. Apply it if you didnt already!
		* Minor bug fix: QuietSave would not remove lock
		  (change to bin/savemulti)
	* *1.8* _12 Mar 2002_
		* Some fixes to the script to make it run on windows under
		  cygwin.
	* *1.7* _10 Mar 2002_
		* *[!]* Name of install topic changed from <nop>KoalaSkinPlugin
		  to just <nop>KoalaSkin. You *must* rename the topic
		  <nop>Plugins.KoalaSkinPlugin if you have one!
		* This readme is now fully in TWiki syntax. You should create
		  the topic Plugins.KoalaSkin to include it (it is
		  installed as an attachement), see new install instructions.
		* script can be run from twiki dir without setting DIR
		* Created the official distribution page on TWiki:
		  TWiki:Plugins/KoalaSkin
	* *1.6* _8 Mar 2002_ 
		* fixes to colors in search results in bookview mode, and in
		  rename topic (result of search for pages refering to page to
		  be moved)
	* *1.5* _4 Mar 2002_ 
		* *[!]* *NOTE:* if you already applied the fix
		TWiki:Codev/PostfixArgToParentMeta
		you need to change all 5 occurences of postfix to suffix in
		lib/TWiki.pm
		* -d option to bin/koalaskin-generate to generate a distrib
		* Note that the <nop>RefreshEditPage fix is not needed anymore
		(but is not harmful)
		* Use of the ?time=nnnn hack in edit pages
	* *1.4* _28 Feb 2002_ 
		* *[!]* patches to apply: #3				 
		* new script bin/savemulti (needs a similar entry to save
		in bin/.htaccess), to provide in edit template 4 buttons: 
		Save, Checkpoint, Preview, and Cancel
		* Raw view with metadata option in More...
		(new koala templates for oopsmore & preview)
		* understands the new var =%<nop>EDITBOXCSS%=
		* uses the new version of the <nop>PostfixToArgParentMeta
	* *1.3* _24 Feb 2002_ 
		* Checkpoint save
	* *1.2* _23 Feb 2002_ 
		* everything works (but with patches to distrib).
		* Announced on TWiki.org
	* *1.1* _20 Feb 2002_ 
		* First functional internal release.
	* _Nov 2001_ First sketches in HTML+CSS by Thierry Kormann

---+ Download
Get the attached <nop>TWikiKoalaSkin.tgz file.
This whole topic is included as the file 
=pub/Plugins/KoalaSkin/TWikiKoalaSkin.txt=
