key Log In

You are here: wiki.fini > TWiki Web > NatSkinPlugin
Printable
Start of topic | Skip to actions

The Natural Skin Plugin

NatSkinPlugin

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

  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

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%

render a list of all known skin styles being attachted to the NatSkin topic

KNOWNVARIATIONS

Syntax: %KNOWNVARIATIONS%

render a list of all known styles variations being attachted to the NatSkin topic

NATLOGON

Syntax: %NATLOGON%

displays Logon|Register for TWikiGuest, and TWikiGuest|Logout otherewise

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%

display Edit|Attach|Move|Raw|Diffs|More when logged in and an empty string for TWikiGuest

WEBCOMPONENT

Syntax: %WEBCOMPONENT{"name"}%

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

  1. MyComponent in the current web,
  2. TWikiMyComponent in the Main web,
  3. TWikiMyComponent in the TWiki web and
  4. 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

Example:

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

see also: MYSIDEBAR

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

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 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, 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 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 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 wiki.fini 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

  • Install the plugins this one depends on (see below) of not done so already.
  • If you are installing this plugin on a TWiki release prior TWiki-4.0, then you need the TWiki:Plugins/SessionPlugin too.
  • Optionally install the TWiki:Plugins/RedDotPlugin to ease editing the sidebar navigation
  • 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/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 TWiki.TWikiPreferences change the SKIN variable to "nat"; customize the default style adding the variables SKINSTYLE, STYLEBORDER, STYLEBUTTONS and STYLESIDEBAR (see NatSkin)
  • 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.

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

Plugin Info

Plugin Author: TWiki:Main/MichaelDaum
Copyright ©: 2003-2006, Michael Daum
License: GPL (GNU General Public License)
Plugin Version: v2.994
Change History:  
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 - 11 Mar 2006

End of topic
Skip to actions | Back to top
TWiki
key Log In or Register

 
 

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