========================================================================
 UPLINK7 SKELETON LOADER (PHP STANDALONE WITH ADMIN DASHBOARD)
========================================================================

A high-performance, lightweight, and modern skeleton loader solution designed 
for any standard PHP website. Includes an integrated admin dashboard for easy 
management of visual settings, requiring zero database setup.

------------------------------------------------------------------------
 TABLE OF CONTENTS
------------------------------------------------------------------------
 1. Quick Start Guide (Installation)
 2. Admin Dashboard (Access & Credentials)
 3. Settings & Configurations Explained
 4. Advanced Customization & CSS Overrides
 5. Programmatic Control (JavaScript API)
 6. How It Works (Technical Flow)
 7. Troubleshooting & Common Issues
 8. Security & Performance Best Practices

------------------------------------------------------------------------
 1. QUICK START GUIDE (INSTALLATION)
------------------------------------------------------------------------
1. Place "uplink7-skeleton-loader.php" inside your web server directory 
   (e.g., in the site root or an includes folder).
2. Include the file into your main PHP templates/pages directly after the 
   opening <body> tag:

   <!DOCTYPE html>
   <html lang="en">
   <head>
       <meta charset="UTF-8">
       <title>My Website</title>
   </head>
   <body>

       <?php include __DIR__ . '/uplink7-skeleton-loader.php'; ?>

       <h1>Welcome to the Website</h1>
       <!-- Remaining page content -->

   </body>
   </html>

------------------------------------------------------------------------
 2. ADMIN DASHBOARD (ACCESS & CREDENTIALS)
------------------------------------------------------------------------
The built-in web dashboard allows you to modify all visual options directly 
from your browser. All settings are automatically saved into a local file named 
"ul7_settings.json".

* DASHBOARD URL:
  Append "?ul7_admin=1" to the URL of any page where the loader is included.
  Examples: 
  - https://your-website.com/?ul7_admin=1
  - https://your-website.com/index.php?ul7_admin=1
  - https://your-website.com/uplink7-skeleton-loader.php?ul7_admin=1

* CREDENTIALS:
  - Username: None required (authentication relies solely on the master password).
  - Default Password: admin123

------------------------------------------------------------------------
 3. SETTINGS & CONFIGURATIONS EXPLAINED
------------------------------------------------------------------------
The following options can be managed in the Dashboard:

1. Layout Style (ul7_style):
   - Classic (Blog): Renders a header title block, paragraph lines, and a large body block.
   - Ecommerce (Grid): Generates a 3-column responsive product card layout.
   - Minimalist (Text): Minimal placeholder lines suited for text-heavy sites or landing pages.
   - Hero (Big Image): A full-width banner block at the top, followed by content text lines.

2. Logo URL (ul7_logo_url):
   - Direct path or URL to your logo (PNG, SVG, WebP, GIF).
   - Example: https://your-website.com/assets/img/logo.svg
   - Displays a pulsing animation in the exact center of the screen while loading.

3. Background Color (ul7_bg_col):
   - Hexadecimal color code for the full-screen overlay (e.g., #ffffff for white).

4. Shimmer Color (ul7_shm_col):
   - Hexadecimal color code for the animated placeholder blocks (e.g., #f0f0f0).

5. Auto-Detect Dark Mode (ul7_dark_mode):
   - When enabled, uses CSS `@media (prefers-color-scheme: dark)` to automatically 
     switch the background to `#121212` and shimmer blocks to dark gray if the 
     visitor's OS uses Dark Mode.

------------------------------------------------------------------------
 4. ADVANCED CUSTOMIZATION & CSS OVERRIDES
------------------------------------------------------------------------
You can override the default styles in your own CSS files by targeting the 
following IDs and classes:

- `#ul7-sl-overlay`: The main fixed overlay wrapper (z-index: 99999999).
- `.ul7-shimmer-box`: Individual animated placeholder elements.
- `.ul7-logo-pulse`: The centered logo container.
- `body.ul7-sl-ready`: Added to the <body> tag as soon as loading completes.

Custom CSS Example (e.g., changing border radii or shimmer speed):
```css
/* Change border radius of shimmer elements */
.ul7-shimmer-box {
    border-radius: 20px !important;
}

/* Adjust animation speed */
.ul7-shimmer-box {
    animation-duration: 0.8s !important;
}
```

------------------------------------------------------------------------
 5. PROGRAMMATIC CONTROL (JAVASCRIPT API)
------------------------------------------------------------------------
By default, the loader automatically hides when the window `load` event fires. 
If you are loading data asynchronously via AJAX/Fetch, you can manually trigger 
or delay the hiding sequence:

* Manually complete loading:
  ```javascript
  document.body.classList.add('ul7-sl-ready');
  ```

* Remove the overlay element completely from DOM:
  ```javascript
  const overlay = document.getElementById('ul7-sl-overlay');
  if (overlay) overlay.remove();
  ```

------------------------------------------------------------------------
 6. HOW IT WORKS (TECHNICAL FLOW)
------------------------------------------------------------------------
1. Server side: PHP reads `ul7_settings.json` (or uses defaults) and outputs 
   inline CSS, HTML structure, and a tiny inline JS script.
2. Initial display: `#ul7-sl-overlay` renders instantly with `position: fixed` and 
   covers the entire viewport before external resources finish downloading.
3. Event Listeners: The script listens for three completion triggers:
   - Window `load` event (all images/scripts loaded).
   - User interaction (`wheel` or `touchstart` events).
   - Fallback timer (automatically hides after 4.5 seconds to prevent endless loops).
4. Fade Out: Adding `.ul7-sl-ready` sets `opacity: 0` and `visibility: hidden`, 
   followed by node removal from the DOM after 1000ms.

------------------------------------------------------------------------
 7. TROUBLESHOOTING & COMMON ISSUES
------------------------------------------------------------------------
Q: Settings are not saving in the Admin Dashboard!
A: Ensure your web server has write permissions for the directory containing 
   "uplink7-skeleton-loader.php". The script needs to create and update 
   the "ul7_settings.json" file.

Q: The overlay stays visible forever.
A: Check your browser developer tools console (F12) for JavaScript errors in 
   other third-party scripts that might prevent the `window.onload` event from firing. 
   The fallback timer will force-close it after 4.5 seconds.

Q: Flash of unstyled content (FOUC) appears briefly.
A: Ensure the `include` statement is placed immediately after the opening `<body>` 
   tag (or as high as possible inside `<head>`), prior to heavy scripts/render-blocking files.

------------------------------------------------------------------------
 8. SECURITY & PERFORMANCE BEST PRACTICES
------------------------------------------------------------------------
- Change Master Password:
   "uplink7-skeleton-loader.php" in a code editor and edit line 11:
  `define('UL7_ADMIN_PASSWORD', 'YourStrongPasswordHere');`
  
- Change Password:
  Login in Admin Dashboard and set new Password.
  
- Restrict Admin Access (Optional):
  If using Apache, you can restrict access to `?ul7_admin=1` by IP or basic auth.

- Asset Optimization:
  Ensure any image provided in "Logo URL" is compressed (PNG/SVG/WebP) and under 100KB 
  to guarantee immediate display.

========================================================================
 License: GPLv2 or later
========================================================================