DevelopmentFHEMWEB
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 for details).
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/ 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 returns 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 displayed preceding 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 be any of
- html-code, checked by regexp <.*>
- empty (""), will display the state as a plain text link
- undef, will continue the default search mechanism for a matching icon for STATE
webCmdFn
NOTE: webCmdFn is deprecated. the new javascript widgets should be used.
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 original thread in fhem-forum.