- general CSS based themeing support.

- added setup option to select theme.
- added search scheme for themable images and stylesheets.
- added marine (default) and redwine theme.
- documented new features. All developers must read
  doc/dev-conventions.txt

3 files changed, 161 insertions, 26 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 69bac21..078e35c 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,16 +1,28 @@
+2007-06-03  Dieter Hametner  <dieter@air.mittelstation.de>
+
+	Added CSS based themeing support. For details please read
+	doc/css-themeing.txt and doc/dev-conventions.txt.
+	* setup.h, setup.cpp, setup.ecpp: added setup for theme and
+		selection of theme.
+	* pages/*.ecpp: added support for themable images.
+	* tntconfig.cpp: cascaded search for images, to support themeing.
+
 2007-06-03  Christian Wieninger <cwieninger at gmx dot de>
-	Setup includes now a local net mask specifying the address range without 
-	necessary login (#321)
+
+	Setup includes now a local net mask specifying the address range
+	without necessary login (#321)
 
 2007-06-02  Christian Wieninger <cwieninger at gmx dot de>
+
 	required version of VDR is now >= 1.4.0-2
 
 2007-06-01  Sascha Volkenandt <sascha at akv-soft dot de>
 
-	The detection of featured plugins was uniformed. The display in the about
-	box now reads "active: <version>" or "required: <version>"
+	The detection of featured plugins was uniformed. The display in
+	the about box now reads "active: <version>" or "required:
+	<version>"
 
-2007-06-01  Dieter Hametner  <dh+vdr@gekrumbel.de>
+2007-06-01  Dieter Hametner  <dh+vdr at gekrumbel dot de>
 
 	These changes fix bug entry #339
 	* css-themeing.txt: describe how to do css themeing.
@@ -26,6 +38,6 @@
 
 unrecorded  Sascha Volkenandt <sascha at akv-soft dot de>
 
-	Due to the introduction of a uniform header for C++ standard extenstions,
-	the boost library is now only necessary if the used g++ compiler version
-	is less than 4.0
+	Due to the introduction of a uniform header for C++ standard
+	extenstions, the boost library is now only necessary if the used
+	g++ compiler version is less than 4.0
diff --git a/doc/css-themeing.txt b/doc/css-themeing.txt
index be84e26..3148838 100644
--- a/doc/css-themeing.txt
+++ b/doc/css-themeing.txt
@@ -3,18 +3,111 @@ How to do live theming with CSS.
 
 Live supports CSS theming. While the structure of the html pages is
 given by the plugin, there is the possibility to change the look
-through CSS.
-
-Currently a predefined, compiled into the plugin stylesheet 'styles.css' is
-delivered first. Then a stylesheet 'css/siteprefs.css' is sent to the
-browser. 'css/siteprefs.css' is a normal file that is found in
-USRDIR. The default of USRDIR is /usr/share/vdr-plugin-live. This
-can be changed at compile time by setting the USRDIR variable
-(i.E. USRDIR=/tmp/live make)
-
-One of the next steps will be a mechanism to select additional style
-files and images through a theme setting in vdr. The different themes
-will be also located in theme related subdirs beneath USRDIR.
+through CSS and exchanged images.
+
+
+Themable resources
+------------------
+
+CSS stylesheets and referenced images are themable. That means a theme
+can replace the icons and background images in the markup.
+
+
+Access scheme for the css stylesheets
+-------------------------------------
+
+Each live page requests at least three stylesheets in the following
+order:
+
+ 1. 'styles.css' (the build in stylesheet) is requested.
+ 2. The theme master stylesheet 'theme.css' is requested.
+ 3. A site preferences stylesheet is requested ('siteprefs.css')
+
+
+Location for the stylesheets
+----------------------------
+
+The initial stylesheet 'styles.css' provides a basic layout. It is a
+builtin stylesheet and can not be altered after live is compiled and
+installed.
+
+The theme stylesheed 'theme.css' is requested through following url:
+
+  themes/<themename>/css/theme.css
+
+The site preference stylesheet is requested through this url:
+
+  css/siteprefs.css
+
+
+Access scheme for themable images
+---------------------------------
+
+All themable images in the pages, that live delivers to the browser are
+accessed through the url
+
+  themes/<themename>/img/<imagename>
+
+If a image is not found under that url, the image is searched in
+  common/img/<imagename>
+
+And if not found there, an attempt to deliver a built in image is taken.
+
+
+Location of the resources in the file system
+--------------------------------------------
+
+All themable content must be present in the directory specified by
+USRDIR. The default USRDIR is /usr/share/vdr-plugin-live. This can be
+changed at compile time by setting the USRDIR variable
+(i.E. USRDIR=/tmp/live make).
+
+That means all themes must reside in USRDIR/themes.
+
+
+Structure of a theme package
+----------------------------
+
+A theme package consists of directory named after the theme name. It
+must contain the subdirectories 'css' and 'img'. Under css and img no
+other subdirectories are allowed for security reasons (see below).
+
+In the subdirectory css a stylesheet theme.css must exist in oder to
+override or extend the already defined styles from 'styles.css'.
+
+Additional images referenced through the stylesheet and images
+replacing the default images go to the 'img' subdirectory. Replacing
+images must have the same name like the image to be replaced.
+
+The live distribution comes with a few predefinded theme packages. You
+should take look into them to better understand this structure.
+
+
+Selecting a theme in live
+-------------------------
+
+In the live setup page, the user can select the desired theme. When
+the settings are saved the selected themes become active. Live detects
+the available themes dynamicaly by scanning the 'themes' directory in
+USERDIR for available themes and creates the select box from this
+information.
+
+So the installation of a new theme is easyly done by unpacking a
+theme-archive in USRDIR/themes. This assumes the theme-archive follows
+the structure of a theme package as described above.
+
+
+Security provisions
+-------------------
+
+Live will map every url starting with themes/<themename>/css or
+themes/<themename>/img to exactly these directories under USRDIR. That
+means any path components after 'img' or 'css' are discarded. Only the
+basename of the url is appended to these directories. This is to
+prevent possible malicous requests to other locations in the
+filesystem by adding '..' to the request path. The downside of this
+is, that no additional directories below 'img' and 'css' are possible
+for the theme designer.
 
 
 User Contribution
diff --git a/doc/dev-conventions.txt b/doc/dev-conventions.txt
index c3472fd..07d026d 100644
--- a/doc/dev-conventions.txt
+++ b/doc/dev-conventions.txt
@@ -1,4 +1,7 @@
-This file contains some guidlines for developers about what to obey
+Live development guidelines
+===========================
+
+This file contains some guidelines for developers about what to obey
 when adding new functionality to live plugin.
 
 First of all please look at the existing code and how it was done
@@ -8,12 +11,15 @@ We want to support a broad range of browsers. On one side are hand held
 devices like WEB-enabled PDAs or mobile phones. They often lack full
 grown support for ECMAScript and have small screen sizes. The other
 extreme are the desktop browsers like FireFox, Konqueror, Opera and
-perhabs IE (if the 'powers that be' make him more CSS compliant).
-Here WEB 2.0 featuers can improve the users experience.
+perhaps IE (if the 'powers that be' make him more CSS compliant).
+Here WEB 2.0 features can improve the users experience.
+
+
+With or without ECMAScript
+--------------------------
 
-In the future some themeing in live might help to cover this broad
-range. Meanwhile we suggest the following rule to activate
-functionality with and without ECMAScript support:
+Since not all browsers support ECMAScript, we suggest the following
+rule to activate functionality with and without ECMAScript support:
 
 Use anchors analog to this example
 
@@ -23,3 +29,27 @@ Use anchors analog to this example
 to retrieve and display extra information either in a WEB 2.0 fashion
 in an popup box or on a separte page in a html fashion.
 
+
+Themeing
+--------
+
+Current CSS based themeing in live depends on additional stylesheets
+and a configurable location to retrieve images from (see
+css-themeing.txt).
+
+Developers must use the <& pageelems.stylesheets &> component in their
+pages to include both the default and the themed stylesheet. This is
+the easy part, because stylesheets are referred in the header at a
+central location.
+
+More difficult is the access to images, which is spread around the
+pages at the corresponding locations. To support this, a new method in
+the live Setup class (see file setup.h) has been added. It is called
+'GetThemedLink'. For every image, that might be customized, you must
+use a img tag according to this example:
+
+  <img src="<$ LiveSetup().GetThemedLink("img", "<imagename>") $>"
+  alt="someimage" />
+
+Please take a look in the existing ecpp pages for additional usage
+examples.