Merge pull request #38 from JVital2013/themes

Implement Theming

README.md

@@ -14,10 +14,11 @@ A Web App for showcasing Geostationary Weather Satellite Data. Vitality GOES is
 4. [Installing Vitality GOES](#installing-vitality-goes)
 5. [Configuring Vitality GOES](#configuring-vitality-goes)
 6. [Updating Vitality GOES](#updating-vitality-goes)
-7. [Integrating weather data into Home Assistant](#integrating-weather-data-into-home-assistant)
-8. [Creating configs for other satellites](#creating-configs-for-other-satellites)
-9. [Credits](#credits)
-10. [Additional Resources](#additional-resources)
+7. [Theming](#theming)
+8. [Integrating weather data into Home Assistant](#integrating-weather-data-into-home-assistant)
+9. [Creating configs for other satellites](#creating-configs-for-other-satellites)
+10. [Credits](#credits)
+11. [Additional Resources](#additional-resources)
 
 ## What does Vitality GOES do?
 
@@ -149,6 +150,9 @@ If you still have your cloned vitality-goes repo from last time, you can also ju
 3. Open a command line within the extracted zip's vitality-goes-main directory
 4. Run the following command: `robocopy html C:\xampp\htdocs /MIR /R:0 /W:0 /XD videos config`
 
+## Theming
+Vitality GOES supports theming. It comes with 5 themes, but you can make your own or install others shared with you. To get started with theming, [take a look at the themes documentation](/docs/themes.md).
+
 ## Integrating weather data into Home Assistant
 Home Assistant is a free and open-source smart home control system. You can use Vitality GOES as a "Weather Provider" in Home Assistant; [look here](docs/home-assistant.md) for more.
 
@@ -170,6 +174,7 @@ Also special thanks to [Aang23 for his SatDump package](https://github.com/altil
 The following software packages are included in Vitality GOES:
 * **FontAwesome Free** ([https://fontawesome.com](https://fontawesome.com/)): made available under the Creative Commons License
 * **LightGallery by Sachin Neravath** ([https://www.lightgalleryjs.com](https://www.lightgalleryjs.com/)): made available under the GPLv3 License.
+* **Perfect DOS VGA 437 Font** ([https://www.dafont.com/perfect-dos-vga-437.font])(https://www.dafont.com/perfect-dos-vga-437.font): available in the Public Domain
 * **OpenSans** ([https://fonts.google.com/specimen/Open+Sans](https://fonts.google.com/specimen/Open+Sans)): made available under the Apache License.
 * **SimplerPicker** ([https://github.com/JVital2013/simplerpicker](https://github.com/JVital2013/simplerpicker)): made available under the MIT License.
 

configs/goestools-goes16/config.ini

@@ -1,4 +1,6 @@
 [general]
+;siteTitle = "My GOES-16 Data"
+;siteTheme = "light"
 ;graphiteAPI	= http://127.0.0.1:8080/render/
 ;adminPath = /path/to/goestoolsrepo/text
 emwinPath = /path/to/goestoolsrepo/emwin

configs/goestools-goes17/config.ini

@@ -1,4 +1,6 @@
 [general]
+;siteTitle = "My GOES-17 Data"
+;siteTheme = "light"
 ;graphiteAPI	= http://127.0.0.1:8080/render/
 ;adminPath = /path/to/goestoolsrepo/text
 emwinPath = /path/to/goestoolsrepo/emwin

configs/goestools-goes18/config.ini

@@ -1,4 +1,6 @@
 [general]
+;siteTitle = "My GOES-18 Data"
+;siteTheme = "light"
 ;graphiteAPI	= http://127.0.0.1:8080/render/
 ;adminPath = /path/to/goestoolsrepo/text
 emwinPath = /path/to/goestoolsrepo/emwin

configs/satdump-goes16/config.ini

@@ -1,4 +1,6 @@
 [general]
+;siteTitle = "My GOES-16 Data"
+;siteTheme = "light"
 ;satdumpAPI = http://127.0.0.1:8080/
 adminPath = "F:\path\to\satdumprepo\Admin Messages"
 emwinPath = "F:\path\to\satdumprepo\EMWIN"

configs/satdump-goes17/config.ini

@@ -1,4 +1,6 @@
 [general]
+;siteTitle = "My GOES-17 Data"
+;siteTheme = "light"
 ;satdumpAPI = http://127.0.0.1:8080/
 adminPath = "F:\path\to\satdumprepo\Admin Messages"
 emwinPath = "F:\path\to\satdumprepo\EMWIN"

configs/satdump-goes18/config.ini

@@ -1,4 +1,6 @@
 [general]
+;siteTitle = "My GOES-18 Data"
+;siteTheme = "light"
 ;satdumpAPI = http://127.0.0.1:8080/
 adminPath = "F:\path\to\satdumprepo\Admin Messages"
 emwinPath = "F:\path\to\satdumprepo\EMWIN"

docs/config.md

@@ -10,13 +10,15 @@ Configurations are highly customizable and can be modified to fit your configura
 * **meso.ini**: Contains information about your mesoscale images.
 * **l2.ini**: Contains infromation about your ABI Level 2 products. These images contain information about estimated rainfall, land surface temp, sea surface temp, and more. Note that goestools does not receive these unless your goesproc config is set up to do so, and SatDump is currently not supported. The sample goesproc config in this repository is configured correctly, but if you're not saving these files, delete l2.ini.
 
-These ini files are parsed with the php [parse_ini_file](https://www.php.net/manual/en/function.parse-ini-file.php) function, so any comments must begin with a semicolon (;).
+Any comments must begin with a semicolon (;).
 
 ## config.ini
 
 This is the main config file. It will likely need configured when you first deploy Vitality GOES. It is broken out into the following sections:
 
 ### General
+* `siteTitle`: Sets the title of the Vitality GOES Web App. If not set, the site title defaults to "Vitality GOES"
+* `siteTheme`: The theme for Vitality GOES. Leave unset to use the built-in theme, or set it to an installed theme. The included themes are "light", "purple", "red", and "uos". This option can be overridden per-browser by using the "Local Settings" screen. For more on theming, [look here](/docs/themes.md).
 * `graphiteAPI`: If you're using goestools and want to view its decoder/demodulator statistcs, this should point to your graphite host. It must include the `/render/` path at the end to work properly. If you're not using goestools/graphite, comment/remove this line. For information on how to set up graphite, [look here](/docs/graphite.md).
 * `satdumpAPI`: Points to the SatDump REST API to pull decoder/demodulator statistics. You must run SatDump with the `--http_server` flag to get statistics. If you're not using SatDump or don't want statistics, comment/delete this line.
 * `emwinPath`: Point to the emwin repository of your choice. If you're picking up both GOES West and East, you can use either's EMWIN files. Comment/delete this line to completely disable emwin data (text and images), or if you're not picking up data from a GOES satellite.
@@ -40,7 +42,7 @@ If hosted on Windows, set your paths to something like `GOES16 = C:\path\to\satd
 ### Location
 This section contains information about your physical location. If you're not displaying EMWIN data, the only thing you need to configure is `timezone`. A list of supported timezones can be found [here](https://www.php.net/manual/en/timezones.php).
 
-If you are displaying EMWIN/local weather data, here's what each of the other options mean. Note that these options can also be changed per client web browser by using the "configure location" screen in Vitality GOES.
+If you are displaying EMWIN/local weather data, here's what each of the other options mean. Note that these options can also be changed per client web browser by using the "Local Settings" screen in Vitality GOES.
 
 * `radarCode`: The last 5 letters of the radar file for your region. In the emwin directory, all radar files end with RAD{radarCode}.GIF. **The radar image you want to display must be configured as an available image in emwin.ini**
 
@@ -62,13 +64,13 @@ If you are displaying EMWIN/local weather data, here's what each of the other op
   *  STHPL (Southern Plains Region)
   *  UMSVY (Upper Mississippi Valley)
 *  `stateAbbr`: The post office abbreviation of your state. Also includes things like PR for Puerto Rico, AS for American Samoa, etc.
-*  `wxZone`: The weather zone of your location. This is typically your state abbreviation, a Z, and a 3 digit number. Example: PAZ066. You can either use the "Configure Location" section of Vitality GOES to figure this out, or use [this site](https://pnwpest.org/cgi-bin/wea3/wea3) to search for your town. "Weather Zone" shows up in the upper-right of that page.
-*  `orig`: The National Weather Service Forecast Office for your local weather information. The code needs to be the office call sign, plus the 2-letter state abbreviation. You can either use the "Configure Location" section of Vitality GOES to figure this out, or look at [https://en.wikipedia.org/wiki/List_of_National_Weather_Service_Weather_Forecast_Offices](https://en.wikipedia.org/wiki/List_of_National_Weather_Service_Weather_Forecast_Offices). For example, State College PA is "CTP", so orig needs to be set to `CTPPA`
+*  `wxZone`: The weather zone of your location. This is typically your state abbreviation, a Z, and a 3 digit number. Example: PAZ066. You can either use the "Local Settings" section of Vitality GOES to figure this out, or use [this site](https://pnwpest.org/cgi-bin/wea3/wea3) to search for your town. "Weather Zone" shows up in the upper-right of that page.
+*  `orig`: The National Weather Service Forecast Office for your local weather information. The code needs to be the office call sign, plus the 2-letter state abbreviation. You can either use the "Local Settings" section of Vitality GOES to figure this out, or look at [https://en.wikipedia.org/wiki/List_of_National_Weather_Service_Weather_Forecast_Offices](https://en.wikipedia.org/wiki/List_of_National_Weather_Service_Weather_Forecast_Offices). For example, State College PA is "CTP", so orig needs to be set to `CTPPA`
 *  `lat` and `lon`: Your exact latitude and longitude. This is only used to determine if you're within an alert area as issued by the NWS. It must contain 2 decimal points to work correctly
-*  `rwrOrig` *(Optional)*: Accepts the same type of code as `orig`, but specifically for the Regional Weather Roundup information ("Current Weather" card in the Vitality GOES interface). It appears that the weather roundup is sometimes issued by a different office than the rest of your forecast. Use the "Configure Location" section within Vitality GOES to figure this out. *If not set, your `orig` value will be used in place of rwrOrig*
-*  `city` *(Optional)*: Your city/town name, exactly as it appears in the Regional Weather Roundup (RWR). The "Configure Location" screen in Vitality GOES can help you figure this out. *If not set, the "Current Weather" card in the current weather screen will not be shown.*
+*  `rwrOrig` *(Optional)*: Accepts the same type of code as `orig`, but specifically for the Regional Weather Roundup information ("Current Weather" card in the Vitality GOES interface). It appears that the weather roundup is sometimes issued by a different office than the rest of your forecast. Use the "Local Settings" section within Vitality GOES to figure this out. *If not set, your `orig` value will be used in place of rwrOrig*
+*  `city` *(Optional)*: Your city/town name, exactly as it appears in the Regional Weather Roundup (RWR). The "Local Settings" screen in Vitality GOES can help you figure this out. *If not set, the "Current Weather" card in the current weather screen will not be shown.*
 
-You may find that the location section is the hardest part of the config to set up. I would recommend leaving it at its defaults, then use the "Configure Location" screen in Vitality GOES to determine what each value should be set to for your location. Once you have it working client-side, configure the settings as appropraite in this config file.
+You may find that the location section is the hardest part of the config to set up. I would recommend leaving it at its defaults, then use the "Local Settings" screen in Vitality GOES to determine what each value should be set to for your location. Once you have it working client-side, configure the settings as appropraite in this config file.
 
 ## abi.ini, meso.ini, and l2.ini
 

docs/themes.md

@@ -0,0 +1,38 @@
+# Themes
+
+Vitality GOES supports theming to give the web app a completely different look and feel. To set a theme globally, [configure the `siteTheme` option in your config.ini ](/docs/config.md#general) to match the desired theme ID.
+
+Your users can also select an available theme from the "Local Settings" screen in the Web App to customize it on their local device.
+
+<img src='https://user-images.githubusercontent.com/24253715/211178470-463b3597-2a65-469f-b75e-e27278e34ada.png' width='49%' /> <img src='https://user-images.githubusercontent.com/24253715/211178484-245fc793-4df8-47ce-889a-e99e18fb7d93.png' width='49%' />
+
+## Included Themes
+The following themes are included with Vitality GOES:
+
+|Name                 |ID (Folder Name) |Description                                                                     |
+|:--------------------|:----------------|:-------------------------------------------------------------------------------|
+|*Built-in*           |*default/unset*  |*The default theme for Vitality GOES if another valid theme is not selected*    |
+|Dark Red             |red              |Red variant of the built-in theme                                               |
+|GOES Assistant       |light            |Light theme inspiried by Home Assistant                                         |
+|Purple               |purple           |My very supportive wife wanted to make her own theme and I said OK              |
+|RobCo Industries UOS |uos              |Vitality GOES for RobCo's Unified Operating System (UOS). Pip-Boy not included. |
+
+## Installing Themes
+A theme is simply a folder containing `theme.ini` and one or more CSS stylesheets/associated resources. To install a theme, copy the theme folder into the `/themes/` folder of your Vitality GOES installation. Afterwards, you can use its folder name in `siteTheme` of your config.ini file.
+
+The theme will also be selectable in the "Local Settings" screen.
+
+![Example Theme Structure](https://user-images.githubusercontent.com/24253715/211179202-700ce13b-92bd-413d-88e0-6cffdf314b0d.png)
+
+## Making Themes
+Making themes requires knowledge of CSS. To make a theme, follow the steps below. You can also copy an existing theme [from this repository](/html/themes/) and modify it as necessary.
+
+1. Create an empty folder in the `themes` folder of your Vitality GOES Installation. The name you give it will be used to select it with the `siteTheme` option.
+2. Create a blank file named `index.html` in the theme folder for security purposes
+3. Create a file named `theme.ini` in the theme folder. Configure the following options in it:
+
+    - `name`: Human-readable name of the theme as shown in the web interface. *Optional*
+    - `themeColor`: Background color used for the theme. Used by the web app's manifest for coloring the user's web browser. *Optional*
+    - `stylesheets[]`: Array of CSS stylesheets to be loaded into the web app. Can be speficied multiple times. Specify either a path relative to the theme folder, or a full URL for an external stylesheet. *At least one stylesheet is required*
+
+Finally, add custom styles into the stylesheet specified in `theme.ini`. Any styles specified will override those set in the built-in theme, making for a highly configurable user experience.

html/dataHandler.php

@@ -1,6 +1,6 @@
 <?php
 /* 
- * Copyright 2022 Jamie Vital
+ * Copyright 2022-2023 Jamie Vital
  * This software is licensed under the GNU General Public License
  * 
  * This file is part of Vitality GOES.
@@ -22,7 +22,12 @@
 $config = loadConfig();
 
 //Only display errors if set to in the config
-ini_set("display_errors", ($config['general']['debug'] ? "On" : "Off"));
+if($config['general']['debug'])
+{
+	ini_set("display_errors", "On");
+	error_reporting(E_ALL);
+}
+else ini_set("display_errors", "Off");
 
 //Load Current User Settings from Cookie
 $sendCookie = false;
@@ -184,8 +189,12 @@
 	$preloadData['showSysInfo'] = $config['general']['showSysInfo'];
 	$preloadData['showSatdumpInfo'] = array_key_exists('satdumpAPI', $config['general']);
 	$preloadData['showGraphs'] = array_key_exists('graphiteAPI', $config['general']);
-	$preloadData['showEmwinInfo'] = array_key_exists('emwinPath', $config['general']) &&  is_dir($config['general']['emwinPath']);
-	$preloadData['showAdminInfo'] = array_key_exists('adminPath', $config['general']) &&  is_dir($config['general']['adminPath']);
+	$preloadData['showEmwinInfo'] = array_key_exists('emwinPath', $config['general']) && is_dir($config['general']['emwinPath']);
+	$preloadData['showAdminInfo'] = array_key_exists('adminPath', $config['general']) && is_dir($config['general']['adminPath']);
+
+	$currentTheme = loadTheme($config);
+	if($currentTheme === false) $preloadData['theme'] = "default";
+	else $preloadData['theme'] = $currentTheme['slug'];
 
 	header('Content-Type: application/json; charset=utf-8');
 	echo json_encode($preloadData);
@@ -736,7 +745,15 @@
 
 			sort($dropdownList);
 			break;
-
+		case "theme":
+			$themes = findAllThemes();
+			$dropdownList['default'] = "Built-In (Dark)";
+			foreach($themes as $theme => $themeData)
+			{
+				if(array_key_exists("name", $themeData)) $dropdownList[$theme] = htmlspecialchars(strip_tags($themeData['name']));
+				else $dropdownList[$theme] = htmlspecialchars(strip_tags($theme));
+			}
+			break;
 		default:
 			break;
 	}
@@ -1090,7 +1107,7 @@
 				if(is_array($dataValue))
 				{
 					usort($returnData[$stormKey][$dataKey], 'sortByTimestamp');
-					for($i = 0; $i < count($returnData[$stormKey][$dataKey]); $i++) $returnData[$stormKey][$dataKey][$i]['subHtml'] = "<b>" . $returnData[$stormKey]['title'] . "</b><div class='goeslabel gl-overlay'>" . $returnData[$stormKey][$dataKey][$i]['description'] . "</div>";
+					for($i = 0; $i < count($returnData[$stormKey][$dataKey]); $i++) $returnData[$stormKey][$dataKey][$i]['subHtml'] = "<b>" . $returnData[$stormKey]['title'] . "</b><div class='lgLabel'>" . $returnData[$stormKey][$dataKey][$i]['description'] . "</div>";
 				}
 			}
 		}