mini-framework v1.2.0

Dictionary

DOM

• createDOMElement

Routing system

• addRoute
• navigateTo
• getCurrentRoute

State management

• useStateManager

Event handling

• events
• onEvent
• triggerCustomEvent

DOCMENTATION EXAMPLE:

createDOMElement

The createDOMElement function allows you to create a DOM element with optional attributes and children.

Parmeters

• 'elementType' (string): The type of DOM element to create (e.g., 'div', 'a', 'p').
• 'attributes' (object): An object containing element attributes as key-value pairs.
• 'children' (Array): An array of child elements or text to be appended to the created element.

Returns

• ElementObject: An object representing a DOM element with various event handling functions.

Example

// Import the createDOMElement func from the framework
import { createDOMElement } from "mini-framework";

// Create an ElementObject representing a div with a paragraph and a link inside
const newElementObject = createDOMElement('div', { class: 'my-div' }, [
  createDOMElement('p', null, ['This is a paragraph inside a div.']),
  createDOMElement('a', { href: 'https://example.com' }, ['Visit Example']),
]);

// Accessing the underlying HTML element:
const div = newElementObject.element;

Usage

1. Import the createDOMElement func from the framework
2. Create a desired element with attributes or/and add child elements.

Notes

• This function is a convenient abstraction for creating DOM elements, making it easier to work with the DOM in your JavaScript projects.
• You can append the resulting element to the document using appendChild or manipulate it further as needed.

addRoute

The addRoute function allows you to add route to a router in your application.

Parameters

• 'path' (string): This parameter represents the URL path for the route. It's a string that typically specifies the path or route that the user wants to navigate to on a website or web application. For example, if the path is "/home," it means the route is for the "home" page.
• 'callback' (function): This parameter is a callback function that will be executed when the specified route is navigated to. Callback functions are a common way to define what should happen when a particular route is visited.

Returns

• nothing

Example

// Import the Router func from the framework
import { Router } from "mini-framework";

// Instantiate the router
const myRouter = new Router();

// Add routes
myRouter.addRoute('/', function () {
    // Write code that you want to execute when calling this route
});

Usage

1. Import the Router func from the framework.

2. Create an instance of the Router to access the addRoute function.

3. Use the addRoute function to add route to a router.

Notes

• You can add multiple routes by calling addRoute multiple times with different paths and callback functions.
• When a user navigates to a route you've added, the associated callback function will be executed.

navigateTo

The navigateTo function allows you to execute associated to a route callback function.

Parameters

• 'path' (string): This parameter represents the URL path for the route. It is a string that typically specifies the path or route that the user wants to navigate to on a website or web application. For example, if the path is "/home," it signifies the route for the "home" page.

Returns

• nothing

Example

// Import the Router func from the framework
import { Router } from "mini-framework";

// Instantiate the router
const myRouter = new Router();

// Add routes
myRouter.addRoute('/', function () {
    // Write code that you want to execute when calling this route
});

myRouter.navigateTo('/');

Usage

1. Import the Router func from your framework.

2. Create an instance of the Router to access the addRoute function.

3. Use the addRoute function to add route to a router.

4. Use the navigateTo function to execute the callback function of the route.

Notes

• Ensure that you have added the necessary routes using the addRoute function before calling navigateTo to avoid route not found errors.

getCurrentRoute

The getCurrentRoute function retrieves the current URL path representing the active route.

Parameters

• nothing

Returns

• string: The current route URL path as a string.

Example

// Import the Router function from the framework
import { Router } from "mini-framework";

// Instantiate the router
const myRouter = new Router();

// Add routes
myRouter.addRoute('/', function () {
    // Write code that you want to execute when calling this route
});

// Get the current route
const currentRoute = myRouter.getCurrentRoute();
console.log(currentRoute); // Output: "/"

myRouter.navigateTo('/about');
const updatedRoute = myRouter.getCurrentRoute();
console.log(updatedRoute); // Output: "/about

Usage

1. Import the Router function from your framework.

2. Create an instance of the Router to access the getCurrentRoute function.

3. Use the getCurrentRoute function to obtain the current route URL path.

Notes

• Ensure that you have added routes and used the navigateTo function to update the current route path before calling getCurrentRoute to retrieve the current path.

useStateManager

The useStateManager allows you to create and manage application state. You can subscribe to changes and get notified when the state updates.

Parameters

• 'initialState' (any): The initial state value for the state manager.

Returns

• An object with the following methods:
  • 'getState()': Returns the current state.
  • 'setState(newState)': Sets the state to the provided newState and notifies all subscribers.
  • 'subscribe(listener)': Adds a listener function that is called whenever the state changes. Returns an unsubscribe function to stop listening.

Example

// Import the useStateManager func from the framework
import { useStateManager } from "mini-framework";

const stateManager = useStateManager(0);

// Subscribe to state changes
const unsubscribe = stateManager.subscribe((newState) => {
   // Your code to handle state changes here
});

// Update the state
stateManager.setState(42);

// Unsubscribe when done
unsubscribe();

Usage

1. Import the useStateManager func from the framework.

2. Create a State Manager.

3. Subscribe to State Changes.

4. Update the State when needed.

5. Unsubsctibe.

Notes

• This custom state manager provides a more manual approach to state management compared to React's useState hook. It allows for more fine-grained control over state updates and subscriptions.
• Be sure to call unsubscribe when you no longer need to listen to state changes to avoid memory leaks.
• You can create multiple state managers with different initial states for various parts of your application.

events

The events is an object representing a DOM element with various event handling functions.

Parmeters

• CLICK (string): Represents the "click" event type.
• KEYDOWN (string): Represents the "keydown" event type.
• KEYUP (string): Represents the "keyup" event type.
• MOUSEENTER (string): Represents the "mouseenter" event type.
• SCROLL (string): Represents the "scroll" event type.
• CHANGE (string): Represents the "change" event type.

Returns

• nothing

Example

// Import the events func from the framework
import { events } from "mini-framework";

// Using the predefined event types in your event handling
element.addEventListener(events.CLICK, handleClick);
element.addEventListener(events.KEYDOWN, handleKeyDown);

Usage

1. Import the events object from your module.
2. Use the predefined event types in your event handling to maintain consistency and readability in your code.

Notes

• This object is a convenient way to ensure uniformity in event type naming throughout your application.
• Using these predefined event types can help improve code maintainability and readability by avoiding hard-coded event type strings.

onEvent

The onEvent function is a generic utility for adding event listeners to an HTML node element.

Parameters

• eventType (string): The type of event to handle (e.g., 'click' or 'change').
• element (HTMLElement): The HTML element to which you want to attach the event listener.
• callback (function): The event handler function to execute when the specified event occurs.

Returns

• nothing

Example

// Import the events func from the framework
import { onEvent } from "mini-framework";


// Define an HTML element
const buttonElement = document.querySelector("#myButton");

// Define an event handler function
function handleClick(event) {
  // Your event handling logic here
}

// Attach a 'click' event listener to the buttonElement
onEvent(events.CLICK, buttonElement, handleClick);

Usage

Call the onEvent function, passing the event type, HTML element, and event handler function as parameters.

Notes

• The onEvent function provides a convenient way to add event listeners to HTML elements, ensuring that the provided callback is a valid function.
• It's essential to pass a valid event type, HTML element, and a function as parameters to use this function effectively.
• Be cautious when using this function to avoid attaching multiple event listeners to the same element, which may lead to unintended behavior or performance issues.

triggerCustomEvent

The triggerCustomEvent function is used to trigger a custom event on a specified HTML element.

Parmeters

• eventType (string): The type of custom event to trigger.
• element (HTMLElement): The HTML element on which the custom event is triggered.
• eventDetail (Object, optional): An optional object containing details to pass with the custom event.

Returns

• nothing

Example

// Import the events func from the framework
import { events } from "mini-framework";

// Define an HTML element
const myElement = document.querySelector("#myElement");

// Define optional event detail
const eventDetail = {
  key: "value",
  anotherKey: 42,
};

// Trigger a custom event with or without event detail
triggerCustomEvent("myCustomEvent", myElement, eventDetail);

Usage

1. Use the various event handling functions to add event listeners to the associated HTML element.
2. Customize the callbacks as needed for different event handling scenarios.

Notes

• The event handling functions allow you to conveniently manage and handle various events associated with the DOM element.
• You can chain multiple event handling functions to attach different event listeners to the same HTML element.
• Ensure that the callbacks provided to the event handling functions are properly defined and handle the events appropriately.
• Leverage the onCustomEvent$ and triggerCustomEvent$ functions to create and trigger custom events, providing additional flexibility for event management.