zerotohero-dev / o2.js

A Coherent Solution to Your JavaScript Dilemma

NOTE

This project is no longer maintained (at least for a while).

If you want to be the maintainer of it contact me at [email protected]

Although this branch is (by definition) stable, it's missing a lot of features since it's being rewritten.

The recent 1.x version with a larger feature set may be found at https://github.com/v0lkan/o2.js/releases/tag/v.0.25.8

...

In Progress…

read CONTRIBUTE.md for now.

also read INSTALL.md for installation instructions.

Installation

…

Dependencies

Each folder in src/o2/ is a separate NPM module.

Although some these modules depend on one another, the dependencies are not explicitly set in package.json; instead these dependencies are checked at runtime as in…

var o = require('../object/core'),

    ...

    if (!o) {
        throw new Error('Please run `npm install o2.object` first.');
    }

So if you see an error message in the console, make sure you npm install necessary modules first.

Release Policy

// TODO: to be edited. This is a very rough outline right now.

Versions are in the form MAJOR.MINOR.PATCH

• PATCH: (backwards compatible) bug fixes (no new features)
• MINOR: (backwards compatible) features
• MAJOR: non-backwards-compatible changes.

every feature/bugfix to be added is forked into a feature branch (under features/branchname)

feature branches branch off from develop and merge back to develop.

every release branch branches off from develop and merges back to develop and master

release branches should not contain featured (i.e., only minor version increases in release branches)

release branch is higher than the version number in package.json

for for version: 2.0.12 the release branch should be at least 'release-2.1'.

before merging, make sure that the release branch does not have any CI build failures.

more info at http://semver.org/ and http://nvie.com/posts/a-successful-git-branching-model/

o2.js's Issues

A form serializer would be nice.

finish o2.extend.js

finish o2.extend.js

update js-doc documentation

1. the new update removed the namespaces from the js-doc documentations. add those namespaces back
2. some of the method signatures and behaviors have changed (especially in DomHelper modules) update them as well.

some of the functions are closing over DOM nodes, avoid it.

For example:

    el = $(el);

    if (!el) {
        return null;
    }

    if (el.querySelectorAll) {
        me.getElementsByClassName = function(el, c) {
            el = $(el);

            if (!el) {
                return null;
            }

            return el.querySelectorAll(['.', c].join(kEmpty));
        };

        return me.getElementsByClassName(el, c);
    }

The closure closes over el, it's a bad in terms of memory utilization. We should take the closure out.

new method: o2.DomHelper.getElementsByTagName

it will be a simple wrapper, just for the sake of completeness.

Add documentation

which means implementing jGrouseDoc.

use first-of-type to speed up o2.DomHelper.first when possible.

also iterate through all DomHelper traversal methods.

additional methods to o2.domhelper.traverse

getChildrenById
getChildrenWithId
getChildrenByAttribute
getChildrenWithAttribute

import all TODO:// 's in the source code as github issues here.

We should be tracking things to be done from github, not from the source code.

o2.DomHelper.getChildren(elem) can take an optional nodename parameter

o2.DomHelper.getChildren(elem) can take an optional nodename parameter

test o2.DomHelper.loadXXX methods in a wide array of browsers

Those callbacks may behave browser-specific and they need to be thoroughly tested.

DomHelper additional methods required.

---> todo: create a getParentWithStyle method
---> todo: create a getParentWithClass method
--> todo: add get**_withStyle and get**_withclass methos.,
getParentByStyle
getParentByClass
getParentbyAttribute

getParentWithAttribute classname fix required

    getAttribute : function(obj, attribute) {
        obj = $(obj);

        if(!obj || !attribute) {

            return null;
        }

        ///////////////////////////////////////////////////////
        if(attribute == 'class'  || attribute == 'className'){
            var value = obj.className;

            if(value !== UNDEFINED) {

                return value;
            }                
        }
        //////////////////////////////////////////////////////


        if( typeof obj.getAttribute == 'function') {

            var value = obj.getAttribute(attribute);

            if(value !== UNDEFINED) {

                return value;
            }
        }

        return obj[attribute] ? obj[attribute] : null;

    }

};

o2.ui.Slider

A slider component that utilizes the Droppable for the sliding operations.

create an easing function generator

This will be useful for the Effect module.

o2.ui.Droppable

A droppable component that utilized HTML5 drag drop api when possible and uses a fallback technique otherwise.

Templating engine o2.Template needs some improvements for practical use.

Currently o2.Template is damn fast.
It's faster than jqtemplate and/or any other templating engine around.
But it needs certain enhancements, such as

• a basic if/else structure
• loop variables
• commands other than "each".

cache commonly used functions in modules as static "aliases" in modules.

... and also cache those aliases if they are excessively used within loops.

for instance:

/*
 * Aliases.
 */
var toCamelCase = o2.StringHelper.toCamelCase;

...

me.addStyle = function(obj, style) {

    var toCamelCaseCached = toCamelCase;

    if(!obj || typeof obj != 'object') {
        return;
    }

    for(var key in style) {
        if(style.hasOwnProperty(key)) {
            obj.style[toCamelCaseCached(key)] = style[key];
        }
    }

};

convert dependencies, license, and readme to .md files

it'd be nice to convert all these documentation files in markdown format.

o2.DomHelper.loadCss should accept success and fail callbacks.

Well this is way too complicated than the o2.DomHelper.loadScirpt case.

Here are a dozen of people who have struggled with the issue, without much luck (in terms of cross-browser support, without using browser sniffing, or nasty hacks)

http://www.phpied.com/when-is-a-stylesheet-really-loaded/
http://plugins.jquery.com/files/jquery.xLazyLoader.js.txt

polling the cssRules collection is an option, but it will fail if the css is going to be loaded from a different domain.
http://www.zachleat.com/web/load-css-dynamically/

we can use something like

// dummy element in the html

// dummy element in the css

cssloaded { height:1px; }

but it's a "nasty" hack. and if we don't have control over the css we're gonna load, it will not work as well.

And here are a set of bugs in different browsers, regarding the issue:
https://bugs.webkit.org/show_bug.cgi?id=38995 (that's open)
https://bugzilla.mozilla.org/show_bug.cgi?id=185236 (that's fixed)
http://code.google.com/p/chromium/issues/detail?id=67522 (that's open)

Besides, I don't see any use (other than fullfilling academic curiosity) of detecting when a stylesheet has loaded, or failed; and firing callbacks afterwards.

So I need to think about this...

complete TODO's

A lot of TODO's have accumulated in the source code. complete and remove them.

write a cross-browser caret finder /helper.

this will be a utility for a text-editor maybe.

o2.DomHelper.loadScript should accept a success callback, and a failure callback

This can be done using script's onload/onreadystatechange (depending on the browser) and onerror even handlers (with an IE caveat, as always)

Loading a script with an error HTTP response:
Firefox 3.5: onerror
Safari 4: onerror
Chrome 4: onerror
IE 7: onreadystatechange
IE 8: onreadystatechange

Loading a good script:
Firefox 3.5: onload
Safari 4: onload
Chrome 4: onload
IE 7: onreadystatechange (if not cached)
IE 8: onreadystatechange (if not cached)

so...
The onerror attribute works on all browsers but IE.
For IE, onreadystatechange is available.
No browser supports both of them, so a handler hooked up to both of them will fire exactly once.

A timer can be used to detect load failures in IE (say, the attempt times out after 20 seconds)

Another complication on IE is that onreadystatechange doesn't differentiate whether the download succeeded or not. Downloading a non-cached version looks the same as a download failure.
Thus, any code using onreadystatechange needs to check whether the download succeeded or not.
Another option would be to disable caching in IE by ammending a random number to the end of the script, but that is counter-productive.

I have to think about all these.
I may not provide a failure callback, if I'm not satisfied with the method's cross-browser behavior.

complete o2.DomHelper.dimension.js

it has missing methods to be implemented.

Add usage examples to the documentation of o2.MethodHelper.* functions

some of those functions are really convoluted and documentation is not enough. a few simple examples are necessary.

o2.DomHelper.getElementsByClassName should also take a list of class names instead of a single class

perhaps a comma delimeted list of classes.

o2.DomHelper scroll with ease

Add easing and animation to DomHelper scorlls...

... this will have to wait o2.Effect object.

Additional o2.DomHelper.get*** Methods

//TODO: getChildrenById & comma delim

//TODO: getChildrenWithId & comma delim

//TODO: getElementsById & comma delim

//TODO: getElementsWithId & comma delim

//TODO: getElementsByAttribute & comma delim & space delim

//TODO: getElementsWithAttribute & comma delim & space delim

//TODO: getElementsByClassName belongs here & comma delim & space delim

//TODO: getElementsWithClassName & comma delim & space delim

//TODO: getFirstChildById

//TODO: getFirstChildWithId

//TODO: getLastChildById

//TODO: getLastChildWithID

//TODO: getFirstChildByClassName

//TODO: getFirstChildWithClassName

//TODO: getFirstChildByAttribute

//TODO: getFirstChildWithAttribute

//TODO: getLastChildByAttribute

//TODO: getLastChildWithAttribute

Enhance o2.CollectionHelper

each, map, reduce, detect, select, reject, all, any, include, invoke, pluck, max, min, sortBy, groupBy, toArray, sizeOf, first, rest, last, compact, flatten, without, union, intersection, difference, uniq, zip, indexOf, lastIndexOf, range, bind, bindAll, memoize, delay, defer, throttle, debounce, once, after, wrap, compose, keys, values, functions, extend, defaults, clone, tap

are a few methods that can be added

implement a PHP counterpart for the template engine.

The o2.Template class uses JavaScript arrays as a basis for templating.
And this enables extremely fast and efficient template rendering when compared to alternatives (such as mustache)

[
    "<ul>",
    [
        "each users",
        [
            "<li>{name}</li>"
        ]
    ],
    "</ul>"
]

Yeah I know, o2.Template is incomplete and its rule engine is rather primitive. But that's not the point.
The point is; it's darn fast!

The good part is that the above template expression is also a valid JSON. -- which means that it can be easily converted to a PHP nested array. This will enable us implement the same templating logic in the PHP side as well.

Therefore we can have identical server-side and client-side rendering of the templates.

complete inline TODO:'s inside the code.

either do them,
or assign them as issues here.

complete o2.extend.js and add documentation to it.

Identify which platforms does o2.js target

I plan to support IE7+ (and to hell with IE6)

The core objects will be platform-agnostic, they will be equally usable in mobile and desktop browsers.
Though individual mobile plug-ins / components may be developed on the long run.

...

Anyway, once you are clear with which platforms you support, add it to the README file.

Write a formatting guideline, on what conventions are used in o2.js

(indendations, naming conventions, spaces etc.)

there are new //TODO's inside the code. either fix 'em or add 'em as issues here.

There are new TODO's inside the code (and that's normal, since it's a living project).
Handle them.

Prepare Unit Tests

Before that, a simple unit testing framework should be built.

I plan to extend o2.Debugger object for this purpose.

The unit testing framework will not be anything fancy.
Just simple assertion functions and basic methods.
... and a "runner" module to run all the unit tests consequentially and collect results.

utilize get bounding rect in offset calculations

http://ejohn.org/blog/getboundingclientrect-is-awesome/

StringHelper.trimLeft, StringHelper.trimRight

trimRight -> trim trailing spaces (may be for source code formatting)
trimLeft -> trim leading spaces

me want UI components!

    Autocompleter
    Calendar
    Colorpicker
    Dialog
    In Place Edit
    Lightbox
    Rater
    Resizable
    Rte
    Selectable
    Slider
    Sortable
    Tabs
    Tags
    Tooltips
    Uploader

are a few.

add o2.EventHandler.removeEventListener* methods

    //TODO: removeAllEventListeners (obj)
    //TODO: removeAllEventListeners (obj, eventName)
    //TODO: removeAllEventListeners (eventName)
    //TODO: removeAllEventListeners ()

o2.DomHelper.get*** methods should be able to select multiple attributes, ids etc.

//TODO: I can have a space delimeted list of attributes.  (OR)
//TODO: I can also have a comma delimeted list of attributes. (AND) or a
// combination of two 'attr1,attr2 attr3 attr4,attr5 attr6' (comma is OR
// space is AND)

o2.DomHelper.strip*** additional methods

stripAlpha -> strips a-zA-Z leaving numbers and symbols like "-" and "." .

add some kind of dependency management to modules.

similar to closure's

goog.require
and
good.provide functions.

o2.StringHelper.stripTags can have an array of tags as a paremeter

not ALL tags, but some tags may need to be stripped.

add comma-delimeted multiple classes as selectos to getXXXbyYYY methods.

for instance.
me.getChildrenByClassName = function(el, c) {

add examples

It will be better to start adding examples after having completed the unit tests.

o2.DomHelper.get*** methods should be able to select more than one classname, id, tags etc.

this may be a duplicate issue.

for instance

o2.DomHelper.getElementsByClassName(node, 'class1, class2');

should return all the inner nodes with "class1" OR "class2" as a classname.

o2.DomHelper.getElementsByClassName(node, 'class1 class2');

should return all the inner nodes with "class1" AND "class2" as a classname.

All the getters should be revised accordingly.

The end-result will NOT be a sizzle-like selector engine, though. Because giving too much selector freedom ofter results in a performance sacrifice. -- In fact, imho in 99% of the cases document.getElementById is the best selector possible. -- and if one does not bother to give a darn ID to their elements, they are in the wrong path, and I do not want to lead them further into that path.

o2.ui.MultiSelect

a multi select component

o2.DomHelper.scroll* methods should take an optional offset argument

may be I want to scroll to slightly below or above a given object

let o2.StringHelper.encode take an optional "map" argument

so that people can plug their own mappings in.

same is true for o2.StringHelper.decode