@apicart/js-utils

Js-Utils

• A small set of useful utilities for simpler development.
• ✅ 7 Kb minified (3 Kb Gzipped)
• ✅ Supports IE 10 +
• ✅ TRY IT ON CODEPEN

Content

• Ajax
• Console
• DOM
• JSON
• Loops
• Objects
• Strings
• Url
• Validators
• Data Binder
• Event Dispatcher
• Flash Messages

Installation

Cdn

<!-- Master version from Github -->
<script src="https://cdn.jsdelivr.net/gh/apicart/js-utils/dist/utils.min.js"></script>

<!-- v1.0.0-alpha1 from jsdelivr.net -->
<script src="https://cdn.jsdelivr.net/npm/@apicart/js-utils@1.0.0-alpha1/dist/utils.min.js" integrity="sha256-eo4u9fSxiYhrAT7PpLhbWEFHsiuBnTV0krDfY7VeQE4=" crossorigin="anonymous"></script>

Npm & Yarn

npm i @apicart/js-utils

yarn add @apicart/js-utils

Ajax (Utils.ajax)

This component simplifies work with the XMLHttpRequest.

Parameters

Parameter	async	cache	data	headers	method	queryParameters	timeout	url	withCredentials	start	complete
Type	boolean	boolean	object	object	string	object	number	string	boolean	function	function
Default value	true	true	{}	{}	get	{}	5000	''	false	function() {}	function() {}

ajax(object $parameters): void

Utils.ajax({
    url: 'https://example.com',
    method: 'post',
    complete: function (response){
        alert('Done');
    }
});

Console (Utils.console)

Wraps the default browser console and ensures the cross-browser compatibility.

error(mixed $parameter, mixed $parameter, ...): utils.console

Utils.console.error('Some', 'Value');

log(mixed $parameter, mixed $parameter, ...): utils.console

Utils.console.log('Some', 'Value');

warn(mixed $parameter, mixed $parameter, ...): utils.console

Utils.console.warn('Some', 'Value');

DOM (Utils.dom)

Simplifies work with Document Object Model.

matches(Element $element, string $selector): boolean

Returns true if element matches selector. If not, returns false.

Utils.dom.matches(document.querySelector('.element', '.selected');

on(array|string $eventTypes, array|string $selectors, function|null $callback): utils.dom

Adds event listener to selected elements. Works even on dynamically added elements.

Utils.dom.on('click', '.element', function() {...});

findParent(Element $element, string $selector): Element|null

Returns element parent based on selector. If the parent was not found, returns null.

Utils.dom.findParent(Element $element, '.parent');

addClass(Element $element, string $classes): utils.dom

Adds one or multiple classes to selected elements.

Utils.dom.addClass(document.querySelector('.element'), 'first second third');

removeClass(Element $element, string $classes): utils.dom

Removes one or multiple classes from selected elements.

Utils.dom.removeClass(document.querySelector('.element'), 'first second third');

trigger(Element $element, string $event): utils.dom

Triggers an event on selected element.

Utils.dom.trigger(document.querySelector('.button'), 'click');

Json (Utils.json)

isJson(string $content): boolean

Checks if the provided data are json. If not returns false.

Utils.json.isJson('{a: "b"}'); // true
Utils.json.isJson('Text'); // false

parse(string $content): object

Converts json to object. If the provided data are not json, returns an empty object.

Utils.json.parse('{a: "b"}'); // {a: "b"}

stringify(object $object): string

Converts javascript object into json.

Utils.json.stringify({a: "b"}); // "{a: "b"}"

Loops (Utils.loops)

forEach(object|array $iterable, function $callback): void

Function that is able to iterate over objects and arrays. Inside this function the this object is an object containing counter, iterableLength parameters and isFirst, isLast, isEven, isOdd functions.

Utils.loops.forEach([1, 2, 3], function(key, value) {...});
Utils.loops.forEach([1, 2, 3], function(key, value) {console.log(this.counter, this.isFirst());...});
Utils.loops.forEach(document.querySelectorAll('.element'), function(key, element) {...});

Objects (Utils.objects)

assign(object $object, string $keyPath, mixed $value): utils.objects

Polyfill of the Object.assign for older browsers. Is able to assign nested properties.

var a = {x: 1};
Utils.objects.assign(a, 'y.z', 2); // {x: 1, y: {z: 2}}

copy(object $object): object

Returns a new copy of the provided object. Object copy is without a reference to copied object.

Utils.objects.copy({a: "b"}); // {a: "b"}

delete(object $object, string $keyPath): utils.objects

Removes keys from object. Is able to remove nested keys.

Utils.objects.delete({a: {b: {c: "1", d: "2"}}}, 'a.b.c'); // {a: {b: {d: "2"}}}

find(object $object, string $keyPath): mixed

This method is able to find a value according to provided key. The key can be arbitrarily nested. If the key doesnt exists, returns null.

Utils.objects.find({a: {b: {c: "1"}}}, 'a.b.c'); // 1

isObject(mixed $data): boolean

Checks if the provided data are object.

Utils.objects.isObject({a: "b"}); // true
Utils.objects.isObject(null); // false
Utils.objects.isObject([]); // false

merge(object $object1, object $object2, ...): object

Merges two objects into a new one. The new object is without reference to the merged objects.

Utils.objects.merge({a: "1"}, {b: "2"}); // {a: "1", b: "2"}
Utils.objects.merge({a: {b: "1"}}, {a: {c: "2"}}); // {a: {b: "1", c: "2"}}

values(object $object): array

Removes keys from provided object and returns its data. Odstraní klíče daného objektu a vrátí jejich data.

Utils.objects.values({a: "b", c: "d"}): // ["b", "d"]

Strings (Utils.strings)

firstToUpper(string $string): string

Converts first letter of the given string to upper case.

Utils.strings.firstToUpper('test') // Test

generateHash(integer $length, string|null $characters = 'abcdefghijklmnopqrstuvwxyz0123456789'): string

Generates hash from given characters and length. Vytvoří hash o dané délce ze zadaných znaků.

Utils.strings.generateHash(32) // 32 characters long hash

sprintf(string $content, object|array $parameters): string

Replaces placeholders by given values.

Utils.strings.sprintf('%0% je %1%', ['Apicart', 'nejlepší']) // Apicart je nejlepší
Utils.strings.sprintf('%spolecnost% je %hodnoceni%', {spolecnost: 'Apicart', hodnoceni: 'nejlepší'}) // Apicart je nejlepší

Url (Utils.url)

getQueryParameter(string $name, string $url): *|null

Returns query parameter from the given url. If the parameter was not found, returns null.

Utils.url.getQueryParameter('number', 'https://example.com?number=1') // 1

Validators (Utils.validators)

isEmpty(mixed $data): boolean

Returns true if the provided data are empty. Otherwise returns false.

Utils.validators.isEmpty([]) // true
Utils.validators.isEmpty({}) // true
Utils.validators.isEmpty('') // true

Data Binder (Utils.dataBinder)

Data binder is a component, that saves data from form elements and fills them back automatically after the page refresh.

Použítí s elementy

All you need is to add the data-bind attribute to the element which data should be saved. Keys provided inside the attribute can be nested.

<input data-bind="username">
<select data-bind="billing.method"></select>

addData(string $keyPath, string|number $value): utils.dataBinder

This method adds data according to given key and value. Keys can be nested.

Utils.dataBinder.addData('name', 'Karel');
Utils.dataBinder.addData('addresses.billing.town', 'Praha');

removeData(string $keyPath): utils.dataBinder

Removes data according to the given key.

Utils.dataBinder.addData('name');
Utils.dataBinder.addData('addresses.billing.town');

bindData(boolean $all = false): utils.dataBinder

This method triggers the autofill. If the all parametr is set to true, it will fill all elements even those that were already filled.

Utils.dataBinder.bindData() // Fills only those elements, that were not filled yet
Utils.dataBinder.bindData(true) // Fills all

Event Dispatcher (Utils.eventDispatcher)

Event dispatcher allows you communicate between components based on events. If for example a product was added into the cart, you can trigger productAddedIntoCart event. Listeners waiting for this event will be triggered with given values.

addListener(string $listenerKey, string|array $eventName, function $callback, boolean|null $singleAction = false)

This method registers listener. If the singleAction parameter is set to true, the listener will be triggered only once (it is useful for dynamically generated listeners).

Utils.eventDispatcher.addListener('number-dumper', 'send-number', function (number) {
    console.log(number);
}, true); // Single action is set to true, so the listener will be triggered only once
Utils.eventDispatcher.addListener('product-popup', 'product-added-into-cart', function (parameters) {...});

removeListener(string|array $listenerKey, string|array $event): utils.eventDispatcher

Removes listener from given event.

Utils.eventDispatcher.removeListener('posluchač', 'event1 event2');
Utils.eventDispatcher.removeListener('posluchač', ['event1', 'event2']);
Utils.eventDispatcher.removeListener('number-dumper', 'send-number');

dispatchEvent(string|array $event, mixed|null $parameters): utils.evendDispatcher

Triggers selected event. Given parameters are provided to the listeners.

Utils.eventDispatcher.dispatchEvent('event1 event2');
Utils.eventDispatcher.dispatchEvent(['event1', 'event2']);
Utils.eventDispatcher.dispatchEvent('rozesli-cislo', 1);

Flash Messages (Utils.flashMessages)

Flash messages allows you to persist messages through redirects.

addMessage(string $content, string|null $type = 'info'): utils.flashMessages

Adds message. You can provide a custom type.

Utils.flashMessages.addMessage('Text');
Utils.flashMessages.addMessage('Warning!', 'warning');

getMessages(): object

Returns messages.

Utils.flashMessages.getMessages();

hasMessages(): boolean

Returns true if there are some persisted messages.

Utils.flashMessages.hasMessages();

processMessages(function $callback, string|null $type): utils.flashMessages

Iterates over messages. If the type is set, the iteration is done only over the messages of the given type.

Utils.flashMessages.processMessages(function (message, type) { ... }); // Processes all messages
Utils.flashMessages.processMessages(function (message, typ) { ... }, 'info'); // Processes only the info messages