belazy.js - Documentation

What is Belazy.js?

Belazy.js is a lightweight JavaScript library designed to lazy-load images. This means images are only loaded when they are about to become visible in the user’s viewport, improving initial page load times and overall website performance. It’s particularly useful for websites with many images, especially large ones, where loading everything upfront can significantly impact the user experience. Belazy.js handles the complexities of intersection observer API, providing a simple and efficient solution for lazy loading.

Why use Belazy.js?

Setting up Belazy.js

  1. Include the Library: You can include Belazy.js via a CDN or by downloading the library and including it locally. The CDN method is generally easier:

    <script src="https://cdn.jsdelivr.net/npm/belazy.js@latest/dist/belazy.min.js"></script>

  2. Initialize (Optional): While Belazy.js automatically selects elements with the data-belazy attribute, you can optionally initialize it manually for more control. This is useful if you have specific initialization requirements or want to control the lazy loading process further. See the Advanced Usage section for details.

Basic Example

This example demonstrates how to use Belazy.js to lazy-load images:

<!DOCTYPE html>
<html>
<head>
  <title>Belazy.js Example</title>
  <script src="https://cdn.jsdelivr.net/npm/belazy.js@latest/dist/belazy.min.js"></script> </head>
<body>

  <img data-belazy="images/image1.jpg" alt="Image 1">
  <img data-belazy="images/image2.jpg" alt="Image 2">
  <img data-belazy="images/image3.jpg" alt="Image 3">

</body>
</html>

Replace "images/image1.jpg", "images/image2.jpg", and "images/image3.jpg" with the actual paths to your images. Belazy.js will automatically detect the data-belazy attribute and lazy-load these images. Remember to place your images in the specified directory. No further JavaScript is needed for this basic setup.

Core Concepts

Belazy.js, being primarily focused on image lazy loading, doesn’t inherently support concepts like component composition, data binding, or complex event handling and lifecycle methods in the way a full-fledged framework like React or Vue.js does. Its core functionality is streamlined for its specific purpose. However, we can discuss how these concepts could be applied in the context of using Belazy.js within a larger application that uses such frameworks.

Lazy Loading

This is the core function of Belazy.js. It uses the Intersection Observer API to detect when an image element is within the viewport. When an image element with the data-belazy attribute is about to become visible, Belazy.js replaces the data-belazy attribute value (the image source URL) with the src attribute, triggering the image loading. This is handled entirely automatically by the library. No further configuration is usually required beyond adding the data-belazy attribute to your <img> tags. You can control the threshold for loading (how far from the viewport the image needs to be before loading) by using options (see advanced usage).

Component Composition

Belazy.js itself doesn’t have components. It operates at a lower level, focusing solely on lazy-loading images. If you’re using Belazy.js within a component-based framework (React, Vue, Angular, etc.), you’d incorporate lazy loading into your components. For instance, in React you might have a component that renders an image, and within that component, you’d use Belazy.js by adding the data-belazy attribute to the <img> element rendered by your component. The component’s logic would be responsible for managing the data associated with the image URL.

Data Binding

Belazy.js doesn’t directly handle data binding. Data binding is a feature of frameworks. If your application uses a framework with data binding, the URL for the image passed to the data-belazy attribute would be dynamically updated via that framework’s data binding mechanism. For instance, if your image URL is stored in a variable in your React component’s state, changes to that state will automatically update the data-belazy attribute (assuming you are using a proper approach to update the DOM).

Event Handling

Belazy.js doesn’t offer specific event handling mechanisms. However, you can use standard JavaScript event listeners on the images to respond to events such as load, error, or abort after Belazy.js has triggered the image load. These events are standard browser events and will fire normally once Belazy.js sets the src attribute. For example:

const image = document.querySelector('img[data-belazy]');
image.addEventListener('load', () => {
  console.log('Image loaded!');
});

Lifecycle Methods

Belazy.js doesn’t have lifecycle methods in the sense of component-based frameworks. The only implicit “lifecycle” is the loading of the image after it enters the viewport. This is handled automatically by the library’s internal use of the Intersection Observer API. Any actions you want to take before or after an image loads would be done using standard JavaScript event listeners on the image element (as described in the Event Handling section).

Components

Belazy.js is not a component-based framework; it’s a single-purpose library for lazy-loading images. The concepts of “components,” “component properties,” “component methods,” “component styling,” “component events,” “nested components,” and “component templates” don’t apply directly to Belazy.js itself. Belazy.js works at a lower level, manipulating the DOM directly to achieve lazy loading. If you’re using Belazy.js within a component-based framework (like React, Vue, or Angular), then those concepts would be relevant within that framework, but not as features of Belazy.js itself.

Creating Components

Belazy.js doesn’t have a mechanism for creating components. If you want to use Belazy.js within a larger application structure, you would create components within your chosen framework (React, Vue, Angular, etc.) and integrate the lazy loading provided by Belazy.js within those components. A component would typically render an <img> tag with the data-belazy attribute.

Component Properties, Component Methods, Component Events

These concepts are all relevant to component-based frameworks, not Belazy.js. For example, in React, you might have a component with properties defining the image source, methods to handle image loading state, and events emitted when the image loads or fails to load. Belazy.js would simply be used within such components.

Component Styling

Styling would be handled by your chosen framework’s styling mechanism (CSS, styled-components, etc.) or within the CSS of your application. Belazy.js itself doesn’t provide any features for styling images. Any styling would be applied to the <img> element directly.

Nested Components

If using Belazy.js within a framework that supports nested components, you could nest components containing images with lazy loading as needed. Belazy.js itself is agnostic to nesting.

Component Templates

Component templates (like JSX in React or templates in Vue) are part of component-based frameworks. Within the template for your component, you’d include the <img> tag with the data-belazy attribute to make use of Belazy.js. Belazy.js doesn’t have its own templating language.

Data Handling

Belazy.js is solely focused on lazy-loading images. It does not have built-in mechanisms for data binding, handling user input, working with forms, or data validation. These are features typically provided by JavaScript frameworks like React, Vue, or Angular. If you’re using Belazy.js within one of these frameworks, you would handle data within the context of that framework, and Belazy.js would simply be used for its lazy-loading functionality within those applications. The examples below assume you are using a framework that provides the described features.

Data Binding with Expressions

Belazy.js doesn’t support expressions for data binding. The data-belazy attribute expects a simple string representing the image URL. If you are using a framework like Vue or React that supports data binding, you would bind the image URL to the data-belazy attribute using the framework’s templating system and data binding mechanisms. For example in Vue:

<template>
  <img :data-belazy="imageUrl" alt="My Image">
</template>

<script>
export default {
  data() {
    return {
      imageUrl: 'path/to/image.jpg'
    }
  }
}
</script>

Data Binding with Methods

Similarly, you can bind the data-belazy attribute to the return value of a method in your framework. This allows for more complex logic to determine the image URL. However, Belazy.js itself is unaware of this data binding—it only uses the final string value of the data-belazy attribute.

Handling User Input

User input handling is done through the framework you’re using, not Belazy.js. Event listeners (e.g., onChange in React or v-on in Vue) would be used to capture user input and update data used to control the image URL or other aspects of your application. Belazy.js remains solely responsible for lazy loading.

Working with Forms

Forms are managed by your chosen framework. Belazy.js doesn’t interact with form submission or form data processing. Any data from forms that impacts the image URLs would be handled through the framework’s data binding and event handling.

Data Validation

Data validation is performed within your framework, not by Belazy.js. You might use validation rules provided by your framework or external libraries to ensure that the image URL entered by a user (or generated by other parts of your app) is valid before it’s used in the data-belazy attribute. Belazy.js doesn’t perform any validation on the image URLs it receives.

Advanced Topics

Asynchronous Operations

Belazy.js’s core lazy-loading operation is inherently asynchronous. The image loading is triggered only when the image is about to become visible, and the browser handles the image loading asynchronously in the background. You can use standard JavaScript promises or async/await within your application’s framework to handle any asynchronous actions related to the loading of the images (e.g., showing a loading indicator, processing the image data after it loads). Belazy.js itself doesn’t provide specific asynchronous API methods.

Error Handling

Error handling is done through standard JavaScript mechanisms. You can use the onerror event on the <img> tag to catch any errors during image loading. For instance:

const image = document.querySelector('img[data-belazy]');
image.onerror = function() {
  console.error('Error loading image:', this.src);
  // Add your error handling logic here, e.g., display a placeholder image.
};

Belazy.js doesn’t have specific error handling methods; it relies on the standard browser mechanisms.

Performance Optimization

Testing Belazy.js Components

Since Belazy.js is not a component framework itself, testing is done within the context of your chosen framework. You’d typically test the integration of Belazy.js within your components by verifying that images are loaded only when they are visible, and that error handling functions correctly. Use your framework’s testing tools and utilities (e.g., Jest, React Testing Library for React applications). Tests should focus on ensuring the image loading behavior within your components, not testing Belazy.js itself directly.

Integration with other libraries

Belazy.js is designed to be compatible with other JavaScript libraries. There are no specific integration points to be aware of. It’s important to remember that Belazy.js interacts only with the DOM—specifically, it modifies <img> elements. As long as your other libraries don’t interfere with this basic DOM manipulation, they should coexist with Belazy.js. However, ensure that any libraries that also modify the DOM are used carefully to prevent conflicts.

API Reference

Belazy.js has a minimal API surface. It’s primarily designed to be used declaratively by adding the data-belazy attribute to image tags. There’s no extensive API with global methods, component lifecycle methods, or utility functions in the same way as a full JavaScript framework. The functionality is streamlined for its single purpose: lazy-loading images.

Global Methods

Belazy.js does not expose any global methods. Its functionality is triggered automatically by the presence of the data-belazy attribute on <img> elements. Any manual control is typically handled through options passed during initialization (see advanced usage).

Component Lifecycle Methods

Belazy.js does not have “components” or component lifecycle methods. It operates at the DOM level. If you are using Belazy.js within a component framework (React, Vue, etc.), your components will have their own lifecycle methods, but these are not directly related to Belazy.js. You might use lifecycle methods in your framework to manage data related to image URLs before passing them to the data-belazy attribute.

Event Handlers

Belazy.js doesn’t provide its own custom events. You can utilize standard browser events such as load, error, and abort on the <img> elements to handle events related to image loading. These events will fire after Belazy.js has triggered the image loading by setting the src attribute. For example:

const image = document.querySelector('img[data-belazy]');
image.addEventListener('load', () => {
  console.log('Image loaded!');
});
image.addEventListener('error', () => {
  console.error('Image load failed!');
});

Utility Functions

Belazy.js does not expose any utility functions. Its functionality is contained within its core lazy-loading mechanism. Any utility functions you need for managing images or related tasks would be part of your application code or provided by external libraries used within your application, not part of Belazy.js itself.

Troubleshooting

Common Errors

Debugging Tips

Helpful Resources