displayWeatherStat Documentation

Purpose

The node is designed to generate visual representations of weather statistics. It retrieves and formats weather data, providing either a single statistic display or a forecast chart based on the specified inputs. This functionality encompasses both the ability to display current weather information (e.g., temperature, humidity) and forecast trends over a defined time period.

Settings

The function operates based on settings provided through the inputs and config parameters. Below are the critical settings that it uses:

Inputs

1. input1

   • Type: Object
   • Description: Main container for input data pertaining to the weather statistics.
   • Default Value: None (must be provided).

   Inside input1, the following specific settings are critical:

   • city

     • Type: Object
     • Description: Contains the name of the city for which the weather data is being displayed.
     • Default Value: None (required to provide the city name).

   • name

     • Type: String
     • Description: Alternative name reference for the weather statistics. This will be used if the city object is not provided.
     • Default Value: None.

   • filteredStat

     • Type: String
     • Description: Identifies the type of weather statistic being displayed (e.g., Temperature, Humidity). This will directly influence both the data fetched and how it is visualized.
     • Default Value: None (specific value must be passed).

   • unitStandard

     • Type: String
     • Description: Specifies the unit system to use for the weather data (e.g., "metric" or "imperial"). Affects the display of temperature, wind speed, etc.
     • Default Value: "metric".

   • type

     • Type: String
     • Description: Determines the type of display. The value can be "single" for a single statistic or "forecast" for a trend chart.
     • Default Value: None (must be provided).

   • value (only applies when type is "single")

     • Type: Numeric
     • Description: The actual value of the filtered statistic to display (e.g., current temperature).
     • Default Value: None.

   • list (only applies when type is "forecast")

     • Type: Array | Object
     • Description: An array or object containing forecast data points related to the filtered statistics over time. Required for generating charts.
     • Default Value: None.

Config

The config parameter can further configure the output display:

• tile_type

  • Type: String
  • Description: Defines the type of visual tile, which can be either "stat" or "chart". Determines the layout for the weather information.
  • Default Value: Determined based on the type of display selected (single or forecast).

• title

  • Type: String
  • Description: The title of the weather display component, usually incorporating the filtered statistic and city name.
  • Default Value: Automatically generated based on filteredStat and input1.city or name.

• subtitle

  • Type: String
  • Description: A secondary descriptor for the display, often empty or simplified description.
  • Default Value: Empty string.

• footerText

  • Type: String
  • Description: Text shown at the bottom of the display indicating when the data was last updated.
  • Default Value: Formatted timestamp generated by serverDate().

• footerColor

  • Type: String
  • Description: CSS class for footer text color.
  • Default Value: "text-gray-500".

• height (only applies when tile_type is "chart")

  • Type: Numeric
  • Description: The height of the chart visual representation.
  • Default Value: 2.

• width (only applies when tile_type is "chart")

  • Type: Numeric
  • Description: The width of the chart visual representation.
  • Default Value: 2.

• chartType (only applies when tile_type is "chart")

  • Type: String
  • Description: Specifies which type of chart to render, in this case, a "line" chart for trend visualization.
  • Default Value: "line".

• xKey (only applies when tile_type is "chart")

  • Type: String
  • Description: The key from the data used for the X-axis representation, usually time.
  • Default Value: "time".

• axisLabels (only applies when tile_type is "chart")

  • Type: Object
  • Description: Contains labels for both the X and Y axes.
  • Default Value: X: "Hours", Y: ${filteredStat} (${getUnits(filteredStat, unitSystem)}).

• showGrid (only applies when tile_type is "chart")

  • Type: Boolean
  • Description: Determines whether grid lines should be displayed on the chart.
  • Default Value: true.

• showTooltip (only applies when tile_type is "chart")

  • Type: Boolean
  • Description: Indicates if tooltips should appear when hovering over chart points.
  • Default Value: true.

• showLegend (only applies when tile_type is "chart")

  • Type: Boolean
  • Description: Toggles the visibility of the legend on the chart.
  • Default Value: true.

• series (only applies when tile_type is "chart")

  • Type: Array
  • Description: Configuration for the data series displayed within the chart, including color and labels.
  • Default Value: Default series defined based on filteredStat.

• data (only applies when tile_type is "chart")

  • Type: Array
  • Description: The actual data points transformed into the structure required for charting. Generated by the node.
  • Default Value: None, as this will be generated dynamically based on the list.

How It Works

1. The function begins by assessing the inputs to determine the relevant data points for the weather statistics.
2. It generates a timestamp using the node to indicate when the information was last updated.
3. Depending on the selected type in the input data ("single" or "forecast"), it formats the data accordingly:
   • Single Statistic Display: Formats and returns the value alongside the title, including special formatting for specific attributes like wind and weather conditions.
   • Forecast Chart: Prepares data points for a line chart based on the timestamped list of forecasted values.
4. Values are adjusted according to the selected unit system (metric or imperial), ensuring the output is contextually relevant to the user's preference.
5. The return structure is designed for seamless integration into user interfaces, offering clear formatting options for titles, visuals, and footers.

Use Cases & Examples

Use Cases

1. Real-Time Weather Dashboard

   • A company could utilize the displayWeatherStat to provide real-time weather updates for its logistics operations, ensuring that delivery schedules take into account current weather conditions.

2. Weather Forecast Visualization

   • An application providing travel planning services could display a week-long weather forecast, helping users choose optimal travel days based on conditions like rain and temperature.

3. IoT Weather Monitoring

   • For an IoT-enabled device that monitors weather conditions in a smart home, this logic can be used to visualize and display current and historical weather statistics to users through a mobile interface.

Example Configuration

For a business looking to visualize short-term weather forecasts to inform outdoor event planning, the following configuration could be used:

{
  "inputs": {
    "input1": {
      "city": {
        "name": "San Francisco"
      },
      "filteredStat": "Temperature",
      "unitStandard": "imperial",
      "type": "forecast",
      "list": [
        { "dt": 1634100000, "value": 68 }, // Example timestamped forecast values
        { "dt": 1634103600, "value": 70 },
        { "dt": 1634107200, "value": 72 },
        { "dt": 1634110800, "value": 65 }
      ]
    }
  },
  "config": {}
}

In this example, the node would generate a chart displaying the temperature trend over several hours for San Francisco, allowing users to visualize how the weather changes throughout the day.