DevelopmentFHEMWEB

Aus FHEMWiki

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.