cbs-bootstrap

Hello, and welcome to Custom Bootstrap! This is a resource for developers who use Bootstrap (5.0+) and would like a framework to manage elements.

Basics

When you import this package into your DOM, you will be given a global constant CBS (Custom Bootstrap) which is an instance of CustomBootstrap. This constant is the equivalent of document in the DOM, it allows you to make elements and manage them.

CBS_Element

A CBS_Element a wrapper around DOM elements where each instance of this class has a .el property that is the DOM element that instance represents. Here is the functionality this class provides:

General

.el: HTMLElement - The element this class instance represents

• If changed, this will apply every Listener and property from .options onto the new element.
• Runs .trigger('element.change')

.options: {} - Options containing .classes, .id, .attributes, and .style, along with more depending on the extended class. Used to change many aspects of a class in a quick and efficient manner.

.id: string - Id of the object

.createElementFromText(html) - Returns an array of all HTMLElements, or CBS_Elements created from an html string. See usage

• html: string

.hide() - Adds d-none to classes

.show() - Removes d-none from classes

.toggleHide() - Toggles d-none

.isHidden: boolean - Whether the classes contains d-none

.destroy() - removes event listeners, destroys all components, and runs .el.remove()

.clone() - Clones the element

.clone(listeners) - Clones the element

• listeners: boolean - (default: true) clones with the listeners

Elements

.el: HTMLElement The element CBS_Element represents

Just for ease, I'll use CBS_Node to represent Node|CBS_Element|String|Boolean|Number

get .content: CBS_Node[] - Array of components that were appended to .el

set .content: CBS_Node - Removes all elements and replaces it with a single one

set .content: CBS_Node[] - Removes all elements and replaces them with several (in order)

.append(...element) - adds element(s) onto .el in order

• element: CBS_Node

.removeElement(...element) - removes element(s) from .el

• element: CBS_Node

.prepend(...element) - prepends elements (in order) before the first element

• element: CBS_Node

replace(nodeToReplace, ...elementsToAdd) - replaces a node with one/multiple

• nodeToReplace: CBS_Node
• elementsToAdd: CBS_Node

insertBefore(nodeToInsertBefore, ...elementsToAdd) - inserts multiple/one nodes before another node

• nodeToReplace: CBS_Node
• elementsToAdd: CBS_Node

insertAfter(nodeToInsertAfter, ...elementsToAdd) - inserts multiple/one nodes after another node

.parent: Node - The parent of this element

Listeners

Instead of .addEventListener() and .removeEventListener(), this uses .on() and .off()

.listeners: Listener[] - The list of event listeners that this element has

.on(event, callback) - adds an event listener

• event: string
• callback: (event: Event) => {}

.on(event, callback, isAsync) - adds an event listener

• event: string
• callback: (event: Event) => {}
• isAsync: boolean (default: true) - Whether this function should be run in async/sync

.hasListener(event) - returns whether this element has a listener of that name

• event: string
• returns: boolean

.off() - removes all event listeners

.off(event) - removes all events with that name

• event: string

.off(event, callback) - removes all event listeners with that name and callback

• event: string
• callback: (event: Event) => {}

.trigger(event) - triggers an event

• event: string
• returns: Promise<boolean> true if there was no error

Classes

.addClass(...classes) - Adds classes to .options and to classes

• classes: string

.removeClass(...classes) - Removes classes from .options and from classes

• classes: string

.toggleClass(...classes) - Toggles classes in .options and in classes

• classes: string

.classes: string[] - Array of classes from .el

.clearClasses() - Removes all classes

.hasClass(...name) - Whether the element has that class

• name: string
• returns: boolean

Parameters

Parameters allow you to edit multiple parts of a CBS_Element at once from one method. This is very useful when used in tandem with CBS.createElementFromText()

.parameters: { [key: string]: Node|CBS_Element|String|Boolean|Number } - Key/value pairs for writable parameters on the object

.write(key, value) - Writes that key/value pair onto the element and subElements

• key: string
• value: Node|CBS_Element|String|Boolean|Number

.write(key, value, trigger) - Writes that key/value pair onto the element and subElements

• key: string
• value: Node|CBS_Element|String|Boolean|Number
• trigger: boolean - (default: true) Will run .trigger('parameters.write')

Padding and Margin

Utilizing Bootstrap's p-# and m-# classes, CBS_Element contains the following properties:

.paddingS: - Padding Start

.paddingE: - Padding End

.paddingT: - Padding Top

.paddingB: - Padding Bottom

.paddingX: - Padding X

.paddingY: - Padding Y

.padding: - Global Padding (deletes all other .padding[value] properties)

.marginS: - Margin Start

.marginE: - Margin End

.marginT: - Margin Top

.marginB: - Margin Bottom

.marginX: - Margin X

.marginY: - Margin Y

.margin: - Global Margin (deletes all other .margin[value] properties)

CBS_Component

This is extended off of CBS_Element so it keeps all properties above. Similar with CBS_Element this only represents a single DOM element, however, it has the property .subcomponents which is an object with CBS_Element|CBS_Component.

The property .subcomponents is useful for Bootstrap elements that require multiple elements, such as cards. For example:

<div class="card">
    <div class="card-header">
        This would be CBS_Card.subcomponents.header (CBS_CardHeader)
        <h3 class="card-title">
            My card title
        <h3>
    </div>
    <div class="card-body">
        This would be CBS_Card.subcomponents.body (CBS_CardBody)
    </div>
    <div class="card-footer">
        This would be CBS_Card.subcomponents.footer (CBS_CardFooter)
    </div>
</div>

Usage

CBS.createElementFromText(html: string)

Create several references to elements in a string. (These will always be in the order that document.querySelectorAll('*') will return)

const [div, p] = CBS.createElementFromString(`
    <div class="m-5">
        <p>Hello world!</p>
    </div>
`);

// references are kept:
div // <div class="m-5"><p>Hello world!</p></div>
p // <p>Hello world!</p>

Create CBS_Elements or CBS_Components

const [card, h5, p] = CBS.createElementFromString(`
    <cbs-card>
        <card-header> // CBS_Card.subcomponents.header
            <h5>My Card Title!</h5>
        </card-header>
        <card-body> // CBS_Card.subcomponents.body
            <p>My card body!</p>
        </card-body>
    </cbs-card>
`); 

// references:
card // CBS_Card
h5 // <h5>My Card Title!</h5>
p // <p>My card body!</p>

Very useful with parameters:

const [card, h5] = CBS.createElementFromString(`
    <cbs-card>
        <card-header> 
            <h5>What time is it?</h5>
        </card-header>
        <card-body>
            {{time}} // this will not be visible until you write something
        </card-body>
    </cbs-card>
`);
card.write(new Date().toTimeString()); // will replace all {{time}} with this string

Similar to React, you can only create one element, if you want to make multiple, use blank tags

const [, p, h5] = CBS.createElementFromString(`
    <>
        <p></p>
        <h5></h5>
    </>
`);

Links

• Main
• Elements