@blockquote-web-components/ajax-provider v1.3.0

AJAX Provider Documentation

A class that provides AJAX functionality with event handling capabilities.

Table of Contents

• Introduction
• Installation
• Usage
  • Creating an Instance
  • Configuring AJAX Requests
  • Sending AJAX Requests
  • Event Handling
• API Reference

Introduction

The AJAX Provider is a JavaScript class that provides AJAX functionality with event handling capabilities through EventTarget. It uses the AjaxProviderMixin, a mixin that leverages RxJS to manage AJAX requests efficiently.

Installation

To use the AJAX Provider, you need to install it as a package dependency.

npm install @blockquote-web-components/ajax-provider

Demo

Usage

Creating an Instance

To use the AJAX Provider, first, create an instance of the AjaxProvider class.

import { AjaxProvider } from '@blockquote-web-components/ajax-provider';

// A basic request configuration looks like this:
const ajaxProvider = new AjaxProvider({
  url: 'https://httpbin.org/get',
});

  // Default method
  method: 'GET',

  // Default request Headers.
  headers: {
    Accept: 'application/json, text/plain, *\/*; q=0.01',
    'Content-Type': 'application/json',
  }

Configuring AJAX Requests

You can configure your AJAX request by setting various options on the ajaxProvider instance. Here are some common configuration options:

const ajaxProvider = new AjaxProvider({
  url: 'https://httpbin.org/get',
  path: method.toLowerCase(),
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'rxjs-custom-header': 'Rxjs',
  },
  body: {
    rxjs: `Hi`,
  },
  includeDownloadProgress: true,
  includeUploadProgress: true,
});

Sending AJAX Requests

Once you have configured the AJAX request, you can send it using the generateRequest method. This method returns a promise that resolves with the AJAX response or attaching event listeners to handle various stages of the AJAX request.

const ajaxProvider = new AjaxProvider({
  url: 'https://api.github.com/users',
  queryParams: 'per_page=4',
});

ajaxProvider
  .generateRequest()
  .then(response => {
    console.log('Response:', response.response);
  })
  .catch(error => {
    console.log('Error:', error.message);
  });

Event Handling

The AJAX Provider allows you to handle events related to HTTP requests. You can listen to events such as:

• 'presend' --> 'progress' --> 'response' --> 'responseend'
• 'presend' --> 'error' --> 'errorend'

Here's how to set up event listeners:

const ajaxProvider = new AjaxProvider({
  url: 'https://api.github.com/users',
  queryParams: 'per_page=3',
});

ajaxProvider.addEventListener('ajaxpresend', ({ detail }) => {
  console.log('Preparing to send request...', detail);
});

ajaxProvider.addEventListener('ajaxprogress', ({ detail }) => {
  console.log(`Progress: ${detail.loaded} of ${detail.total} bytes`);
});

ajaxProvider.addEventListener('ajaxresponse', ({ detail }) => {
  const { response } = detail;
  console.log('Received response:', response);
});

ajaxProvider.addEventListener('ajaxresponseend', ({ detail }) => {
  console.log('End request:', detail);
});

ajaxProvider.addEventListener('ajaxerror', ({ detail }) => {
  const error = detail;
  console.log('Request error:', error.message);
});

ajaxProvider.addEventListener('ajaxerrorend', ({ detail }) => {
  console.log('End error:', detail);
});

ajaxProvider.generateRequest();

API Reference

Requests can be made by passing the relevant config to AjaxProvider.

Properties

Configuration for the RxJS/ajax creation function.

• url: The base URL for the AJAX request. (string)
• body: The request body. (*)
• async: Whether or not to send the request asynchronously. (boolean)
  • Default value: true
• method: The HTTP request method (e.g., GET, POST). (string)
  • Default value: GET
• headers: Custom headers for the request. (Object|undefined)
  • Default value:
    • Accept: 'application/json, text/plain, \/; q=0.01'
    • Content-Type: 'application/json'
• timeout: The request timeout in milliseconds. (number)
  • Default value: 0
• user: The user for authentication. (string)
• password: The password for authentication. (string)
• withCredentials: Indicates whether to include credentials with the request. (boolean)
  • Default value: false
• xsrfCookieName: The name of the XSRF cookie. (string)
• xsrfHeaderName: The name of the XSRF header. (string)
• responseType: The response type (e.g., 'json', 'text'). (string)
  • Default value: json
• queryParams: The query parameters to include in the request URL. (Object|undefined)
• includeDownloadProgress: Indicates whether to include download progress in the response. (boolean)
  • Default value: false
• includeUploadProgress: Indicates whether to include upload progress in the response. (boolean)
  • Default value: false

Configuration AJAX Provider.

• path: The path to append to the base URL. (string)
• dispatchEventContext: The context for dispatching events. (AjaxProvider instance)
• lastResponse: The last AJAX response object. (Object)
• lastError: The last error object. (Object)
• customEventPrefix: A custom event prefix for events related to HTTP requests. (string)
  • Default value: ajax
• avoidBoundary: Set to true to stop delegating the use of boundaries for multipart requests to the browser. (boolean)
  • Only change this to true if you know what you are doing. Default value: false

Methods

• generateRequest(): Generates and sends the AJAX request. This method can be used both with promises and by attaching event listeners to handle various stages of the AJAX request.

src/AjaxProvider.js:

class: AjaxProvider

Mixins

Fields

Methods

Methods

Exports

Mixin for providing AJAX functionality using RxJS. This mixin can be used to enhance classes with AJAX capabilities.

src/AjaxProviderMixin.js:

mixin: AjaxProviderMixin

Mixins

Parameters

Fields

Methods

Methods

Exports

src/index.js:

Exports

src/utils.js:

Variables

Functions

Exports