From b7417a07ad441d2d1b925a435e7e7531f746393e Mon Sep 17 00:00:00 2001 From: Jokob-sk Date: Sat, 9 Sep 2023 20:36:00 +1000 Subject: [PATCH] cleanup + docs --- docs/FRONTEND_DEVELOPMENT.md | 46 +++++++++++++++++++++++++++++++++++ docs/README.md | 1 + front/js/pialert_common.js | 32 +++--------------------- front/plugins/README.md | 47 +++++++++++++++--------------------- 4 files changed, 70 insertions(+), 56 deletions(-) create mode 100644 docs/FRONTEND_DEVELOPMENT.md diff --git a/docs/FRONTEND_DEVELOPMENT.md b/docs/FRONTEND_DEVELOPMENT.md new file mode 100644 index 00000000..c87f68ea --- /dev/null +++ b/docs/FRONTEND_DEVELOPMENT.md @@ -0,0 +1,46 @@ +# 🖼 Frontend development + +This page contains tips for frontend development when extending PiAlert. Guiding principles are: + +1. Maintainability +2. Extendability +3. Reusability +4. Placing more functionality into Plugins and enhancing core Plugins functionality + +That means that, when writing code, focus on reusing what's available instead of writing quick fixes. Or creating reusable functions, instead of bespoke functionaility. + +## 🔍 Examples + +Some examples how to apply the above: + +> Example 1 +> +> I want to implement a scan fucntion. Options would be: +> +> 1. To add a manual scan functionality to the `deviceDetails.php` page. +> 2. To create a separate page that handles the execution of the scan. +> 3. To create a configurable Plugin. +> +> From the above, number 3 would be the most appropriate solution. Then followed by number 2. Number 1 would be approved only in special circumstances. + +> Example 2 +> +> I want to change the behavior of the application. Options to implement this could be: +> +> 1. Hard-code the changes in the code. +> 2. Implement the changes and add settings to influence the behavior in the `initialize.py` file so the user can adjust these. +> 3. Implement the changes and add settings via a setting-only plugin. +> 4. Implement the changes in a way so the behavior can be toggled on each plugin so the core capabilities of Plugins get extended. +> +> From the above, number 4 would be the most appropriate solution. Then followed by number 3. Number 1 or 2 would be approved only in special circumstances. + +## 💡 Frontend tips + +Some useful frontend JavaScript functions: + +- `getDeviceDataByMacAddress(macAddress, devicesColumn)` - method to retrieve any device data (database column) based on MAC address in the frontend +- `getString(string stringKey)` - method to retrieve translated strings in the frontend +- `getSetting(string stringKey)` - method to retrieve settings in the frontend + + +Check the [pialert_common.js](https://github.com/jokob-sk/Pi.Alert/blob/main-2023-06-10/front/js/pialert_common.js) file for more frontend function. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 4be76c30..201abb2b 100755 --- a/docs/README.md +++ b/docs/README.md @@ -49,6 +49,7 @@ There is also an in-app Help / FAQ section that should be answering frequently a - [Plugin system details and how to develop your own](/front/plugins/README.md) - [Settings system](/docs/SETTINGS_SYSTEM.md) - [New Version notifications](/docs/VERSIONS.md) +- [Frontend development tips](/docs/FRONTEND_DEVELOPMENT.md) Feel free to suggest or submit new docs via a PR. diff --git a/front/js/pialert_common.js b/front/js/pialert_common.js index f5a88e0b..771abe3d 100755 --- a/front/js/pialert_common.js +++ b/front/js/pialert_common.js @@ -490,34 +490,8 @@ function getNameByMacAddress(macAddress) { } // ----------------------------------------------------------------------------- -// function getDeviceDataByMacAddress(macAddress, property) { - -// const sessionDataKey = 'devicesListAll'; -// const sessionData = sessionStorage.getItem(sessionDataKey); - -// if (!sessionData) { -// console.log(`Session variable "${sessionDataKey}" not found.`); -// return "Unknown"; -// } - -// const devices = JSON.parse(sessionData); - -// for (const device of devices) { -// if (device.mac === macAddress) { -// if ( device.mac == 'd2:a4:1a:74:ae:86') -// { -// console.log(device) -// } - -// return device[property]; -// } -// } - -// return "Unknown"; // Return a default value if MAC address is not found -// } - -// ----------------------------------------------------------------------------- -function getDeviceDataByMacAddress(macAddress, property) { +// +function getDeviceDataByMacAddress(macAddress, dbColumn) { const sessionDataKey = 'devicesListAll_JSON'; const sessionData = sessionStorage.getItem(sessionDataKey); @@ -538,7 +512,7 @@ function getDeviceDataByMacAddress(macAddress, property) { console.log(device) } - return device[property]; + return device[dbColumn]; } } diff --git a/front/plugins/README.md b/front/plugins/README.md index af75a817..dbf7932f 100755 --- a/front/plugins/README.md +++ b/front/plugins/README.md @@ -1,32 +1,21 @@ -## 📚 Docs for individual plugins +### 🔌 Plugins & 📚 Docs -### Community translations of this file +| Code | Plugin Type | Link | +|-----------------------|------------------------|----------------------------------------------------------| +| ARPSCAN | Script | [arp_scan](/front/plugins/arp_scan/) | +| CSVBCKP | Script | [csv_backup](/front/plugins/csv_backup/) | +| DHCPLSS | Script | [dhcp_leases](/front/plugins/dhcp_leases/) | +| DHCPSRVS | Script | [dhcp_servers](/front/plugins/dhcp_servers/) | +| NEWDEV | Template | [newdev_template](/front/plugins/newdev_template/) | +| NMAP | Script | [nmap_scan](/front/plugins/nmap_scan/) | +| PIHOLE | External SQLite DB | [pihole_scan](/front/plugins/pihole_scan/) | +| SETPWD | Script | [set_password](/front/plugins/set_password/) | +| SNMPDSC | Script | [snmp_discovery](/front/plugins/snmp_discovery/) | +| UNDIS | Script | [undiscoverables](/front/plugins/undiscoverables/) | +| UNFIMP | Script | [unifi_import](/front/plugins/unifi_import/) | +| WEBMON | Script | [website_monitor](/front/plugins/website_monitor/) | +| N/A | SQL query | No example available, but the External SQLite based plugins work very similar | -- [Spanish](https://github.com/jokob-sk/Pi.Alert/blob/main/front/plugins/README_ES.md) - -### Script based plugins - -- [arp_scan (ARPSCAN)](/front/plugins/arp_scan/) -- [website_monitor (WEBMON)](/front/plugins/website_monitor/) -- [dhcp_servers (DHCPSRVS)](/front/plugins/dhcp_servers/) -- [dhcp_leases (DHCPLSS)](/front/plugins/dhcp_leases/) -- [unifi_import (UNFIMP)](/front/plugins/unifi_import/) -- [snmp_discovery (SNMPDSC)](/front/plugins/snmp_discovery/) -- [undiscoverables (UNDIS)](/front/plugins/undiscoverables/) -- [pholus_scan (ARPSCAN)](/front/plugins/pholus_scan/) -- [set_password (SETPWD)](/front/plugins/set_password/) -- [nmap_scan (NMAP)](/front/plugins/nmap_scan/) - -### SQL query-based plugins - -- No example available, but the External SQLite based plugins work very similar - - -### template based plugins -- [newdev_template (NEWDEV)](/front/plugins/newdev_template/) - -### External SQLite based plugins -- [pihole_scan (PIHOLE)](/front/plugins/newdev_template/) ## 🌟 Create a custom plugin: Overview @@ -702,6 +691,10 @@ The UI will adjust how columns are displayed in the UI based on the resolvers de } ``` +### Community translations of this file + +- [Spanish](https://github.com/jokob-sk/Pi.Alert/blob/main/front/plugins/README_ES.md) + [screen1]: https://raw.githubusercontent.com/jokob-sk/Pi.Alert/main/docs/img/plugins.png "Screen 1"