DomWizard is a library designed to simplify the manipulation of DOM elements, offering features for creating, updating, reading, and deleting elements in an accessible and engaging manner. It also facilitates CSS styling and style manipulation, making it a user-friendly tool for web developers.
-
Effortless DOM Manipulation: DomWizard empowers developers with the ability to effortlessly create, modify, read, and remove DOM elements. Its intuitive functions make working with the DOM a breeze.
-
Seamless CSS Styling: DomWizard provides a straightforward approach to adding and manipulating CSS styles in JavaScript.
-
Lightweight Routing: Ideal for small applications, DomWizard offers a simple routing solution. It enables users to switch between multiple pages without the need for page reloading or managing multiple HTML files.
-
Global Variable Store (Experimental): While still in the experimental phase, DomWizard introduces a global store. This feature allows for the storage and accessibility of global variables throughout your application, enhancing data management.
-
Quick App Setup: DomWizard's 'create-app' tool simplifies the application setup process by leveraging Webpack. Say goodbye to complex configurations and dive straight into development.
DomWizard caters to small JavaScript projects seeking an efficient and straightforward way to handle CSS and DOM elements. It's the perfect choice for developers looking to enhance their productivity without the overhead of a complex framework.
- domManager Module
- cssManager Module
- router Module
- store Module (Experimental)
The domManager
module offers functionalities for creating, updating, reading, and deleting DOM elements. Central to this module is the create
function, designed to streamline the creation and manipulation of HTML elements within the DOM.
The create
function generates an HTML element based on the provided element
object and appends it to a specified parent element or replaces existing content in the parent.
-
element
(Object
): An object providing information about the element to be created. It should have the following properties:tagName
(string
): Specifies the type of HTML element to create. The default value isdiv
because it is commonly used.children
(Array
): An array of child elements to be appended to the created element.options
(Object
): Additional options for configuring the element (e.g.,classList
,id
,link
,onclick
).before
(function
): Function to be invoked before the element is appended to the page.after
(function
): Function to be invoked after the element is appended to the page.
-
selector
(string
, optional): Selector of the parent to append the newly created element into. If not provided, it defaults to'#root'
. -
append
(boolean
, optional): Indicates whether to append the new element as a child or replace existing content in the parent. Default isfalse
.
-
Element Creation (
_createElement
): This helper function creates an HTML element based on theelement
object provided. It first checks if thetagName
is provided, throwing an error if not. It then usesdocument.createElement
to create the element and sets any additional properties specified in theoptions
object, such asclassList
orid
. -
DOM Tree Construction (
_createDOMTree
): This helper function recursively constructs a DOM tree by iterating through the providedelement
and its children. It uses_createElement
to create the HTML elements and build the tree structure. -
Appending the Element (
create
): Thecreate
function utilizes_createDOMTree
to create the HTML element. It then selects the parent element using the providedselector
or the default#root
. Depending on theappend
parameter, it appends the element as a child or replaces the parent's content.
import { domManager } from 'dom-wizard';
const simpleElement = {
tagName: 'div',
options: {
id: 'myDiv',
classList: ['box'],
},
};
domManager.create(simpleElement);
In this example, a div
element with the specified id
and classList
is created and appended to the default parent, #root
.
import { domManager } from 'dom-wizard';
const childElement = {
tagName: 'span',
children: [
{
tagName: 'p',
option: {
innerHTML: 'This is a child element.',
},
},
],
};
domManager.create(childElement, '#parentDiv');
Here, a span
element is appended to a specific parent with the selector #parentDiv
.
The create
function significantly simplifies DOM manipulation. By encapsulating the creation and appending of elements, it promotes code reusability and allows for dynamic content generation within web applications. This enhances development efficiency, making it a valuable tool for front-end developers.
Certainly! Let's create detailed documentation for the read
function within the domManager
module.
The read
function retrieves information from the DOM based on the provided selector and property name.
-
selector (
string
): The CSS selector to query the DOM and identify the element(s). -
propertyName (
string
) [Optional]: The property name to retrieve from the selected element(s). Defaults toundefined
. -
all (
boolean
) [Optional]: Iftrue
, retrieves the property from all matching elements; otherwise, retrieves from the first matching element. Defaults tofalse
.
- Throws an error if retrieving the element was not possible or if the selector didn't match any elements.
-
If
all
istrue
andpropertyName
is provided, an array of property values from all matching elements. -
If
propertyName
is provided, the property value from the first matching element. -
If
propertyName
is not specified, andall
is set totrue
, a NodeList or an array containing all elements with the specified selector.
-
Retrieve a Property from a Single Element:
const result = domManager.read('.example-element', 'innerText'); // Retrieves the 'innerText' property of the first element matching the selector '.example-element'
-
Retrieve All Elements Matching the Selector:
const elements = domManager.read('.example-elements', undefined, true); // Retrieves all elements matching the selector '.example-elements'
-
Retrieve an Attribute from All Elements Matching the Selector:
const attributeValues = domManager.read( '.example-elements', 'data-custom', true, ); // Retrieves an array of 'data-custom' attribute values from all elements matching the selector '.example-elements'
-
Retrieve an Array of All Elements Matching the Selector:
const allElements = domManager.read('.example-elements', undefined, true); // Retrieves a NodeList or array of all elements matching the selector '.example-elements'
-
Retrieving text content from multiple elements sharing the same class.
-
Fetching attributes (e.g.,
data-*
) from a group of elements for further processing. -
Collecting values from a group of form elements (e.g., all input fields within a specific container).
The read
function provides flexibility in querying the DOM and fetching relevant information based on specified criteria, making it a powerful tool for data extraction in various scenarios.
The remove
function removes elements from the DOM based on the provided selector.
-
selector (
string
): The CSS selector to target elements for removal. -
all (
boolean
) [Optional]: Iftrue
, removes all matching elements; otherwise, removes the first matching element. Defaults tofalse
.
- Throws an error if the selector doesn't match any elements or if removal fails.
- If
all
istrue
, an array of removed elements; otherwise, the removed element.
The remove
function uses the provided selector to query the DOM for elements. If all
is true
, it uses querySelectorAll
to retrieve all matching elements; otherwise, it uses querySelector
to retrieve the first matching element. It then removes the selected element(s) from the DOM.
-
Removing specific UI components based on their identifiers or classes.
-
Clearing out temporary or dynamically created elements.
-
Implementing a feature to remove multiple items at once (e.g., in a list).
-
Remove a Single Element:
domManager.remove('.example-element'); // Removes the first element matching the selector '.example-element'
-
Remove All Elements Matching the Selector:
domManager.remove('.example-elements', true); // Removes all elements matching the selector '.example-elements'
The remove
function provides a straightforward way to remove elements from the DOM based on specified criteria. This is essential for keeping the DOM updated and tidy, especially in complex web applications where elements might need to be dynamically added or removed based on user interactions or other events. The ability to remove specific elements or a group of elements enhances the flexibility and user experience of web applications, making the remove
function a valuable utility for managing the DOM effectively.
The update()
function is a versatile tool for modifying information and attributes of elements within the DOM. It supports actions such as toggling class names, adding classes to the classList, updating IDs, and modifying specific attributes.
-
instr
(Object) - Instructions for updating elements, including what to update and how. Theinstr
object should always containselector
andaction
as required properties. Here's an example of aninstr
object:{ selector: ".content > div", action: "update", innerHTML: "<p>New Text</p>" }
-
Supported actions are:
toggle
,replace
,replaceAll
,update
,add
,remove
,style
,addChildren
,removeChildren
, andnewChildren
. Each action has its own required properties.
- Throws an error when
selector
and/oraction
are missing. - Throws an error when the specified element is not found in the DOM.
The toggle
action toggles a class in the classList
of the provided element. It exclusively works with the class
attribute and requires the className
property.
domManager.update({
selector: '.content > div',
action: 'toggle',
className: 'active',
});
The replace
action replaces a specific attribute in the provided element. It requires the properties attribute
, new
, and old
. If the specified attribute doesn't support replace
, an error is raised.
domManager.update({
selector: '.content > div',
action: 'replace',
attribute: 'classList',
old: 'start',
new: 'stop',
});
The replaceAll
action is similar to replace
, but it replaces all occurrences of a specific value within the provided element.
domManager.update({
selector: '.content > div',
action: 'replaceAll',
attribute: 'textContent',
old: 'e',
new: '#',
});
The update
action allows you to modify the element's properties and attributes. It can also update the children of the specified element.
domManager.update({
selector: '.content > div',
action: 'update',
id: 'new-id',
textContent: 'New Text',
});
The add
and remove
actions add and remove data, respectively, from the specified element. Both require the attribute
and value
properties. An error is thrown if the specified attribute
doesn't support add
or remove
.
The style
action is used to update styles of the specified element.
domManager.update({
selector: '.content > div',
action: 'style',
backgroundColor: 'red',
padding: '20px',
});
The addChildren
action is used to add new children to the element.
import navigation from './components';
import main from './components';
domManager.update({
selector: '.content > div',
action: 'addChildren',
children: [navigation, main],
});
The removeChild
removes children from an element based on a predicate function.
domManager.update({
selector: '.content > div',
action: 'removeChildren',
predicate: (element) => {
return element.dataset.id === 'dfu8-x';
},
});
The updateChild
updates children of an element, replacing the existing children.
import navigation from './components';
import main from './components';
domManager.update({
selector: '.content > div',
action: 'updateChildren',
children: [navigation, main],
});
The update
function simplifies DOM element updates, streamlining the implementation and error handling process. It saves time and reduces the need for repetitive code, as it eliminates the hassle of manually fetching elements and performing updates.
The cssManager module facilitates the creation and application of CSS styles to elements. It's important to note that this module isn't intended to replace traditional CSS, but rather to provide an API for efficiently adding CSS rules to elements using JavaScript when it's the most suitable approach.
The addRule
function adds a CSS rule to the stylesheet.
Parameter
rule
(Object): An object representing the CSS rule to be added. It consists of a selector as the key and a declaration as the value. The declaration can include complex CSS properties, states, and media queries. Here are some examples:
-
Simple selector:
{ 'body': 'background-color: yellow' }
-
Selector with a state:
{ 'button:hover': 'background-color: #0f0' }
-
Multiple declarations in the value:
{ 'button': ` border-radius: 20px; background: yellowgreen; padding: 10px 20px; ` }
-
Using media queries:
{ '@media screen and (min-width: 480px)': ` button { background-color: blue; } ` }
The addRule
function utilizes the CSSStyleSheet
web API to add and manage CSS rules.
The createCSSRules
function adds an array of styles to the page by using the addRule
function.
Parameter
rules
(Array): An array of objects, where each object represents a CSS rule to be added. The format of these objects is explained in theaddRule
documentation.
Usage
You can use the createCSSRules
function as follows:
cssManager.createCSSRules([
{
'@media screen and (min-width: 480px)': `
body {
background-color: blue;
}
`,
},
{
body: `
min-height: 100vh;
background-color: red;
`,
},
]);
The removeRule
function removes a CSS rule by its index. This function ensures that the index is a number before attempting removal.
index
(Number): The index of the CSS rule to be removed. This should be a number. Ifindex
is not a number, an error will be thrown to prevent incorrect removal. You can obtain the index from the return value ofaddRule
or by keeping track of the indexes when usingcreateCSSRules
.
Here's an example of how to use the removeRule
function to remove a CSS rule by its index:
const ruleIndex = cssManager.addRule({ body: 'background-color: red' });
// Use the index to remove the rule:
cssManager.removeRule(ruleIndex);
Note: Every time a style is added using addRule
or createCSSRules
, it is added as the last index of cssRules
. The index is equivalent to stylesheet.cssRules.length
.
The router
module handles route registration and link configuration, allowing for navigation within a web application.
Register routes for navigation within the application.
routes
(Array): An array containing route information objects. Each route object must have the following properties:id
(String): A unique identifier for the route.route
(Object): An object to be used bydomManager.create()
to construct the DOM of the new route/page.
Example:
[
{ id: 'home', route: home },
{ id: 'about', route: about },
{ id: 'contact', route: contact },
];
After validation, the function adds each route to the internal _pages
array.
The register
function performs the following error checks:
- It can only be invoked once throughout the application.
- The
routes
parameter must be an array. - Each item in the
routes
array must be an object with key-value pairs. - Each item in the
routes
array must have the required 'id' and 'route' keys. - No two routes are allowed to share the same 'id'.
Configure an HTML element to act as a link for navigation.
linkInfo
(Object): An object containing specific information about the link element. It should have the following properties:name
(String): The name of the link.to
(String): The ID of the page to which the link will navigate.element
(HTMLElement): The HTML element to attach a click event listener to.host
(String, optional): A selector specifying where the content should be rendered. If not provided, it defaults to#root
.
The to
property must correspond to a valid route ID within the _pages
array. If the constraints are not met, the function throws an error.
The configureLink
function adds an event listener to the specified element. When triggered, the linked content will be displayed in the page at the specified container using domManager
.
The function is useful in conjunction with domManager
and allows developers to manually configure links within the app. It also adds the 'active' class to the clicked element, making it easier to style active links.
The store
module serves as a central storage mechanism for variables accessible throughout the app. Users can retrieve and modify these variables from anywhere within the application. It's important to note that the store
is not designed for server-side purposes; its primary function is to facilitate the use of shared variables across different app files. However, please be aware that all data stored in the store
is temporary and gets reset when the app stops running.
The createStore
function initializes the store by accepting an object with key-value pairs. It can be invoked only once to maintain organization within the store and enable users to easily manage all variables stored within it.
store.createStore({
userID: 'fd4rew34_dfr4',
username: 'therealjohndoe',
profileUpdated: false,
profileImg: undefined,
});
The getState
function retrieves the value associated with a specified key in the store.
const username = store.getState('username');
The updateState
function allows you to modify the value associated with a specific key in the store. If the key doesn't exist, an error is thrown.
store.updateStore('username', 'justJohn');