Getting Started
Configuration
First, a basic configuration file "config.js" needs to be filled out, which can then be modified as needed.
The configuration file is an exportable object with the following supported properties:
All properties are optional.
The configuration file is an exportable object with the following supported properties:
Property
Type
Description
duration
number
The duration of basic animations, in milliseconds, specified in CSS styles.
It is used for certain dynamic elements, such as when removing a template element.
It is used for certain dynamic elements, such as when removing a template element.
init
object
An object with the following properties:
All properties are optional.
Property
Type
Description
type
string
The type of initial initialization, which can be:
"ready" – Called when the HTML document has been fully parsed.
"load" – Called after the entire page, including all dependent resources such as stylesheets, scripts, frames, and images (except for those that are lazily loaded), has fully loaded.
"ready" – Called when the HTML document has been fully parsed.
"load" – Called after the entire page, including all dependent resources such as stylesheets, scripts, frames, and images (except for those that are lazily loaded), has fully loaded.
preloader
string
array
array
A selector can be a string or an array of strings that target DOM elements managing the preloader and containing the "aria-busy="true"" attribute.
After the document loads, the "aria-busy" attribute of these elements will be updated to "false".
To control the display of the preloader, assign the necessary CSS styles to the "aria-busy="true"" and "aria-busy="false"" attributes and their corresponding elements.
Instead of explicitly defining this property, the "data-it="preloader"" attribute can be used directly.
After the document loads, the "aria-busy" attribute of these elements will be updated to "false".
To control the display of the preloader, assign the necessary CSS styles to the "aria-busy="true"" and "aria-busy="false"" attributes and their corresponding elements.
Instead of explicitly defining this property, the "data-it="preloader"" attribute can be used directly.
module
object
Specifies the modules that must be initialized immediately after loading.
The object keys represent the names of modules located in the "modules" folder.
The values are the arguments to be passed to the module, if needed.
To pass multiple values as separate arguments, use an array.
If the module does not require any data, specify null.
The object keys represent the names of modules located in the "modules" folder.
The values are the arguments to be passed to the module, if needed.
To pass multiple values as separate arguments, use an array.
If the module does not require any data, specify null.
events
object
This object defines events using keys as event names and values that determine how the events are managed.
The value for each event can be a boolean (true or false), null, or an object, with the following behaviors:
To use a global event from the "events" folder in parallel, prefix the event name with a "$", e.g., "$ready: true".
Events are automatically assigned to either the document or window based on the event type.
To explicitly specify the target scope (though typically unnecessary), append "_document" or "_window" to the event name, e.g., "click_document: true".
By default, the event's behavior is determined automatically.
To explicitly specify it (though typically unnecessary), append "_prevent" (prevents the event's default action) or "_allow" (ensures the event's default action is executed), e.g., "click_prevent: true".
Event parameters can be combined in any order, e.g., "$click_window_allow: true".
If the event value is an object, it acts as a configuration for that event.
This configuration can be overridden for specific DOM elements using "data-config-*" attributes, e.g., "data-config-visible="root: null, rootMargin: '0px 0px 250px 0px', threshold: 0"".
The value for each event can be a boolean (true or false), null, or an object, with the following behaviors:
Value
Description
true
object
object
An instance for the event is created.
The event is immediately enabled and can be dynamically managed later.
The event is immediately enabled and can be dynamically managed later.
false
An instance for the event is created.
The event remains disabled but can be dynamically managed later.
The event remains disabled but can be dynamically managed later.
null
The same behavior occurs as if the event were not included in the object at all.
No instance for the event is created.
The event is disabled and cannot be dynamically managed.
No instance for the event is created.
The event is disabled and cannot be dynamically managed.
Events are automatically assigned to either the document or window based on the event type.
To explicitly specify the target scope (though typically unnecessary), append "_document" or "_window" to the event name, e.g., "click_document: true".
By default, the event's behavior is determined automatically.
To explicitly specify it (though typically unnecessary), append "_prevent" (prevents the event's default action) or "_allow" (ensures the event's default action is executed), e.g., "click_prevent: true".
Event parameters can be combined in any order, e.g., "$click_window_allow: true".
If the event value is an object, it acts as a configuration for that event.
This configuration can be overridden for specific DOM elements using "data-config-*" attributes, e.g., "data-config-visible="root: null, rootMargin: '0px 0px 250px 0px', threshold: 0"".
api
object
The base object used for making API requests, applied when certain properties are not specified in the request.
More details about the API object can be found in the documentation for the api() interface.
More details about the API object can be found in the documentation for the api() interface.
spa
object
Object keys are custom names used for different page navigations.
The values are objects, and each object can have the following properties:
Each property corresponds to a specific page navigation, allowing the content to be changed anywhere on the page as needed.
The order in which properties are defined determines their priority.
This means that if one navigation element is nested within another, it should be defined after the navigation it belongs to.
If not defined, standard behavior will be used.
The values are objects, and each object can have the following properties:
Property
Type
Description
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.
The "body" property object allows storing variable attribute values that can be passed along with the API request.
To pass an attribute value, enclose the attribute name between "{{" and "}}" symbols, e.g., {path: '{{href}}'}.
More details about the API object can be found in the documentation for the api() interface.
The "body" property object allows storing variable attribute values that can be passed along with the API request.
To pass an attribute value, enclose the attribute name between "{{" and "}}" symbols, e.g., {path: '{{href}}'}.
update
object
string
array
string
array
An object where the keys represent the property names from the API response, whose content needs to be output, and the values are selectors (either a string or an array of strings) that target DOM elements where 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".
Selectors (either a string or an array of strings) of DOM elements, to which the content will be output if the request returns content immediately.
If a property is not specified or 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.
If the content is nested, dot notation can be used to access the desired content, such as "response.user.name".
Selectors (either a string or an array of strings) of DOM elements, to which the content will be output if the request returns content immediately.
If a property is not specified or 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.
loader
string
array
array
Selectors (either a string or an array of strings) of DOM elements that handle the loaders.
For the found DOM elements, 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.
Instead of explicitly defining this property, the "data-it="loader:spaName"" attribute can be used directly, where "spaName" is a custom name matching the "spa" property key.
For the found DOM elements, 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.
Instead of explicitly defining this property, the "data-it="loader:spaName"" attribute can be used directly, where "spaName" is a custom name matching the "spa" property key.
mode
string
object
boolean
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:
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 property 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.
The default value is 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).
To assign a specific option to each block, use an object, e.g., {main: 'end', 'response.user.name': false}.
If this property 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.
The default value is false.
scroll
object
boolean
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.
The "it" and "target" properties must contain strings that are DOM element selectors.
If true, scrolling will be done to the top with default settings.
The default value is false.
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.
The "it" and "target" properties must contain strings that are DOM element selectors.
If true, scrolling will be done to the top with default settings.
The default value is false.
The order in which properties are defined determines their priority.
This means that if one navigation element is nested within another, it should be defined after the navigation it belongs to.
If not defined, standard behavior will be used.
cache
object
An object with the following properties:
All properties are optional.
Property
Type
Description
component
number
Maximum number of cached components.
Once the limit is reached, the cache will be cleared to accommodate new components.
The recommended value is 50.
Once the limit is reached, the cache will be cleared to accommodate new components.
The recommended value is 50.
module
number
Maximum number of cached modules.
Once the limit is reached, the cache will be cleared to accommodate new modules.
The recommended value is 50.
Once the limit is reached, the cache will be cleared to accommodate new modules.
The recommended value is 50.
api
number
Maximum number of cached API request results.
Once the limit is reached, the oldest cached result will be removed.
Caching is only applied if the API request specifies a caching duration.
The recommended value is 50.
Once the limit is reached, the oldest cached result will be removed.
Caching is only applied if the API request specifies a caching duration.
The recommended value is 50.
state
number
Maximum number of cached browser history entries.
Once the limit is reached, the oldest cached entry will be removed.
This does not affect the browser's default behavior or history records.
Caching is only required for managing the history of visits related to components, modules, or within scripts.
The recommended value is 5.
Once the limit is reached, the oldest cached entry will be removed.
This does not affect the browser's default behavior or history records.
Caching is only required for managing the history of visits related to components, modules, or within scripts.
The recommended value is 5.
cacheTime
number
The cache duration for components and modules, in seconds.
The cache is cleared only if the specified time has elapsed since the last use of a particular component or module.
If not defined, the cache is stored indefinitely.
The recommended value is 300.
The cache is cleared only if the specified time has elapsed since the last use of a particular component or module.
If not defined, the cache is stored indefinitely.
The recommended value is 300.
Example of a configuration file:
export default {
duration: 200,
init: {
type: 'ready',
/*
Instead of explicitly defining this property,
the 'data-it="preloader"' attribute can be used directly.
*/
preloader: '#preloader'
/*
// Only if it is necessary to initialize modules immediately upon loading.
module: {
'myModule': null
}
*/
},
events: {
// For a global event with the '$' prefix, the 'events' folder must contain that event.
$ready: true,
click_prevent: true,
input: true,
resize: false,
visible: {
root: null,
rootMargin: '0px 0px 100px 0px',
threshold: 0
}
/*
// A rarely used event that can create unnecessary overhead if used improperly.
mutation: {
childList: true,
attributes: true,
characterData: true,
subtree: true,
attributeOldValue: true,
characterDataOldValue: true,
attributeFilter: ['class', 'id']
}
*/
},
api: {
url: '/api',
method: 'POST',
headers: false,
format: 'json'
},
spa: {
main: {
api: {
url: '/api',
method: 'POST',
headers: false,
format: 'json',
body: {
method: 'getPage',
path: '{{href}}'
}
},
// This property can be omitted, and the 'data-it' attributes can be used directly.
update: {
body: '#view',
head: 'head'
},
/*
Instead of explicitly defining this property,
the 'data-it="loader:main"' attribute can be used directly.
*/
loader: '#loader',
mode: false,
scroll: {
it: '#view',
target: null,
speed: 300,
type: 'smooth',
align: 'top',
offset: 0,
axis: 'Y'
}
}
},
cache: {
component: 50,
module: 50,
api: 50,
state: 5
},
cacheTime: 300
}