diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7610df5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,24 @@ +# +-------------------------------------------------------------------------+ +# | Copyright (C) 2004-2026 The Cacti Group | +# | | +# | 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. | +# +-------------------------------------------------------------------------+ +# | Cacti: The Complete RRDtool-based Graphing Solution | +# +-------------------------------------------------------------------------+ +# | This code is designed, written, and maintained by the Cacti Group. See | +# | about.php and/or the AUTHORS file for specific developer information. | +# +-------------------------------------------------------------------------+ +# | http://www.cacti.net/ | +# +-------------------------------------------------------------------------+ + +locales/po/*.mo +locales/LC_MESSAGES/*.mo +vendor/ diff --git a/locales/po/cacti.pot b/locales/po/cacti.pot index 7e8c767..2ed5b81 100644 --- a/locales/po/cacti.pot +++ b/locales/po/cacti.pot @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: Cacti \n" "Report-Msgid-Bugs-To: developers@cacti.net\n" -"POT-Creation-Date: 2026-09-21 13:14-0400\n" +"POT-Creation-Date: 2026-09-24 13:43-0400\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: Howard Jones >\n" "Language-Team: Howard Jones \n" @@ -71,8 +71,8 @@ msgstr "" msgid "Branch Name" msgstr "" -#: quicktree.php:125 quicktree.php:177 quicktree.php:343 setup.php:152 -#: setup.php:159 setup.php:166 setup.php:173 setup.php:180 setup.php:187 +#: quicktree.php:125 quicktree.php:177 quicktree.php:343 setup.php:266 +#: setup.php:273 setup.php:280 setup.php:287 setup.php:294 setup.php:301 msgid "QuickTree" msgstr "" @@ -173,46 +173,46 @@ msgstr "" msgid "No Graphs Added Yet" msgstr "" -#: setup.php:35 +#: setup.php:45 msgid "QuickTree Management" msgstr "" -#: setup.php:54 +#: setup.php:88 msgid "Misc" msgstr "" -#: setup.php:58 setup.php:112 +#: setup.php:92 setup.php:172 msgid "Quicktree" msgstr "" -#: setup.php:62 +#: setup.php:96 msgid "Page Style" msgstr "" -#: setup.php:63 +#: setup.php:97 msgid "Where to display the QuickTree page" msgstr "" -#: setup.php:66 +#: setup.php:100 msgid "Tab" msgstr "" -#: setup.php:67 +#: setup.php:101 msgid "Console Menu" msgstr "" -#: setup.php:68 +#: setup.php:102 msgid "Both Tab and Console Menu" msgstr "" -#: setup.php:124 +#: setup.php:200 msgid "Add this graph to QuickTree" msgstr "" -#: setup.php:134 +#: setup.php:223 msgid "Management" msgstr "" -#: setup.php:134 +#: setup.php:223 msgid "QuickTree Trees" msgstr "" diff --git a/quicktree_security.php b/quicktree_security.php index 0c9c956..f1f35d0 100644 --- a/quicktree_security.php +++ b/quicktree_security.php @@ -23,6 +23,16 @@ +-------------------------------------------------------------------------+ */ +/** + * Normalizes a requested QuickTree page location to one of two allowed + * values, treating anything other than 'console' as 'tab'. Called from + * quicktree.php's dispatcher to sanitize the 'location' request variable + * before it is used to build URLs or navigation entries. + * + * @param string $value The raw requested location value. + * + * @return string Either 'console' or 'tab'. + */ function quicktree_normalize_location($value) { if ($value === 'console') { return 'console'; diff --git a/setup.php b/setup.php index 756a683..07840ae 100644 --- a/setup.php +++ b/setup.php @@ -23,6 +23,16 @@ +-------------------------------------------------------------------------+ */ +/** + * Installs the quicktree plugin: registers its Cacti hooks (top_header_tabs, + * top_graph_header_tabs, config_arrays, config_settings, + * draw_navigation_text, graph_buttons, graph_buttons_thumbnails, page_head), + * adds its quicktree.php realm, and creates its database table. Invoked by + * Cacti's plugin architecture when an administrator installs this plugin + * from Console > Plugin Management. + * + * @return bool Always returns true. + */ function plugin_quicktree_install() { api_plugin_register_hook('quicktree', 'top_header_tabs', 'quicktree_show_tab', 'setup.php'); api_plugin_register_hook('quicktree', 'top_graph_header_tabs', 'quicktree_show_tab', 'setup.php'); @@ -41,6 +51,17 @@ function plugin_quicktree_install() { return true; } +/** + * Reads this plugin's INFO file and returns its [info] section. Used by + * Cacti's plugin architecture via the api_plugin_version hook, and + * internally by quicktree_check_upgrade() to detect version changes. + * + * @return array The parsed [info] section of the plugin's INFO file (keys + * such as name, version, author, description). + * + * @global array $config Cacti global configuration array; used to locate + * the plugin's base path. + */ function plugin_quicktree_version() { global $config; @@ -48,6 +69,19 @@ function plugin_quicktree_version() { return $info['info']; } +/** + * Hook implementation for Cacti's 'config_settings' filter. Registers the + * "Misc" tab's Quicktree Page Style setting (tab, console menu, or both). + * Called by Cacti core via api_plugin_hook('config_settings', ...) while + * building the Settings page. + * + * @return void + * + * @global array $tabs Cacti's registered Settings page tabs, extended + * here with the 'misc' tab label. + * @global array $settings Cacti's registered Settings page fields, extended + * here under the 'misc' key. + */ function quicktree_config_settings() { global $tabs, $settings; @@ -77,6 +111,19 @@ function quicktree_config_settings() { } } +/** + * Resolves whether QuickTree should actually render at $preferred's + * location ('tab' or 'console'), based on the 'quicktree_pagestyle' + * setting (Tab only, Console Menu only, or Both). Called from + * quicktree_show_tab() when building the tab/console menu link. + * + * @param string $preferred The caller's preferred location, 'tab' or + * 'console'; defaults to 'tab'. + * + * @return string The location to actually use: $preferred when allowed by + * the current page-style setting, otherwise the other + * location. + */ function quicktree_page_location($preferred = 'tab') { $locsetting = read_config_option('quicktree_pagestyle'); @@ -99,6 +146,19 @@ function quicktree_page_location($preferred = 'tab') { } } +/** + * Hook implementation for Cacti's 'top_header_tabs'/'top_graph_header_tabs' + * filters. Prints the QuickTree tab icon (highlighted when quicktree.php is + * the current page) when the user is authorized and the page style + * includes the tab. Called by Cacti core via + * api_plugin_hook('top_header_tabs'/'top_graph_header_tabs', ...) while + * rendering the page header tabs. + * + * @return void Outputs HTML directly. + * + * @global array $config Cacti global configuration array; used to build + * the tab's image/link URLs. + */ function quicktree_show_tab() { global $config; @@ -114,6 +174,22 @@ function quicktree_show_tab() { } } +/** + * Hook implementation for Cacti's 'graph_buttons'/'graph_buttons_thumbnails' + * filters. Prints an "Add this graph to QuickTree" icon/link for the + * current graph, when the user is authorized. Called by Cacti core via + * api_plugin_hook('graph_buttons'/'graph_buttons_thumbnails', ...) while + * rendering a graph's action buttons. + * + * @param array $data Hook payload; $data[1] contains the current graph's + * 'local_graph_id' and 'rra' (RRA id). + * + * @return void Outputs HTML directly. + * + * @global array $config Cacti global configuration array (unused directly + * here; declared for parity with other graph_buttons + * hook implementations). + */ function quicktree_graph_buttons($data) { global $config; @@ -125,6 +201,19 @@ function quicktree_graph_buttons($data) { } } +/** + * Hook implementation for Cacti's 'config_arrays' filter. Adds the + * "QuickTree Trees" entry under the Management section of Cacti's menu + * when the page style setting allows the console view, and triggers the + * version-upgrade check. Called by Cacti core via + * api_plugin_hook('config_arrays', ...) while building the navigation + * menu. + * + * @return void + * + * @global array $menu Cacti's main navigation menu array, extended here + * with this plugin's entry when applicable. + */ function quicktree_config_arrays() { global $menu; @@ -135,6 +224,17 @@ function quicktree_config_arrays() { } } +/** + * Hook implementation for Cacti's 'page_head' filter. Includes this + * plugin's JavaScript on every page, and its stylesheet specifically on + * quicktree.php. Called by Cacti core via api_plugin_hook('page_head', ...) + * while rendering the page section. + * + * @return void Outputs HTML directly. + * + * @global array $config Cacti global configuration array; used to build + * the JS/CSS asset URLs. + */ function quicktree_page_head() { global $config; @@ -147,6 +247,20 @@ function quicktree_page_head() { } } +/** + * Hook implementation for Cacti's 'draw_navigation_text' filter. Adds + * breadcrumb entries for quicktree.php's default, add_ajax, add, remove, + * save, and clear views, mapping back to the console index when viewed in + * console mode. Called by Cacti core via + * api_plugin_hook('draw_navigation_text', ...) while rendering the page + * breadcrumb trail. + * + * @param array $nav The existing breadcrumb map contributed by Cacti core + * and other plugins. + * + * @return array The $nav array with this plugin's breadcrumb entries + * added. + */ function quicktree_draw_navigation_text($nav) { $nav['quicktree.php:'] = array ( 'title' => __('QuickTree', 'quicktree'), @@ -193,6 +307,14 @@ function quicktree_draw_navigation_text($nav) { return $nav; } +/** + * Creates the quicktree_graphs database table used to store each user's + * saved QuickTree graphs, and initializes the 'quicktree_pagestyle' setting + * to a valid default if it is currently unset or out of range. Called from + * plugin_quicktree_install() and quicktree_check_upgrade(). + * + * @return void + */ function quicktree_setup_table() { $data = array(); @@ -213,21 +335,55 @@ function quicktree_setup_table() { } } +/** + * Triggers this plugin's version-upgrade check. Invoked by Cacti's plugin + * architecture to determine whether the plugin needs to run an upgrade + * routine. + * + * @return bool Always returns false (no separate upgrade routine to run). + */ function plugin_quicktree_upgrade() { /* Here we will upgrade to the newest version */ quicktree_check_upgrade(); return FALSE; } +/** + * Uninstalls the quicktree plugin. Invoked by Cacti's plugin architecture + * when an administrator uninstalls this plugin from Console > Plugin + * Management; currently a no-op (the quicktree_graphs table is + * intentionally left in place). + * + * @return void + */ function plugin_quicktree_uninstall() { /* Do any extra Uninstall stuff here */ } +/** + * Verifies the plugin's configuration is up to date. Invoked by Cacti's + * plugin architecture on relevant page loads; currently a no-op + * placeholder. + * + * @return bool Always returns true. + */ function plugin_quicktree_check_config() { /* Here we will check to ensure everything is configured */ return TRUE; } +/** + * Compares the plugin's INFO-file version against the version recorded in + * plugin_config and, if they differ, re-registers the page_head hook, + * re-runs the table setup, and updates the stored plugin_config row (or, + * on newer Cacti versions, registers the upgrade via + * api_plugin_upgrade_register()). Skips its work on requests other than + * plugins.php, quicktree.php, index.php, or graph_view.php to avoid + * unnecessary database access on every page load. Called from + * quicktree_config_arrays() and plugin_quicktree_upgrade(). + * + * @return void + */ function quicktree_check_upgrade() { $files = array('plugins.php', 'quicktree.php', 'index.php', 'graph_view.php'); if (isset($_SERVER['PHP_SELF']) && !in_array(basename($_SERVER['PHP_SELF']), $files)) { diff --git a/ui_helpers.php b/ui_helpers.php index 416efdd..a7bb0df 100644 --- a/ui_helpers.php +++ b/ui_helpers.php @@ -12,6 +12,16 @@ */ if (!function_exists('quicktree_action_form_begin')) { + /** + * Opens a QuickTree action form: prints the page header (unless + * suppressed via the 'header' request variable), then starts the form + * and its enclosing box. Called from quicktree.php before rendering an + * action's input fields. + * + * @param string $title The box title to display above the form. + * + * @return void Outputs HTML directly. + */ function quicktree_action_form_begin($title) { if (get_nfilter_request_var('header') == null) { top_header(); @@ -23,6 +33,13 @@ function quicktree_action_form_begin($title) { } if (!function_exists('quicktree_action_form_end')) { + /** + * Closes a QuickTree action form opened by quicktree_action_form_begin(): + * ends the enclosing box and the form itself. Called from quicktree.php + * after rendering an action's input fields. + * + * @return void Outputs HTML directly. + */ function quicktree_action_form_end() { html_end_box(); form_end();