The Natural Skin Plugin

This is the supplemental plugin for the NatSkin. Its main purpose is to supply "skin states" to control different styles and variants to be switched dynamically while you are online. But see the below for a full list of all provided features.

This plugin tries to be maximal compatible with all past, current and upcomming TWiki releases, namely beijing, cairo and dakar. Therefore some mechanisms have been internalized that are only available on the newest dakar engine, sandbox security and html login dialogues comparable to TWiki:Plugins/AuthPagePlugin. In addition the plugin tries to be interface-compatible to all engines using the Func.pm API. In those cases where this is not possible, because needed functions are not part of the Func.pm API, access functions have been added to address the different implementations and incompatibilities (e.g. access to topic meta data).

This plugin is inspired by the TWiki:Plugins/GnuSkin by TWiki:Main/JoachimNilsson and the TWiki:Plugins/PhotonSkin by TWiki:Main/EstebanManchado (PhotonSearch) renamed to natsearch .

Current Features

• Skin state: an internal representation of different ways to render the NatSkin concerning
  • the skin style,
  • style variants,
  • the sidebar location,
  • the page border decoration,
  • the web buttons in the topbar and
  • the positioning of the search box
• Conditional content:
  • USERACTIONS, NATLOGON: display topic actions depending on the user being logged in or not
  • IFSKINSTATE: render skin differently depending on the current skin state
  • IFACCESS: render different content or include topics depending on access rights
  • IFDEFINED: render content based on twiki variables being defined or not (compare to the IfStatement of the upcomming dakar release)
• skin style control: infrastructure to get, set and display the skin style that is currently active using the NatSkinStyleBrowser
• WebLeftBar: a configurable navigation bar on the left hand side, with topic content on the right;
• MySideBar: every user can extend the sidebar with a personalized navigation
• NatSearch: a search+go box that combines advanced search with the GO feature of twiki
• Login page: independent implementation of a login page (see ) for maximal compatibility with old TWiki releases
• GROUPSUMMARY: render TWikiGroups nicely
• Group based subsription: generate an automated email notification if a new TWiki user want's to join a TWiki Group
• email address obfuscation: all email addresses in topic texts are obfuscated by the use of dynamic html; so mailto links are still clickable while the pure html text does not allow to extract the addresses by respective web crawlers.
• marking external links: add a nice icon to offsite links
• FORMATLIST: render list items according a format parameter (will be externalized into a separate plugin asap).
• Sandbox security: backport of the dakar sandbox

Syntax Rules

Tag	Desciption
%WEBSIDEBAR%	displays the left navigation menu using the WebLeftBar topic
%MYSIDEBAR%	display a personalized WebLeftBar for the user currently logged in
%WEBLINK{web="..." name="..."}%	display a link to a WebHome with the given name and add the SITEMAPUSEDTO description to to the hover balloon
%NATLOGON%	displays Logon|Register for WikiGuest, and WikiGuest|Logout otherewise
%USERACTIONS%	display Edit|Attach|Move|Raw|Diffs|More when logged in and an empty string for WikiGuest
%GROUPSUMMARY%	display list of group members in a TWikiGroups nicely by extracting the GROUP and ALLOWTOPICCHANGE variables of a group topic and adds links "Contact all members" and "Contact all maintainters"; by definition maintainers of a group are those listed in the ALLOWTOPICCHANGE variable of the group topic
%ALLUSERS%	display a list of all registered users generated from the TWikiUsers topic; this is usefull for specific access configurations on beijing and cairo engines (obsolete on dakar)
%KNOWNSKINSTYLES%	render a list of all known skin styles being attachted to the NatSkin topic
%KNOWNVARIATIONS%	render a list of all known styles variations being attachted to the NatSkin topic
%GETSKINSTYLE%	get the current skin style; the priority is (1) urlparam style=<name>, (2) value of the session variable NATSKIN_STYLE and (3) preference value SKINSTYLE set in (a) the user preferences (b) the WebPreferences or (c) TWikiPreferences
%IFSKINSTATE{<tests> then="..." else="..."}%	conditionally returns content depending on the current skin state; <tests> can be style="<name>": test if the current style is <name> variation="<name>": test if the style variation is <name> border="on,off,thin": test if the current border is on, off or "thin" buttons="on,off": test if the web buttons are currently on or off sidebar="left,right,off": test if the sidebar is currently on the right, left or off searchbox="top,pos1,pos2,pos3,off": test if the searchbox is currently on given position or off release="beijing,cairo,dakar": test if the twiki release this plugin is installed on is beijing, cairo or dakar action="view,edit,preview,...": test the current topic action glue="on,off": control wether to eat surrounding whitespaces or not The tag will render the "then" content if all tests evaluate to true and the "else" content otherwise. Tested strings can be regular expressions.
%IFSKINSTATETHEN{<tests>}%   <then content> [%ELSIFSKINSTATE{<tests>}%   <elsif content>]* [%ELSESKINSTATE%   <else content>]? %FISKINSTATE%	This is the multi-line version if %IFSKINSTATE{}% that uses the same tests as above but takes the content from between the sections; thus, arbitrary TWikiML might be rendered conditionaly. Note, that IFSKINSTATETHENs can be nested safely
%IFDEFINED{"<TWikiML>"   [action="view,edit,preview,..."]?   then="..." else="..." glue="on,off"}%	returns "then" or "else" depeinding on the <TWikiML> expression expanding to the emtpy string or not and the current topic action matching the given one; this tag works similar to the IfStatement in dakar but is backwards compatible to beijing and cairo and omits the overhead of an expression parser
%IFDEFINEDTHEN{"<TWikiML>" [action="view,edit,preview,..."]?}%   <then content> [%ELSIFDEFINED{...}%   <elsif content>]* [%ELSEDEFINED%   <else content>]? %FIDEFINED%	This is the multi-line version if %IFSDEFINED{}%; IFDEFINEDTHENs can be nested safely
%WIKIRELEASENAME%	returns "beijing", "cairo" or "dakar" depending on the TWiki engine this plugin is installed on
%IFACCESS{"<topic>" action="" then="..." else="..." mode="" [then_]args="..." else_args="..."}%	display content in then or else argument depending on the access rights of the current user to the topic <topic>;   =action can be view, change or rename specifying the requested access mode; mode can be text or include where text conditionally renders the text in the then and else arguments and text includes the topic in then or else; if then is not specified in include mode then <topic> is included if access is granted; example: %IFACCESS{"AdminSideBar" mode="include"}% includes the AdminSideBar if the current user has view access to this topic
%NATREVISIONS%	substitute for the %REVISIONS% tag which only works on the TWiki:Plugins/PatternSkin (todo: fix REVISIONS)
%NATMAXREV%	substitute for %MAXREV% which differes on beijing, cairo and dakar
%PREVREV%	returns the previous topic revision taking NumberOfRevisions into account
%CURREV%	returns the current topic revision (compatible among all TWiki engines)

About NatSearch

This is a cgi-script that is heavily based on the PhotonSearch of the TWiki:Plugins/PhotonSkin. So natsearch is basically a fork of that including fixes to similar security flaws that hit the WebSearch those days also. Here's the list of differences:

• replaced the a flag with g to indicate global search
• obey the NOSEARCHALL flag for global search
• remember the original search string and insert it back into the input field
• added perl's use strict and fixed all warnings
• fixed several mod-perl issues
• add friendly message when nothing's been found
• light weighted google-like hit colorization

NatSearch can be further reduced to certain webs and topics by setting WebPreferences. Besides the NOSEARCHALL feature of every web that excludes a web from search the following variables restrict the hit set:

Name	Description
NATSEARCHEXCLUDETOPIC	a regular expression that excludes a topic from the hit set
NATSEARCHEXCLUDEWEB	a regular expression that must not match a web
NATSEARCHINCLUDETOPIC	a regular expression that must match a topic in the hit set
NATSEARCHINCLUDEWEB	a regular expression that must match webs to be considered

Furthermore, the variable NATSEARCHTOPICSUMMARY can be set to a TopicFunction that returns a summary text that is to be displayed when a topic matches the search. The TopicFunction is called by using a parametriced INCLUDE of the form

%INCLUDE{"<topic-function>" THISWEB="<web>" THISTOPIC="<topic>"}%

where <web>.<topic> is the current hit to be summarized. The returned text is used instead of the normal text summary of TWiki which extracts the text from the whiteboard area of a topic. This feature is usefull for TWikiApplications where the data of a topic is stored in TWikiForms instead.

Please see the TWiki:Plugins/PhotonSkin for an explanation of the possible search parameters (TODO: maby move that stuff in here).

About the WebLeftBar

The WebLeftBar is used to generate a navigation appearing next to the main topic area. Each web in your Foswiki might optionaly have a separate WebLeftBar. The default System.WebLeftBar can be used to add a default section common to all WebLeftBars. If the WebLeftBar isn't defined the default System.WebLeftBar is used. Each user might define a personalized WebLeftBar called %WIKINAME%SideBar that is appended to the WebLeftBar. The TWiki:Plugins/RedDotPlugin is used to make customizing the WebLeftBar easier appended to the different parts that make up the complete sidebar. These are hidden if you don't have write access to the respective topic fragments.

About Logon & Logout

LOGONTOPIC

Plugin Settings

Below are the settings which affect the behavior of the NatSkin.

• Set SHORTDESCRIPTION = Supplements the bare bones NatSkin theme for TWiki

Skin state configuration

The skin state is controlled by a set of variables that are configured on the user's home topic, the WebPreferences or the System.TWikiPreferences and are then loaded into the current session of the user. So every setting can be changed by an url parameter to take effect for the duration of the user session. The default values are given below

• switch to the given style, Base, Clean, GeorgiaBlue, Gettysburg, Independence, Kubrick, PlainJane, Rusty, SeaGreen, Squash or Stormy, url param style
  • Set SKINSTYLE = Clean
• switch to the given style variation (PlasticLove, Subway, OrangeTunnel etc) or none, url param stylevariation
  • Set STYLEVARIATION = none
• change the border decoration on, off or to thin (enabling a thin blog-like page layout), url param is styleborder
  • Set STYLEBORDER = off
• switch on/of the web buttons in the top bar of the page
  • Set STYLEBUTTONS = off
• switch the sidebar to be displayed on the right or left side or off, url param is stylesidebar
  • Set STYLESIDEBAR = left
• switch the searchbox to be displayed in the topbar (top), at the top of the sidebar (pos1), in the middle of the sidebar (pos2), at the bottom of the sidebar (pos3) or off, url param is stylessearchbox
  • Set STYLESSEARCHBOX = top

In addition there's a url parameter togglesidebar that disables the sidebar for this request only.

To emulate the Kubrick style on the old BinaryBonsai (not the new K2 style) then copy-paste this

• Set SKINSTYLE = Kubrick
• Set STYLEBORDER = thin
• Set STYLEBUTTONS = on
• Set STYLESIDEBAR = right
• Set STYLESVARIATION = none
• Set STYLESSEARCHBOX = pos1

to your System.TWikiPreferences. Try out other settings using the NatSkinStyleBrowser, or even INCLUDE it in your User.WikiGuestSideBar.

There are some constraints build into the NatSkin templates that try guarantee a pleasant appearance when combining the different skin states:

• If the styleborder is "thin" the sidebar will be disabled for the edit, manage, rdiff, natsearch, changes and search topic actions.
• The web buttons will alternate with the sidebar so that they will not be displayed on the same side.
• If the web buttons are enabled the default WebLeftBar will disable the redundant navigation to other webs.

Style support for the TablePlugin

These attributes will be loaded into your session and thereby overwriting any default settings on the TablePlugin topic. Depending on the skin style you are currently using these settings will be changed accordingly.

• Set BASETABLEATTRIBUTES = databg="white" headercolor="black" headerbg="white" tableborder="0" cellpadding="0" cellspacing="0"
• Set CLEANTABLEATTRIBUTES = headercolor="#444444"
• Set GEORGIABLUETABLEATTRIBUTES = headercolor="#999966"
• Set GETTYSBURGTABLEATTRIBUTES = headercolor="#03366"
• Set INDEPENDENCETABLEATTRIBUTES = databg="white, #f0f0f0" headercolor="white"
• Set KUBRICKTABLEATTRIBUTES = databg="#f4f4f4, white" headercolor="#0055aa"
• Set PLAINJANETABLEATTRIBUTES = headercolor="#666666"
• Set RUSTYTABLEATTRIBUTES = headercolor="white"
• Set SEAGREENTABLEATTRIBUTES = databg="white, #f0f0f0" headercolor="white"
• Set SQUASHTABLEATTRIBUTES = databg="white, #f0f0f0" headercolor="white"
• Set STORMYTABLEATTRIBUTES = databg="#333333, #444444" headercolor="#cccccc" headerbackground="black", headerbg="black"

Email Obfuscation

The standard TWiki engine tries to obfuscate email addresses by adding a phrase to the email url (like NOSPAM) to fool collecting web crawlers. But that is not adequate enough today as crawlers are aware of that. The solution to that is to remove every trace of a pattern that could be an email address from the html source code and regenerate them using javascript. Most likely, web crawlers will only parse the html and don't run a javascript interpreter beforehand. Nevertheless the obfuscation feature can be switched on and off by adding the OBFUSCATEEMAIL variable to your TWikiPreferences like

• Set OBFUSCATEEMAIL = on

Plugin Installation Instructions

• Install the plugins this one depends on (see below) of not done so already.
• Download the ZIP file from the Plugin web (see below)
• Unzip NatSkinPlugin.zip in your twiki installation directory. Content:

File:	Description:
bin/natlogon	logon cgi script
bin/natsearch	search cgi script
data/TWiki/NatSkinPlugin.txt	plugin topic
data/TWiki/MySideBar.txt	plugin to customize a personalized sidebar
data/TWiki/MySideBarTemplate.txt	topic template for MySideBar
lib/TWiki/Plugins/NatSkinPlugin.pm	main module
lib/TWiki/Plugins/NatSkinPlugin/Sandbox.pm	security module
lib/TWiki/Plugins/NatSkinPlugin/Search.pm	NatSearch module
lib/TWiki/Plugins/NatSkinPlugin/Auth.pm	authentication module

• (Dakar) Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.
• on System.TWikiPreferences change the SKIN variable to "nat"; customize the default style adding the variables SKINSTYLE, STYLEBORDER, STYLEBUTTONS and STYLESIDEBAR (see NatSkin)

Plugin Info

Plugin Author:	TWiki:Main/MichaelDaum
Plugin Version:	v2.76 (2005-11-10)
Change History:
10 Nov 2005:	added switchvariation urlparam; work arround bug in dakar (nested calls to getRenderedVersion()); fixed duplicate target/class in external links; improved MySideBarTemplate using Twisties
09 Nov 2005:	fixed wrong call to expandCommonVariables() ... doh
08 Nov 2005:	fixed use of uninitialized variables; https links to the same site are not external once
02 Nov 2005:	added OBFUSCATEEMAIL flag to switch off this feature
28 Oct 2005:	add searchbox and style variations to the skin state; configuring header art is now done using style variations; fixed the NatSkinStyleBrowser to only "stick" to changes; extended IFSKINSTATE to cover the new skin state variables
25 Oct 2005:	customization of natsearch by WebPreferences
20 Oct 2005:	improved external link detection
10 Oct 2005:	added switchstyle feature to cycle thru all installed skin styles
09 Oct 2005:	rewrite of skin state: support switching border, sidebar, webbuttons and style independently; rewrite of the email obfuscator; improved skin style browser
27 Sep 2005:	added conditional content tags IFSKINSTATE and IFDEFINED; added web button support
30 Aug 2005:	added external link detection; fixed IFSKINSTYLE; added style support for the TWiki:Plugins.TablePlugin
26 Aug 2005:	new NatSkin-2.0 release
28 Apr 2005:	pre-release to fix installation on TWiki/Cairo
16 Mar 2005:	Initial version
TWiki Dependency:	$TWiki::Plugins::VERSION 1.024
CPAN Dependencies:	none
Other Dependencies:	SpreadSheetPlugin, SessionPlugin, RedDotPlugin
Perl Version:	>=5.6
License:	GPL (GNU General Public License)
TWiki:Plugins/Benchmark:	TWiki:TWiki/GoodStyle nn%, TWiki:TWiki/FormattedSearch nn%, NatSkinPlugin nn%
Plugin Home:	TWiki:Plugins.NatSkinPlugin
Feedback:	TWiki:Plugins.NatSkinPluginDev
Appraisal:	TWiki:Plugins.NatSkinPluginAppraisal

Related Topics: TWiki:Plugins/NatSkinPlugin, TWiki:Plugins/NatSkin

-- TWiki:Main.MichaelDaum - 10 Nov 2005