.config/awesome/lain/wiki/weather.md

   1 ## Usage
   2
   3 [Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
   4
   5 ### Description
   6
   7 Provides current weather status widgets and X-days forecast popup notifications.
   8
   9 Powered by [OpenWeatherMap](http://openweathermap.org/api) API.
  10
  11 By default, it uses [current](http://openweathermap.org/current) for current weather data and [forecast16](http://openweathermap.org/forecast16) for forecasts.
  12
  13 ```lua
  14 local myweather = lain.widget.weather()
  15 ```
  16
  17 ## Input table
  18
  19 Variable | Meaning | Type | Default
  20 --- | --- | --- | ---
  21 `timeout` | Refresh timeout seconds for current weather status | number | 900 (15 min)
  22 `timeout_forecast` | Refresh timeout seconds for forecast notification | number | 86400 (24 hrs)
  23 `current_call` | Command to fetch weather status data from the API | string | see `default_current_call`
  24 `forecast_call` | Command to fetch forecast data from the API | string | see `default_forecast_call`
  25 `city_id` | API city code | number | not set
  26 `utc_offset` | UTC time offset | function | see [here](https://github.com/lcpz/lain/blob/master/widget/weather.lua#L35-L39)
  27 `units` | Temperature units system | string | "metric"
  28 `lang` | API data localization | string | "en"
  29 `cnt` | Forecast days interval | integer | 5
  30 `date_cmd` | Forecast notification format style | string | "date -u -d @%d +'%%a %%d'"
  31 `icons_path` | Icons path | string | `lain/icons/openweathermap`
  32 `notification_preset` | Preset for notifications | table | empty table
  33 `notification_text_fun` | Function to format forecast notifications | function | see `notification_text_fun` below
  34 `weather_na_markup` | Markup to be used when weather textbox is not available | text | " N/A "
  35 `followtag` | Display the notification on currently focused screen | boolean | false
  36 `showpopup` | Display popups with mouse hovering | string, possible values: "on", "off" | "on"
  37 `settings` | User settings | function | empty function
  38
  39 - ``default_current_call``
  40
  41     `"curl -s 'http://api.openweathermap.org/data/2.5/weather?id=%s&units=%s&lang=%s'"`
  42
  43     You can rewrite it using any fetcher solution you like, or you can modify it in order to fetch data by city name, instead of ID: just replace `id` with `q`:
  44
  45     `"curl -s 'http://api.openweathermap.org/data/2.5/weather?q=%s&units=%s&lang=%s'"`
  46
  47     and set `city_id` with your city name, for instance `city_id = "London,UK"`.
  48
  49 - ``default_forecast_call``
  50
  51     `"curl -s 'http://api.openweathermap.org/data/2.5/forecast/daily?id=%s&units=%s&lang=%s&cnt=%s'"`
  52
  53     Like above.
  54     If you want to use [forecast5](http://openweathermap.org/forecast5), use this API call string:
  55     `http://api.openweathermap.org/data/2.5/forecast?id=%s&units=%s&lang=%s&cnt=%s`
  56
  57 - ``city_id``
  58
  59     An integer that defines the OpenWeatherMap ID code of your city.
  60     To obtain it go to [OpenWeatherMap](http://openweathermap.org/) and query for your city in the top search bar. The link will look like this:
  61
  62         http://openweathermap.org/city/2643743
  63
  64     your `city_id` is the number at the end.
  65
  66 - ``units``
  67
  68     - For temperature in Fahrenheit use `units = "imperial"`
  69     - For temperature in Celsius use `units = "metric"` (Lain default)
  70     - For temperature in Kelvin use `units = "standard"` (OpenWeatherMap default)
  71
  72 - ``lang``
  73
  74     See *Multilingual Support* section [here](http://openweathermap.org/current).
  75
  76 - ``cnt``
  77
  78     Determines how many days to show in the forecast notification. Up to 16 if you use [forecast16](http://openweathermap.org/forecast16)  (default), and up to 5 if you use [forecast5](http://openweathermap.org/forecast5).
  79
  80 - ``date_cmd``
  81
  82     OpenWeatherMap time is in UNIX format, so this variable uses `date` to determine how each line in the forecast notification is formatted. Default looks like this:
  83
  84         day #daynumber: forecast, temp_min - temp_max
  85
  86     see `man date` for your customizations.
  87
  88 - ``icons_path``
  89
  90     You can set your own icons path if you don't wish to use `lain/icons/openweathermap`. Just be sure that your icons are PNGs and named exactly like [OpenWeatherMap ones](http://openweathermap.org/weather-conditions).
  91
  92 - ``notification_preset``
  93
  94    Notifications preset table. See [here](https://awesomewm.org/doc/api/libraries/naughty.html#notify) for the details.
  95
  96 - ``notification_text_fun``
  97    ```lua
  98    function (wn)
  99        local day = string.gsub(read_pipe(string.format(date_cmd, wn["dt"])), "\n", "")
 100        local tmin = math.floor(wn["temp"]["min"])
 101        local tmax = math.floor(wn["temp"]["max"])
 102        local desc = wn["weather"][1]["description"]
 103
 104        return string.format("<b>%s</b>: %s, %d - %d ", day, desc, tmin, tmax)
 105    end
 106    ```
 107    See [here](https://github.com/lcpz/lain/issues/186#issuecomment-203400918) for a complete customization example.
 108
 109 - ``followtag``
 110
 111    With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.
 112
 113 - ``settings``
 114
 115     In your `settings` function, you can use `widget` variable to refer to the textbox, and the dictionary `weather_now` to refer to data retrieved by `current_call`. The dictionary is built with [dkjson library](http://dkolf.de/src/dkjson-lua.fsl/home), and its structure is defined [here](http://openweathermap.org/weather-data).
 116     For instance, you can retrieve current weather status and temperature in this way:
 117     ```lua
 118     descr = weather_now["weather"][1]["description"]:lower()
 119     units = math.floor(weather_now["main"]["temp"])
 120     ```
 121
 122 ## Output table
 123
 124 Variable | Meaning | Type
 125 --- | --- | ---
 126 `widget` | The widget | `wibox.widget.textbox`
 127 `icon` | The icon | `wibox.widget.imagebox`
 128 `update` | Update `widget` | function
 129 `timer` | The widget timer | [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html)
 130 `timer_forecast` | The forecast notification timer | [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html)
 131
 132 ## Functions
 133
 134 You can attach the forecast notification to any widget like this:
 135
 136 ```lua
 137 myweather.attach(obj)
 138 ```
 139
 140 Hovering over ``obj`` will display the notification.
 141
 142 ## Keybindings
 143
 144 You can create a keybinding for the weather popup like this:
 145
 146 ```lua
 147 awful.key( { "Mod1" }, "w", function () myweather.show(5) end )
 148 ```
 149
 150 where ``show`` argument is an integer defining timeout seconds.