# Handbook for macros.js This handbook provides a detailed guide on using `macros.js` in your web projects. `macros.js` is a lightweight JavaScript library that simplifies common DOM manipulations and event handling, similar to jQuery, but with a modern and compact approach. It is designed to work directly in the browser without dependencies. ## Table of Contents 1. [Introduction](#introduction) 2. [Installation](#installation) 3. [DOM Selectors](#dom-selectors) 4. [DOM Manipulation](#dom-manipulation) 5. [Event Handling](#event-handling) 6. [Currency Formatting](#currency-formatting) 7. [Example Project](#example-project) 8. [Comparison with jQuery](#comparison-with-jquery) 9. [Best Practices](#best-practices) ## Introduction `macros.js` provides a set of helper functions and methods to select, manipulate, and manage events for DOM elements. It is a modern alternative to jQuery, focusing on simplicity and performance. It supports: - Shorthand DOM selectors (`$`, `$$`, `$id`) - Chainable DOM manipulation methods (`addClass`, `removeClass`, `toggleClass`, `show`, `hide`, `toggleVisibility`) - Flexible event handling (`on`, `off`) - Currency formatting (`formatCurrency`) Unlike jQuery, `macros.js` is more compact and leverages modern JavaScript APIs like `querySelector` and `classList`. ## Installation Include `macros.js` in your project by adding the script to your HTML file: ```html ``` Place the ` ``` This example: - Uses `onReady` to wait for the DOM to load. - Adds a click event to each `.item` element to toggle the `active` class. - Adds a button to show/hide the list. - Formats prices using `formatCurrency`. ## Comparison with jQuery Here’s a quick comparison to help transition from jQuery to `macros.js`: | Functionality | jQuery | macros.js | |------------------------|---------------------------------|---------------------------------| | Select one element | `$('div')` | `$('div')` | | Select multiple | `$('div')` | `$$('div')` | | Select by ID | `$('#id')` | `$id('id')` | | Add class | `$('#id').addClass('cls')` | `$id('id').addClass('cls')` | | Remove class | `$('#id').removeClass('cls')` | `$id('id').removeClass('cls')` | | Toggle class | `$('#id').toggleClass('cls')` | `$id('id').toggleClass('cls')` | | Show element | `$('#id').show()` | `$id('id').show()` | | Hide element | `$('#id').hide()` | `$id('id').hide()` | | Add event | `$('#id').on('click', fn)` | `$id('id').on('click', fn)` | | Delegated event | `$(document).on('click', '.item', fn)` | `document.on('click', '.item', fn)` | | DOM ready | `$(document).ready(fn)` | `onReady(fn)` | **Differences**: - `macros.js` returns native DOM elements (`Element` or `NodeList`), while jQuery returns a jQuery object. - `macros.js` lacks animations or AJAX functionality, which jQuery provides. - `macros.js` is much smaller and has no external dependencies. ## Best Practices 1. **Use `onReady` or `onLoad`**: Place scripts at the end of the `` or use `onReady` to ensure the DOM is available. 2. **Chain Methods**: Leverage method chaining for readable code. ```javascript $id('my-element').addClass('highlight').show(); ``` 3. **Use Delegated Events**: For dynamically added elements, use `document.on('click', '.selector', handler)` to optimize performance. 4. **Minimize DOM Access**: Cache selectors in variables to avoid repeated DOM queries. ```javascript const button = $id('my-button'); button.on('click', () => button.toggleClass('active')); ``` 5. **Validate Selectors**: Ensure selectors are valid to avoid `null` errors. ```javascript const element = $('div.my-class'); if (element) { element.addClass('active'); } ``` ## Conclusion `macros.js` is a powerful, lightweight tool for modern web development. It offers a familiar, jQuery-like API while leveraging native browser APIs for better performance. By following the guidelines and examples above, you can quickly and efficiently build interactive web applications.