File: Readme

Recommend this page to a friend!
  Classes of Dong Nguyen   BellaJS   Readme   Download  
File: Readme
Role: Documentation
Content type: text/markdown
Description: Readme
Class: BellaJS
Utility library that works on browser and Node.js
Author: By
Last change: Up to 3.5.1
Date: 9 years ago
Size: 11,955 bytes
 

Contents

Class file image Download

bella.js

BellaJS is a lightweight library with the useful functions for handling string, array, date, schedule and dom/event. It supports both Node.js and browser environments.

Setup

In Node.js:

npm install bellajs

And then:

    var Bella = require('bellajs');
    console.log(Bella.date.utc());

In the browsers

Assuming there is a file bella.min.js located at "/public/js/lib/", the following ways can be used to include BellaJS:

Using SystemJS

    System.config({
        baseURL: '/public/js/lib',
        map: {
            bella: 'bella.min'
        }
    });

    System.import('bella').then(function(Bella){
        console.log(Bella.date.utc());
    });

Using RequireJS

    require.config({
        baseUrl: '/public/js/lib',
        paths: {
            bella: 'bella.min'
        }
    });

    requirejs('bella', function(Bella){
        console.log(Bella.date.utc());
    });

Using traditional script tag

<script type="text/javascript" src="/public/js/lib/bella.min.js"></script>

Usage

Methods

DataType detection

- Bella.isString(Anything val) - Bella.isNumber(Anything val) - Bella.isObject(Anything val) - Bella.isArray(Anything val) - Bella.isFunction(Anything val) - Bella.isBoolean(Anything val) - Bella.isElement(Anything val) - Bella.isDef(Anything val) - Bella.isNull(Anything val) - Bella.isEmpty(Anything val)

Device detection

- Bella.detectDevice([String userAgent])

In the browsers, this method automatically executes and its result - current browser info - is being set to Bella.device object.

In Node.js environment, this method can be used to detect the device with it the request has been sent. Here is an example:

var Bella = require('bellajs');

var server = require('http').createServer(function(req, res){

    res.writeHeader(200, {'Content-Type': 'text/plain'});
    res.write('Running...');

    var ua = req.headers['user-agent'];

    // Let's BellaJS parse userAgent string
    var deviceInfo = Bella.detectDevice(ua);

    // see how does it look like:
    console.log(deviceInfo);

    res.end();
});

var port = 8080;
server.listen(port, function(){
    console.log('Running at http://127.0.0.1:%s', port);
});

An another example with ExpressJS:

var Bella = require('bellajs');

var express = require('express');

var app = express();

app.use(function(req, res, next){

    var ua = req.headers['user-agent'];

    // Let's BellaJS parse userAgent string
    var deviceInfo = Bella.detectDevice(ua);

    // see how does it look like:
    console.log(deviceInfo);

    // or attach to response object to reuse at another place
    res.device = deviceInfo;

  next();
});

var port = 8080;
app.listen(port, function(){
  console.log('Running at http://127.0.0.1:%s', port);
});

String manipulation

- Bella.createId(Number length [, String prefix]) - Bella.encode(String s) - Bella.decode(String s) - Bella.trim(String s) - Bella.strtolower(String s) - Bella.strtoupper(String s) - Bella.ucfirst(String s) - Bella.ucwords(String s) - Bella.escapeHTML(String s) - Bella.unescapeHTML(String s) - Bella.stripTags(String s) - Bella.truncate(String s, Number limit) - Bella.leftPad(String s, Number limit, String pad) - Bella.rightPad(String s, Number limit, String pad) - Bella.replaceAll(String s, String|Array search, String|Array replace) - Bella.md5(String s) - Bella.sha256(String s)

Array & Object

- Bella.inherits(Proto o) - Bella.clone(Array|Object|Date o) - Bella.copies(Array|Object src, Array|Object dest [, Boolean mustMatch[, Array exclude] ]) - Bella.unique(Array a) - Bella.max(Array a) - Bella.min(Array a) - Bella.empty(Array a) - Bella.contains(Array a, String|Object search [, String key]) - Bella.sort(Array a [, String order | Object option ])

How to use Bella.sort?

var a = [1, 5, 19, 6, 4, 11, 7, 22, 40, 3, 8];
console.log('Array a, default:');
console.log(a);

console.log('Array a, from lower to higher:');
var a1 = Bella.sort(a);
console.log(a1);
console.log('Array a, descendant:');
var a2 = Bella.sort(a, -1);
console.log(a2);

var players = [
    {
      'name': 'Jerome Nash',
      'age': 24
    },
    {
      'name': 'Jackson Valdez',
      'age': 21
    },
    {
      'name': 'Benjamin Cole',
      'age': 23
    },
    {
      'name': 'Manuel Delgado',
      'age': 33
    },
    {
      'name': 'Caleb McKinney',
      'age': 28
    }
];

console.log('\nList of players as it is:');
players.forEach(function(item){
    console.log([item.name, item.age].join(' | '));
});

console.log('\nSort by age from young to old:');
var players1 = Bella.sort(players, 'age');
players1.forEach(function(item){
    console.log([item.name, item.age].join(' | '));
});

console.log('\nAnd then reverse them:');
var players2 = Bella.sort(players, {age: -1});
players2.forEach(function(item){
    console.log([item.name, item.age].join(' | '));
});

DateTime

- Bella.date.format(String pattern, Date|Number|String input) - Bella.date.relativize(Date|Number|String input) - Bella.date.local(Date|Number|String input) - Bella.date.utc(Date|Number|String input) - Bella.date.strtotime(String input) - Bella.date.pattern([String pattern])

Default pattern is 'D, M d, Y H:i:s A'. Without any parameter, Bella.date.format() return a string related to current time, in the format of default pattern.

BellaJS' datetime pattern is familiar with PHP developers than MomentJS. The available characters in the pattern are:

- Y: full year, ex: 2050
- y: short year, ex: 50
- F: full month name, ex: August
- M: short month name, ex: Aug
- m: month index with zero, ex: 08 (in 08/24/2050)
- n: short month name with no zero, ex: 8 (in 8/24/2050)
- S: the ordering subfix for date, ext: 1st, 2nd, 3rd, 4th
- j: day of the month, with no zero, ex: 3 (in 18/3/2050)
- d: day of the month, with zero, ex: 03 (in 18/03/2050)
- t: date in year
- w: weekday in number
- l: long name of weekday, ex: Sunday
- D: short name of weekday, ex: Sun
- G: hour, with no zero: 0 - 24
- g: hour, with no zero: 0 - 12
- h: hour, with zero:  00 - 24
- H: hour, with zero:  00 - 12
- i: minute:  00 - 59
- s: second:  00 - 59
- a: am, pm
- A: AM, PM
- O: timezone

Examples:

    // default datetime (local)
    var t = Bella.now();
    console.log(t);

    // format it as YYYY/MM/DD hh:ii:ss
    var f = Bella.date.format('Y/m/d H:i:s', t);
    console.log(f);

    // this is a time in future

    var atime = 80616962585961;
    console.log(atime);

    // display it as your local time
    var local = Bella.date.local(atime);
    console.log(local);

    // display it as GMT time
    var utc = Bella.date.utc(atime);
    console.log(utc);

    // display it with default pattern
    var s = Bella.date.format(false, atime);
    console.log(s);

Scheduler

- Bella.scheduler.every(String pattern, Function callback) - Bella.scheduler.once(String pattern, Function callback) - Bella.scheduler.hourly(String pattern, Function callback) - Bella.scheduler.daily(String pattern, Function callback) - Bella.scheduler.monthly(String pattern, Function callback) - Bella.scheduler.yearly(String pattern, Function callback)

Scheduler is the best utility BellaJS provides. Almost cases you can use Bella.scheduler instead of setInterval or setTimeout, because it runs only one timer for the entire process. Regarding parameter "pattern" for Bella.scheduler.every, it may be:

1, A string in the format of 'Y m d H i s'.

For example:

- Bella.scheduler.every('2040 05 16 15 30 10', callback);
   --> run callback at 15:30:10 on May 16, 2040
- Bella.scheduler.every('* 05 16 15 30 10', callback);
   --> run callback at 15:30:10 on May 16 of years
   --> similar to yearly('05 16 15 30 10', callback)
- Bella.scheduler.every(' 16 15 30 10', callback);
   --> run callback at 15:30:10 on the 16th of months
   --> similar to monthly('16 15 30 10', callback)
- Bella.scheduler.every(' * 15 30 10', callback);
   --> run callback at 15:30:10 of days
   --> similar to daily('15 30 10', callback)
- Bella.scheduler.every('  30 10', callback);
   --> run callback at the 10th second of the 30th minute of hours
   --> similar to hourly('30 10', callback)
- Bella.scheduler.every('  * 10', callback);
   --> run callback at the 10th second of minutes.

2, A string in the format of 'weekday H:i:s'.

For example:

- Bella.scheduler.every('sunday 15:30:10', callback);
   --> run callback on Sundays at 15:30:10
- Bella.scheduler.every('sunday 15:30', callback);
   --> run callback on Sundays at 15:30:00
- Bella.scheduler.every('sunday 15', callback);
   --> run callback on Sundays at 15:00:00

It's possible to use "sun" instead of "sunday", "mon" for "monday", and so on.

3, A string in the format of 'N unit'.

For example:

- Bella.scheduler.every('5m', callback)
   --> call callback every 5 minutes
- Bella.scheduler.once('5m', callback)
   --> call callback in 5 minutes, then stop

The available units: d (days), h (hours), m (minutes), s (seconds).

Bella.scheduler.once do the same thing as Bella.scheduler.every, but just once. The 4 remain methods yearly(), monthly(), daily(), hourly() can be looked as the shortcuts of every().

The following Bella.dom and Bella.event are not available in Node.js environment.

DOM & Event manipulation

- Bella.dom.ready(Function callback) - Bella.dom.one(String selectors) - Bella.dom.all(String selectors) - Bella.dom.get(String ID) - Bella.dom.add(Element|String tag [, Element parent]) - Bella.dom.create(Element dom) - Bella.event.listen(String|Element s, String eventName, Function callback) - Bella.event.ignore(String|Element s, String eventName, Function callback) - Bella.event.simulate(String|Element s, String eventName) - Bella.event.exit(Event e) - Bella.event.locate(Event e)

The HTML DOM Element returned by Bella.dom's methods have several helpful functions as below:

- hasClass(String className) - addClass(String className) - removeClass(String className) - toggleClass(String className) - html([String html]) - empty() - destroy()

BellaJS DOM vs jQuery 2.x DOM : http://jsperf.com/bellajs-dom

Examples:

Bella.dom.ready(function(){

    // Add a new element to document.body
    var container = Bella.dom.add('DIV');

    // then add a DIV element into container
    var div1 = Bella.dom.add('DIV', container);

    // then add a class "sub-item" to child DIV
    div1.addClass('sub-item');

    // more a child DIV
    var div2 = Bella.dom.add('DIV', container);

    // also add a class "sub-item"
    div2.addClass('sub-item');

    // now, we can extract list of elements by class name:
    var subItems = Bella.dom.all('.sub-item');

    console.log(subItems);


    // create a button
    var btn = Bella.dom.add('BUTTON');

    // set label
    btn.html('Say Hello!');

    // set an event listener
    Bella.event.listen(btn, 'click', function(){
        alert('Hello! How it\'s going?');
    });

    // simulate a click event on there (it works as same as jQuery.trigger method)
    Bella.event.simulate(btn, 'click');

});

Properties

- Bella.id - Bella.device (browser only)

Test with Jasmine

/test/SpecRunner.html