Weather Info on Web Pages using Websockets

While weather data can be displayed in web pages using <HV:Run </i>> and <HV:Image </i>> tags (See Triggering Weather Fetches), the weather data is determined at the time the web page is sent to the browser and is static thereafter. The Weather plug-in can send "real-time" weather data to web pages via the Web plug-in's websockets.

Web plug-in version 7.2 or later is required to support websockets. See the "Real-time Updates of Web Pages" help page in the Web plug-in for more details on websockets.

An additional supplementary plug-in, wxjsondata.hap, provides support for websockets. If websocket support is desired, this plug-in should be enabled. Also, if other custom objects are supported, then wxjsondata.hap should be enabled. Otherwise, it can remain disabled.

An additional supplementary JavaScript file containing websocket setup and weather helper functions, wxwebsocket.js, is also required. This file is placed in the plugin/html directory when the weather plug-in is installed. If your web server uses a directory other than plugin/html to store its web files, you must manually move wxwebsocket.js to that directory.

Like the Web plug-in's "real-time" support for HomeVision objects, to get weather data in "real-time", the following is needed:

• One or more HTML tags that define the desired data.
• A Script tag that sources the weather websocket functions (wxwebsocket.js).
• A JavaScript array that describes how to handle each tag.

Example:

    <center>
    <h3>Weather</h3>
    <HV:Image png WeatherGetIcon id="icon">
    <br>
    <span id="wind"><HV:Run WeatherGet Wind></span>
    <br>
    <span id="fcloc"><HV:Run WeatherGet FcLoc></span>
    <br>
    <span id="fcday1"><HV:Run WeatherGet FcDay1></span>
    <br>
    <HV:Image png WeatherGetIcon FcImg1 id="iconfc1">
    <br>
    <span id="FcSc1"><HV:Run WeatherGet FcSc1></span>
    </center>
    <script src="wxwebsocket.js" type="text/javascript"></script>
    <script type="text/javascript">
    if (typeof(hvobjs) === "undefined") {hvobjs = {}}
    hvobjs["wx"] = [
        {
            "element": document.getElementById("icon"),
            "index": 0, "function": wxf, "type": "icon"
        }, {
            "element": document.getElementById("wind"),
            "index": 0, "function": wxf, "type": "wind"
        }
     ]
     hvobjs["fc"] = [
         {
            "element": document.getElementById("fcloc"),
            "index": 0, "function": fcf, "type": "loc"
         }, {
            "element": document.getElementById("fcday1"),
            "index": 1, "function": fcf, "type": "day"
         }, {
            "element": document.getElementById("iconfc1"),
            "index": 1, "function": fcf, "type": "img"
         }, {
            "element": document.getElementById("FcSc1"),
            "index": 1, "function": fcf, "type": "sc"
         }
     ]
     </script>

Let's go through this rather simple example.

The first part has a series of HTML tags that will show the current weather icon and the current wind, followed by the forecast location, "day 1" day name, weather icon, and the short weather description. Note each HTML tag of interest has a unique ID. The <HV:Image> tag will generate an HTML <img> tag with the included "id". The other <HV> tags need a surrounding HTML tag. In this case, a simple <span> tag will do.

Technically, when using websockets to provide weather data, the <HV> tags are not necessary. An "empty" HTML tag like this:

    <span id="wind"></span>

would display the right weather text via websockets. However, it is probably a good idea to include the corresponding <HV> tag so that some information will be shown even if a browser that doesn't support websockets is used.

Next, the wxwebsocket.js script is sourced. This JavaScript file sets up the websocket and provides weather helper functions.
Note: weather objects and standard HomeVision objects (e.g., "var") can be mixed in a web page, as long as

    <script src="wxwebsocket.js" type="text/javascript"></script>

comes AFTER

    <script src="hvwebsocket.tcl" type="text/javascript"></script>

Lastly, the hvobjs array is set up with an entry for each weather item. There are two separate "sub-arrays", one for current weather info - "wx", and one for forecast info - "fc".

• The "element" part identifies a specific HTML tag, according to the tag's "id".
• The "index" is always "0" for current weather items. For forecast information, index "0" contains general information items for the forecast (e.g., location). Index "1" through "7" contain the day-specific forecast information for day "n".
• The "function" and "type" parts specify the weather helper function and its "sub-function". The helper function retrieves specific weather information from data received over the websocket.

Weather Helper Functions

The weather helper functions are divided into two main functions: "wxf" for current weather, and "fcf" for forecast weather. Each has its own "sub functions", which are specified in the "type" field. Note that when specifying the helper function in the "function" field of the array, it is NOT quoted. However, the "sub function" specified in the "type" filed IS quoted.

Selecting Weather Items and Corresponding Helper Functions

Possible weather items for web use are the same as those for the Control plug-in. In the same way as for the Control plug-in, a subset of items can be selected for web use, but independently of those selected for the Control plug-in. Since there are a lot of possible weather items, some of which can be very wordy, it is a good idea to minimize the amount of data transmitted over the websocket by selecting only those items actually needed by the web pages. See Using Weather Control Variables for how to set up which items to send over the websocket.

To use a weather item on a web page, you must configure its corresponding array entry to use the right helper function and sub function.

For current weather, "function" is "wxf" and the sub function ("type") is as follows:

• For items in Table 2 the sub function ("type") is exactly the name of the variable, but in lower case. One exception is "WeatherIcon", which uses the sub function "img". The "index" is always "0". Example: TempC would be

    "index": 0, "function": wxf, "type": "tempc"

For forecast weather, "function" is "fcf" and the sub function ("type") is as follows:

• For items in Table 3 that have no day number, the sub function ("type") is the name of the variable without the leading "fc", and in lower case. The "index" is "0". Example: Fcloc would be

    "index": 0, "function": fcf, "type": "loc"

• For items in Table 3 that have a day number, the sub function ("type") is the name of the variable without the leading "fc" and without the trailing day number, and in lower case. The "index" is "n". where n is the day number.
  
  Example: Fcdayn2 would be

    "index": 2, "function": fcf, "type": "dayn"

• When using the NWS as a source, both "day" and "night" forecasts are available for any specific day. However, sometimes only one of the "day" and "night" sets of infomation for the first or last day are provided. For example, a weather fetch in the evening will usually have only the "night" forecast for that day. For these situations, a set of forecast sub functions are available that choose the best information (either the day or the night data) for a specific day: "bestday", "bestsc", "bestlc", "bestpop", "bestimg".
  
  Example: To get either the day or night icon for day one, depending on which was available:

    "index": 1, "function": fcf, "type": "bestimg"

Changing Weather Settings Via a Web Page

The wxinvoke function is used primarily with an HTML button or input object's "onclick" attribute. wxinvoke sends an WeatherSet command through the websocket to the web server, which in turn sends it to the Weather plug-in for execution. Using wxinvoke allows web control of any action that WeatherSet can do. Arguments for wxinvoke are the same as those used for the WeatherSet command. See Triggering Weather Fetches for details.

Here's an example that has an entry box to put in the zipcode, a button to send the entry box's value, and another button to trigger a new weather fetch with the new zipcode information.

    <form>
    <input id="szip" class="entry" type="text" name="setzip"/>
    <button class="button" onclick="return wxinvoke('ZipCode ' + this.form.setzip.value)">Set ZipCode</button>
    </form>
    <button class="button" onclick="return wxinvoke('Go')">Update</button>
    .
    .
    .
    <script src="wxwebsocket.js" type="text/javascript"></script>
    <script type="text/javascript">
    hvobjs["wx"] = [
       {
           "element": document.getElementById("szip"),
           "index": 0, "function": wxf, "type": "zipcode"
       }
    ]
    </script>

Next:
Custom Objects and Websockets
Weather Info for NetIO
Weather with MQTT
See Also:
Introduction to the Weather Plug-in
Web-Based Weather Data
Using Weather Control Variables
Forecast Examples
HomeVision Controller Weather Variables
Local Weather Data Files
Speaking Weather Data
Triggering Weather Fetches
Disclaimer