Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 46 additions & 46 deletions docs/example/example.html

Large diffs are not rendered by default.

Binary file modified docs/example/my_router.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1,491 changes: 0 additions & 1,491 deletions docs/example/overlib.js

This file was deleted.

3 changes: 2 additions & 1 deletion docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,8 @@ <h2>Reference and examples</h2>
distinguishes 2.0 features from historical behaviour.</p>
<p>The original <a href="howto.png">configuration diagram</a> (<a href="howto.pdf">PDF</a>)
and <a href="example/example.html">sample map</a> remain useful for learning the format. They
are historical examples, not screenshots of the 2.0 editor.</p>
are historical examples, not screenshots of the 2.0 editor. The sample map no longer ships
overLIB; its hover captions use plain browser tooltips.</p>
<footer>
<p>Network Weathermap 2.0, maintained by The Cacti Group. Based on the original PHP Network
Weathermap and manual by Howard Jones, © 2005–2019; Cacti fork contributions © 2022–2026
Expand Down
6 changes: 3 additions & 3 deletions docs/pages/cli-reference.html
Original file line number Diff line number Diff line change
Expand Up @@ -112,9 +112,9 @@ <h2>Output and permissions</h2>
without coordinating schedules.</p>
<p><code>HTMLSTYLE static</code> produces an image map with click links. <code>HTMLSTYLE
overlib</code> also emits hover metadata. The integrated Cacti viewer supplies the
JavaScript that displays those previews. The legacy command-line HTML wrapper still
references <code>overlib.js</code>, which is no longer bundled, so its exported page is not
a complete standalone hover viewer. Use the Cacti viewer for supported interactive maps;
JavaScript that displays those previews. overLIB is no longer shipped, and the legacy
command-line HTML wrapper no longer references <code>overlib.js</code>. Its exported page
keeps the hover metadata but is not a complete standalone hover viewer. Use the Cacti viewer for supported interactive maps;
changing HTMLSTYLE alone does not make an exported page equivalent.</p>
</section>
<footer>
Expand Down
72 changes: 72 additions & 0 deletions tests/Browser/DocsExampleHoverTest.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
// Loads docs/example/example.html with its subresources, checks that its hover
// captions work without overLIB, then feeds engine-style data-hover content
// through js/weathermap.js. Needs only jsdom and jQuery.
const {JSDOM, VirtualConsole} = require('jsdom');
const jquery = require('jquery');
const fs = require('node:fs');
const path = require('node:path');
const vm = require('node:vm');
const assert = require('node:assert/strict');

/**
* Load a page from disk with its scripts and subresources enabled, recording load errors.
*
* @param {string} file Absolute path of the HTML page.
* @returns {Promise<{dom: JSDOM, errors: string[]}>} The loaded page and any resource or script errors.
*/
async function loadPage(file) {
const errors = [];
const virtualConsole = new VirtualConsole();
virtualConsole.on('jsdomError', (error) => errors.push(error.message));
virtualConsole.on('error', (message) => errors.push(String(message)));
const dom = await JSDOM.fromFile(file, {runScripts: 'dangerously', resources: 'usable', virtualConsole});
await new Promise((resolve) => dom.window.addEventListener('load', resolve));
return {dom, errors};
}

(async () => {
const example = path.join(__dirname, '../../docs/example/example.html');
const {dom, errors} = await loadPage(example);
const doc = dom.window.document;
const links = [...doc.querySelectorAll('area[id^="LINK:"]')];

assert.equal(doc.querySelectorAll('script').length, 0, 'static example loads no script');
assert.equal(typeof dom.window.overlib, 'undefined', 'overLIB is not defined');
assert.ok(links.length > 0, 'example has link areas');
for (const area of links) {
assert.ok(area.title.trim() !== '', `${area.id} has a hover caption`);
assert.deepEqual(area.getAttributeNames().filter((name) => name.startsWith('on')), [], `${area.id} has no inline handler`);
area.dispatchEvent(new dom.window.MouseEvent('mouseover', {bubbles: true}));
area.dispatchEvent(new dom.window.MouseEvent('mouseout', {bubbles: true}));
}
const image = doc.getElementById('wmapimage').getAttribute('src');
assert.ok(fs.existsSync(path.join(path.dirname(example), image)), 'map image is shipped');
assert.deepEqual(errors, [], 'page loads and hovers without errors');

// HTMLSTYLE overlib output is now rendered by the viewer from data-hover, not by overLIB.
const viewer = new JSDOM('<map><area id="LINK:L114:0" data-caption="sync-core"></map>', {runScripts: 'outside-only', url: 'https://cacti.example/cacti/plugins/weathermap/view.php'});
const w = viewer.window;
const $ = jquery(w);
let options;
w.$ = $;
$.fn.tooltip = function (value) {
if (value === 'instance') return undefined;
options = value;
return this;
};
// Loads the repository's own viewer script into the test DOM, as jsdom documents.
vm.runInContext(fs.readFileSync(path.join(__dirname, '../../js/weathermap.js'), 'utf8'), viewer.getInternalVMContext()); // NOSONAR
await new Promise((resolve) => $(resolve));
await new Promise((resolve) => setImmediate(resolve));
const area = $('area');
area.attr('data-hover', Buffer.from("<div><img data-height='153' data-width='395' src='graph_image.png'></div>").toString('base64'));
let output;
options.content.call(area[0], (html) => (output = html));
assert.equal($(output).find('img').attr('src'), 'graph_image.png');
assert.match($(output).text(), /sync-core/);
assert.equal(typeof w.overlib, 'undefined');
console.log('Docs example hover captions and viewer hover content without overLIB PASS');
})().catch((error) => {
console.error(error);
process.exit(1);
});
8 changes: 0 additions & 8 deletions tests/Browser/EditorIconPickerTest.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -51,12 +51,4 @@ let escaped=0;$(w.document).on('keydown',e=>{if(e.key==='Escape')escaped++});
$('#wm-icon-picker summary').trigger($.Event('keydown',{key:'Escape'}));assert.equal(escaped,1,'closed picker lets Escape close its parent dialog');
$('input[type=search]').val('nothing-matches').trigger('input');
assert.equal($('.wm-icon-count').text(),'No matching icons');
const overlib=fs.readFileSync(path.join(__dirname,'../../docs/example/overlib.js'),'utf8');
const escapeStart=overlib.indexOf('function escSglQuote('),escapeEnd=overlib.indexOf('\n}',escapeStart)+2;
w.eval(overlib.slice(escapeStart,escapeEnd));
assert.equal(w.escSglQuote("O'Brien"),"O\\'Brien");
assert.equal(w.escSglQuote('back\\slash'),'back\\\\slash');
assert.equal(w.escSglQuote('line\nbreak'),'line\\nbreak');
assert.equal(w.escSglQuote('line\u2028break'),'line\\u2028break');
assert.equal(w.escSglQuote('line\u2029break'),'line\\u2029break');
console.log('Icon picker selection, search, reopening and Escape PASS');
207 changes: 207 additions & 0 deletions tests/E2E/DocumentationExampleHoverTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,207 @@
<?php
/*
+-------------------------------------------------------------------------+
| Copyright (C) 2004-2026 The Cacti Group, Howard Jones |
| |
| 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/ |
+-------------------------------------------------------------------------+
*/

use PHPUnit\Framework\Attributes\PreserveGlobalState;
use PHPUnit\Framework\Attributes\RunInSeparateProcess;
use PHPUnit\Framework\TestCase;

// Pest's Composer proxy exposes the autoloader; PHPUnit needs it in isolated children.
if (!defined('PHPUNIT_COMPOSER_INSTALL') && isset($GLOBALS['_composer_autoload_path'])) {
define('PHPUNIT_COMPOSER_INSTALL', $GLOBALS['_composer_autoload_path']);
}

/**
* Renders the shipped docs/example/example.conf with the real engine and checks
* that HTMLSTYLE overlib hovers work without the retired overLIB library.
*/
final class DocumentationExampleHoverTest extends TestCase {
/** Engine-rendered fragment and standalone pages carry viewer hover data, not overLIB calls. */
#[RunInSeparateProcess]
#[PreserveGlobalState(false)]
public function testExampleConfigRendersViewerHoverWithoutOverlib(): void {
$plugin = dirname(__DIR__, 2);
[$map, $fragment, $standalone] = self::renderExample($plugin);

$this->assertSame('overlib', $map->htmlstyle);
$this->assertSame(0, $GLOBALS['weathermap_warncount'], 'example.conf renders without warnings');

foreach ([$fragment, $standalone] as $html) {
$this->assertStringNotContainsStringIgnoringCase('overlib(', $html);
$this->assertStringNotContainsStringIgnoringCase('overlib.js', $html);
$this->assertStringNotContainsString('overDiv', $html);
}

$areas = self::linkAreas(self::parse($fragment));
$captions = [];
$this->assertNotEmpty($areas, 'example links produce image-map areas');

foreach ($areas as $area) {
foreach ($area->attributes as $attribute) {
$this->assertStringStartsNotWith('on', strtolower($attribute->name), 'no inline event handlers on ' . $area->getAttribute('id'));
}

$name = $area->getAttribute('data-caption');
$link = $map->links[$name] ?? null;
$this->assertNotNull($link, 'caption names a configured link');
$captions[$name] = true;

$hover = base64_decode($area->getAttribute('data-hover'), true);
$this->assertIsString($hover, 'data-hover is valid base64');
$images = self::parse($hover)->getElementsByTagName('img');
$this->assertSame(count($link->overliburl[IN]), $images->length, "$name hover shows every OVERLIBGRAPH");

foreach ($images as $index => $image) {
$this->assertSame('395', $image->getAttribute('data-width'));
$this->assertSame('153', $image->getAttribute('data-height'));
$this->assertStringStartsWith($link->overliburl[IN][$index], $image->getAttribute('src'));
}
}

// The static historical page uses the same captions as plain title tooltips.
$static = self::parse(file_get_contents($plugin . '/docs/example/example.html'));
$titles = [];

foreach (self::linkAreas($static, 'title') as $area) {
$titles[$area->getAttribute('title')] = true;
}

ksort($captions);
ksort($titles);
$this->assertSame(array_keys($captions), array_keys($titles), 'static example titles match engine captions');
$this->assertSame(0, $static->getElementsByTagName('script')->length, 'static example loads no script');
}

/** The standalone page only references scripts that the plugin ships or Cacti provides. */
#[RunInSeparateProcess]
#[PreserveGlobalState(false)]
public function testStandaloneExampleReferencesOnlyAvailableScripts(): void {
$plugin = dirname(__DIR__, 2);
[, , $standalone] = self::renderExample($plugin);
$scripts = self::parse($standalone)->getElementsByTagName('script');
$cactiProvided = ['/cacti/include/js/jquery.js', '/cacti/include/js/jquery-ui.js', '/cacti/include/js/pace.js'];
$pluginScriptPrefix = '/cacti/plugins/weathermap/';
$this->assertGreaterThan(0, $scripts->length);

foreach ($scripts as $script) {
$src = $script->getAttribute('src');

if (str_starts_with($src, $pluginScriptPrefix)) {
$this->assertFileExists($plugin . '/' . substr($src, strlen($pluginScriptPrefix)), "$src is shipped");
} else {
$this->assertContains($src, $cactiProvided, "$src is a Cacti core script");
}
}
}

/**
* Render docs/example/example.conf through ReadConfig, DrawMap and MakeHTML.
*
* The engine is constructed in the plugin root so data-source plugins load, then
* reads the example from its own directory so its relative fonts and background resolve.
* ReadData is skipped: the example's RRD targets are not shipped.
*
* @param string $plugin Absolute plugin root.
*
* @return array{0: WeatherMap, 1: string, 2: string} The map, the viewer fragment and the standalone page.
*/
private static function renderExample(string $plugin): array {
chdir($plugin);
require_once $plugin . '/setup.php';
require_once $plugin . '/lib/WeatherMap.class.php';

if (!function_exists('get_selected_theme')) {
/**
* Stand in for Cacti's theme lookup used by standalone HTML.
*
* @return string The theme directory name.
*/
function get_selected_theme() {
return 'modern';
}
}

$GLOBALS['weathermap_warncount'] = 0;
$map = new WeatherMap();
$map->rrdtool = PHP_BINARY;
chdir($plugin . '/docs/example');

if (!$map->ReadConfig('example.conf')) {
throw new RuntimeException('Cannot parse docs/example/example.conf');
}

// DrawMap picks the image writer from the extension, so the temporary file needs .png.
$temporary = tempnam(sys_get_temp_dir(), 'wm-example-');
$output = $temporary . '.png';
unlink($temporary);

try {
$map->DrawMap($output);
} finally {
if (is_file($output)) {
unlink($output);
}
}

$map->imageuri = 'example.png';

return [$map, $map->MakeHTML(), $map->MakeHTML('weathermap_example_imap', true)];
}

/**
* Parse an HTML fragment or page without emitting libxml warnings.
*
* @param string $html Markup to parse.
*
* @return DOMDocument The parsed document.
*/
private static function parse(string $html): DOMDocument {
$document = new DOMDocument();
$previous = libxml_use_internal_errors(true);
$document->loadHTML('<?xml encoding="UTF-8">' . $html);
libxml_clear_errors();
libxml_use_internal_errors($previous);

return $document;
}

/**
* Return the image-map areas for links that carry a hover attribute.
*
* @param DOMDocument $document Parsed page.
* @param string $attribute Attribute that marks a hover area.
*
* @return DOMElement[] Matching LINK areas.
*/
private static function linkAreas(DOMDocument $document, string $attribute = 'data-hover'): array {
$areas = [];

foreach ($document->getElementsByTagName('area') as $area) {
if (str_starts_with($area->getAttribute('id'), 'LINK:') && $area->hasAttribute($attribute)) {
$areas[] = $area;
}
}

return $areas;
}
}
Loading
Loading