1.2.1 • Published 4 months ago

eo-webkit v1.2.1

Weekly downloads
-
License
MIT
Repository
github
Last release
4 months ago

eo-webkit.js - A Comprehensive JavaScript Utility Library

eo-webkit.js is a comprehensive JavaScript utility library designed to streamline web development. It provides a wide range of functions for common tasks, including data manipulation, date/time handling, DOM manipulation, network requests, random data generation, form handling, UI components, third-party integrations, settings management, and calculators.

Table of Contents

Introduction

eo-webkit.js aims to simplify front-end development by providing a single, well-documented library for a variety of everyday tasks. It's designed to be modular and easy to use, helping developers build web applications more efficiently.

Installation

Browser

1. Include the script: The simplest way to use eo-webkit.js in a browser is to include the script directly in your HTML file. Place the following <script> tag just before the closing </body> tag:

<body>
   <!-- your html content here -->

   <script type='text/javascript' src='path/to/eo-webkit.js' />
</body>

Replace "path/to/eo-webkit.js" with the actual path to your eo-webkit.js file. If you're using a CDN, you would use the CDN URL here.

2. Use the module:
After including the script, you can access the module's functions through the eo global object:

console.log(eo.trim("  hello  ")); // Example usage

Node.js

1. Install the package

npm install eo-webkit

2. Require the module:
In your Node.js code, require the module:

const eo = require('eo-webkit.js');

console.log(eo.trim("  hello  "));

AMD (Asynchronous Module Definition)

If you're using an AMD module loader like RequireJS, you can load eo.js as an AMD module:

1. Configure RequireJS:
Make sure RequireJS is configured in your HTML file.

2. Define the module path:
Configure the path to your eo.js file in your RequireJS configuration:

require.config({
  paths: {
    'eo-webkit': 'path/to/eo-webkit' // Path to your eo.js file (without the .js extension)
  }
});

3. Use the module:
Use require to load and use the module:

require(['eo-webkit'], function(eo) {
  console.log(eo.trim("  hello  ")); // Example usage
});

API-Reference

Data Manipulation

eo.trim

eo.trim(stringValue, maxLength) truncates a string if it exceeds the specified maxLength and appends "...". If the string is within the limit, it remains unchanged.

Parameters

ParameterTypeDescription
stringValueStringThe input string to be trimmed.
maxLengthNumberThe maximum allowed length of the string (including ... if truncated).

Returns

String The original string if within maxLength, otherwise a truncated version with "..." appended.

Example Usage

console.log(eo.trim("Hello, world!", 10)); 
// Output: "Hello, w..."

console.log(eo.trim("Short", 10)); 
// Output: "Short" (unchanged)

eo.formatFileSize

eo.formatFileSize(bytes, decimalPlaces = 0) converts a file size in bytes into a human-readable format (e.g., KB, MB, GB). It supports up to Yottabytes (YB) and allows formatting with a specified number of decimal places.

Parameters

ParameterTypeDefaultDescription
bytesNumberRequiredThe file size in bytes.
decimalPlacesNumber0 (optional)The number of decimal places for formatting.

Returns

String A human-readable file size with units (e.g., "1.5 MB", "500 KB").

Example Usage

console.log(eo.formatFileSize(1024));       
// Output: "1 KB"

console.log(eo.formatFileSize(1048576));    
// Output: "1 MB"

console.log(eo.formatFileSize(1500000, 2)); 
// Output: "1.50 MB"

console.log(eo.formatFileSize(0));          
// Output: "0 Bytes"

eo.uuidv4

eo.uuidv4() generates a random UUID (Universally Unique Identifier) Version 4 in the standard format:
xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
where x is a random hexadecimal digit and y is one of 8, 9, A, or B (per UUID v4 specification).

Returns

String A randomly generated UUID v4 in the format "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".

Example Usage

console.log(eo.uuidv4()); 
// Output: "3f94a8a7-1d2b-4c19-9b2f-6de8f0ea6df0" (random each time)

eo.formatCurrency

eo.formatCurrency(amount) formats large numbers into a more readable currency notation using suffixes like K (thousand), M (million), B (billion) T (trillion), and beyond, up to Googol (1e100).

Parameters

ParameterTypeDescription
amountNumber | StringThe numeric value to be formatted. Can be a number or a string that represents a number.

Returns

String A formatted string representing the number with an appropriate suffix (e.g., "1.5M", "2B").

Example Usage

console.log(eo.formatCurrency(1500));      // "1.5K"
console.log(eo.formatCurrency(1000000));   // "1M"
console.log(eo.formatCurrency(2500000000)); // "2.5B"
console.log(eo.formatCurrency(1e100));     // "1V"  (Googol)
console.log(eo.formatCurrency(999));       // "999"

eo.serializeFormData

eo.serializeFormData(formData) converts form data into a plain JavaScript object. It supports different input types, including:

  • FormData (browser API)
  • Array of objects (e.g., { name: "email", value: "test@example.com" })
  • Plain JavaScript objects

    Parameters

    ParameterTypeDescription
    formDataFormData | Array | ObjectThe data to be converted into a plain object.

    Returns

    Object A JavaScript object where keys represent form field names and values represent user input.

    Example Usage

  • Handling FormData

    const formElement = document.querySelector("form");
    const formData = new FormData(formElement);
    console.log(eo.serializeFormData(formData));
    // { name: "John", email: "john@example.com", password: "123456" }
  • Handling an Array of Objects

    const formArray = [
        { name: "username", value: "johndoe" },
        { name: "email", value: "john@example.com" }
    ];
    console.log(eo.serializeFormData(formArray));
    // { username: "johndoe", email: "john@example.com" }
  • Handling a Plain Object

    const formObject = { age: 25, country: "USA" };
    console.log(eo.serializeFormData(formObject));
    // { age: 25, country: "USA" }

    eo.objectToDotNotation

    eo.objectToDotNotation(obj, prefix = '') Converts a nested object into a flat object with dot notation keys.

    Features

  • Object Flattening: Converts a nested object into a flat object with dot notation keys.

  • Recursive Handling: Recursively processes nested objects to ensure all nested properties are flattened.
  • Custom Prefix: Allows specifying a prefix for the keys in the resulting flat object.

    Parameters

    ParameterTypeDescription
    objObjectThe nested object to be converted.
    prefixstringAn optional prefix for the keys in the resulting flat object.

    Returns

    Object A new flat object with dot notation keys.

    Example Usage

    const nestedObj = {
       user: {
          name: 'John Doe',
          address: {
                city: 'New York',
                zip: '10001'
          }
       }
    };
    
    const flatObj = eo.objectToDotNotation(nestedObj);
    console.log(flatObj); // Outputs: { 'user.name': 'John Doe', 'user.address.city': 'New York', 'user.address.zip': '10001' }
    
    const anotherNestedObj = {
       product: {
          id: 123,
          details: {
                name: 'Laptop',
                specs: {
                   cpu: 'Intel i7',
                   ram: '16GB'
                }
          }
       }
    };
    
    const anotherFlatObj = eo.objectToDotNotation(anotherNestedObj);
    console.log(anotherFlatObj); // Outputs: { 'product.id': 123, 'product.details.name': 'Laptop', 'product.details.specs.cpu': 'Intel i7', 'product details.specs.ram': '16GB' }

    eo.dotNotationToObject

    eo.dotNotationToObject(obj) Converts a nested object into a flat object with dot notation keys.

    Features

  • Dot Notation to Object Conversion: Converts an object with dot notation keys into a nested object.

  • Recursive Handling: Recursively processes dot notation keys to create a deeply nested object structure.
  • Efficient Processing: Uses the reduce method for efficient key processing and object construction.

    Parameters

    ParametersTypeDefaultDescription
    objObjectrequiredThe object with dot notation keys to be converted.

    Returns

    Object A new flat object with dot notation keys.

    Example Usage

    const dotNotatedObj = {
       'product.id': 123,
       'product.details.name': 'Laptop',
       'product.details.specs.cpu': 'Intel i7',
       'product.details.specs.ram': '16GB'
    };
    
    const nestedProduct = eo.dotNotationToObject(dotNotatedObj);
    console.log(nestedProduct); // Outputs: { product: { id: 123, details: { name: 'Laptop', specs: { cpu: 'Intel i7', ram: '16GB' } } } }
    
    const anotherDotNotatedObj = {
       'order.number': 456,
       'order.date': '2023-01-01',
       'order.items.0.name': 'Book',
       'order.items.0.price': 19.99,
       'order.items.1.name': 'Pen',
       'order.items.1.price': 2.99
    };
    
    const nestedOrder = eo.dotNotationToObject(anotherDotNotatedObj);
    console.log(nestedOrder); // Outputs: { order: { number: 456, date: '2023-01-01', items: [ { name: 'Book', price: 19.99 }, { name: 'Pen', price: 2.99 } ] } }

    eo.removeFalseArray

    eo.removeFalseArray(arr) Filters an array by removing empty strings, null, false, undefined, and boolean values.

    Features

  • Filter Out Falsy Values: Removes empty strings, null, false, undefined, and boolean values from an array.

  • Simplified Filtering: Uses the filter method for efficient and concise array filtering.

    Parameter

    ParameterTypeDescription
    arrArrayThe array to be filtered.

    Return

    Array A new array with the falsy values removed.

    Example Usage

    const array = [0, 1, false, '', 'hello', null, undefined, true, 'world'];
    const filteredArray = eo.removeFalseArray(array);
    console.log(filteredArray); // Outputs: [0, 1, 'hello', 'world']
    
    const mixedArray = [0, '', false, true, null, undefined, 'string', 123];
    const filteredMixedArray = eo.removeFalseArray(mixedArray);
    console.log(filteredMixedArray); // Outputs: [0, 'string', 123]

    eo.removeDuplicatesArray

    eo.removeDuplicatesArray(arr) Removes duplicate elements from an array.

    Features

  • Remove Duplicate Elements: Efficiently removes duplicate elements from an array.

  • Simplified Usage: Uses the Set object to filter out duplicates, returning a new array.

    Parameter

    ParameterTypeDescription
    arrArrayThe array from which duplicates will be removed.

    Return

    Array A new array with duplicate elements removed.

    Example Usage

    const array = [1, 2, 2, 3, 4, 4, 5];
    const uniqueArray = eo.removeDuplicatesArray(array);
    console.log(uniqueArray); // Outputs: [1, 2, 3, 4, 5]
    
    const stringArray = ['apple', 'banana', 'apple', 'orange'];
    const uniqueStringArray = eo.removeDuplicatesArray(stringArray);
    console.log(uniqueStringArray); // Outputs: ['apple', 'banana', 'orange']

    Date and Time

    eo.epochToTimeString

    eo.epochToTimeString(epoch) converts a Unix epoch timestamp (seconds/milliseconds since 1970-01-01 UTC) into a human-readable date string formatted in US English. Converts an epoch time (in seconds/milliseconds) to a localized string in the format: "Weekday, Month Day, Year, HH:MM AM/PM"

    Parameters

    ParameterTypeDescription
    epochNumberA Unix timestamp in seconds/milliseconds.

    Returns

    String A formatted date string in English (US locale).

    Example Usage

    console.log(eo.epochToTimeString(1700000000)); 
    // Output: "Sunday, November 12, 2023, 12:26 PM"

    eo.readableDate

    eo.readableDate(timestamp) Converts a timestamp into a human-readable date string similar to Meta Messenger's format. It can accept epoch time in seconds, milliseconds, a string representation of a date, or a Date object.

    Parameter

    ParameterTypeDescription
    timestampnumber or string or DateThe input timestamp to be converted. Can be a number (in seconds or milliseconds), a string representation of a date, or a Date object.

    Returns

    string The formatted date string.

    Throws

    Error Throws an error if the timestamp type is invalid.

    Example Usage

    console.log(eo.readableDate(1739845344)); // Outputs: formatted date assuming input in seconds
    console.log(eo.readableDate(1739845344000)); // Outputs: formatted date assuming input in milliseconds
    console.log(eo.readableDate('2022-12-31T23:59:59Z')); // Outputs: formatted date from string
    console.log(eo.readableDate(new Date())); // Outputs: current time if input is Date object

    eo.diffDays

    eo.diffDays(date, otherDate) Calculates the difference in days between two dates.

    Features

  • Date Difference Calculation: Calculates the difference in days between two dates.

  • Handles Various Date Formats: Can accept Date objects, timestamp in milliseconds, or any other format that JavaScript's Date constructor can handle.
  • Accurate Calculation: Uses Math.abs and Math.ceil to ensure accurate and non-negative results.

    Parameters

    ParametersTypeDescription
    dateDate, number, stringThe first date to compare. Can be a Date object, a timestamp in milliseconds, or a string representation of a date.
    otherDateDate or number or stringThe second date to compare. Can be a Date object, a timestamp in milliseconds, or a string representation of a date.

    Returns

    number The difference in days between the two dates.

    Example Usage

    const date1 = new Date('2022-01-01');
    const date2 = new Date('2022-01-10');
    console.log(eo.diffDays(date1, date2)); // Outputs: 9
    
    const timestamp1 = Date.now();
    const timestamp2 = timestamp1 + (1000 * 60 * 60 * 24 * 7); // 7 days later
    console.log(eo.diffDays(timestamp1, timestamp2)); // Outputs: 7
    
    const dateStr1 = '2022-01-01';
    const dateStr2 = '2022-01-05';
    console.log(eo.diffDays(new Date(dateStr1), new Date(dateStr2))); // Outputs: 4

    DOM Manipulation

    eo.moveHtmlElement(fromSelector, toSelector)

    eo.moveHtmlElement(fromSelector, toSelector) moves the inner HTML from one element to another. This is useful for dynamically repositioning content within a webpage.

    Parameters

    ParameterTypeDescription
    fromSelectorstringCSS selector of the element whose content will be moved.
    toSelectorstringCSS selector of the element where the content will be placed.

    Returns

    void Does not return a value. It modifies the DOM directly.

    Example Usage

  • Move Content from One Element to Another

    <div id="source">
        <p>Hello, World!</p>
    </div>
    
    <div id="destination">
        <!-- Content will be moved here -->
    </div>
    eo.moveHtmlElement('#source', '#destination');
  • Output

    <div id="source">
        <!-- Empty after move -->
    </div>
    
    <div id="destination">
        <p>Hello, World!</p>
    </div>

    eo.createElements

    eo.createElements(tag, attributes, children) dynamically creates an HTML element, applies attributes, and appends child elements or text nodes. Ensures data sanitization before inserting into the DOM.

    Parameters

    ParameterTypeDescription
    tagstringThe HTML tag name (e.g., 'div', 'span').
    attributesobject (optional)An object containing attribute key-value pairs (e.g., { class: 'btn', id: 'my-button' }).
    childrenarray (optional)An array of child elements or strings (text content).

    Returns

    HTMLElement Returns a newly created DOM element with the specified attributes and children.

    Example Usage

    Creating a Simple <div>

    const div = eo.createElements('div', { class: 'container', id: 'main' }, ['Hello, world!']);
    document.body.appendChild(div);

    Output

    <div class="container" id="main">Hello, world!</div>

    Creating a Nested Structure

    const button = eo.createElements('button', { class: 'btn', type: 'button' }, ['Click Me']);
    const wrapper = eo.createElements('div', { class: 'wrapper' }, [button]);
    
    document.body.appendChild(wrapper);

    Output

    <div class="wrapper">
        <button class="btn" type="button">Click Me</button>
    </div>

    Error Handling

    Error ConditionThrown Error
    tag is not a string or empty"Invalid tag name"
    attributes is not an object"Attributes must be an object"
    children is not an array"Children must be an array"

    eo.createHiddenInput

    eo.createHiddenInput(name, value) creates a hidden input field with a specified name and value. This is useful for storing data in forms without displaying it to the user.

    Parameters

    ParameterTypeDescription
    namestringThe name attribute of the hidden input.
    valuestringThe value to be stored in the hidden input.

    Returns

    HTMLElement A hidden element with the provided name and value.

    Example Usage

    Creating a Hidden Input

    const hiddenInput = eo.createHiddenInput('user_id', '12345');
    document.body.appendChild(hiddenInput);

    Output

    <input type="hidden" name="user_id" value="12345">

    Error Handling

    Error ConditionThrown Error
    name is not a string or empty"Invalid name"
    value is not a string"Invalid value"

    eo.getYoutubeVideoData

    eo.getYoutubeVideoData(url) extracts YouTube video details from a given URL. It retrieves:

  • The video ID

  • Thumbnail URLs in various resolutions
  • The direct watch URL
  • The embed URL

    If the URL is invalid, an error alert is triggered.

    Parameters

    ParameterTypeDescription
    urlstringThe YouTube video URL to extract details from.

    Returns

    TypeDescription
    ObjectReturns an object with video details (if the URL is valid).
    nullReturns null and triggers an alert if the URL is invalid.

    Example Usage

  • Valid Youtube URL

    const videoData = eo.getYoutubeVideoData("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
    console.log(videoData);
    /* {
    id: "dQw4w9WgXcQ",
    thumbnail: {
       default: "http://img.youtube.com/vi/dQw4w9WgXcQ/default.jpg",
       hq: "http://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
       mq: "http://img.youtube.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
       sd: "http://img.youtube.com/vi/dQw4w9WgXcQ/sddefault.jpg",
       maxres: "http://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    },
    url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    embed: "https://www.youtube.com/embed/dQw4w9WgXcQ"
    } */
  • Invalid YouTube URL

    const videoData = eo.getYoutubeVideoData("https://example.com/video");
    console.log(videoData); // null
    // ⚠️ Alert: "Invalid YouTube URL"

    Supported Youtube URL Formats

    Format TypeExample
    Standard URLhttps://www.youtube.com/watch?v=VIDEO_ID
    Shortened URLhttps://youtu.be/VIDEO_ID
    Embed URLhttps://www.youtube.com/embed/VIDEO_ID
    Other Variantshttps://www.youtube.com/v/VIDEO_ID, https://www.youtube.com/watch?v=VIDEO_ID&feature=share

    Network Requests

    eo.post

    The eo.post function performs an HTTP POST request to a specified url using the Fetch API. It supports different data types (FormData, JSON, array, or plain objects), allows custom content types, and provides callback hooks for different stages of the request.

    Syntax

    eo.post(url, data, {
        onBeforeSend,
        onSuccess,
        onError,
        onComplete,
        contentType = 'application/x-www-form-urlencoded; charset=UTF-8'
    });

    Parameters

    ParameterTypeDescription
    urlstringThe API endpoint where the request is sent.
    dataFormData, Object, ArrayThe data to be sent in the request body.
    optionsobjectOptional configuration options (see below).

    Options Object | Option | Type | Description | | --- | --- | --- | | onBeforeSend | function | Callback function executed before the request is sent. | | onSuccess | function | Callback function executed when the request is successful. | | onError | function | Callback function executed when the request fails. | | onComplete | function | Callback function executed when the request completes (whether successful or not). | | contentType | string | The Content-Type of the request (application/json, application/x-www-form-urlencoded, etc.). |

    Returns

    void Does not return a value. Instead, it executes the provided callback functions.

    Example Usage

    Send Form Data

    const formData = new FormData();
    formData.append('username', 'john_doe');
    formData.append('password', 'securePass123');
    
    eo.post('/login', formData, {
        onSuccess: (response) => console.log('Login Success:', response),
        onError: (xhr, status, error) => console.error('Error:', status, error)
    });

    Send JSON Data

    const userData = { username: 'john_doe', age: 30 };
    
    eo.post('/update-profile', userData, {
        contentType: 'application/json',
        onSuccess: (response) => console.log('Profile Updated:', response),
        onError: (xhr, status, error) => console.error('Profile Update Failed:', error)
    });

    Note You can integrate the CSRFToken (Optional) Please read CSRFToken Implementation

    <meta name="csrf-token" content="{{ csrf_token() }}">

    eo.get

    The eo.get function is an asynchronous utility to make HTTP GET requests using the Fetch API. It allows for optional query parameters, customizable data type handling, and optional success callbacks.

    Parameters

    ParameterTypeDescription
    urlstringThe API endpoint from which data is fetched.
    dataObject / Function OptionalAn object containing query parameters or a callback function.
    successFunction OptionalA callback function to handle the response data.
    dataTypeString OptionalThe expected data type of the response (e.g., 'json').

    Returns

    Promise<any> A promise that resolves with the response data or logs an error.

    Example Usage

    // Making a GET request with query parameters and handling JSON response
    const data = await get('/api/data');
    
    // GET with query params
    const userData = await get('/api/user', { id: 123 });
    
    // With success callback
    get('/api/data', { id: 123 }, (data) => console.log(data));
    
    // Explicit JSON response handling
    const jsonData = await get('/api/data', { id: 123 }, null, 'json');

    Error Handling

    Any fetch error is logged to the console and re-thrown for further handling.

    get('/api/user', { id: 456 })
       .then((response) => console.log('User Data:', response.data))
       .catch((error) => console.error('Error:', error));

    eo.redirect

    eo.redirect(url) navigates the browser to the specified URL by setting window.location.

    Parameters

    ParameterTypeDescription
    urlStringThe URL to which the browser should be redirected.

    Returns

    void This function does not return anything. It redirects the user immediately.

    Example Usage

    eo.redirect("https://example.com");
    // The browser navigates to "https://example.com"

    eo.userClient

    The eo.userClient collects and manages client-related data, including:

  • User Agent: The client's browser user agent string.

  • Geo Information: The client's location data (retrieved from ipinfo.io).
  • Browser Detection: Determines the browser name based on the user agent.

    This information is cached in localStorage to avoid redundant API calls.

    Usage Example

    console.log(eo.userClient.userAgent); // e.g., "Mozilla/5.0 (Windows NT 10.0; Win64; x64)..."
    console.log(eo.userClient.geo); // e.g., { country: "US", city: "New York", ... }
    console.log(eo.userClient.browser); // e.g., "Google Chrome"

    Properties

    eo.userClient Object | Property | Type | Description | | --- | --- | --- | | userAgent | string | The browser's user agent string. | | geo | Object | null | | browser | string | string |

    Implementation Details

    Fetching Geolocation Data

  • If geolocation data isn't stored, userClient calls https://ipinfo.io/json to retrieve location details.

  • The response is cached in localStorage for future use.

    Browser Detection

  • Uses navigator.userAgent to determine the browser name.

  • Compares the user agent string against common browser signatures.

    Error Handling

  • Geo Fetch Failure: Logs an error (Error getting geo info:).

  • Unknown Browser: Defaults to "Unknown Browser" if no match is found.

    eo.CSRFToken

    eo.CSRFToken Automatically retrieves the CSRF token from the meta tags.

    Features

  • Automatic CSRF Token Retrieval: Automatically retrieves the CSRF token from the meta tags.

  • Error Logging: Logs an error to the console if the CSRF token is not found.

    Setup

    Ensure the CSRF token is generated and validated on the server side:

    Server-Side: Generating and Validating CSRF Token

  1. Generate CSRF Token:
    • Generate a CSRF token on the server side and include it in the meta tags of your HTML document.
    • Example in PHP:
    session_start();
    if (empty($_SESSION['csrf_token'])) {
       $_SESSION['csrf_token'] = bin2hex(random_bytes(32));
    }
    $csrf_token = $_SESSION['csrf_token'];
    ?>
    <meta name="csrf-token" content="<?= $csrf_token ?>">
  2. Validate CSRF Token:

    • Validate the CSRF token on the server side when processing form submissions or AJAX requests.
    • Example in PHP:
      session_start();
      if ($_SERVER['REQUEST_METHOD'] === 'POST') {
         $csrf_token = $_POST['csrf_token'] ?? '';
         if (!hash_equals($_SESSION['csrf_token'], $csrf_token)) {
            die('Invalid CSRF token');
         }
         // Proceed with processing the request
      }

    Returns

  • string The CSRF token if found.
  • undefined If the CSRF token is not found, logs an error message to the console.

    Example Usage

    document.addEventListener('DOMContentLoaded', () => {
       if (CSRFToken) {
          console.log('CSRF Token:', CSRFToken);
          // You can use CSRFToken in your AJAX requests or forms
       } else {
          console.error('CSRF Token is missing!');
       }
    });

    Random Data Generation

    eo.getRandomChar

    eo.getRandomChar(length) generates a random hexadecimal string of the specified length using the Web Crypto API for cryptographic security.

    Parameters

    ParameterTypeDescription
    lengthNumberThe desired length of the output string.

    Returns

    String A random hexadecimal string of the given length.

    Example Usage

    console.log(eo.getRandomChar(10)); 
    // Output: "f3a9c2b4d1" (random each time)

    eo.getRandomNum

    eo.getRandomNum(start, end) generates a random integer between start and end (inclusive).

    Parameters

    ParameterTypeDefaultDescription
    startNumberRequiredThe minimum value (inclusive).
    endNumberRequiredThe maximum value (inclusive).

    Returns

    Number A random integer between start and end (both inclusive).

    Example Usage

    console.log(eo.getRandomNum(1, 10)); 
    // Output: Random number between 1 and 10

    Form Handling and Validation

    eo.validator

    The eo.validator is a lightweight data validation utility that checks objects against predefined rules. It supports nested properties using dot notation and provides customizable validation rules and error messages.

    Features

  • Validates objects based on predefined constraints.

  • Supports nested properties using dot notation.
  • Customizable validation rules.
  • Customizable error messages.

    Usage Example

    const rules = {
      name: { required: true, length: { min: 3, max: 50 } },
      email: { required: true, email: true },
      age: { number: { min: 18, max: 99 } },
      address: { 
        street: { required: true }, 
        city: { required: true }
      }
    };
    
    eo.validator.setConstraints(rules);
    
    const data = {
      name: "John",
      email: "invalid-email",
      age: 17,
      address: { street: "123 Main St" }
    };
    
    if (!eo.validator.validate(data)) {
      console.log(eo.validator.getErrors()); 
      // Output: [ "Email is not a valid email address.", "Age must be a number greater than 18.", "Address City is required." ]
    }

    Methods

  1. validate(data, rules) Validates the given data object against rules and collects errors.

    Parameters:

    • data (Object) – The object to validate.
    • rules (Object, optional) – The validation rules. If omitted, previously set constraints are used.

    Returns:

    • true if validation passes.
    • false if validation fails (errors can be retrieved using getErrors()).

    Example:

    const isValid = eo.validator.validate({ name: "Alice" });
    console.log(isValid); // true or false
  2. getErrors() Retrieves an array of validation errors from the last validate() call.

    Returns:

    • Array<String> – A list of human-readable error messages.

    Example:

    console.log(eo.validator.getErrors());
    // Output: [ "Email is not a valid email address." ]
  3. setConstraints(rules) Sets default validation rules to be used for all future validations.

    Parameters:

    • rules (Object) – The validation rules object.

    Example:

    eo.validator.setConstraints({ username: { required: true } });
  4. resetConstraints() Clears all previously set validation rules.

    Example:

    eo.validator.resetConstraints();

    Validation Rules

    The validator supports various rules that can be applied to fields.

    RuleParameter TypeDescription
    requiredBooleanEnsures a value is present (not null, undefined, or empty).
    length{ min, max }Enforces string length constraints.
    number{ min, max }Ensures a value is a number and optionally within a range.
    urlBoolean / Array { format }Ensures a valid URL format (http:// or https://).
    emailBoolean / Array { format }Ensures a valid email format.
    dateBoolean / Array { format }Ensures a valid date format (YYYY-MM-DD).
    datetimeBoolean / Array { format }Ensures a valid datetime format.
    equalityAnyEnsures the value matches the given parameter exactly.
    typeStringEnsures the value is of the specified JavaScript type (string, number, etc.).

    Rules Parameter format parameter can be added to url, email, date and datetime rules. | Rule | Parameter Type | Possible Value | Description | | --- | --- | --- | --- | | format | Array | { pattern: regex, message: string } | |

    format Parameters | Parameter | Type | Description | | --- | --- | --- | | pattern | Regex | regex value e.g. /^[^\s@]+@[^\s@]+\.[^\s@]+$/ | | message | String | The error message when the validation fails, will replace the original error message |

    Example Rule Definition:

    const rules = {
      name: { required: true, length: { min: 3, max: 50 } },
      email: { required: true, email: true },
      age: { number: { min: 18, max: 99 } },
      brithdate: { date: true },
      address: { 
        street: { required: true }, 
        city: { required: true }
      }
    };

    Custom Error Messages Custom error messages can be defined in the rules. If a custom message is provided, it will be used instead of the default error message.

    Example Usage with Custom Messages

    const rules = {
     first_name: {
       required: true,
       length: { min: 2, max: 50 },
     },
     email: {
       required: true,
       email: {
          format: {
             pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
             message: 'must be a valid email format.'
          }
       }
     }
    };

    Equality Rule Example The equality rule should use the value of the compared field and the key must be the comparing field.

    In this validation rule structure, the equality rule uses the confirm_password field as the key, indicating the field to be compared. The value associated with this key (data.password) represents the value of the password field, which the confirm_password field must match.

    const data = {
       password: 'myPasswordThatNeverFails',
       confirm_password: 'myPasswordThatNeverFails'
    };
    
    const rules = {
       password: { required: true },
       equality: {
          confirm_password: data.password
       }
    };

    eo.submitForm

    The eo.submitForm simplifies handling form submissions, including validation, AJAX posting, and success/error handling. It integrates with the eo.validator for form validation

    Features

  • Validates form data using the eo.validator before submission.
  • Submits form data via AJAX (post function).
  • Displays alerts using the eo.alert.
  • Handles success and error responses.
  • Disables & enables buttons during the request to prevent multiple submissions.
  • Redirects users upon success if redirectUrl is provided.

    This method used the following:

  • eo.validator

  • eo.post
  • eo.alert
  • eo.button
  • csrf-token in meta tag (optional) Please read CSRFToken

    <meta name="csrf-token" content="{{ csrf_token() }}">

    Syntax

    eo.submitForm(formId, { rules, callback, onBeforeSend, redirectUrl } = {})

    Parameters

    ParameterTypeDescription
    formIdstringThe ID of the form to submit (with or without #).
    optionsobjectConfiguration options for the eo.submitForm.

    Options | Options | Type | Description | | --- | --- | --- | | rules | object | The validation rules based on the eo.validator. | | callback | function | A callback function executed on a successful submission. | | onBeforeSend | function | A function executed before sending the form data. | | redirect | url | The url to redirect to on success |

    Example Usage

    eo.submitForm('#myForm', {
       rules: {
           name: { required: true, min: 3 },
           email: { required: true, email: true },
       },
       callback: (formData, response) => {
           console.log('Form submitted successfully:', response);
       },
       onBeforeSend: (formData) => {
           console.log('Processing form data:', formData);
       },
       redirectUrl: '/dashboard'
    });

    Cookie Management

    eo.setCookie

    eo.setCookie Sets a cookie with a specified key, value, and expiration date in days.

    Features

  • Easy Cookie Management: Allows setting cookies with a specified key, value, and expiration date.

  • Customizable Expiration: Supports setting cookie expiration in days.
  • Universal Path: Sets the cookie's path to the root ("/") for universal accessibility across the entire site.

    Parameters:

    ParametersTypeDescription
    keystringThe name of the cookie to be set.
    valuestringThe value to be stored in the cookie.
    daysnumberThe number of days until the cookie expires.

    Returns

    void This function does not return anything.

    Example Usage

    eo.setCookie('username', 'JohnDoe', 7); // Sets a cookie "username" with value "JohnDoe" that expires in 7 days
    eo.setCookie('sessionToken', 'abc123', 1); // Sets a cookie "sessionToken" with value "abc123" that expires in 1 day

    eo.getCookie

    eo.getCookie(key) Retrieves the value of a specified cookie by its key.

    Features

  • Easy Cookie Retrieval: Allows retrieving the value of a specified cookie by its key.

  • Trim and Find: Efficiently trims and searches through cookies to find the desired key.
  • Default Value: Returns an empty string if the cookie is not found.

    Parameters

    ParametersTypeDescription
    keystringThe name of the cookie to retrieve.

    Returns

    string The value of the cookie if found, otherwise an empty string.

    Example Usage

    const username = eo.getCookie('username'); // Retrieves the value of the "username" cookie
    console.log('Username:', username);
    
    const sessionToken = eo.getCookie('sessionToken'); // Retrieves the value of the "sessionToken" cookie
    console.log('Session Token:', sessionToken);

    UI Components

    eo.modal

    The eo.modal provides an easy way to create and manage Bootstrap modals dynamically. It supports custom modal sizes, dynamic content injection, and automatic cleanup of destroyable modals.

    Features

  • Dynamically create modals with custom sizes.

  • Inject content into the modal using a callback function.
  • Support for modals with status indicators.
  • Automatic destruction of modals when closed (if enabled).
  • Handles modal close events properly.

    Notes

  • Ensure Bootstrap is loaded for this to function properly.

  • The callback function should return a valid HTML string or a DOM element.
  • Destroyable modals are automatically removed from the DOM upon closing.

    Method

  1. create({ id, size, callback, status = false, destroyable = true })

    Creates and displays a Bootstrap modal.

    Parameters | Parameter | Type | Default | Description | | --- | --- | --- | --- | | id | String | required | The unique ID of the modal. | | size | String | required | Modal size (xs, sm, md, lg, xl, fullscreen). | | callback | Function | optional | A function returning the modal content (HTML string or DOM element). | | status | Boolean | optional, default: false | If true, adds a status indicator inside the modal. | | destroyable | Boolean | optional, default: true | If true, the modal will be removed from the DOM after closing. |

    Example Usage

    eo.modal.create({
      id: 'exampleModal',
      size: 'md',
      callback: () => '<p>This is a dynamic modal!</p>',
      status: 'success',
      destroyable: true
    });

    eo.alert

    To use the eo.alert, ensure the necessary HTML structure includes a container for displaying alerts.

    Required HTML Structure

    <div class="response"></div>

    This will act as the default container for displaying alerts and loaders.

    Methods

  2. success(message, element) and error(message, element)

    Displays a success alert. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | message | String | required | The success message. | | element | String | optional, default: '.response' | The container where the alert will be displayed. |

    Example Usage

    eo.alert.success('Operation completed successfully!');
    eo.alert.error('An error occurred while processing your request.');
  3. loader(message, element)

    Displays a processing loader with a message. | Parameter | Type | Default | Description | | --- | --- | --- | --- | | message | String | optional, default: 'Processing, Please wait...' | The success message. | | element | String | optional, default: '.response' | The container where the alert will be displayed. |

    Example Usage

    eo.alert.loader();
    eo.alert.loader('Uploading file, please wait...');

    eo.button

    The eo.button provides utility functions to enable or disable buttons (or any clickable elements) dynamically. It ensures a smooth user experience by preventing interactions when necessary (e.g., during form submission or loading states).

    Methods

  4. disable(selector = '.btn')

    Disables all buttons (or specified elements) by:

    • Changing the cursor to "wait".
    • Disabling pointer events.
    • Reducing opacity to indicate inactivity.
    • Disabling the button element.

    Parameters | Parameter | Type | Default | Description | | --- | --- | --- | --- | | selector | String | optional defaults: '.btn' | The CSS selector of the elements to disable.| Example Usage

    eo.button.disable(); // Disables all buttons with class '.btn'
    eo.button.disable('.custom-button'); // Disables elements with class '.custom-button'
  5. enable(selector = '.btn')

    Re-enables previously disabled buttons (or elements) by:

    • Resetting the cursor to default.
    • Restoring pointer events.
    • Restoring opacity.
    • Enabling the button element.

      Parameters | Parameter | Type | Default | Description | | --- | --- | --- | --- | | selector | String | optional defaults: '.btn' | The CSS selector of the elements to enable.|

      Example Usage

      eo.button.enable(); // Enables all buttons with class '.btn'
      eo.button.enable('.custom-button'); // Enables elements with class '.custom-button'

    eo.uploader

    The eo.uploader provides an easy-to-use interface for uploading images and documents with preview functionality. It supports both single and multiple file uploads, customizable options, and callback hooks for different stages of the upload process.

    Features

  • Supports image and document uploads.
  • Provides preview functionality for uploaded files.
  • Supports single and multiple file uploads.
  • Customizable options for upload type, file acceptance, and event callbacks.
  • Automatically handles UI creation and event binding.
  • Sequential upload
  • File removal support

    Note
    You can use a csrf-token in meta tag. please read eo.CSRFToken once implemented it will automatically added in FormData.

    <meta name="csrf-token" content="{{ csrf_token() }}">

    Setup

    Required HTML Structure: Container for the response.

    <div class="response"></div>

    Container for the upload button.

    <div class="upload-container"></div>

    Initializes the uploader with specified configuration and attaches necessary event listeners.

    eo.uploader.create('.upload-container', '/upload-url', {
       inputName: 'eoFileUpload',
       previewSelector: '.uploaded-photo',
       multiple: true,
       onBeforeSend: () => { console.log('Before sending the request'); },
       onSuccess: (response, files) => {
           console.log('Upload successful!', response, files);
           // Manipulate hidden input value, e.g., add a URL property
           file.url = response.url; // Assuming response contains URLs for each file
       },
       onError: (error) => { console.error('Upload failed!', error); }
    });

    Parameters

    ParametersTypeDefaultDescription
    uploadSelectorStringrequiredCSS selector for the upload container.
    urlStringrequiredThe endpoint URL where the files will be uploaded.
    optionsObjectoptionalConfiguration options for the uploader.

    Options | Parameter | Type | Default | Description | | --- | --- | --- | --- | | inputName | String | eoFileUpload | The input name. | | previewSelector | String | .uploaded-photo | CSS selector for the preview container. | | disablePreview | Boolean | false | Whether to disable the preview functionality. | | uploadType | String | image | Type of upload (image or document). | | accept | String | image/* for images and application/pdf for documents | File types to accept. | | multiple | Boolean | true | Whether to allow multiple file uploads. | | onBeforeSend | Function | optional | Callback function before the upload request is sent. | | onSuccess | Function | optional | Callback function on successful upload. | | onError | Function | optional | Callback function on upload error. | | onFileRemove | Function | optional | Callback function when file was removed. |

    onSuccess Example: Executed when the upload is successful.

    onSuccess: (response, files) => {
        // Manipulate hidden input value
       file.url = response.url; // Assuming response contains URLs for each file
    }

    onBeforeSend Example Triggered before the file upload starts. Returning false cancels the upload.

    onBeforeSend: () => {
       console.log('Preparing file for upload');
       return true;
    }

    onError Example Executed when the upload fails.

    onError: (error) => {
       console.error('Upload failed:', error);
    }

    onFileRemove Example Executed when a file is removed.

    onFileRemove: (removeBtn) => {
       const filename = btn.getAttribute('data-name');
       console.log(`File ${filename} removed`);
    }
  1. onSuccess Callback: This function is called when the upload is successful.
  2. Updating File Properties

    • Inside the loop, a new property url is added to each file object.
    • The url property is assigned a value (e.g., 'https://your-assigned-url-from-server-response.com').
    • This URL can be dynamically assigned based on your requirements.

    Hidden Input Creation The uploader module automatically creates hidden inputs for each file property (name, size, type, lastModified, etc.).

    Image-Specific Properties If the upload type is image, the module also creates hidden inputs for the image's width and height. By using the onSuccess callback, you can dynamically manipulate the files array and update properties based on your requirements. This ensures that you have full control over the file objects after a successful upload.

    disablePreview if disablePreview is true, then the eo.uploader won't create the upload preview where the hidden input will be added. To create your own upload preview use the onSuccess callback to manipulate the DOM.

    Comprehensive Guide

    First Scenario
    In this scenario, you upload an image, process it, move it to a temporary folder, and return the image data in JSON format. Upon a successful response, hidden input fields are dynamically created based on the server’s response. Finally, submit your form to save the image data to the database.

  3. Create a <form> Tag:

    <form id="uploadForm" action="/submit-form-url" method="post">
        <div class="response"></div>
        <div class="upload-container"></div>
        <button type="submit">Submit</button>
    </form>
  4. Initialize the Uploader:

    eo.uploader.create('.upload-container', '/upload-file-url', {
       inputName: 'eoFileUpload',
       multiple: true,
       onBeforeSend: () => { console.log('Before sending the request'); },
       onSuccess: (response, files) => {
           files.forEach((file, index) => {
               // Manipulate hidden input value
              file.url = response[index].url; // Assuming response contains URLs for each file
           });
    			 return files;
       },
       onError: (error) => { console.error('Upload failed!', error); },
       onFileRemove: function (btn) {
    				const filename = btn.getAttribute('data-name');
    				const container = document.querySelector(btn.getAttribute('data-container'));
    				const url = `${DOMAIN}/images/${filename}/delete`;
    			
          // find if an error has occured
          // the p element is the container of the error message
    				if (!container.querySelector('p')) { 
    					eo.post(url, {
    						filename: filename,
    						'csrf_token': eo.CSRFToken
    					}, {
    						onSuccess: function (response) {
    							console.log(response);
    							eo.alert.success(response.message);
    						}
    					});
    				}
    			}
    });
  5. Uploader Creates a Form: The uploader will create a form inside the <body> tag and handle file selection and submission.

  6. Access the File on the Server Side:

    // upload.php
    header('Content-Type: application/json; charset=utf-8');
    if ($_SERVER['REQUEST_METHOD'] === 'POST') {
       // if multiple file upload was used, the $_FILES array has a different structure,
       // so you need first to re-structure it so it can be looped through
       $files = array(); 
       foreach ($_FILES['eoFileUpload'] as $k => $l) {
          foreach ($l as $i => $v) {
             if (!array_key_exists($i, $files)) $files[$i] = array();
             $files[$i][$k] = $v;
          }
       }
       foreach ($files as $key => $file) {
          // Move file to the desired folder
          $file_data['name'] = basename($file[$key]['name']);
          $file_data['url'] = "https://your-domain.com/images/" . $file_data['name'];
          move_uploaded_file($file[$key]['tmp_name'], '/temporary/' . $file_data['name']);
       }
       echo json_encode($file_data);
       /**
        * for single upload
        * Example: move_uploaded_file($_FILES['eoFileUpload']['tmp_name'], '/temporary/' . $file_data['name']);
       */
    }
  7. Manipulate Hidden Input Values Based on Response:

    onSuccess: (response, files) => {
       console.log('Upload successful!', response, files);
       // Access and manipulate the hidden input values based on the response
       // Example: add URL property
       file.url = response.url; // Assuming response contains URLs for each file
       // Example: update NAME property
       file.name = response.name; // Assuming response contains Name for each file
       file.lastModifiedDate = eo.epochToTimeString((file.lastModified / 1000)); // Assuming response contains Name for each file
    }

    Created hidden input after successful upload.

    <input type="hidden" name="upload[4CN44n6AAtK][name]" value="example.jpg">
    <input type="hidden" name="upload[4CN44n6AAtK][size]" value="102400">
    <input type="hidden" name="upload[4CN44n6AAtK][type]" value="image/jpeg">
    <input type="hidden" name="upload[4CN44n6AAtK][lastModified]" value="1633024800000">
    <input type="hidden" name="upload[4CN44n6AAtK][width]" value="800">
    <input type="hidden" name="upload[4CN44n6AAtK][height]" value="600">
    <input type="hidden" name="upload[4CN44n6AAtK][url]" value="https://your-assigned-url-from-server-response.com">
    <input type="hidden" name="upload[4CN44n6AAtK][lastModifiedDate]" value="Friday, October 1, 2021 2:00:00 AM">
  8. Submit Your Form

  9. Access the Hidden Input on the Server Side: After submitting the form, the hidden inputs created by the uploader module can be accessed on the server side using $_POST['upload'].

    // save_image_data.php
    if ($_SERVER['REQUEST_METHOD'] === 'POST') {
        // Loop through each uploaded file's information
        foreach ($_POST['upload'] as $file_id => $file_info) {
            $name = $file_info['name'];
            $size = $file_info['size'];
            $type = $file_info['type'];
            $lastModified = $file_info['lastModified'];
            $width = isset($file_info['width']) ? $file_info['width'] : null;
            $height = isset($file_info['height']) ? $file_info['height'] : null;
    
            // Process the file information as needed
            echo "File ID: $file_id\n";
            echo "Name: $name\n";
            echo "Size: $size bytes\n";
            echo "Type: $type\n";
            echo "Last Modified: " . date('Y-m-d H:i:s', $lastModified / 1000) . "\n";
            echo "Width: $width px\n";
            echo "Height: $height px\n";
        }
    }

    Second Scenario
    In this scenario, you upload an image, process its data, move the image to a directory, and save it in the database.

  10. Include Required HTML Tags:

    <div class="response"></div>
    <div class="upload-container"></div>
  11. Initialize the Uploader:

    eo.uploader.create('.upload-container', '/upload-file-url', {
       inputName: 'eoFileUpload', // give the input file a name
       multiple: true,
       onBeforeSend: () => { console.log('Before sending the request'); },
       onError: (error) => { console.error('Upload failed!', error); }
    });
  12. Uploader Creates a Form: The uploader will create a form inside the <body> tag and handle file selection and submission.

  13. Access the File on the Server Side:

    // upload.php
    if ($_SERVER['REQUEST_METHOD'] === 'POST') {
       // if multiple file upload was used, the $_FILES array has a different structure,
       // so you need first to re-structure it so it can be looped through
       $files = array(); 
       foreach ($_FILES['eoFileUpload'] as $k => $l) {
          foreach ($l as $i => $v) {
             if (!array_key_exists($i, $files)) $files[$i] = array();
             $files[$i][$k] = $v;
          }
       }
       foreach ($files as $key => $file) {
          // Move file to the desired folder and save in the Database
          $file_data['name'] = basename($file[$key]['name']);
          $file_data['url'] = "https://your-domain.com/images/" . $file_data['name'];
          $file_data['size'] = $file[$key]['size'];
          move_uploaded_file($file[$key]['tmp_name'], '/upload/' . $file_data['name']);
          // INSERT into Database 
       }
       /**
        * for single upload
        * Example: move_uploaded_file($_FILES['eoFileUpload']['tmp_name'], '/upload/' . $file_data['name']);
       */
    }

    eo.video

    The Video Component is for managing YouTube videos within a web interface. It provides functionalities to:

  • Add a YouTube video by URL.
  • Play the video in a modal.
  • Remove added videos.
  • Create a hidden input dynamically.

    • id, url, embed, thumbnail, and created_at

    Parameters

    ParametersTypeDescription
    onBeforeSendFunctionCallback function executed before processing the URL. It can return false to stop the process or a Promise that resolves to true (to proceed) or false (to stop).
    onSuccessFunctionCallback function executed when the video is added successfully.
    onPlaybackFunctionCallback function executed after the video displayed
    onRemoveFunctionCallback function executed after the video remove

    Usage

    Call eo.video.init() before the page loads.

    window.addEventListener('load', () => {
       eo.video.init({
          onBeforeSend: (data) => console.log(data),
          onSuccess: (data) => console.log(data),
          onPlayback: (data) => console.log(data),
          onRemove: (id) => console.log(id)
       });
    });

    Required HTML Structure

    To integrate the video module, add the following HTML elements:

    <div class="response"></div>
    <div id="videoInput"></div>
    <div class="video-list-container"></div>
  • Description
    • .response - Displays messages after adding a video.
    • #videoInput - The container where the input field and add button will be appended.
    • .video-list-container - The section where added videos will be listed.
    • Clicking on an added video will play it in a fullscreen modal.