Advanced Weather Widget for WordPress

A feature-rich weather widget for WordPress that displays current weather conditions and forecasts using the OpenWeatherMap API. The widget includes automatic fallback to cached data to ensure weather information is always displayed, even during API outages.

Features

• Current Weather Display: Temperature, conditions, humidity, and wind information
• Weather Forecasts: Configurable 3, 5, or 7-day forecasts
• Smart Caching System: Automatic fallback to previously cached data when API is unavailable
• Multiple Temperature Units: Support for both Celsius and Fahrenheit
• Customizable Display Options: Choose which weather elements to show
• Responsive Design: Works seamlessly on desktop, tablet, and mobile devices
• Multiple Layout Styles: Default and Flat design options
• Dark Mode Support: Automatic dark theme adaptation
• Weather Icons: Visual weather condition icons from OpenWeatherMap
• AJAX Updates: Dynamic weather updates without page reload
• Auto-refresh: Automatic weather data refresh every 15 minutes

Requirements

• WordPress 5.0 or higher
• PHP 7.0 or higher
• Free OpenWeatherMap API key (get it from openweathermap.org)

Installation

1. Download the Plugin

   • Download all plugin files to your computer

2. Create Plugin Folder Structure

   adv-weather-widget/
   ├── adv-weather-widget.php
   └── assets/
       ├── weather-widget.css
       └── weather-widget.js

3. Upload to WordPress

   • Upload the adv-weather-widget folder to /wp-content/plugins/ directory
   • Or upload via WordPress admin: Plugins → Add New → Upload Plugin

4. Activate the Plugin

   • Go to WordPress Admin → Plugins
   • Find "Adv Weather Widget" and click "Activate"

5. Get Your API Key

   • Sign up at OpenWeatherMap
   • Get your free API key from your account dashboard

Configuration

Adding the Widget

1. Go to Appearance → Widgets in your WordPress admin
2. Find "Weather Widget" in the available widgets list
3. Drag it to your desired widget area (sidebar, footer, etc.)
4. Configure the widget settings (see below)

Widget Settings

Basic Settings

• Title: Widget title displayed above the weather information
• OpenWeatherMap API Key: Your API key from OpenWeatherMap (required)
• Location: City and country code (Format: City,CountryCode)
  • Examples: London,UK, New York,US, Tokyo,JP, Paris,FR
• Temperature Unit: Choose between Celsius (metric) or Fahrenheit (imperial)

Advanced Settings

• Forecast Days:

  • Disabled (0 days)
  • 3 Days
  • 5 Days (default)
  • 7 Days

• Cache Time: How long to cache weather data (5-60 minutes, default: 15)

  • Lower values = more API calls = more up-to-date data
  • Higher values = fewer API calls = better performance

• Layout Style:

  • Default: Clean white background with subtle shadows
  • Flat: Gradient purple background with modern design

Display Options

Toggle visibility of specific weather elements:

• ☑ Show City name
• ☑ Show Weather Condition (e.g., "Partly cloudy")
• ☑ Show Humidity percentage
• ☑ Show Wind speed and direction

Features Explained

Smart Caching & Fallback System

The plugin implements a two-tier caching system:

1. Temporary Cache (Transients):

   • Stores data for the configured cache time (default: 15 minutes)
   • Reduces API calls and improves performance

2. Permanent Backup:

   • Stores the last successful weather data permanently
   • Used automatically when API is unavailable
   • Ensures weather is ALWAYS displayed, never showing error messages

How it works:

• First load → Fetches from API → Stores in both cache & backup
• Normal operation → Uses cached data
• Cache expires → Fetches fresh data from API
• API fails → Returns backup data silently (no errors shown)

Auto-Refresh

• Weather data automatically refreshes every 15 minutes
• Silent updates in the background (no page reload needed)
• Uses AJAX for seamless user experience

Responsive Design

The widget automatically adapts to different screen sizes:

• Desktop: Two-column layout with forecast in rows
• Tablet: Adjusted spacing and icon sizes
• Mobile: Single-column layout, forecast in vertical list

Dark Mode

Automatically detects system dark mode preference and adjusts colors accordingly.

Usage Examples

Example 1: Basic Setup

Location: London,UK
Temperature Unit: Celsius
Forecast Days: 5

Example 2: US Location

Location: Miami,US
Temperature Unit: Fahrenheit
Forecast Days: 7

Example 3: Minimal Display

Location: Sydney,AU
Temperature Unit: Celsius
Forecast Days: 3
Display Options: ☐ Humidity, ☐ Wind (unchecked)

Example 4: Modern Flat Design

Location: Berlin,DE
Layout: Flat
Temperature Unit: Celsius
Forecast Days: 5

Shortcode Usage

While primarily a widget, you can also display weather programmatically in your theme:

<?php
if (class_exists('Weather_Widget')) {
    $widget = new Weather_Widget();
    $args = array(
        'before_widget' => '<div class="weather-widget-container">',
        'after_widget' => '</div>',
        'before_title' => '<h3 class="widget-title">',
        'after_title' => '</h3>',
    );
    $instance = array(
        'title' => 'Current Weather',
        'api_key' => 'YOUR_API_KEY',
        'location' => 'London,UK',
        'temp_unit' => 'metric',
        'cache_time' => 15,
        'forecast_days' => 5,
        'layout' => 'default',
        'show_city' => true,
        'show_condition' => true,
        'show_humidity' => true,
        'show_wind' => true
    );
    $widget->widget($args, $instance);
}
?>

Troubleshooting

Weather Not Displaying

1. Check API Key: Ensure your OpenWeatherMap API key is valid and active
2. Check Location Format: Use City,CountryCode format (e.g., London,UK)
3. API Activation: New API keys may take up to 2 hours to activate
4. Check Browser Console: Look for JavaScript errors
5. Clear Cache: Clear WordPress and browser cache

"Failed to fetch weather data" Error

This error only appears on first load when:

• API key is invalid
• Location format is incorrect
• API is not yet activated
• No previous backup data exists

Solution: After fixing the issue, the widget will work normally and future API failures will show cached data instead of errors.

Weather Data Not Updating

1. Check if cache time has expired (default: 15 minutes)
2. Click the refresh button manually
3. Check if you've exceeded OpenWeatherMap API limits (60 calls/minute for free tier)

Styling Issues

If the widget doesn't look correct:

1. Clear browser cache
2. Check for CSS conflicts with your theme
3. Inspect with browser developer tools
4. Ensure the CSS file is properly loaded

API Limits

OpenWeatherMap Free Tier:

• 60 calls per minute
• 1,000,000 calls per month
• More than enough for normal widget usage

Plugin API Usage:

• 2 API calls per cache cycle (current + forecast)
• With 15-minute cache: ~192 calls/day per widget
• Well within free tier limits

Customization

Custom Styling

Add custom CSS to your theme's style.css or Customizer:

/* Change widget background */
.weather-widget {
    background: #f5f5f5;
    border-radius: 10px;
}

/* Change temperature color */
.current-temp {
    color: #ff6b6b;
}

/* Modify forecast layout */
.weather-forecast {
    gap: 10px;
}

Modify Temperature Display

To add additional temperature formats, edit weather-widget.js:

formatTemperature: function(temp, unit) {
    var rounded = Math.round(temp);
    var symbol = (unit === 'metric') ? '°C' : '°F';
    return rounded + symbol;
}

Security

• All user inputs are sanitized and validated
• API keys are stored securely in WordPress database
• AJAX requests use WordPress nonces for security
• No external scripts loaded (except weather icons from OpenWeatherMap CDN)

Performance

• Efficient caching system reduces API calls
• Minimal database queries
• Lightweight CSS and JavaScript (~30KB total)
• No jQuery UI or heavy libraries required
• Optimized for fast page load times

Browser Support

• Chrome (latest 2 versions)
• Firefox (latest 2 versions)
• Safari (latest 2 versions)
• Edge (latest 2 versions)
• Mobile browsers (iOS Safari, Chrome Mobile)

Changelog

Version 1.0.2 (Current)

• Added permanent backup system for weather data
• Implemented automatic fallback to cached data on API failures
• Weather data now always displays, even during API outages
• Improved error handling
• Enhanced reliability

Version 1.0.1

• Initial stable release
• Current weather display
• Forecast support (3, 5, 7 days)
• Multiple layout options
• Responsive design
• Dark mode support

Support

For support, questions, or feature requests:

• Email: support@forward.co.in
• Website: https://forward.co.in

License

This plugin is licensed under GPL v2 or later.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

Credits

• Developer: Sachin Solanki
• Website: https://forward.co.in
• Weather Data: OpenWeatherMap API
• Icons: OpenWeatherMap Weather Icons

Privacy Policy

This plugin:

• Does NOT collect or store personal user data
• Does NOT track users
• Only stores weather data temporarily in your WordPress database
• Makes API calls to OpenWeatherMap (subject to their privacy policy)
• Does NOT use cookies

FAQ

Q: Is the plugin free?
A: Yes, the plugin is completely free. You'll need a free OpenWeatherMap API key.

Q: How accurate is the weather data?
A: Weather data comes from OpenWeatherMap, which aggregates data from multiple weather services and meteorological stations.

Q: Can I display multiple weather widgets for different cities?
A: Yes! Add multiple widget instances to your sidebars, each configured for different locations.

Q: Will the widget slow down my site?
A: No. The caching system ensures minimal performance impact. Weather data is loaded asynchronously.

Q: What happens if OpenWeatherMap API is down?
A: The widget automatically displays the last successfully cached weather data, ensuring your visitors always see weather information.

Q: Can I translate the widget?
A: Yes, the plugin is translation-ready with proper text domains. Use a plugin like Loco Translate.

Q: Does it work with page builders?
A: Yes, it works with Elementor, WPBakery, Divi, and other page builders that support WordPress widgets.

Q: Can I use it in my theme's PHP templates?
A: Yes, see the "Shortcode Usage" section above for implementation examples.

Q: How often does the weather update?
A: By default, every 15 minutes (configurable from 5-60 minutes).

---

Made with ❤️ by Sachin Solanki | Forward.co.in