Version vom 25. Juli 2013, 13:33 Uhr

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

Global Variables

The following global variables are used throughout FHEMWEB, and should be used if you are extending it:

$FW_ME: When using FHEMWEB, you have to specify a base path in all requests, this value is stored in the variable $FW_ME and defaults to /fhem. The user may change it by setting the webname attribute.

$FW_dir: base directory from which FHEMWEB serves files. Defaults to $attr{global}{modpath}/www.

$FW_icondir: base directory from which FHEMWEB serves icons. Defaults to $FW_dir/images.

$FW_cssdir: base directory from which FHEMWEB serves HTML and SVG style sheets and javascript files. Defaults to $FW_dir/pgm2.

$FW_gplotdir: base directory where FHEMWEB searches for gplot files. Defaults to $FW_dir/gplot.

Special URLs

You can request any file directly by specifying its exact path starting with $FW_dir, but there are also some special URLs available:

Icons

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

This is the standard mechanism to get an icon representing a device.

For finding an icon for a device, the directories are scanned by the iconPath FHEMWEB attribute, default ist stylesheetDir:fhemSVG:openautomation:default. Then the icon is chosen depending on the device name,type and state. The user can specify a devStateIcon to change this behaviour, and the module can also override it by specifying its FW_summaryFn, see below.

Due to historic reasons, you can still load any image from the iconPath directly by specifying its name without extension, but this feature may go away in the future.

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.

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.

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 as a text link usual
undef, will continue the default search mechanism for a matching icon for STATE

webCmdFn

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

$data{webCmdFn}{myModule} = "my_Routine";

my_Routine will be called with parameters $FW_wname, $deviceName, $FW_room, $cmd, $values.

For more details refer to the original thread in fhem-forum.

@@ Zeile 1: / Zeile 1: @@
 This page describes the FHEMWEB module from a developer's perspective.
 = Global Variables =
-In the source code [http://hostname:port/ http://hostname:port/]&lt;webname&gt; is in $FW_ME. The following global variables are used throughout fhem:
-<dl><dt>$FW_dir</dt><dd> base directory from which FHEMWEB serves files. The first existing directory from the following list is taken:
+The following global variables are used throughout FHEMWEB, and should be used if you are extending it:
-</dd></dl>
- <nowiki>$modpath/www
-$modpath/FHEM</nowiki>
-<dl><dt>$FW_icondir</dt><dd> base directory from which FHEMWEB serves icons. The first existing directory from the following list is taken:
-</dd></dl>
- <nowiki>$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]</nowiki>
-<dl><dt>FW_docdir</dt><dd> base directory from which FHEMWEB serves documentation. The first existing directory from the following list is taken:
-</dd></dl>
- <nowiki>$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]</nowiki>
-<dl><dt>$FW_cssdir</dt><dd> base directory from which FHEMWEB serves style sheets and svg definitions. The first existing directory from the following list is taken:
-</dd></dl>
- <nowiki>$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]</nowiki>
-<dl><dt>$FW_jsdir</dt><dd>    base directory from which FHEMWEB serves javascript includes. The first existing directory from the following list is taken:
-</dd></dl>
- <nowiki>$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]</nowiki>
-<dl><dt>$FW_gplotdir</dt><dd>  base directory from which FHEMWEB serves gplot files. The first existing directory from the following list is taken:
-</dd></dl>
- <nowiki>$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]</nowiki>
+<dl><dt>$FW_ME<dd> When using FHEMWEB, you have to specify a base path in all requests, this value is stored in the variable $FW_ME and defaults to /fhem. The user may change it by setting the webname attribute.
+</dl>
-= Special URLs =
+<dl><dt>$FW_dir<dd> base directory from which FHEMWEB serves files. Defaults to  $attr{global}{modpath}/www.
-Why do we need special URLs?
+</dl>
-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.
+<dl><dt>$FW_icondir<dd> base directory from which FHEMWEB serves icons. Defaults to $FW_dir/images.
+</dl>
-== Icons ==
+<dl><dt>$FW_cssdir<dd> base directory from which FHEMWEB serves HTML and SVG style sheets and javascript files. Defaults to $FW_dir/pgm2.
-[http://hostname:port/ http://hostname:port/]&lt;webname&gt;/icons/&lt;icon&gt;
+</dl>
-This is the standard mechanism to retrieve image files.
+<dl><dt>$FW_gplotdir<dd> base directory where FHEMWEB searches for gplot files. Defaults to $FW_dir/gplot.
+</dl>
-==== Documentation ====
+= Special URLs =
-[http://hostname:port/ http://hostname:port/]&lt;webname&gt;/docs/file
+You can request any file directly by specifying its exact path starting with $FW_dir, but there are also some special URLs available:
-This is the standard mechanism to retrieve documentation, especially commandref.html: [http://hostname:port/ http://hostname:port/]&lt;webname&gt;/docs/commandref.html.
+== Icons ==
+[http://hostname:port/ http://hostname:port/]&lt;webname&gt;/icons/&lt;device&gt;
-html, txt and pdf files are recognized by their extensions. They are served from $FW_docdir (no subdirectories possible at this stage).
+This is the standard mechanism to get an icon representing a device.
+For finding an icon for a device, the directories are scanned by the iconPath FHEMWEB attribute, default ist stylesheetDir:fhemSVG:openautomation:default. Then the icon is chosen depending on the device name,type and state. The user can specify a devStateIcon to change this behaviour, and the module can also override it by specifying its FW_summaryFn, see below.
+Due to historic reasons, you can still load any image from the iconPath directly by specifying its name without extension, but this feature may go away in the future.
-==== Style Sheets ====
+== Documentation ==
-[http://hostname:port/ http://hostname:port/]&lt;webname&gt;/css/file
+[http://hostname:port/ http://hostname:port/]&lt;webname&gt;/docs/file
-This is the standard mechanism to retrieve style sheets, e.g. default.css: [http://hostname:port/ http://hostname:port/]&lt;webname&gt;/css/default.css.
+This is the standard mechanism to retrieve documentation, especially commandref.html: [http://hostname:port/ http://hostname:port/]&lt;webname&gt;/docs/commandref.html.
-They are served from $FW_cssdir (no subdirectories possible at this stage).
-==== Javascript Includes ====
-[http://hostname:port/ http://hostname:port/]&lt;webname&gt;/js/file
-This is the standard mechanism to retrieve style sheets, e.g. default.css: [http://hostname:port/ http://hostname:port/]&lt;webname&gt;/js/svg.css.
-They are served from $FW_jsdir (no subdirectories possible at this stage).
-==== GPlot Files ====
-[http://hostname:port/ http://hostname:port/]&lt;webname&gt;/gplot/file
-This is the standard mechanism to retrieve gplot files, e.g. temp4hum8.gplot: [http://hostname:port/ http://hostname:port/]&lt;webname&gt;/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 &lt;icon&gt;, e.g. ''lamp.on''or ''weather/sunny''or ''myicons/klaus''. &lt;icon&gt; can thus be a path.
-fhem serves icons from the URL [http://hostname:port/ http://hostname:port/]&lt;webname&gt;/icons/&lt;icon&gt;
-If &lt;icon&gt; is requested, a physical file needs to be served. Its filename must be &lt;icon&gt; with a suffix of .ico, .gif, .jpg, or .png. For example, the logical icon ''lamp.on''could be stored in a file named ''lamp.on.ico''and the logical icon ''weather/sunny''could be in a file named ''weather/sunny.png''.
-The physical file that is actually served for &lt;icon&gt; 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 &lt;style&gt;, then icon files from $FW_icondir/&lt;style&gt; take precedence over those with same file names in $FW_icondir/default. Highest priority has the path specified in the ''iconpath''attribute of the FHEMWEB instance. ''iconpath''is 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 &lt;icon&gt; in a subdirectory, the priority is as follows: 1. &lt;icon&gt;.png (highest), 2. &lt;icon&gt;.jpg, 3. &lt;icon&gt;.ico, 4. &lt;icon&gt;.gif (lowest).
-Conclusions:
-# Put the icons into $FW_icondir/default and its subdirectories. If you need style-specific icons, put them into $FW_icondir/&lt;style&gt; and its subdirectories.
-# The actual icons you get from <nowiki>[http://hostname:port/ http://hostname:port/]</nowiki>&lt;webname&gt; 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-&gt;{fhem}{icons} as semicolon-separated list of ''&lt;icon&gt;;&lt;filename&gt;''pairs with &lt;filename&gt; relative to $FW_icondir.
-The strategy for collection the icons is as follows (see FW_ReadIcons):
-. First collect all icons in the directory $FW_icondir/default.
-. If the stylesheetPrefix attribute is set, then collect all icons in the directory $FW_icondir/&lt;stylesheetPrefix&gt;.
-. If the iconpath attribute ist set, then collect all icons in the directory $FW_icondir/&lt;iconpath&gt;.
-. 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 &lt;stylesheetPrefix&gt; 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(&lt;icon&gt;). 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(&lt;icon&gt;) to determine the full(!) path to the icon, e.g. $FW_icondir/dark/lamp.off.png. and FW_IconURL(&lt;icon&gt;) to determine the URL of the icon, e.g. [http://hostname:port/ http://hostname:port/]&lt;webname&gt;/icons/lamp.off.
-Other useful functions are FW_IconPath(&lt;icon&gt;) to determine the full(!) path to the icon, e.g. $FW_icondir/dark/lamp.off.png. and FW_IconURL(&lt;icon&gt;) to determine the URL of the icon, e.g. [http://hostname:port/ http://hostname:port/]&lt;webname&gt;/icons/lamp.off.
 = Plugins =