logo
v2.7.0

Helper Functions

The BladewindUI library comes with a couple of Javascript helper functions used by the library itself. These functions can also be used in your projects if you have need for them.

addToStorage

Adds a key/value pair to either localStorage or sessionStorage. The documentation website uses this to set the dark/light mode settings of the user.

        
            /* -----------------------------------------------------------
                key:            label of key to store
                val:            value to store for key
                storageType:    where to store key/val pair.
                                localStorage or sessionStorage
            -----------------------------------------------------------*/
            addToStorage(key, val, storageType = 'localStorage');

            // example
            addToStorage('theme', 'dark');

        
    

animateCSS

Animates any element in the DOM. Works with any of the animation classes from animate.css by Daniel Eden. The animation class names should be used without the animate__ prefix.

        
            /* ---------------------------------------------------------------
                element:     css class that identifies the element to animate
                animation:   animation class to be applied to element
            -----------------------------------------------------------------*/
            animateCSS(element, animation);

            // example
            animateCSS('.navigation','slideInRight');

        
    

changeCss

Add to or remove CSS classes from a single element in the DOM.

        
            /* ---------------------------------------------------------------
                element:    css class that identifies the element to change
                css:        comma separated list of css class names to apply
                mode:       should the css be added or removed
                elementIsDomObject: is the element a dom Object
            -----------------------------------------------------------------*/
            changeCss(element, css, mode = 'add', elementIsDomObject = false);

            // example 1: elementIsDomObject = true
            current_theme = getFromStorage('theme');
            changeCss(document.documentElement, current_theme, 'add', true);

            // example 2: remove list of css from an element
            changeCss('.nav a.active', 'selected, active', 'remove');
        
    

changeCssForDomArray

Very similar to changeCss but this adds or removes CSS classes from an array of CSS elements in the DOM. This targets elements with the same class name or tag name.

        
            /* ---------------------------------------------------------------
                elements:   css class that identifies the element to change
                css:        comma separated list of css class names to apply
                mode:       should the css be added or removed.
            -----------------------------------------------------------------*/
            changeCssForDomArray(elements, css, mode = 'add');

            // example 1: add list of css classes
            changeCssForDomArray('li', 'underline, my-2');

            // example 2: remove list of css classes
            changeCssForDomArray('.nav a', 'selected, active', 'remove');
        
    

compareDates

Performs a validation for two dates. Used by the range datepicker to ensure an end date is not less than a start date. Returns boolean.

        
            /* ---------------------------------------------------------------
                date1_field:   name of input field that has the start date
                date2_field:   name of input field that has the end date
                error_message:  message to display if the end date is less than start date
                error_inline:   determines if message is displayed inline. Default is in the notification
            -----------------------------------------------------------------*/
            compareDates(date1_field, date2_field error_message, error_inline);

            compareDates(
                'task_begins',
                'task_ends'
                'Please ensure your task end date is after the task start date',
                1); // uses 0 and 1 for boolean

            // from above
            // 1. the start date datepicker field has the name task_begins
            // 2. the end date datepicker field has the name task_ends
        
    

domEl

Shortcut for writing Javascript's document.querySelector. This function has an alias dom_el that does exactly the same thing.

        
            /* ---------------------------------------------------------------
                element:   css class that identifies the element to target
            -----------------------------------------------------------------*/
            domEl(element);

            // examples
            domEl('input.fname').getAttribute('disabled');
            let data = new FormData(dom_el(form));
        
    

domEls

Shortcut for writing Javascript's document.querySelectorAll. This function has an alias dom_els that does exactly the same thing.

        
            /* ---------------------------------------------------------------
                elements:   css class that identifies the elements to target
            -----------------------------------------------------------------*/
            domEls(elements);

            // example
            domEls('input.required').forEach((el) => {
                console.log(el.value);
            });
        
    

getFromStorage

Retrieve a value from the enduser's localStorage or sessionStorage based on key that is passed.

        
            /* ---------------------------------------------------------------
                key:            key to get value for
                storageType:    storage to fetch the value from
            -----------------------------------------------------------------*/
            getFromStorage(key, storageType = 'localStorage');

            // example
            getFromStorage('theme');
        
    

hide

Hide an element from/in the DOM .

        
            /* ---------------------------------------------------------------
                element:    css class that identifies the element to hide
                elementIsDomObject: is the element a dom Object
            -----------------------------------------------------------------*/
            hide(element, elementIsDomObject = false);

            // example
            hide('.top-bar');
            hide(domEl('.top-bar'), true);
        
    

hideButtonSpinner

Hide the spinner associated with a button.

        
            /* ---------------------------------------------------------------
                element:    name of the button
            -----------------------------------------------------------------*/
            hideButtonSpinner(element);

            // example
            hideButtonSpinner('.save-user');
        
    

hideModal

Specifically hides a BladewindUI Modal component.

        
            /* ---------------------------------------------------------------
                element:    css class that identifies the modal to hide
            -----------------------------------------------------------------*/
            hideModal(element);

            // example
            hideModal('.make-payment');
        
    

hideModalActionButtons

Hides the action buttons on a BladewindUI Modal component. The action buttons are the Ok and Cancel buttons. See the example here for how this is used.

        
            /* ---------------------------------------------------------------
                element:    css class that identifies the modal to hide
            -----------------------------------------------------------------*/
            hideModalActionButtons(element);

            // example
            // this will hide the Cancel and Ok buttons on the make-payment modal
            hideModalActionButtons('make-payment');
        
    

isNumberKey

Used by the Bladewind Textbox component to restrict user input to only numeric values. You can however use this helper function in your own non-Bladewind textboxes. For example to enter verification codes.

        
            /* ---------------------------------------------------------------
                evt:    javascript keypress events
            -----------------------------------------------------------------*/
            isNumberKey(evt);

            // example
            <input type="text" onkeypress="return isNumberKey(event)" />
        
    

removeFromStorage

Remove a key from the enduser's localStorage or sessionStorage.

        
            /* ---------------------------------------------------------------
                key:            key to remove
                storageType:    which storage to remove the  key from
            -----------------------------------------------------------------*/
            removeFromStorage(key, storageType = 'localStorage');

            // example
            removeFromStorage('theme');
        
    

serialize

Prepares form data as key/value pairs to send via Ajax posts or requests..

        
            /* ---------------------------------------------------------------
                form:  css class that identifies the form to serialize
            -----------------------------------------------------------------*/
            serialize(form);

            // example
            <form class="signup-form">...</form>

            serialize('.signup-form');
        
    

showButtonSpinner

Unhide a spinner associated with a Button component with has_spinner="true".

        
            /* ---------------------------------------------------------------
                element:    name of the button
            -----------------------------------------------------------------*/
            showButtonSpinner(element);

            // example
            showButtonSpinner('.save-user');
        
    

showModal

Specifically unhides a Bladewind Modal component.

        
            /* ---------------------------------------------------------------
                element:    css class that identifies the modal to unhide
            -----------------------------------------------------------------*/
            showModal(element);

            // example
            showModal('.make-payment');
        
    

showModalActionButtons

Unhides the action buttons on a BladewindUI Modal component. The action buttons are the Ok and Cancel buttons.

        
            /* --------------------------------------------------------------------
                element:    css class that identifies the modal to show buttons for
            --------------------------------------------------------------------*/
            showModalActionButtons(element);

            // example
            // this will show the Cancel and Ok buttons on the make-payment modal
            showModalActionButtons('make-payment');
        
    

stringContains

Checks to see if a string contains the specified keyword. Returns true if string contains the keyword and false if string does not contain the keyword.

        
            /* ---------------------------------------------------------------
                str:        main string to check keyword against
                keyword:    keyword to check if it's contained in str
            -----------------------------------------------------------------*/
            stringContains(str, keyword);

            // example
            stringContains(location.href, '/admin');
        
    

unhide

Unhides any DOM element.

        
            /* ---------------------------------------------------------------
                element:    css class that identifies the element to unhide
                elementIsDomObject: is the element a dom Object
            -----------------------------------------------------------------*/
            unhide(element, elementIsDomObject = false);

            // example
            unhide('.top-bar');
            unhide(domEl('.top-bar'), true);
        
    

validateForm

Performs a very basic not empty validation on a form that has input fields marked as required. This won't work if the input fields have not been marked as required. If you're using the Bladewind Textbox component, you will need to set the attribute required="true". If you want to validate non-Bladewind input fields, add class="required" to your input field. At the moment, this function only works on text-based input fields and the textarea field. See the Validating Input Fields section of the Textbox component documentation.

        
            /* ---------------------------------------------------------------
                form:    css class that identifies the form to validate
            -----------------------------------------------------------------*/
            validateForm(form);

            // example
            <form class="signup-form">
                <x-bladewind.input required="true" name="fullname" label="Name" />
                <x-bladewind.input required="true" name="email" label="Email" />
                <x-bladewind.input required="true" name="mobile"
                    label="Mobile" numeric="true" />
            </form>

            domEl('.signup-form').addEventListener('submit', function (e){
                e.preventDefault();
                signUp();
            });

            signUp = () => {
                if ( validateForm('.signup-form') ) {
                    // form is valid.. do this
                    unhide('.btn-signup .bw-spinner');
                    ajaxCall('/user/signup', 'signUpCallback', serialize('.signup-form'));
                }
            }