Visual Diff Merge - Usage Guide | Code Comparison Tool

Usage Modes

Visual Diff Merge offers four distinct modes for comparing content. Each mode requires specific files and setup. The diff-viewer directory contains sample implementations of each mode.

Click on a mode tab below to view detailed implementation instructions for each comparison mode.

File Browser Mode

The File Browser mode allows users to browse files on the server and select two files for comparison. This mode requires server-side access to files.

Required Files

file-browser.php - PHP script for the file browser interface
file-browser.min.js - JavaScript for the file browser functionality
diff-viewer.min.css - CSS for the diff viewer
diff-viewer-theme.min.css - CSS for the diff viewer UI elements (buttons, alerts, etc.)

Implementation Example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>File Browser Comparison - Visual-Diff-Merge</title>
    <meta name="description" content="Compare files in a browser with Visual-Diff-Merge.">
    <meta name="keywords" content="Visual-Diff-Merge, file comparison, diff viewer, merge tool">

    <!-- Include the Visual Diff Merge CSS -->
    <link rel="stylesheet" href="../dist/css/diff-viewer.min.css">

    <!-- Include the Visual Diff Merge theme CSS -->
    <link rel="stylesheet" href="../dist/css/diff-viewer-theme.min.css">
</head>
<body>
    <div class="vdm-container vdm-p-3">
        <h1 class="vdm-mb-3">File Browser Comparison</h1>
        <p class="vdm-mb-4"><a href="index.html" class="vdm-btn vdm-btn--flat vdm-btn-sm">← Back Home</a></p>

        <div class="vdm-card vdm-p-3 vdm-mb-4">
            <form id="vdm-file-comparison-form" class="vdm-d-flex vdm-flex-column">
                <div class="vdm-file-selectors vdm-d-flex vdm-flex-wrap vdm-justify-content-between vdm-mb-3">
                    <div class="vdm-mb-2 vdm-flex-grow-1 vdm-me-3" style="min-width: 45%;">
                        <label for="old-file" class="vdm-mb-1 vdm-d-block">Old File:</label>
                        <select id="old-file" class="vdm-form-control" data-type="old">
                            <?php foreach ($oldFiles as $file) : ?>
                                    <option value="<?= htmlspecialchars($file['path']) ?>"
                                            data-ref-id="<?= htmlspecialchars($file['ref_id']) ?>">
                                        <?= htmlspecialchars($file['language']) ?> (<?= htmlspecialchars($file['name']) ?>)
                                    </option>
                            <?php endforeach; ?>
                        </select>
                    </div>
                    <div class="vdm-mb-2 vdm-flex-grow-1" style="min-width: 45%;">
                        <label for="new-file" class="vdm-mb-1 vdm-d-block">New File:</label>
                        <select id="new-file" class="vdm-form-control" data-type="new">
                            <?php foreach ($newFiles as $file) : ?>
                                    <option value="<?= htmlspecialchars($file['path']) ?>"
                                           data-ref-id="<?= htmlspecialchars($file['ref_id']) ?>">
                                        <?= htmlspecialchars($file['language']) ?> (<?= htmlspecialchars($file['name']) ?>)
                                    </option>
                            <?php endforeach; ?>
                        </select>
                    </div>
                </div>

                <button type="submit" class="vdm-btn vdm-btn--primary vdm-ms-auto">Compare Files</button>
            </form>
        </div>

        <div id="vdm-merge__result" class="vdm-p-3 vdm-mb-3 vdm-d-none"></div>

        <div id="vdm-container__wrapper" class="vdm-theme--dark vdm-d-none">
            <div class="vdm-user-content">
                <h2 class="vdm-text-center vdm-mb-2">Side by Side Comparison</h2>
                <p class="vdm-text-center vdm-mb-3">Click on a section to select it for the merged result</p>
            </div>

            <!-- UI elements will be generated by JavaScript -->

        </div>
    </div>

    <!-- Required JavaScript files -->
    <script src="../dist/diff-viewer.min.js"></script>
    <script src="../dist/file-browser.min.js"></script>
</body>
</html>

PHP Server-Side Requirements

The server-side PHP component needs to:

Provide a way to access available files (two options available)
Generate secure reference IDs for each file
Populate the dropdown menus
Process the selected files when the form is submitted

There are two ways to configure the files for comparison:

Option 1: Directory-based file scanning

Automatically scan directories for files:

<?php
// Include required files
require_once __DIR__ . '/../vendor/autoload.php';

use VisualDiffMerge\FileBrowser;

// Configuration - Specify directories to scan for files
$config = [
    'old' => [
        'type' => 'directory',
        'path' => realpath(dirname(__FILE__)) . '/../diff-viewer/samples/old/',
        'baseUrl' => '../diff-viewer/samples/old/'
    ],
    'new' => [
        'type' => 'directory',
        'path' => realpath(dirname(__FILE__)) . '/../diff-viewer/samples/new/',
        'baseUrl' => '../diff-viewer/samples/new/'
    ]
];

// Initialize the FileBrowser
$fileBrowser = new FileBrowser();

// Get files from directories
$oldFiles = $fileBrowser->getFiles($config['old']['path'], $config['old']['baseUrl']);
$newFiles = $fileBrowser->getFiles($config['new']['path'], $config['new']['baseUrl']);

// Continue with the HTML output
?>

Option 2: Explicit file list

Manually specify files to compare:

<?php
// Include required files
require_once __DIR__ . '/../vendor/autoload.php';

use VisualDiffMerge\FileBrowser;

// Configuration - Specify explicit file lists
$config = [
    'old' => [
        'type' => 'files',
        'files' => [
            realpath(dirname(__FILE__)) . '/../diff-viewer/samples/old/example1.js',
            realpath(dirname(__FILE__)) . '/../diff-viewer/samples/old/example2.php',
            // Add more files as needed
        ],
        'baseUrl' => '../diff-viewer/samples/old/'
    ],
    'new' => [
        'type' => 'files',
        'files' => [
            realpath(dirname(__FILE__)) . '/../diff-viewer/samples/new/example1.js',
            realpath(dirname(__FILE__)) . '/../diff-viewer/samples/new/example2.php',
            // Add more files as needed
        ],
        'baseUrl' => '../diff-viewer/samples/new/'
    ]
];

// Initialize the FileBrowser
$fileBrowser = new FileBrowser();

// Get files from explicit file lists
$oldFiles = $fileBrowser->getFiles($config['old']['files'], $config['old']['baseUrl']);
$newFiles = $fileBrowser->getFiles($config['new']['files'], $config['new']['baseUrl']);

// Continue with the HTML output
?>

Workflow

User selects old and new files from the dropdowns
User clicks "Compare Files" button
FileBrowserManager handles the form submission
File content is retrieved securely using reference IDs
Content is sent to diff-processor.php for processing
Result is displayed in the diff viewer

File Upload Mode

The File Upload mode allows users to upload two files from their local machine for comparison. This mode does not require server-side file access but still needs PHP for diff processing.

Required Files

file-upload.html - HTML file with the upload form
file-upload.min.js - JavaScript for file upload functionality
diff-viewer.min.css - CSS for the diff viewer
diff-viewer-theme.min.css - CSS for the diff viewer UI elements (buttons, alerts, etc.)

Implementation Example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>File Upload - Visual Diff Merge</title>
    <meta name="description" content="Compare files by uploading them with Visual-Diff-Merge.">
    <meta name="keywords" content="Visual-Diff-Merge, file comparison, diff viewer, merge tool">

    <!-- Include the Visual Diff Merge CSS -->
    <link rel="stylesheet" href="../dist/css/diff-viewer.min.css">

    <!-- Include the Visual Diff Merge theme CSS -->
    <link rel="stylesheet" href="../dist/css/diff-viewer-theme.min.css">
</head>
<body>
    <div class="vdm-container vdm-p-3">
        <h1 class="vdm-mb-3">File Upload Comparison</h1>
        <p class="vdm-mb-4"><a href="index.html" class="vdm-btn vdm-btn--flat vdm-btn-sm">← Back Home</a></p>

        <!-- File upload form -->
        <form id="file-upload-form" class="vdm-card vdm-p-3 vdm-mb-4">
            <div class="vdm-file-selectors vdm-d-flex vdm-flex-wrap vdm-justify-content-between vdm-mb-3">
                <div class="vdm-mb-2 vdm-flex-grow-1 vdm-me-3" style="min-width: 45%;">
                    <label for="old-file-upload" class="vdm-custom-file-label vdm-icon-file vdm-mb-1 vdm-d-block">
                        Upload Old File
                    </label>
                    <input type="file" id="old-file-upload" class="vdm-form-control" required>
                    <div id="old-file-name" class="vdm-file-name vdm-mt-1"></div>
                </div>
                <div class="vdm-mb-2 vdm-flex-grow-1" style="min-width: 45%;">
                    <label for="new-file-upload" class="vdm-custom-file-label vdm-icon-file vdm-mb-1 vdm-d-block">
                        Upload New File
                    </label>
                    <input type="file" id="new-file-upload" class="vdm-form-control" required>
                    <div id="new-file-name" class="vdm-file-name vdm-mt-1"></div>
                </div>
            </div>

            <button type="submit" id="compare-btn" class="vdm-btn vdm-btn--primary vdm-ms-auto vdm-icon-compare">
                Compare Files
            </button>
        </form>

        <div id="vdm-merge__result" class="vdm-p-3 vdm-mb-3 vdm-d-none"></div>

        <div id="vdm-container__wrapper" class="vdm-theme--dark vdm-d-none">
            <div class="vdm-user-content">
                <h2 class="vdm-text-center vdm-mb-2">Side by Side Comparison</h2>
                <p class="vdm-text-center vdm-mb-3">Click on a section to select it for the merged result</p>
            </div>

            <!-- UI elements will be generated by JavaScript -->
        </div>
    </div>

    <!-- Required JavaScript files -->
    <script src="../dist/diff-viewer.min.js"></script>
    <script src="../dist/file-upload.min.js"></script>
</body>
</html>

Workflow

User selects local files using the file inputs
User clicks "Compare Files" button
FileUploadManager reads the files using the FileReader API
File content is sent to diff-processor.php for processing
Loading indicators are dynamically created by the LoaderManager
Result is displayed in the diff viewer

Important Notes

Files are read on the client side using JavaScript's FileReader API
Only the file content is sent to the server, not the actual files
Loading indicators are created dynamically by the LoaderManager utility
File size limitations apply based on your server configuration

Text Compare Mode

The Text Compare mode allows users to enter or paste code snippets directly for comparison. This is useful for comparing small sections of code or testing changes.

Required Files

text-compare.html - HTML file with the text input form
text-compare.min.js - JavaScript for text comparison functionality
diff-viewer.min.css - CSS for the diff viewer
diff-viewer-theme.min.css - CSS for the diff viewer UI elements (buttons, alerts, etc.)

Implementation Example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Text Comparison - Visual-Diff-Merge</title>
    <meta name="description" content="Compare text snippets with Visual-Diff-Merge.">
    <meta name="keywords" content="Visual-Diff-Merge, text comparison, diff viewer, merge tool">

    <!-- Include the Visual Diff Merge CSS -->
    <link rel="stylesheet" href="../dist/css/diff-viewer.min.css">

    <!-- Include the Visual Diff Merge theme CSS -->
    <link rel="stylesheet" href="../dist/css/diff-viewer-theme.min.css">
</head>
<body>
    <div class="vdm-container vdm-p-3">
        <h1 class="vdm-mb-3">Text Comparison</h1>
        <p class="vdm-mb-4"><a href="index.html" class="vdm-btn vdm-btn--flat vdm-btn-sm">← Back Home</a></p>

        <div class="vdm-card vdm-p-3 vdm-mb-4">
            <form id="text-comparison-form" class="vdm-d-flex vdm-flex-column">
                <div class="vdm-d-flex vdm-flex-wrap vdm-mb-3">
                    <div class="vdm-mb-3 vdm-flex-grow-1 vdm-me-3" style="min-width: 45%;">
                        <label for="old-text" class="vdm-mb-1 vdm-d-block">Old Content:</label>
                        <textarea id="old-text" class="vdm-form-control vdm-code-textarea" rows="10" placeholder="Paste your original code/text here" required></textarea>
                    </div>
                    <div class="vdm-mb-3 vdm-flex-grow-1" style="min-width: 45%;">
                        <label for="new-text" class="vdm-mb-1 vdm-d-block">New Content:</label>
                        <textarea id="new-text" class="vdm-form-control vdm-code-textarea" rows="10" placeholder="Paste your modified code/text here" required></textarea>
                    </div>
                </div>

                <div class="vdm-d-flex vdm-flex-wrap vdm-mb-3 vdm-align-items-center">
                    <div class="vdm-mb-2 vdm-me-3">
                        <label for="language-select" class="vdm-mb-1 vdm-d-block">Language:</label>
                        <select id="language-select" class="vdm-form-control">
                            <option value="auto" selected>Auto-detect</option>
                            <option value="javascript">JavaScript</option>
                            <option value="html">HTML</option>
                            <option value="css">CSS</option>
                            <option value="php">PHP</option>
                            <option value="python">Python</option>
                            <option value="java">Java</option>
                            <option value="csharp">C#</option>
                            <option value="cpp">C++</option>
                            <option value="ruby">Ruby</option>
                            <option value="go">Go</option>
                            <option value="rust">Rust</option>
                            <option value="swift">Swift</option>
                            <option value="typescript">TypeScript</option>
                            <option value="kotlin">Kotlin</option>
                            <option value="sql">SQL</option>
                            <option value="xml">XML</option>
                            <option value="json">JSON</option>
                            <option value="yaml">YAML</option>
                            <option value="markdown">Markdown</option>
                            <option value="plaintext">Plain Text</option>
                        </select>
                    </div>
                </div>

                <button type="submit" class="vdm-btn vdm-btn--primary vdm-ms-auto">Compare</button>
            </form>
        </div>

        <div id="vdm-merge__result" class="vdm-p-3 vdm-mb-3 vdm-d-none"></div>

        <div id="vdm-container__wrapper" class="vdm-theme--dark vdm-d-none">
            <div class="vdm-user-content">
                <h2 class="vdm-text-center vdm-mb-2">Side by Side Comparison</h2>
                <p class="vdm-text-center vdm-mb-3">Click on a section to select it for the merged result</p>
            </div>

            <!-- UI elements will be generated by JavaScript -->
        </div>
    </div>

    <!-- Required JavaScript files -->
    <script src="../dist/diff-viewer.min.js"></script>
    <script src="../dist/text-compare.min.js"></script>
</body>
</html>

Workflow

User enters or pastes text into the old and new textareas
User selects a language for syntax highlighting (optional)
User clicks "Compare" button
TextCompareManager collects the input
Text content is sent to diff-processor.php for processing
Result is displayed in the diff viewer

Features

Language selection for proper syntax highlighting
Auto-detection of language based on content (when "Auto-detect" is selected)
Support for various programming languages and formats

URL Compare Mode

The URL Compare mode allows users to compare content from two URLs. This is useful for comparing web pages, remote code repositories, or API responses.

Required Files

url-compare.html - HTML file with the URL input form
url-compare.min.js - JavaScript for URL comparison functionality
diff-viewer.min.css - CSS for the diff viewer
diff-viewer-theme.min.css - CSS for the diff viewer UI elements (buttons, alerts, etc.)

Implementation Example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>URL Compare - Visual Diff Merge</title>
    <meta name="description" content="Compare content from URLs with Visual-Diff-Merge.">
    <meta name="keywords" content="Visual-Diff-Merge, URL comparison, diff viewer, merge tool">

    <!-- Include the Visual Diff Merge CSS -->
    <link rel="stylesheet" href="../dist/css/diff-viewer.min.css">

    <!-- Include the Visual Diff Merge theme CSS -->
    <link rel="stylesheet" href="../dist/css/diff-viewer-theme.min.css">
</head>
<body>
    <div class="vdm-container vdm-p-3">
        <h1 class="vdm-mb-3">URL Comparison</h1>
        <p class="vdm-mb-4"><a href="index.html" class="vdm-btn vdm-btn--flat vdm-btn-sm">← Back Home</a></p>

        <div class="vdm-card vdm-p-3 vdm-mb-4">
            <form id="url-comparison-form" class="vdm-d-flex vdm-flex-column">
                <div class="vdm-d-flex vdm-flex-wrap">
                    <div class="vdm-mb-3 vdm-me-3 vdm-flex-fill vdm-min-width-0">
                        <label for="old-url" class="vdm-mb-1 vdm-d-block">Old Content URL:</label>
                        <input type="url" id="old-url" class="vdm-form-control" placeholder="https://example.com/old-content.html" required>
                    </div>
                    <div class="vdm-mb-3 vdm-flex-fill vdm-min-width-0">
                        <label for="new-url" class="vdm-mb-1 vdm-d-block">New Content URL:</label>
                        <input type="url" id="new-url" class="vdm-form-control" placeholder="https://example.com/new-content.html" required>
                    </div>
                </div>

                <button type="submit" id="compare-btn" class="vdm-btn vdm-btn--primary vdm-ms-auto">Compare URLs</button>
            </form>
        </div>

        <div id="vdm-merge__result" class="vdm-p-3 vdm-mb-3 vdm-d-none"></div>

        <div id="vdm-container__wrapper" class="vdm-theme--dark vdm-d-none">
            <div class="vdm-user-content">
                <h2 class="vdm-text-center vdm-mb-2">Side by Side Comparison</h2>
                <p class="vdm-text-center vdm-mb-3">Click on a section to select it for the merged result</p>
            </div>

            <!-- UI elements will be generated by JavaScript -->
        </div>
    </div>

    <!-- Required JavaScript files -->
    <script src="../dist/diff-viewer.min.js"></script>
    <script src="../dist/url-compare.min.js"></script>
</body>
</html>

Workflow

User enters two URLs
User selects a language for syntax highlighting (optional)
User clicks "Compare URLs" button
UrlCompareManager sends the URLs to get-url-content.php
Server fetches content from both URLs
Content is sent to diff-processor.php for processing
Result is displayed in the diff viewer

Important Notes

URLs must be accessible from the server
CORS restrictions are bypassed because the server fetches content, not the browser
Timeout limitations apply based on your server configuration

Common Features Across All Modes

All modes provide navigation controls for moving between differences:

Next difference button (↓)
Previous difference button (↑)
Difference counter showing current/total

For technical details on how navigation works, see the DiffNavigator component in the architecture documentation.

Theme Selection

All modes support theme selection for syntax highlighting:

Dark/light mode toggle
Theme family selector (atom-one, github, etc.)

Merge Capability

When enabled, all modes support interactive merging:

Select chunks from either side
Preview merged result
Save merged content (functionality varies by mode)

Using the API

For more advanced usage, you can directly use the API endpoints:

Main API Endpoints

diff-processor.php - Main endpoint for processing diffs
ajax-diff-merge.php - Endpoint for merge operations
get-file-content.php - Endpoint for securely retrieving file content
get-url-content.php - Endpoint for fetching URL content

For detailed API documentation, see the API Reference.

Visual Diff Merge Usage Guide

Usage Modes

File Browser Mode

Required Files

Implementation Example

PHP Server-Side Requirements

Option 1: Directory-based file scanning

Option 2: Explicit file list

Workflow

File Upload Mode

Required Files

Implementation Example

Workflow

Important Notes

Text Compare Mode

Required Files

Implementation Example

Workflow

Features

URL Compare Mode

Required Files

Implementation Example

Workflow

Important Notes

Common Features Across All Modes

Navigation Controls

Theme Selection

Merge Capability

Using the API

Main API Endpoints