phoenix-common

Basic common functions for Phoenix JS packages: namespaces and classes


Install
bower install phoenix-common

Documentation

Phoenix Common.js

A set of simple utilities for namespacing, inheritance, DOM selection, and helpers.

Getting Started

Get Via Bower (recommended)

Add

"dependencies": {
    "phoenix-common": "~0.3"
  },

to your bower.json file or run bower install phoenix-common --save

Or Download Zip File

You may also download the latest release or the master branch from http://github.com/phoenix-labs/common.js

Installation and Dependencies

Add <script src="dist/phoenix.common.min.js"></script> to your <head> By default, all methods are contained in window.px or just px.

Namespace

Namespace objects, classes, and properties in javascript.

var ns = px.namespace("Phoenix.Whatever.Namespace");
ns.New = function() {};

Will automatically create an Phoenix object under window, a Whatever object under Phoenix, and a Namespace object under Whatever.

You can also attach the namespace to a specific parent:

var Phoenix = {};
var ns = px.namespace("Whatever.Namespace", Phoenix);

This will contain the namespace to the local scope, not the window scope.

Navigating Namespaces

Each namespace object has an up() method that allows you to move up the namespace chain.

var ns = px.namespace("Yet.Another.Test.Namespace");
var another = ns.up(2);
// another === Yet.Another

Note that up() does not count the current namespace.

Also note that it is possible to add namespace to a function or other object, but you cannot (yet) move up past that object. Here is what I mean.

var ns = px.namespace("One.Two");
ns.Three = function() {};
var nsB = px.namespace("One.Two.Three.Four");

Now, nsB return the namespace object Four. But if you use .up(2), an error is produced. See Issue #10

Classes and Inheritance

Why does the world need another class system for Javascript? It doesn't really, except that this is uber small and not connected to a ton of other libraries. Therefore, you can use it alone. It also has a simpler interface (in our opinion).

Building a Class

Create a plain, empty class

var myClass = px.makeClass();
var myInstance = new myClass();

Or, add as many methods and properties to the class's prototype as you like.

var myClass = px.makeClass({
    one: 1,
    two: function() { return 'has_method' }
});
var myInstance = new myClass();
//myInstance.one = 1
//myInstance.two() returns 'has_method'

Even add a constructor that is called upon instantiation

var myClass = px.makeClass({
    constructor: function (param) {
        this.param = param;
    }
});
var myInstance = new myClass('testing');
// myInstance.param === 'testing'

Lastly, if you have a function or class you would like to add methods or propeties to, use extendClass()

var baseClass = function() {};

px.extendClass(baseClass, {
    a: "A",
    b: function() { return "B"}
});

var instance = new baseClass(); // now has a and b()

Inheritance

Extend a base class:

 var myFirstClass = px.makeClass({
    testMethod: function () { return 'test_method' }
});

var mySecondClass = px.makeClass({
    extends: myFirstClass
});

var myInstance = new mySecondClass();

// myInstance.testMethod returns 'test_method'
// myInstance instanceof myFirstClass
// myInstance instanceof mySecondClass

You can also inherit constructors:

var myFirstClass = px.makeClass({
    constructor: function(param) {
        this.param = param;
    }
});

var mySecondClass = px.makeClass({
    extends: myFirstClass,
    testMethod: function() {
        return this.param;
    }
});

var myInstance = new mySecondClass('testing');
// myInstance.param === 'testing'

Override constructors:

var myFirstClass = px.makeClass({
    constructor: function(param) {
        this.param = param;
    }
});

var mySecondClass = px.makeClass({
    extends: myFirstClass,
    constructor: function(param) {
        this.param = 'override ' + param;
    }
});

var myInstance = new mySecondClass('testing');
// myInstance.param === 'override testing'

And call parent constructors

var myFirstClass = px.makeClass({
    constructor: function(param) {
        this.param = param;
    }
});

var mySecondClass = px.makeClass({
    extends: myFirstClass,
    constructor: function(first, second) {
        mySecondClass.parent.constructor.apply(this, arguments);
        this.second = second;
    }
});

var myInstance = new mySecondClass('first', 'second');
// myInstance.param === 'first'
// myInstance.second ==='second'

DOM Select

A very simple DOM selector. Really just a basic wrapper for API consistency

Select by class or id

px.select('.class-name');
px.select('#id-name');

Returns either a node list, or the HTML object.

Select by another attribute

Think of this a select "something" by "attribute". Right now, only the attribute name is supported and tested.

// Select a form by its name
px.select('my-form', 'name');

Returns either a node list, or the HTML object.

Helpers

Why does the world need another class system for Javascript? It doesn't really, except that this is uber small and not connected to a ton of other libraries. Therefore, you can use it alone. It also has a simpler interface (in our opinion).

px.isCallable()

Returns true or false if a parameter can be executed as a function

isCallable(object);

Contributing

Phoenix Labs is a non-profit organization developing community-driven experiments in collaboration and content. "Community Driven" is more than just a slogan. It's a core value. Everything we do is for the community and by the community. Collaboration on any of the projects is welcome.

To contribute to this project (one of the Backstage packages):

  • Fork or clone this repository. All work is done in the development branch which may have many feature branches. The master is always the latest, production ready release.
  • Build the library on your local machine.
    1. Make sure that node, gulp, and bower are installed.
    2. Run gulp install in the terminal. This will install all dependencies and build library files.
    3. If this didn't work, just run bower install and npm install and gulp build
  • Commit your changes. All active files are in the /src/ directory.
  • Build again with gulp build
  • Test as needed. Write tests and add them to one of the test suites in /tests/. Please write new tests as needed and make sure you didn't break another test.
  • Issue a Pull Request on this repository.

Be sure to be active. All discussion takes place in issue. Phoenix Common.js is licenced under the MIT open source licence.