@blockquote-web-components/ajax-provider

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

Name	Module	Package
AjaxProviderMixin	/src/AjaxProviderMixin.js

Fields

Name	Privacy	Type	Default	Description	Inherited From
dispatchEventContext		Object	this	The context for dispatching events.
lastResponse		Object|undefined	undefined	The last AJAX response object.
lastError		Object|undefined	undefined	The last error object.
customEventPrefix		string	'ajax'	A custom event prefix for events related to HTTP requests.
avoidBoundary		boolean	false	Set to `true` to stop delegating the use of boundaries for multipart requests to the browser. Only change this to `true` if you know what you are doing.
url		string	''	The base URL for the AJAX request.	AjaxProviderMixin
path		string	''	The path to append to the base URL.	AjaxProviderMixin
body		*	undefined	The request body.	AjaxProviderMixin
async		boolean	true	Whether or not to send the request asynchronously.	AjaxProviderMixin
method		string	'GET'	The HTTP request method (e.g., GET, POST).	AjaxProviderMixin
_headers		Object	{ Accept: 'application/json, text/plain, */*; q=0.01', 'Content-Type': 'application/json', }	The default headers for the request.	AjaxProviderMixin
headers		Object|undefined	undefined	Custom headers for the request.	AjaxProviderMixin
timeout		number	0	The request timeout in milliseconds.	AjaxProviderMixin
user		string	''	The user for authentication.	AjaxProviderMixin
password		string	''	The password for authentication.	AjaxProviderMixin
withCredentials		boolean	false	Indicates whether to include credentials with the request.	AjaxProviderMixin
xsrfCookieName		string	''	The name of the XSRF cookie.	AjaxProviderMixin
xsrfHeaderName		string	''	The name of the XSRF header.	AjaxProviderMixin
responseType		string	''	The response type (e.g., 'json', 'text').	AjaxProviderMixin
queryParams		Object|undefined	undefined	The query parameters to include in the request URL.	AjaxProviderMixin
includeDownloadProgress		boolean	false	Indicates whether to include download progress in the response.	AjaxProviderMixin
includeUploadProgress		boolean	false	Indicates whether to include upload progress in the response.	AjaxProviderMixin

Methods

Name	Privacy	Description	Parameters	Return	Inherited From
_assignAjaxProviderConfig		Assigns configuration options to the AjaxProvider instance.	config: Object
generateRequest		Generates and sends the AJAX request.		Promise<any>	AjaxProviderMixin

Private API

Methods

Name	Privacy	Description	Parameters	Return	Inherited From
_assignAjaxRxjsConfig	private	Assigns the configuration settings for the AJAX request.		Object	AjaxProviderMixin
_joinUrlData	private	Joins the base URL and path to create the complete request URL.		string	AjaxProviderMixin
_joinHeaders	private	Joins the default headers with custom headers.	formData	Object	AjaxProviderMixin
_dispatchEvent	private	Dispatches a custom event with the specified type and payload.	type: string, payload: *		AjaxProviderMixin

---

Exports

Kind	Name	Declaration	Module	Package
js	AjaxProvider	AjaxProvider	src/AjaxProvider.js

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

src/AjaxProviderMixin.js:

mixin: AjaxProviderMixin

Mixins

Name	Module	Package
dedupeMixin		@open-wc/dedupe-mixin

Parameters

Name	Type	Default	Description
Base

Fields

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

Methods

Name	Privacy	Description	Parameters	Return	Inherited From
generateRequest		Generates and sends the AJAX request.		Promise<any>

Private API

Methods

Name	Privacy	Description	Parameters	Return	Inherited From
_assignAjaxRxjsConfig	private	Assigns the configuration settings for the AJAX request.		Object
_joinUrlData	private	Joins the base URL and path to create the complete request URL.		string
_joinHeaders	private	Joins the default headers with custom headers.	formData	Object
_dispatchEvent	private	Dispatches a custom event with the specified type and payload.	type: string, payload: *

---

Exports

Kind	Name	Declaration	Module	Package
js	AjaxProviderMixin	AjaxProviderMixin	src/AjaxProviderMixin.js

src/index.js:

Exports

Kind	Name	Declaration	Module	Package
js	AjaxProvider	AjaxProvider	./AjaxProvider.js
js	AjaxProviderMixin	AjaxProviderMixin	./AjaxProviderMixin.js

src/utils.js:

Variables

Name	Description	Type
isStandardBrowserEnv	Determines if the code is running in a standard browser environment. This function checks for specific conditions that indicate whether the code is running in a standard browser environment, allowing Axios to work in various environments like web workers, React Native, or NativeScript.
isStandardBrowserWebWorkerEnv	Determines if the code is running in a standard browser WebWorker environment. This function checks for specific conditions that indicate whether the code is running in a standard browser WebWorker environment. It takes into account the limitations of the `isStandardBrowserEnv` method when working with WebWorkers.

---

Functions

Name	Description	Parameters	Return
isFormData	Determine if a value is a FormData	thing: *	boolean
assignIfDefined	Utility function to assign a property to an object if the value is defined.	obj: Object, prop: string, value: *

---

Exports

Kind	Name	Declaration	Module	Package
js	isStandardBrowserEnv	isStandardBrowserEnv	src/utils.js
js	isStandardBrowserWebWorkerEnv	isStandardBrowserWebWorkerEnv	src/utils.js
js	isFormData	isFormData	src/utils.js
js	assignIfDefined	assignIfDefined	src/utils.js