v2.8.1
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.
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');
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');
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');
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');
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
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));
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
scope: scope within which to search for <elements>
-----------------------------------------------------------------*/
domEls(elements, scope = null);
// example: find all inputs with css class 'required'
domEls('input.required').forEach((el) => {
console.log(el.value);
});
// find inputs with class='required' in a form with class='signup'
domEls('input.required', 'form.signup').forEach((el) => {
console.log(el.value);
});
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 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);
Hide the spinner associated with a button.
/* ---------------------------------------------------------------
element: name of the button
-----------------------------------------------------------------*/
hideButtonSpinner(element);
// example
hideButtonSpinner('.save-user');
Specifically hides a BladewindUI Modal component.
/* ---------------------------------------------------------------
element: css class that identifies the modal to hide
-----------------------------------------------------------------*/
hideModal(element);
// example
hideModal('.make-payment');
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');
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)" />
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');
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');
Unhide a spinner associated with a Button component with has_spinner="true".
/* ---------------------------------------------------------------
element: name of the button
-----------------------------------------------------------------*/
showButtonSpinner(element);
// example
showButtonSpinner('.save-user');
Specifically unhides a Bladewind Modal component.
/* ---------------------------------------------------------------
element: css class that identifies the modal to unhide
-----------------------------------------------------------------*/
showModal(element);
// example
showModal('.make-payment');
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');
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');
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);
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.
You can either pass a string targeting the class of the HTML form or pass an HTMLFormElement.
/* ---------------------------------------------------------------
form: css class of the form or HTMLFormElement 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>
// ---- this option uses the css class name of the 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'));
}
}
// ----- this option uses the HTMLFormElement ------------------------
// https://github.com/mkocansey/bladewind/issues/403#issue-2662756420
const forms = document.getElementsByTagName('form');
for (let i = 0; i < forms.length; i++) {
forms[i].addEventListener('submit', function (e) {
e.preventDefault();
let validationStatus = validateForm(this);
if (validationStatus) {
this.submit();
}
});
}