DEV Community: Okoro Redemption

ToolJS: Creating a Plugin

Okoro Redemption — Tue, 19 Jan 2021 00:19:34 +0000

ToolJS as said in the introductory part of this series, is open-source, is a collection of functions and methods. This means even you can contribute to it, by creating a plugin/module for it.

This is useful, as you get to share your own most used JavaScript functions and methods as a plugin/module on the library.

We will be covering how to create a plugin which can be used alongside the main library in both Node.js and browser.

We will be creating a plugin/module that holds a number of greetings, so lets call it ToolJS-Greetings Plugin.

1. Create a new .js file and give it a name

This is the first step, a pretty obvious one for that matter. Create a .js file and name it anything you like, but preferably with the "tooljs-" prefix for easy recognition. In our case we will call ours "tooljs-greetings.js". This will hold all our plugin code.

2. Check if ToolJS is included in your working environment

This step is very important. For your plugin to be recognized by ToolJS, you have to make sure ToolJS main class (which is the default export in Node and ESM) is included in your working environment either through a Node.js require statement, a script tag, or an ES6 import.

// check if ToolJS is registered in your work environment
if(ToolJS !== undefined){
  // rest of your code goes in here
}
else{
  console.warn("ToolJS is not registered in your work environment. Include ToolJS before you register a plugin on to it");
}

Now that we are sure ToolJS is available we can go ahead with our plugin code. All our plugin code goes into the "if" block.

3. Write plugin's code

 // import the built in "Str" module from the ToolJS library
    var Str = ToolJS.export("Str");

    // define a function that returns an object for your module
    function myModule() {
        // module methods
        var methods = {
            hello: (name) => { alert(`${Str.toUpper(name)} says hello to you.`); },
            goodbye: (name) => { alert(`${Str.toUpper(name)} says goodbye to you.`); },
            morning: (name) => { alert(`${Str.toUpper(name)} says good morning to you.`); },
            afternoon: (name) => { alert(`${Str.toUpper(name)} says good afternoon to you.`); },
            evening: (name) => { alert(`${Str.toUpper(name)} says good evening to you.`); }
        };

        // return the methods
        return methods;
    };

You might have noticed that we exported the in-built "Str" module from the library. This means that you can use in-built modules and even other plugins for yours too.

As mentioned earlier, we are creating a module that holds a bunch of greetings, each being a method of the module.

Note that your module function MUST return an object of methods

4. Register the Plugin.

Its time to register our plugin unto the ToolJS library(locally). This can be achieved using the ToolJS.register method made available by the library. This method accepts two(2) parameters

moduleName - The name to register your plugin as.
moduleFunc - The function that exports your modules methods.

// use ToolJS register method to register your module.
// the first parameter of the method is the module name, and the second is the module functions/methods
ToolJS.register("Greet", myModule);

The code above will register our plugin/module as "Greet", which means when we want to export it's methods, we'll pass "Greet" to the ToolJS.export method.

You can optionally wrap the whole code in an iife format and store it in a variable, for easy export using either CJS or ES6 formats, depending on your preference. You can host your plugin either on NPM or on a CDN.

See the full code below

5. Using a created plugin

So we created a plugin, its time to actually use it. The usage depends on your environment.

For Node.js

const ToolJS = require("@redeakaa/tooljs").default;
const Greet = require("./path/to/tooljs-greetings.js");

Greet.hello("Okoro Redemption");
// alerts "OKORO REDEMPTION says hello"

For ES6

import ToolJS from "./path/to/tooljs.esm.js";
import Greet from "./path/to/tooljs-greetings.js";

Greet.hello("Okoro Redemption");
// alerts "OKORO REDEMPTION says hello"

For Browser

<script src="https://unpkg.com/@redeakaa/tooljs@1.0.1/dist/umd/tooljs.min.js"></script>
<script src="./path/to/tooljs-greetings.js"></script>

var Greet = ToolJS.export("Greet");

Greet.hello("Okoro Redemption");
// alerts "OKORO REDEMPTION says hello"

See the full code of the example plugin below

var tooljsPlugin = (function(){
        // check if ToolJS is registered in your work environment
        if(ToolJS !== undefined){
            var Str = ToolJS.export("Str");

            // define a function that returns an object for your module
            function myModule() {
                // module methods
                var methods = {
                    hello: (name) => { alert(`${Str.toUpper(name)} says hello to you.`); },
                    goodbye: (name) => { alert(`${Str.toUpper(name)} says goodbye to you.`); },
                    morning: (name) => { alert(`${Str.toUpper(name)} says good morning to you.`); },
                    afternoon: (name) => { alert(`${Str.toUpper(name)} says good afternoon to you.`); },
                    evening: (name) => { alert(`${Str.toUpper(name)} says good evening to you.`); }
                };

                // return the methods
                return methods;
            };

            // use ToolJS register method to register your module.
            // the first parameter of the method is the module name, and the second is the module functions/methods
            ToolJS.register("Greet", myModule);
        }
        else{
            console.warn("ToolJS is not registered in your work environment. Include ToolJS before you register a plugin on to it");
        }
    })();

    // export the tooljsPlugin variable as needed by the environment specifics. Omit for browser usage.

// For Node.js
modules.export = tooljsPlugin;

// For ES6
export default tooljsPlugin;

See the Pen ToolJS: Creating a Plugin by Redemption Okoro (@akaawereniya) on CodePen.

Conclusion

ToolJS offers its user the ability of extending the libraries functionalities by creating plugins/modules which can be used alongside the library itself and shared amongst other developers.

ToolJS: DOM Manipulation Using ToolJS

Okoro Redemption — Mon, 18 Jan 2021 21:48:56 +0000

ToolJS: DOM Manipulation.

The DOM is an integral part of front-end development. The DOM is being manipulated one way or the other using JavaScript. This can sometimes be a bit tedious, as the in-built JavaScript methods can be a bit too long, take for example document.getElementBy("myElement").

Well ToolJS comes with a DOM module that simplifies manipulation of the DOM, lets check it out.

First of all, make sure ToolJS is included in your work environment either by using the script tag with the CDN or by using the ES6 Import syntax to either import only the DOM module or to import the whole library and export the DOM module.

// export all methods from the "DOM" module
var $ = ToolJS.export("DOM");

Using ES6 destructing import syntax

import { DOM as $ } from "https://unpkg.com/@redeakaa/tooljs@1.0.1/dist/esm/tooljs.esm.js";

NOTE: if you imported the DOM module from the ESM version of the library using ES6 import syntax, then call all methods on the DOM variable you exported it as

Now that we have the DOM methods in a variable "$", we can start manipulation

Getting elements from the DOM

Getting elements from the DOM is done by calling the getEl method with a valid css selector string as its first parameter.

// The code below gets all elements in the DOM with the class "myElements"
var myElements = $.getEl(".myElements");

// The code below gets the element with id = "myParagraph"
var myParagraph = $.getEl("#myParagraph");
console.log(myParagraph);
// => <p id="myParagraph" class="myElements">This is a p tag</p>

If more than one element matches the query, then ToolJS returns an instance of the ToolJSNodeList array, else it returns the only element found.

Now let's say you want to limit the scope of your getEl query to a particular portion of your DOM(maybe a div). You can archieve this by passing a second parameter to the getEl method specifying another valid css selector string that matches an element in the DOM.

// The code below gets all "p" elements in the div with class "my-dom"
var myParagraph = $.getEl("p", ".my-dom");
console.log(myParagraph);
// => <p id="myParagraph" class="myElements">This is a p tag</p>

The getEl method also accepts an optional third parameter, the options parameter, an object which manipulates the element(s) returned by the query. This is usually the last parameter in the methods that accepts it.

var myParagraph = $.getEl("p", ".my-dom", {
  css: "color: red; font-size: 30px", // this option accepts any valid css string
  style: { // this option accepts any valid style object property
    fontFamily: "consolas",
    border: "2px solid red"
  },
  title: "I am a paragraph" // this sets the title of each element
});

Pretty cool uh(😎)..

For a list of all the accepted options see ToolJS DOM Manipulation Options Object

The options parameter accepts a set of pre-defined options (see link above) and also accepts the default properties of an element in pure vanilla js, properties such as "id", "className", "title", "tabIndex" and so on..

Shorthands

The second parameter in the .getEl is optional, which means it can be omitted. This also means that you can pass it the options object parameter instead.

// get all h4 elements in the DOM and append to the element with class = "my-dom"
$.getEl("h4", {
  attr: { // this option accepts an object
    set: {
      "data-name": "John Doe",
      "aria-label": "ToolJS"
    },
    remove: ["tabIndex", "title"]
  }
  appendTo: ".my-dom",
});

Creating Elements

The ToolJS DOM module ships with it a method .createEl that replicates the document.createElement() function, and adds a few more functionalities to it.

Creating elements using plain old javascript

// this is plain old js

var myNewElement = document.createElement("div");
myNewElement.innerHTML = "Hello i was created just now";
document.body.appendChild(myNewElement);

Creating elements using ToolJS

// The code below creates an a div element and manipulate it
var myNewElement = $.createEl("div", {
  innerText: "Hello i was created just now",
  appendTo: "body"
});

Binding Events to Elements

Using plain old js to bind say maybe a click event to an element, you would need to get the element from the DOM, then call the addEventListener method on the element. Now imagine wanting to do this for multiple elements, it'll be a pain in the a** 😩

Well ToolJS simplifies this for you, and adds a little flavour to it.

// binding an event to all p elements in the DOM
$.on("p", "click", function(){
  alert("This is a " + this.tagName + " tag");
});

The code above is familiar to what you would do using JQuery.

Binding multiple events to an element with the same callback can be done by passing an array of events to the event parameter(the second parameter) or passing it a string of events separating each with a comma.

// binding multiple events to all p elements in the DOM
$.on("p", "click, contextmenu, mouseover", function(){
  alert("This is a " + this.tagName + " tag");
});

// binding multiple events to all p elements in the DOM using array
$.on("p", ["click", "contextmenu", "mouseover"], function(){
  alert("This is a " + this.tagName + " tag");
});

Pretty Basic.

Now say you want to bind multiple events to an element with each event having a different callback function. This can be achieved by passing an object literal of events and functions pairs to the events parameter, instead of a string or array.

// binding multiple events with multiple callbacks to all p elements in the DOM
$.on("p", {
  click: function(){
    alert("I was triggered on a click event");
  },
  contextmenu: function(){
    alert("I was triggered on a contextmenu event");
  },
  mouseover: function(){
    alert("I was triggered on a mouseover event");
  }
});

This same syntax can be used in the manipulation options parameter under the event option for any of the ToolJS DOM method that accepts it.

// bind events to the h4 elements referenced using the .getEl method
var h4Tag = $.getEl("h4", {
  innerHTML: "<i>You can click on me</i>",
  event: {
    click: function(){
      alert("I was triggered on a click event");
    },
    contextmenu: function(){
      alert("I was triggered on a contextmenu event");
    },
    mouseover: function(){
      alert("I was triggered on a mouseover event");
    }
  }
});

So far, we have covered just a few of the methods that ToolJS DOM module offers for manipulating the DOM. Check out the DOM Module Documentation for a list of all available methods, how to use them and even examples.

Be sure to bookmark this post, as updates will be made periodically as demands are made.

See the Pen ToolJS: DOM Manipulation Using ToolJS by Redemption Okoro (@akaawereniya) on CodePen.

Conclusion

ToolJS DOM Module helps us manipulate the DOM and its elements swiftly and efficiently by extending and utilizing JavaScript's DOM methods and functions.

ToolJS: Exporting Module Functions

Okoro Redemption — Mon, 18 Jan 2021 10:22:38 +0000

Export ToolJS Modules.

We looked at the ToolJS.config method the last time. Today we'll checkout the ToolJS.export method which you might have noticed the above method in the previous posts.

Though available in all working environment, this method was created mainly for users who reference the library through its CDN or locally. It gives the users the ability to export or bind the modules they want to any variable of their choice for flexibility.

In popular libraries like Lodash and JQuery when being used in browser or through their CDN, the methods are bound to "_" and "$" respectively. This feature also helps to reduce pollution of the window object with so many namespace.

ToolJS, as of version 1.0.1 and as the time of this post comes with six(6) in-built modules, namely "DOM", "Obj", "Str", "Num", "Calc" and "Utils", each with a handful of methods.

To export any of this modules, pass the module name to the ToolJS.export method as a string, and for multiple exports, pass it an array of strings.

// The export function accepts either a single string or an array of strings representing a registered module
var $ = ToolJS.export("Str");
// the above code exports all methods of the "Str" module to the variable "$" and can now be used as shown below

var myString = $.joinBy("_", "Hello", "World");
console.log(myString);
// => Hello_World

Say you want to export both the "Str" and "Num" modules into a variable, just pass an array to the method

// The code below will export all the methods in both the "Str" and "Num" module to the variable "_"
var _ = ToolJS.export(["Str", "Num"]);

// the code below checks if a number is odd
_.isOdd(6);
// => false

// the code below slugifies a given string
var post_title = _.slugify("How to use ToolJS library");
console.log(post_title);
// => "how-to-use-toolJS-library"

The ToolJS.export method exports all modules in the library by default if no parameter was passed to it.

// this exports all the methods in all the modules of the library
var All = ToolJS.export();

See the Pen ToolJS: The Export Function by Redemption Okoro
(@akaawereniya) on CodePen.

Conclusion

The ToolJS.export method exports a registered module's methods to a variable for use. This helps to avoid polluting the window object.

ToolJS: Enabling Code Debugging

Okoro Redemption — Mon, 18 Jan 2021 09:30:54 +0000

ToolJS: Code Debugging

In the previous post, we introduced ToolJS and saw how to install it into a work environment.

In this post, we'll see the code debugging capabilities of ToolJS. This will be the shortest post in the series.

ToolJS Config

The ToolJS default export offered for node, es6 users and the ToolJS namespace in the window object for browser users, offers a set of methods which helps the use of the class. We'll be talking about the ToolJS.config() method.

The ToolJS.config method offers us the ability to configure our ToolJS working environment. This configuration at the moment of this post includes code debugging.

There are useful console logs and warnings that might come in handy during development, but not so much for production. With that said, ToolJS offers a configuration option that disables and enable the debugging of your ToolJS code. Let us see how its done.

// use the config method of the ToolJS class to set debugging to true
ToolJS.config({ debugging: true });

The above code will enable logs to your console during your execution process.

Lets see an example..

Consider the follow html

<p>I am a p tag with no id</p>

And then the following javascript

// use the config method of the ToolJS class to set debugging to true
ToolJS.config({ debugging: true });

// export the DOM module's methods
var $ = ToolJS.export("DOM");

// the below code will fail, because there is no element in the DOM matching the selector
// this will output a log to the console

// trying to get an with to get an element from the DOM with id = "pTag"
var myPara = $.getEl("#pTag");

Lets try another example using one of the methods in the Calc module

// export all the methods in Calc module
var MyCalc = ToolJS.export("Calc");

// the add method only accepts numbers or array of numbers as a parameter,
// so passing it a string would output a warning to the console.
MyCalc.add(4, 4, "Okoro");

See the Pen ToolJS: Code Debugging by Redemption Okoro
(@akaawereniya) on CodePen.

This feature can come in handy when you have bugs, this makes it easier to know what the bug might be.

Conclusion

Debugging is always very useful when coding, thats why this feature was included into the ToolJS library to help debug your ToolJS code

Introduction to ToolJS. A JavaScript Utility Library

Okoro Redemption — Mon, 18 Jan 2021 02:23:48 +0000

This is the first part of a series based on "ToolJS". This part covers the introduction, installation and a bit of the usage.

What is ToolJS

ToolJS is an open-source dependency free library built from the ground-up using plain old javascript, that aims at simplifying the workflow of any developer working in a javascript environment.

It is basically a collection of functions and methods that as a javascript developer, or a front-end developer, will prove useful in development circle.

It comprises of functions that manipulates strings, objects, numbers, DOM elements and even mathematical methods. Think of it as Lodash and JQuery all in one.

This functions are categorized into modules, which can be used independently. The libraries first release comes with six(6) modules which include "DOM", "Obj", "Str", "Num", "Calc", "Util"

Where can it be used

ToolJS was written to ease the working javascript in both Node.js and browser enviroment, which means it offers a version for both.

Installation

ToolJS supports both Node.js and browser environment as do most javascript libraries, which means there is an installation means for both environments.

For Node.js

ToolJS comes with an npm package.

npm install @redeakaa/tooljs

For Browser

Simply include the following script tag below in your html

<script src="https://unpkg.com/@redeakaa/tooljs@1.0.1/dist/umd/tooljs.min.js"></script>

If you want to us ES6 import syntax then, you make your imports from the CDN below

https://unpkg.com/@redeakaa/tooljs@1.0.1/dist/esm/tooljs.esm.js

Usage

The usage is same for both environments, but only depends on how you include the ToolJS library into your work environment

For Node.js, you are required to...well, require😂 the package in your code after installing.

(Note that the npm package and the ESM version of the library uses both named and default exports).

To include the libraries default export

const ToolJS = require("@redeakaa/tooljs).default;

After which you can export any of the libraries registered module, to use its methods.

// this exports all methods from the "Str", "Calc" and "Utils" modules.
var $ = ToolJS.export(["Str", "Calc", "Utils"]);

var total = $.add(10, 50, 40);
console.log(total);
// => 100

var toCamelCase = $.camelCase("Hello World from ToolJS");
console.log(toCamelCase);
// => "helloWorldFromToolJS"

var type = $.typeOf(400);
console.log(type);
// => "number"

You can optionally do a destructing import/require and choose out of the in-built modules to import

const { DOM, Obj, Str, Num, Calc, Utils } = require("@redeakaa/tooljs");

var capitalized = DOM.capitalize("hello world from toolJS");
console.log(capitalized);
// => "Hello World From ToolJS"

var obj = Obj.push({ name: "John Doe", age: 25 }, { gender: "Male" });
console.log(obj);
// => { name: "John Doe", age: 25, gender: "Male" }

For Browser usage, if you include the library using the first CDN provided above in a script tag, then you expose the ToolJS namespace to the window object.

// export all methods in all registered module
var _ = ToolJS.export();

// increment 10 by 5.
var val = _.increment(10, 5);
console.log(val);
// => 15

var odd = _.isOdd(27);
console.log(odd);
// => true"

// gets the element whose id = "#myElement"
var el = _.getEl("#myElement");

// creates a p tag, sets its innerText, applies some style to it and appends it to the body element.
_.createEl("p", {
  innerText: "Hello there! i was created using ToolJS",
  appendTo: "body",
  style: {
    color: "red",
    fontSize: "44px"
  }
});

You can optionally use the ES6 import syntax with the second CDN link provided to either import the libraries default export or any of the its named exports(the modules are the named exports).

var url = "https://unpkg.com/@redeakaa/tooljs@1.0.1/dist/esm/tooljs.esm.js";

import ToolJS from url;
import { Utils, Obj } from url;

// sets a cookie which expires in 14 days
Utils.setCookie("username", "John Doe", 14, "/");

// gets the cookie named "username"
var user = Utils.getCookie("username",);
console.log(user);
// => "John Doe"

var myObj = Obj.toObj(["John Doe", "Male"]);
console.log(myObj);
// => { 0: "John Doe", 1: "Male" }

This was just an introduction to ToolJS. It is one utility library that is sure to ease front-end development.

Here's a link to its official Documentation.

Other features of ToolJS which will be covered later in other posts includes.

Optional Debugging.
DOM Manipulation.
ToolJS Plugin Creation.

Conclusion

This is an open-source collection of functions, methods and routine javascript operations which every front-end developer might have a use for at some point in their project.