IntelligenceBank Public CDN Image Optimization Script (Magic Links)

Overview

The IntelligenceBank CDN Image Optimization Script, or 'Magic Links', is a JavaScript library designed to dynamically optimize images served from the IntelligenceBank CDN. It ensures that images are appropriately sized for their containers, takes into account device pixel ratios for high-resolution displays, and implements lazy loading for improved page performance.

Key Features

1. Responsive Image Sizing: Automatically calculates the optimal image size based on the parent container width and device pixel ratio.

2. Lazy Loading: Loads images only when they enter the viewport, improving initial page load times.

3. High-DPI Support: Serves higher resolution images for devices with high pixel ratios (e.g., Retina displays).

4. WebP Format: Utilizes the WebP image format for better compression and faster loading.

5. Customizable Quality: Allows setting custom image quality parameters. Default is 80%.

6. Flexible Sizing Tiers: Uses predefined size tiers to match a wide range of container widths.

7. Maximum Size Capping: Prevents serving excessively large images to maintain performance.

8. Conditional Cropping: Applies cropping when parent containers have an explicitly set height, maintaining aspect ratios in fixed-dimension layouts. Focal point is automatically detected.

9. Debug Logging: Includes a comprehensive logging system for troubleshooting and verification.

10. Flexible Attribute Support: Works with both data-src and src attributes for broad CMS compatibility.

How It Works

1. Initialization: The script runs when the DOM content is loaded, selecting all <img> elements on the page.

2. Device Information: Logs device information including screen size, pixel ratio, and effective resolution.

3. Image Processing:

   • For each image, the script:
     a. Checks for data-src or src attributes.
     b. Stores the original source in a data-original-src attribute.
     c. Removes the src attribute to prevent immediate loading.
     d. Sets up an Intersection Observer for lazy loading.

4. Lazy Loading: When an image enters the viewport, the script:

   • Retrieves the original URL.

   • Calculates the optimal image size.

   • Transforms the URL with new parameters.

   • Sets the src attribute to load the optimized image.

5. Size Calculation:

   • Determines the parent container width.

   • Caps the width at a maximum of 2048px.

   • Selects the appropriate size tier based on the container width.

   • Multiplies the selected size by the device pixel ratio.

6. Conditional Cropping:

   • Checks if any parent element has an explicitly set height.

   • If a fixed height is found and is greater than 100px:

     • Applies a crop parameter to the image URL.

     • Uses the calculated width and the parent's height for cropping dimensions.

   • Auto-detects the focal point of the image to determine the crop position.

7. URL Transformation:

   • Adds parameters for size, format (WebP), quality, and cropping (if applicable).

   • Reconstructs the URL with these new parameters.

Implementation Guide

1. Include the IntelligenceBank provided CDN link to the script on your webpage from the versions list below, or create your own copy of the file:

   <script src="path/to/cdn_magic_links.js"></script>

2. Prepare your images:

   • You can use either data-src or src for the image URL.

   • Examples:

     <img data-src="<https://cdn.intelligencebank.com/your-image-path>" alt="Description">

     or

     <img src="<https://cdn.intelligencebank.com/your-image-path>" alt="Description">

3. Choosing between data-src and src:

   • data-src (Preferred for optimal lazy loading):

     • Prevents the browser from loading the image immediately.

     • Gives full control to the script for when and how to load the image.

     • Ideal for pages with many images or where performance is critical.

   • src (Supported for broader compatibility):

     • Works with CMS systems that automatically insert images with the src attribute.

     • Ensures images are visible even if JavaScript is disabled or fails to load.

     • May result in initial page load being slightly slower if there are many images.

4. CMS Compatibility:

   • The script is designed to work with various CMS systems, including those that use the src attribute by default.

   • If your CMS uses an IntelligenceBank Connector to insert image CDN links, no special configuration is needed.

   • For optimal performance, configure your CMS to use data-src if possible, but src will work if that's not an option.

5. Cropping behavior:

   • To enable automatic cropping, set a fixed height on a parent container of the image.

   • Example:

     <div style="height: 300px;">
       <img data-src="<https://cdn.intelligencebank.com/us/share/8BEayg/ble5/Pnap/original/imagename>" alt="Description">
     </div>

   • The script will detect this fixed height and apply appropriate cropping parameters.

6. The script will automatically process images when the page loads.

Script Behavior

• The script checks for both data-src and src attributes on each image.

• If both attributes are present, data-src takes precedence.

• The original image URL is stored in a data-original-src attribute for reference.

• The src attribute is temporarily removed to prevent immediate loading, regardless of which attribute was initially used.

Custom Image Parameters (Optional)

The script allows you to customize image quality and format on a per-image basis using data attributes:

1. Quality: Use the 'data-quality' attribute to set a custom quality value for specific images. The value should be a number between 1 and 100. Example: <img data-src="https://cdn.intelligencebank.com/us/share/8BEayg/ble5/Pnap/original/imagename" data-quality="60" alt="Custom quality image">
2. Format: Use the 'data-format' attribute to specify a different image format for particular images. Example: <img data-src="https://cdn.intelligencebank.com/us/share/8BEayg/ble5/Pnap/original/imagename" data-format="png" alt="Custom format image">

If these attributes are not specified, the script uses default values:

• Default quality: 80
• Default format: webp

You can use these attributes individually or together: Example: <img data-src="https://cdn.intelligencebank.com/us/share/8BEayg/ble5/Pnap/original/imagename" data-quality="75" data-format="png" alt="Custom quality and format">

These custom parameters allow you to fine-tune image optimization for specific use cases, balancing quality, file size, and format compatibility as needed.

Note: Supported formats are webp, jpg, png, and gif.

Browser Compatibility

This script uses modern JavaScript features and the Intersection Observer API. It's compatible with all major modern browsers.

Versions

Version 1.0.3 (25 July 2024)

• Automatic focal point is now applied when cropping applies.

Version 1.0.2 (10 July 2024)

• Initial Beta version. This initial version doesn't yet support automatic focal point detection when a crop applies. The center of the image is used by default.

To always dynamically refer to the latest version of the Javascript file, use:

<script src="https://cdn.jsdelivr.net/gh/ibproduct/magiclinks@latest/cdn_magic_links.js"></script>

Coming Soon

• Resize event listener (for better handling of Viewport Changes and CSS Media Queries).

Known Limitations

1. Initial Load Only: The script currently optimizes images present at the time of initial page load. It does not automatically handle images added dynamically after the page has loaded.
2. Fixed Breakpoints: The script uses predefined container size tiers and does not dynamically adjust to custom breakpoints that may be defined in the site's CSS.
3. Container Detection: The script attempts to determine image constraints by traversing parent containers. In complex layouts or with certain CSS techniques, it may not always identify the most visually relevant container for constraint calculations.
4. Viewport Changes: While the script considers the device pixel ratio, it does not automatically readjust image sizes if the viewport size changes (e.g., device rotation or browser window resizing).
5. Complex Layouts: In cases of deeply nested containers or complex CSS layouts (like flexbox or grid), the script may not always calculate the most appropriate dimensions.
6. Inline Styles: The script primarily relies on classes and computed styles. It may not fully account for dimensions set by inline styles.
7. Performance: For pages with a large number of images, the initial processing might cause a slight delay in image loading. Once the image has been generated for the first time though, it will always be distributed via the CDN on subsequent loads.

Guidelines

1. Direct Containment: Where possible, place images directly within their constraint-defining container. This helps our script accurately determine the intended dimensions.
2. Responsive Design: Use relative units (like percentages or viewport units) for image container dimensions to ensure proper responsiveness.
3. Inline Styles: While our script attempts to account for inline styles, it's best to define image container dimensions in your CSS for more reliable detection.
4. Flexbox and Grid: When using flexbox or grid layouts, ensure that image containers have explicit dimensions or flex-basis values for more accurate sizing.
5. Overflow Handling: Be mindful of how you use overflow properties on image containers, as this can affect how images are displayed and sized.
6. Testing: Test thoroughly across different devices and screen sizes to ensure images are being optimized correctly in all scenarios within your own context.

By following these guidelines and being aware of the limitations, you'll ensure the best performance and compatibility of our image optimization script with your website's structure.

Feedback

This Javascript library is still in beta, and we would love to hear your feedback and suggestions at product@intelligencebank.com.

To learn more about IntelligenceBank Public CDN Links, visit this page.