Dynamic Application API

spa()

async

Navigation without reloading the page, with either full or partial content updates.

Accepts an object with the following properties:

Property

Type

Description

path

string

URL path of the new page.

spa

string

The key of the object used from the "spa" property in the "config.js" configuration file for the new page.

component

string
object

The name of a component or an object containing components dynamically used on the new page.

api

object

The object that is used by the new page to make the API request.
More details about the API object can be found in the documentation for the api() interface.

it

DOM element

A DOM element associated with navigation, which can additionally have the following attributes:

Attribute

Type

Description

data-spa-api

object

The object to be used for making the API request.
More details about the API object can be found in the documentation for the api() interface.
Example: data-spa-api="url: '/api', method: 'POST'"

data-spa-update

object
array
DOM element

An object where the keys represent the property names from the API response whose content needs to be output, and the values are the DOM elements relative to which this content should be output.
If the content is nested, dot notation can be used to access the desired content, such as "response.user.name".
An array of DOM elements, relative to which the content will be output if the request returns content immediately.
A DOM element relative to which the content will be output if the request returns content immediately.
If an attribute is null, DOM elements with "data-it" attributes will be used as placeholders for replacement. The values of these attributes should match the keys from the API response, such as "data-it="name"" or "data-it="response.user.name"".
If a <head> element is specified for content replacement, it will be automatically disassembled and reassembled to avoid visual breaks.
Existing CSS styles will remain intact and will not be duplicated, even if they are present in the replacement data.
Example: data-spa-update="body: $('#view'), target: null"

data-spa-loader

DOM element
array

The element or an array of elements that handles the loaders.
For the specified element, the aria-busy="true" attribute will be automatically set during the request and changed to aria-busy="false" once the request is complete.
To control the display of blocks, assign the necessary CSS styles to the relevant attributes.
Example: data-spa-loader="$('#loader')"

data-spa-mode

string
object
boolean

If content needs to be replaced, it must be false.
Otherwise, it must be one of the following values, indicating where the content will be output:

Argument

Description

'before'

Places the content before the matched DOM element (before the opening tag).

'after'

Places the content after the matched DOM element (after the closing tag).

'begin'

Places the content immediately after the matched DOM element's opening tag (before the first child).

'end'

Places the content right before the matched DOM element's closing tag (after the last child).

If multiple blocks change simultaneously, specifying this option as a string applies it to all blocks.
To assign a specific option to each block, use an object, e.g., {main: 'end', 'response.user.name': false}.
If this attribute is specified and not set to false, DOM elements with the "data-remove" attribute matching existing DOM elements will be removed.
This is useful for scenarios such as adding new content and removing outdated elements, like replacing old pagination with updated content.
Example: data-spa-mode="end"

data-spa-scroll

object
boolean

The object to use for scrolling.
More details on the scroll object can be found in the documentation for the toScroll() method.
To specify the DOM element that needs to be scrolled, the "it" property can be used.
If true, scrolling will be done to the top with default settings.
Example: data-spa-scroll="speed: 300, it: $('#view'), target: null"

All attributes are optional and simply override values and behavior when needed.

All properties are optional; however, the object must have either the "path" or "it" property.
When updating the URL to a similar one, it doesn't create duplicates but instead updates the data associated with the current URL.
Returns true on success; otherwise, returns false.
It is not necessary to wait for the method to be executed using await if not needed.

Example:

// Navigation is based on the underlying configuration object.
spa({path: '/page'});

// Navigation is based on the underlying configuration object with optional overrides.
spa({it: $('a[href="/page"]')});

// Performs navigation by appending additional parameters.
spa({
   path: '/page',
   spa: 'main',
   component: 'navigation',
   api: {
      url: '/api',
      method: 'POST',
      headers: false,
      body: {
         method: 'getPage',
         path: '/page'
      },
      format: 'json'
   }
});

// Waits for the method to complete its execution.
await spa({path: '/page'});

Previous waitState() Next stream()