The Natural Skin Plugin

Description

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. See the below for a full list of all provided features.

This plugin tries to be maximal compatible with all past, current and upcoming TWiki releases, namely Beijing, Cairo and Dakar (aka TWiki-4.x). Therefore some mechanisms have been internalized that are only available since TWiki-4.0. 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). In the future a sensible part of that will be moved over to the TWiki:Plugins/DakarContrib package and be used by the NatSkinPlugin and similar.

The documentation of the NatSkinPlugin only covers the additional tags that have been implemented. Have a look at the NatSkin^? topic for more information.

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 .

Syntax

CURREV

Syntax: %CURREV%

returns the current topic revision (compatible among all TWiki engines)

see also: NATMAXREV, NATREVISIONS PREVREV,

GETSKINSTYLE

Syntax: %GETSKINSTYLE%

get the current skin style; the priority is

urlparam style=<name>,
value of the session variable NATSKIN_STYLE and
preference value SKINSTYLE set in (a) the user preferences (b) the WebPreferences or (c) TWikiPreferences

IFACCESS

Syntax:

%IFACCESS{"<topic>" 
  action="..." 
  then="..." 
  else="..." 
  mode="..." 
  [then_]args="..." 
  else_args="..."}%

display the 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

IFSKINSTATE

Syntax: %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
final="<name>": test if a skin state variable called <name> is set to be changeable or not using the the FINALPREFERENCES setting; known names are are "style", "sidebar", "buttons", "border", "variation" or "searchbox"; "all" tests wether you can vary the skin at all; "switches" tests of you can change at least one of "sidebar", "buttons", "border" or "searchbox"

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, ELSIFSKINSTATE, ELSESKINSTATE, FISKINSTATE

Syntax:

%IFSKINSTATETHEN{<tests>}% 
  <then content> 
[%ELSIFSKINSTATE{<tests>}% 
  <elsif content>]* 
[%ELSESKINSTATE% 
  <else content>]?
%FISKINSTATE%

This is the multi-line version of IFSKINSTATE that uses the same tests as above but takes the content from between the sections; thus, arbitrary TWikiML might be rendered conditionaly. IFSKINSTATETHEN expressions can be nested safely. Within a single IFSKINSTATETHEN the ELSIFSKINSTATE parts can be repeated arbitrarily. Before rendering the <then|elsif|else condition> any $nop string will be removed first. Thereby nested TWikiML expressions can be prevented from being expanded in advance.

KNOWNSKINSTYLES

Syntax: %KNOWNSKINSTYLES%

returns a list of all known skin styles.

KNOWNVARIATIONS

Syntax: %KNOWNVARIATIONS%

returns a list of all known styles variations.

NATLOGON

Syntax: %NATLOGON%

displays a link to a logon url depending on the current login scheme. This will be a link to

natlogon on any legacy twiki releases or in case the LoginManager is set to "none"
login on using dakar's TemplateLogin
viewauth using ApacheLogin

NATLOGOUT

Syntax: %NATLOGOUT%

displays a link to a logout url depending on the current login scheme. This will be a link to

natlogon on any legacy twiki releases or in case the LoginManager is set to "none"
view...?logout=1 on using dakar's TemplateLogin
the empty string in case you are using ApacheLogin (you can't logout explicitely)

NATMAXREV

Syntax: %NATMAXREV%

substitute for %MAXREV% which differes all too much on Beijing, Cairo and Dakar. This version grants to behave the same.

NATREVISIONS

Syntax: %NATREVISIONS%

substitute for the %REVISIONS% tag which only works on the TWiki:Plugins/PatternSkin.

PREVREV

Syntax: %PREVREV%

returns the previous topic revision taking NumberOfRevisions into account

USERACTIONS

Syntax: %USERACTIONS%

WEBCOMPONENT

Syntax: %WEBCOMPONENT{"name"}%

display a web component. A web component "MyComponent" is searched looking for

MyComponent in the current web,
TWikiMyComponent in the Main web,
TWikiMyComponent in the TWiki web and
MyComponent in the TWiki web.

The WEBCOMPONENT tag will retrieve the component where it was found first. Thereby every web can define a component of its own but if it is not defined locally a predefined component will be returned. Components can be predefined in the Main and the TWiki where the name of the component is prefix with "TWiki" to distinguish them from the local web components that may be present in the Main and the TWiki. As a last resort the local components of the TWiki are used.

By default the NatSkin^? comes with predefined components

TWiki.TWikiWebSideBar^?
TWiki.TWikiWebButtons^?
TWiki.TWikiWebLinks^?
TWiki.TWikiWebTopicActions^?

Example:

use %WEBCOMPONENT{"WebSideBar"}% to display a the sidebar component
use %WEBCOMPONENT{"WebButtons"}% to display the WebButtons^?

WEBLINK

Syntax: %WEBLINK{web="..." name="..."}%

display a link to a WebHome with the given name and add the SITEMAPUSEDTO description to to the hover balloon

WIKIRELEASENAME

Syntax: %WIKIRELEASENAME%

returns "beijing", "cairo" or "dakar" depending on the TWiki engine this plugin is installed on

Plugin Settings

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

Set SHORTDESCRIPTION = Supplements the bare bones NatSkin^? theme for TWiki

CSS Styles

The NatSkin^? can be themed using cascading styles attached to the TWiki.NatSkin or any other topic defined in the STYLEPATH preference variable. This variable is a list of topics that are consulted for css attachments. The default value is

   * Set STYLEPATH = TWiki.NatSkin

Styles are collected in the order specified. This allows to insert style contributions that are not part of the NatSkin^?. For example given you uploaded NatSkin^? css definitions to a topic Main.NatSkinThemesContrib you can activate them by setting the STYLEPATH to

   * Set STYLEPATH = Main.NatSkinThemesContrib, TWiki.NatSkin

Css files must obey the following naming scheme to be recognized

<name>Style.css: basic style definitions for style <name>
<name>Buttons.css: WebButton definitions for style <name>
<name>Border.css: definitions for style <name> displayed using STYLEBORDER = on
<name>Thin.css: definitions for style <name> displayed using STYLEBORDER = thin
<name>Thin.css: definitions for style <name> displayed using STYLEBORDER = thin
<name>Variation.css: style variations that can be applied to any base style; this can be used to vary a base style, e.g. to add header art or change some fonts and colours

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 TWiki.TWikiPreferences and are 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's session. The default values are given below

switch to the given style, Base, Clean, GeorgiaBlue, Gettysburg, Independence, Kubrick, Pattern, PlainJane, Rusty, SeaGreen, Squash or Stormy, url param is style
- Set SKINSTYLE = Clean
switch to the given style variation (PlasticLove, Subway, OrangeTunnel etc) or none, url param is 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, url param is stylebuttons
- 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 STYLESEARCHBOX = top

There are a couple of special url parameters:

togglesidebar: disable the sidebar for this request only.
style=off: switch off any styles (simulating a non-css browser)
style=reset: switch back to the user and server settings by reverting any session preferences
switchstyle=next/prev: switch to the next/previous known style
switchvariation=next/prev: switch to the next/previous known style variation

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 STYLESEARCHBOX = pos1

to your TWiki.TWikiPreferences. Try out other settings using the NatSkinStyleBrowser^?, or even INCLUDE it in your Main.TWikiGuestSideBar^?.

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 WebSideBar^? 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"
Set PATTERNTABLEATTRIBUTES = databg="#f0f0f0, white" headercolor="#444444"

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

WysiwygPlugin support

When the TWiki:Plugins/WysiwygPlugin is installed on your TWiki installation the "Edit" topicaction can be enabled to start the Kupu wysiwyg html editor instead of the normal TWiki textarea by setting the USEWYSIWYG variable to "on" (in your TWikiGuest topic, WebPreferences or TWikiPreferences)

Set USEWYSIWYG = off

By default this value is set to "off"

Plugin Installation Instructions

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
`lib/TWiki/Plugins/NatSkinPlugin.pm`	main module
`lib/TWiki/Plugins/NatSkinPlugin/Search.pm`	NatSearch module
`lib/TWiki/Plugins/NatSkinPlugin/Auth.pm`	authentication module

If you are installing this plugin on a TWiki release prior to TWiki-4.0, then you need the TWiki:Plugins/SessionPlugin too.
Optionally, run NatSkinPlugin_installer.pl to automatically check and install other TWiki modules that this module depends on. You can also do this step manually.
Alternatively, manually make sure the dependencies listed in the table below are resolved.

Name	Version	Description
TWiki::Plugins::SpreadSheetPlugin	>=1.018	Required. Download and install from the TWiki:Plugins/SpreadSheetPlugin code library.
TWiki::Plugins::RedDotPlugin	>=1.25	Recommended; Download from TWiki:Plugins/RedDotPlugin repository.
TWiki::Plugins::FilterPlugin	>=0.94	Required; Download from TWiki:Plugins/FilterPlugin repository.
TWiki::Plugins::IfDefinedPlugin	>=0.90	Required; Download from TWiki:Plugins/IfDefinedPlugin repository.
TWiki::Contrib::DakarContrib	>=0.1	Optional; Download from TWiki:Plugins/DakarContrib repository.

Optionally install the TWiki:Plugins/RedDotPlugin to ease editing the sidebar navigation
(Dakar) Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.
on TWiki.TWikiPreferences change the SKIN variable to "nat"; customize the default style adding the variables SKINSTYLE, STYLEBORDER, STYLEBUTTONS and STYLESIDEBAR (see NatSkin^?)
to enable the NatSkin^?'s logon scheme disable TWiki's LoginManager and remove all lines containing "require valid-user" (except for the configure cgi script) from the file bin/.htaccess
make sure that the scripts natlogon and natsearch are recognized as cgi scripts in your server configuration
if you have set up ssl for your server add the following variable to your TWikiPreferences:
```
 * Set HTTPSLOGON = on 
```
This will prevent passwords being sent in clear-text over a possibly insecure net.
to enable ssl as soon as you logged in use the following rewrite rules in bin/.htaccess:
```
 RewriteEngine On
 RewriteCond %{SERVER_PORT} !443
 RewriteCond %{QUERY_STRING} template=oopslogon
 RewriteRule ^(.*)$ https://%{HTTP_HOST}/bin/$1 [R,L] 
```
Note, that you might need to accommodate the /bin url path above to your installation!

Plugin Info

Plugin Author:	TWiki:Main/MichaelDaum
Copyright ©:	2003-2006, _email0
License:	GPL (GNU General Public License)
Plugin Version:	v2.9993
Change History:
05 Mai 2006:	fixed table bgcolor for Independence style; display default WebLinks for non-public webs
19 Apr 2006:	use <link rel="stylesheet" ... /> instead of @import url() to ease the pain for js wysiwyg editors
11 Apr 2006:	added STYLEPATH feature; added style=off feature to emulate non-css browser; disable email obfuscation javascript if unused
05 Apr 2006:	added support for dakar's TemplateLogin; changed semantics of NATLOGON, added NATLOGOUT; fixed some grave bugs exposed by the PublishContrib
27 Mar 2006:	moved MySideBar tempaltes to NatSkin; added docu for HTTPSLOGON
20 Mar 2006:	multiple errors in natsearch: always first look into the current web, even for a global search; default to local search, was global before, use g: to switch to global search explicitely; GO function searches in all webs; display number of hits; sort hit results in reverse chronological order
13 Mar 2006:	dont remove leading and trailing whitespaces from web components
11 Mar 2006:	removed MYSIDEBAR tag; new web component search path; new sidebar construction logic using WebLinks; docu restructuring; packaging using BuildContrib
22 Feb 2006:	removed GROUPSUMMARY, ALLUSERS and registrationHandle which where only used on the NatsWiki installation, moved into a plugin of its own; fixed initPlugin not to return 0, disable the plugin if not used with thet NatSkin^? on a per handler base
21 Feb 2006:	externalized the IFDEFINED family into a plugin of its own and added a new dependency for it
15 Feb 2006:	properly detect scripted mode on Dakar
14 Feb 2006:	moved FORMATLIST to TWiki:Plugins/FilterPlugin; added dependency on it; fixed uninitialized variables with perl-5.8.8; added escape chars to IFDEFINED; don't switch off using an atom skin
03 Feb 2006:	added escape chars (percnt, dollar) to IFACCESS to make it more useful; fixed detection of a Dakar engine; fixed default REDDOT in the MySideBarTemplate^?
26 Jan 2006:	docu fixes
23 Jan 2006:	fixed natlogn; fixed FORMATLIST to expandCommonVariables of the format result
09 Jan 2006:	removed local sandbox; added dependency on DakarContrib; added variable expansion to IFDEFINED; added cleanup code if the AliasPlugin is not installed; improved natsearch customization; w3c fixes in the MySideBarTemplate
06 Dec 2005:	switching off the plugin if the skin is not NatSkin^?
05 Dec 2005:	skin state variables respect FINALPREFERENCES settings; added WEBCOMPONENT
01 Dec 2005:	added tooltips to topic actions
29 Nov 2005:	fixed warning about using the deprecated endRenderingHandler on Dakar
23 Nov 2005:	added $nop to IFSKINSTATETHEN content
22 Nov 2005:	added support for the WysiwygPlugin; added custom templates for the BlackListPlugin's error messages
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
Perl Version:	>=5.6
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

-- TWiki:Main/MichaelDaum - 05 Mai 2006

Topic NatSkinPlugin . { Edit | Attach | Backlinks: Web All webs | Printable | History: r1 More }

Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.NatSkinPlugin

	TWiki > TWiki > NatSkinPlugin	TWiki webs: Main \| TWiki \| Sandbox
	TWiki . { Welcome \| Register \| Changes \| Topics \| Index \| Search \| Go }