jie

Posted on or around March 28, 2017

jie is a lightweight, clean, fast, and easy to use Javascript library. And was born out of wanting a library with a smaller footprint. As I use jQuery day to day at work, and love it. It includes lots of the same features, it also steals a few ideas from Python, negative list indexing is a good example.

Sometimes, you just don't need everything jQuery has to offer..

Getting Started

To get started simply download the minified Javascript file over on my Bitbucket project page, and include this in your HTML document like so...

<script type="text/javascript" src="jie.min.js"></script>

The jie method is the main method of the pie library, it has several functions. Firstly it is a shortcut for window ready. So all of your code should live within a function passed to the pie method. Something like this:

jie(function() {
    print("Hello, world!");
});

It also serves as a way of selecting DOM elements using a valid CSS selector. The elements returned are _JieElements, which are normal DOM elements wrapped in a class that provides us with lots of useful methods, which you can check out by reading the full documentation at the bottom of this page.

An example of selecting all hyperlinks with a class of foo, would be:

var links = jie("a.foo");

As mentioned, any valid CSS selector will work, so it could be as elaborate as:

jie("input[type=text].foo:not(.bar)");

The full documentation can be found at the bottom of this page, but I will be using a few methods below to show you how you can chain method calls.  I don't think I need to explain what is going on here?

jie("ul li").classes("foo").loop(function(li) {
    if(li.hasClass("bar")) {
        li.removeClass("bar");
    }
}).styles("margin", "10px");

jie also extends some of Javascript's types, like String and Array, which is what is covered first in the documentation...

Boolean

::: .then()

jie extends Boolean values with a then method which takes a function as parameter, which will be called if the value is true. Example:

var likeCakes = true;

likeCakes.then(function() {
    print("Eat cakes");
});

::: .otherwise()

The otherwise method takes a function as parameter which is called if the value is false. This can obviously be chained with a call to .then() as well.

var likeCakes = false;

likeCakes.then(function() {
    print("Eat cakes");
}).otherwise(function() {
    print("Learn to like cakes");
});

String

::: .times()

The times method was originally intended to be added to Number, but as you can not call methods of a number literal, I decided to add it to strings that contain numbers as I liked the method so much I didn't want to omit it.

Times takes a function as parameter and calls this function x amount of times, where x is the integer value of the string. The function will receive the current increment as parameter if you require it.

"10".times(function(i) {
    print(i);
});

::: .contains()

The contains method takes a string as parameter and checks wether or not this string contains the string passed in.

if("foobar".contains("foo")) {
    print("Woohoo we have foo!");
}

// Or...

"foobar".contains("foo").then(function() {
    print("Woohoo we have foo!");  
});

::: .startsWith()

startsWith takes a string as parameter and returns wether or not this string starts wth the string passed in.

"foobar".startsWith("foo").then(function() {
    print("We have foo!");
});

::: .endsWith()

Like startsWith, endsWith takes a string as parameter and returns wether or not this string ends with the string passed in.

"foo bar".endsWith("bar").then(function() {
    print("No foo, but bar!");
});

::: .join()

The join method takes an array as parameter and creates a new string by joining the items in the array separated by this string. For instance to create a CSV from a list of names...

var names = [
    "Lee",
    "Mark",
    "Carl"
];

print(", ".join(names));

// This would output Lee, Mark, Carl

::: .upper()

upper is simply a shortcuts for toUpperCase(), and returns the string in upper case.

print("foobar".upper());

::: .lower()

lower is simply a shortcut for toLowerCase() and returns the string in lower case.

print("foobar".lower());

::: .capitalize()

The capitalize method returns the string with the first character in upper case.

print("foobar".capitalize());

::: .print()

Yes, you guessed it, it prints this string.

"foo bar".print();

Array

::: .contains()

Does this array contain the passed in object? That's what the contains method determines.

["Foo", "Bar"].contains("Foo").then(function() {
    print("Foo!");
});

::: .size()

The size method returns how many items are in the array.

var names = ["Lee", "Mark"];
print(names.size()); // Outputs 2

::: .explode()

The explode method creates a string from the array of items separated by the passed in string. For instance to create a CSV from a list of names...

["Lee", "Carl", "Simon"].explode(", ").print()

// This would output Lee, Carl, Simon

::: .loop()

loop takes a function as parameter which is called for every item in the array. The item is passed along with the increment to the function if required...

["foo", "bar"].loop(function(item) {
   print(item);
});

_JieElement

As mentioned earlier, all elements returned from the jie function are wrapped in a special class that adds the useful methods. You don't need to know or use the class directly, but it's called _JieElement.

::: .attributes()

The attributes method allows you to set one attribute, many attributes, get the value of a single attribute, or all attributes depending on the type of parameter passed to it...

// Grab an element
var element = jie("#foobar").first();

// To set the value of a single attribute,
// you pass two strings, the name of the
// attribute and the value to apply to it..
element.attributes("title", "foobar");

// To get the value of a single attribute,
// you pass a single string of the name of
// the attribute to fetch. Be warned, if it
// does not exist we return null
// ( You can use hasAttribute() to test this ).
var value = element.attributes("title");

// To set multiple attributes you pass an object..
element.attributes({
    "title": "foobar",
    "target": "_blank"
});

// And finally to grab all the attributes,
// you pass nothing, and an object is returned..
var attributes = element.attributes();
for(key in attributes) {
    print(key + " = " + attributes[key]);
}

::: .hasAttribute()

hasAttribute returns wether or not an element has said attribute set.

// Grab an element..
var element = $("#foobar").first();

element.hasAttribute("title").then(function() {
    // Do something
});

::: .styles()

The styles method allows you to set a single style, multiple styles, retrieve a single style, or retrieve all styles depending on the parameters passed to it...

// Grab an element
var element = jie("#foobar").first();

// Return all styles by passing no arguments
// This returns an object like:
// {"margin": "10px", "border": "1px solid"}
var styles = element.styles();

// Set a single style by passing two strings
element.styles("margin", "10px");

// Return a single style by passing one string
var margin = element.styles("margin");

// Or set multiple styles by passing an object..
element.styles({
    "margin": "10px",
    "padding": "10px"
});

::: .appendTo()

appendTo appends this element to the element received.

var child = jie("foo").first();
var parent = jie("bar").first();
child.appendTo(parent);

::: .prependTo()

prependTo prepends this element to the element received.

var child = jie("foo").first();
var parent = jie("bar").first();
child.prependTo(parent);

::: .hasClass()

The hasClass method returns a boolean value wether or not the element has a class.

jie("foobar").first().hasClass("foo").then(function() {
    print("We have foo!");
});

::: .classes()

The classes method allows you to set one or multiple classes, or return all classes based on the parameters passed in..

// Grab an element
var element = jie("#foobar").first();

// Return all classes as an array of strings
var classes = element.classes();

// Add a class by passing a single string
element.classes("foo");

// Add one or more classes by passing an
// array of strings
element.classes(["foo", "bar"]);

::: .addClass()

addClass adds a class to the element.

jie("foobar").first().addClass("foo");

::: .removeClass()

The removeClass method removes a class from the element.

jie("foobar").first().removeClass("foo");

::: .on()

The on method attaches an event handler to the element.

// Grab an element
var element = jie("#foobar").first();

element.on("click", function() {
   // Do something
});

element.on("hover", function() {
   // Do something
});

// etc, etc.

_JieElementList

Although you do not need to know the name of this class, its is very important, and all queries made using the jie method return a _JieElementList, which is essentially just an array of _JieElement's ... With some added goodness..

::: .size()

The size method returns the amount of items in the list.

jie("ul li").size();

::: .isEmpty()

The isEmpty method determines wether or not the list is empty.

jie("ul li").isEmpty().then(function() {
    print("Empty");
});

::: .isntEmpty()

The isntEmpty method determines wether or not the list is empty.

jie("ul li").isntEmpty().then(function() {
    print("Not empty");
});

::: .first()

The first method returns the first element (_JieElement) in the list if it has one. You can use the isEmpty and isntEmpty methods to test.

jie("ul li").first();

::: .last()

The last method returns the last element(_JieElement) in the list if it has elements. You can use the isEmpty and isntEmpty methods to determine this.

jie("ul li").last();

::: .get()

The get method returns the element at the given index if it exists. You can also use negative indexing...

var lis = jie("ul li");

var firstLi = lis.get(0);
var lastLi = lis.get(-1);

::: .loop()

The loop method calls the passed in function for each element in the list, passing the element and the increment if required.

jie("ul li").loop(function(li, i) {
    print(i);
});

::: .contains()

The contains method checks to see wether or not the list contains the given element.

var lis = jie("ul li");
var firstLi = lis.first();

lis.contains(firstLi).then(function() {
    print("Yup!");
});

::: .attributes()

The attributes method calls the attributes method on all element within the list.

jie("ul li a").attributes("target", "_blank");

::: .styles()

The styles method calls the styles method on all elements in the list.

jie("ul li").styles({
    "margin": "10px",
    "padding": "10px"
});

::: .appendTo()

The appendTo method appends all elements within the list to the given element.

var footer = jie("footer").first();
jie("ul li").appendTo(footer);

::: .prependTo()

The prependTo method prepends all elements within the list to the given element.

var footer = jie("footer").first();
jie("ul li").prependTo(footer);

::: .on()

The on method attaches an event listener to each element in the list.

jie("ul li a").on("click", function() {
   alert("clicked");
});

Tagged:

I have very kindly tagged this item so you can find similiar stuff.

Javascript Development Web Project Code