DevelopmentFHEMWEB

This page describes the FHEMWEB module from a developer's perspective.

Global Variables

In the source code http://hostname:port/<webname> is in $FW_ME. The following global variables are used throughout fhem:

$FW_dir

base directory from which FHEMWEB serves files. The first existing directory from the following list is taken:

$modpath/www
$modpath/FHEM

$FW_icondir

base directory from which FHEMWEB serves icons. The first existing directory from the following list is taken:

$FW_dir/images  [which is $modpath/www/images in the new layout]
 $FW_dir/pgm2   [which is $modpath/www/pgm2 in the interim layout]
 $FW_dir      [which is $modpath/FHEM in the old layout]

FW_docdir

base directory from which FHEMWEB serves documentation. The first existing directory from the following list is taken:

$FW_dir/docs    [usually does not exist] 
$modpath/docs   [this is where the documentation has ever been residing, no need to copy commandref.html etc. anymore]
$FW_dir      [which is $modpath/FHEM in the old layout]

$FW_cssdir

base directory from which FHEMWEB serves style sheets and svg definitions. The first existing directory from the following list is taken:

$FW_dir/pgm2   [which is $modpath/www/pgm2 in the new and in the interim layout]
 $FW_dir      [which is $modpath/FHEM in the old layout]

$FW_jsdir

base directory from which FHEMWEB serves javascript includes. The first existing directory from the following list is taken:

$FW_dir/pgm2   [which is $modpath/www/pgm2 in the new and in the interim layout]
 $FW_dir      [which is $modpath/FHEM in the old layout]

$FW_gplotdir

base directory from which FHEMWEB serves gplot files. The first existing directory from the following list is taken:

$FW_dir/gplot   [which is $modpath/www/gplot in the interim layout]
 $FW_dir/pgm2    [which is $modpath/www/pgm2 in the interim layout]
 $FW_dir      [which is $modpath/FHEM in the old layout]

Special URLs

Why do we need special URLs?

One would expect, that the URLs correspond to paths in the local filesystem relative to the document root. This was the case with the directory FHEM being the document root but not with the more tidier interim and new directory structures. Thus, one layer of indirection was required to transparently map the below URLs to the respective directories no matter what the actual directory structure is.

Icons

http://hostname:port/<webname>/icons/<icon>

This is the standard mechanism to retrieve image files.

Documentation

http://hostname:port/<webname>/docs/file

This is the standard mechanism to retrieve documentation, especially commandref.html: http://hostname:port/<webname>/docs/commandref.html.

html, txt and pdf files are recognized by their extensions. They are served from $FW_docdir (no subdirectories possible at this stage).

Style Sheets

http://hostname:port/<webname>/css/file

This is the standard mechanism to retrieve style sheets, e.g. default.css: http://hostname:port/<webname>/css/default.css.

They are served from $FW_cssdir (no subdirectories possible at this stage).

Javascript Includes

http://hostname:port/<webname>/js/file

This is the standard mechanism to retrieve style sheets, e.g. default.css: http://hostname:port/<webname>/js/svg.css.

They are served from $FW_jsdir (no subdirectories possible at this stage).

GPlot Files

http://hostname:port/<webname>/gplot/file

This is the standard mechanism to retrieve gplot files, e.g. temp4hum8.gplot: http://hostname:port/<webname>/gplot/temp4hum8.gplot.

They are served from $FW_gplotdir (no subdirectories possible at this stage).

Icon subsystem

General

fhem adds one layer of indirection to the icons in the $FW_icondir directory structure. The icon is requested under its logical name <icon>, e.g. lamp.onor weather/sunnyor myicons/klaus. <icon> can thus be a path.

fhem serves icons from the URL http://hostname:port/<webname>/icons/<icon>

If <icon> is requested, a physical file needs to be served. Its filename must be <icon> with a suffix of .ico, .gif, .jpg, or .png. For example, the logical icon lamp.oncould be stored in a file named lamp.on.icoand the logical icon weather/sunnycould be in a file named weather/sunny.png.

The physical file that is actually served for <icon> is determined as follows: Per default, the icon file is taken from $FW_icondir/default. If the stylesheetPrefix attribute of the underlying FHEMWEB instance is set to <style>, then icon files from $FW_icondir/<style> take precedence over those with same file names in $FW_icondir/default. Highest priority has the path specified in the iconpathattribute of the FHEMWEB instance. iconpathis relative to $FW_icondir. Icons not found in the style-specific subdirectories are taken from the default subdirectory anyway. Only if absolutely no icons can be found in any of these subdirectories, $FW_icondir itself is searched.

Serving icons from a subdirectory is not even tidier but also required to place third party collections together with a copyright notice in the structure as it is the case for Martin Preidel's weather icons.

If more than one physical file exists for <icon> in a subdirectory, the priority is as follows: 1. <icon>.png (highest), 2. <icon>.jpg, 3. <icon>.ico, 4. <icon>.gif (lowest).

Conclusions:

1. Put the icons into $FW_icondir/default and its subdirectories. If you need style-specific icons, put them into $FW_icondir/<style> and its subdirectories.
2. The actual icons you get from [http://hostname:port/ http://hostname:port/]<webname> and b) the stylesheetPrefix attribute of that FHEMWEB instance.

Source code for server mechanism

For some reason FHEMWEB uses global variables to certain extent (this is no problem since fhem is not multi-threaded). FW_SetDirs() is the essential function to set $FW_icondir (and other directories) relative to the document root $FW_dir of the FHEMWEB server. It must be called before any action involving icons to assure $FW_icondir is correctly set for the FHEMWEB instance that serves the requested icon.

The mapping between the physical icon files in the $FW_icondir directory structure and the logical icon structure is done in FW_ReadIcons($). FW_ReadIcons() is called once upon definition of the FHEMWEB device or explicitely with set myFHEMWEB rereadicons.

The mapping table is stored in $hash->{fhem}{icons} as semicolon-separated list of <icon>;<filename>pairs with <filename> relative to $FW_icondir.

The strategy for collection the icons is as follows (see FW_ReadIcons):

1. First collect all icons in the directory $FW_icondir/default. 2. If the stylesheetPrefix attribute is set, then collect all icons in the directory $FW_icondir/<stylesheetPrefix>. 3. If the iconpath attribute ist set, then collect all icons in the directory $FW_icondir/<iconpath>. 4. If no icons have been found so far, then collect all icons in the directory $FW_icondir.

Step #4 is required to find icons in the FHEM subdirectory $modpath/FHEM, where the icons used to reside in the old layout.

If a previously icon is found again in a later step, this icon is given preference over the previously found icon. For example, if <stylesheetPrefix> is "dark" and we have fhemicon both in $FW_icondir/default and in $FW_icondir/dark, the fhemicon from $FW_icondir/dark is taken.

The icon files can be in gif, ico, jpg or png format. If two or three icon files for the same logical icon name are available in the same directory, e.g. fhemicon.png and fhemicon.gif, png is preferred over jpg and jpg is preferred over ico and ico is preferred over gif.

Usage in your own code

If you need an icon to be visualized in a web site, use the function FW_makeImage(<icon>). It returns the img tag for the icon plus a comment where the icon is located. It even return an error message if no icon file exists that fits the requested logical name.

If a connection to the webserver is made, the underlying FHEMWEB instance needs to be determined that serves the request. After this has been done the global variables still need to be set. Thus make sure to call FW_SetDirs() at the appropriate place.

Other useful functions are FW_IconPath(<icon>) to determine the full(!) path to the icon, e.g. $FW_icondir/dark/lamp.off.png. and FW_IconURL(<icon>) to determine the URL of the icon, e.g. http://hostname:port/<webname>/icons/lamp.off.

Plugins

FHEMWEB provides some meachnisms to plug-in own functionality. To do so, own routines can be registered in the hashes $data or $hash respectively, see details below.

FW_detailFn

Provides the possibility to display additional data on the details-screen of a device, will be dosplayed above the "Internals"-section. Registration in a modules' initialize-Routine:

$hash->{FW_detailFn} = "my_routine";

my_routine will be called with the parameters $FW_wname, $deviceName, $FW_room. Have a look at 01_FHEMWEB.pm for examples.

FW_summaryFn

Provides the possibility to display own data instead of the state-icon of a device. Registration in a modules' initialize-Routine:

$hash->{FW_summaryFn} = "my_routine";

my_routine will be called with the parameters $FW_wname, $deviceName, $FW_room. Have a look at 01_FHEMWEB.pm for examples. The return-value of my_routine can bei any of

• html-code, checked by regexp <.*>
• empty (""), will display the state-icon as usual
• undef, will display ???