NETJUKE THEME AUTHORING
Second Revision : 4/15/2003
By : Florian Maul <fmaul@users.sourceforge.net>


 1. Creating a simple colored theme
 -------------------------------------------------------------------------------

  Themes are stored in var/html/themes as single php-files named somename.php. 
  These files will automatically be recognized and included in the netjuke code. 
  Each theme is supposed to return an Object of the class Theme (defined in 
  lib/inc-theme.php) or of a class derived from theme. Here is an simple example 
  of a theme-file which just replaces some colors from the original theme:
  
      <?php
      
      class ModernBlue extends Theme {
      
        function ModernBlue() {
          $this->setDefault('background', 'FFFFFF');    
          $this->setDefault('text',       '000000');    
          $this->setDefault('link',       '333366');    
          $this->setDefault('linkvisited','333366');    
          $this->setDefault('linkactive', 'FF3300');    
          $this->setDefault('header',     'C0C0D0');    
          $this->setDefault('headertext', '333366');    
          $this->setDefault('border',     'FFFFFF');
          $this->setDefault('content',    'E8E8EE');
      
          $this->setMetaData('name',        'Modern Blue');  
          $this->setMetaData('author',      'Florian Maul');  
          $this->setMetaData('version',     '1.0');  
          $this->setMetaData('description', 'Modern fresh look in light blue');  
          $this->setMetaData('icon_invert', 'f');
          $this->setMetaData('icon_set',    'colorful');
      
          parent::Theme();
        }
      }
      
      // IMPORTANT!! return a theme object
      return new ModernBlue;
      
      ?>
  
  This is everything you need to create a theme with custom colors. The 
  setDefault function sets a default value for the specified attribute which 
  will be used when no user- or admin-settings were made for these attributes or 
  when resetting the colors to the default. Each of the attributes must be 
  defined in the Theme of course, here they were defined in the base class 
  Theme, e.g. for the attribute background:
  
      var $default_settings = array (
      
          'background' => array (
                  'title'      => 'Background Color', 
                  'type'      => 'color', 
                  'default'   => 'FFFFFF' ),
  
           // more attributes here }
  
  The function setMetaData($key, $value) is used very similar. It also stores 
  the data in an array in the Theme baseclass and returns this data whenever it 
  is needed by netjuke with the function getMetaData($key). 
  
  Finally our example theme above calls the constructor of the baseclass 
  parent::Theme() which initialises the actual settings with the default values 
  defined by SetDefault() and also do other common initializations in the future.


 2. The Theme-baseclass 
 -------------------------------------------------------------------------------

  The following section will provide an overview over the functions the Theme-
  class currently provides.

    Theme()           
    Constructor, creates a Theme by reseting the settings
  
    ---- affecting meta data ----
  
    setMetaData($item, $value)
    sets the specified meta-data item to $value
  
    getMetaData($item)
    returns a specified meta-data item if $item is specified
    else an array with all the data will be returned
  
    ---- affecting actual/current settings ----
  
    resetSettings()
    initialisizes $settings array from defaults
  
    readUserSettings($themeid, $usermail)
    determines default and user-settings from the database
  
    saveUserSettings($themeid, $usermail )
    saves the user-settings to the database
  
    getSettings()
    returns the current settings array
  
    setSetting($item, $value)
    sets the setting $item with $value
  
    ---- affecting default values ----
  
    setDefault($setting, $value)
    sets a value in the default_settings-array. It can be used by
    themes which are based on this class to alter the default
    values easily.
  
    getDefaultSettings()
    returns the default settings array
  
    getDefaultSettingsCount()
    returns the amount of settings that are available to
    the user
  
    ---- generating output ----
    
    getCSS()
    returns CSS definitions depending on the values of the
    settings array
  

  Currently only the getCSS() function provides output (the CSS settings) which 
  influences the appearance of the user interface. The theme class might be 
  easily extended in the future though to provide functions which generate the 
  actual HTML- output.
  



================== OLD THEMES VERSION ====================================================

Initial Revision : 4/9/2003
By : Blake Watters <sbw@ibiblio.org>

Introducation -

  Netjuke themes are designed to allow users to quickly and easily customize the look
and feel of their Netjuke streaming media jukebox web application and allow individuals
to share their creativity with the rest of the Netjuke community. The modular design allows
the maximum amount of flexibility, while maintaining ease of development of a small learning
curve.

API Definition -

  The following data must be defined by your theme for it to function:

Theme Data -

  This is simply an array of values corresponding to the colors, font face,
  and font size that are to be loaded into Netjuke as a theme.

  Keys for Theme Array   | Values and Description
    THEME_NAME           |  String     : The name of this theme
    THEME_AUTHOR         |  String     : The name/e-mail address of the theme's author
    THEME_VERSION        |  String     : The version number of this theme
		THEME_DESCRIPTION		 |  String		 : A brief description of this theme
    THEME_INV_ICN        |  't' or 'f' : If this theme uses inverse icons
    THEME_BGCOLOR        |  Hex Color  : The color to be used for the background
    THEME_TEXT           |  Hex Color  : The color to be used for text
    THEME_LINK           |  Hex Color  : The color to be used for links
    THEME_ALINK          |  Hex Color  : The color to be used for active links
    THEME_VLINK          |  Hex Color  : The color to be used for visited links
    THEME_TD_BORDER      |  Hex Color  : The color to be used for table borders
    THEME_TD_HEADER      |  Hex Color  : The color to be used for table headers
    THEME_TD_HEADER_FC   |  Hex Color  : The color to be used for header fonts
    THEME_TD_CONTENT     |  Hex Color  : The color to be used for content cells
    THEME_FONT_FACE      |  Font Face  : The font to be used for textual content
    THEME_FONT_SIZE      |  Font Size  : The color size to be used for textual content
    THEME_ICON_SET       |  Hex Color  : The color to be used for the background ('' for no change)

CSS Data -

  This optional function allows the theme to override the CSS being used in generating Netjuke
  pages. This can be used to provide a higher level of customization, but is more susceptible to
  errors and care must be taken to ensure clean cross-browser rendering.

Returning Data -

  The last line of your theme must return the array of data with the theme array and a string of css data (or '').

Sample Theme -

<?php
// Sample theme

$theme = array ( 'THEME_NAME' => 'My Sample Theme',
                 'THEME_AUTHOR' => 'A Cool Netjuke Hacker',
                 'THEME_VERSION' => '1.0',
                 'THEME_DESCRIPTION' => 'This theme uses awesome colors.',
                 'THEME_INV_ICN' => 'f',
                 'THEME_BGCOLOR' => 'FFFFFF',
                 'THEME_TEXT' => '000000',
                 'THEME_LINK' => '333333',
                 'THEME_ALINK' => '333366',
                 'THEME_VLINK' => '333333',
                 'THEME_TD_BORDER' => '000000',
                 'THEME_TD_HEADER' => '666666',
                 'THEME_TD_HEADER_FC' => 'EEEEEE',
                 'THEME_TD_CONTENT' => 'EEEEEE',
                 'THEME_FONT_FACE' => 'Verdana, Geneva, Arial, Helvetica, sans-serif',
                 'THEME_FONT_SIZE' => '11',
                 'THEME_ICON_SET' => '' );

return (array ($theme, false));

?>
