Overview

Qbix contains code for PHP, Node.js and front end Javascript, which works together to power social apps. What normally happens when a user accesses a web page is that PHP generates an HTML file (or a cached version is returned) and then the front-end Javascript loads and executes. The client may send requests to the PHP server to pull more data, or post some messages (which modify the state of the back end system), and optionally connect to a Node.js server which could push messages to the client in real time.

The web front end

As a complete framework for creating social apps, Qbix comes with an extensive front-end API designed to facilitate interaction with the PHP and Node.js back end servers.

By default, your app already includes Q.js which is relatively small and efficient, and works well alongside jQuery, Angular JS, prefixfree and other libraries.

(If you are already using a library called Q, such as this one, simply call Q.noConflict() anytime after including all your Javascript files, such as in your app's JS file. Although you don't even have to do that, since the Qbix Platform works alongside it, too.)

Best Practices

In general, it is a good idea to write your front end first — keeping it as self-sufficient as possible — and add the back end later (mostly as a set of web services), as this minimizes the load on the web server, and makes your application more responsive.

Objects

Qbix has some basic methods for working with objects:

• Q.typeOf returns the type of something
• Q.each can iterate over objects, arrays, etc.
• Q.first returns the first value found, if any
• Q.copy clones objects in an intelligent way
• Q.extend merges objects on top of others

Q.extend

In particular, Q.extend(a, 2, b) is used extensively when merging trees of options and other things. It proceeds recursively, and you can specify how many levels to traverse and merge. The rules are:

• Merging any scalar (Number, String, Boolean, null, etc.) on top of anything replaces it
• Merging undefined on top of anything deletes it
• Merging Array or Object on top of a scalar replaces it (with a copy, unless the object type has been added to
• Q.extend.dontCopy(Q.typeOf(object)))
• Merging Object on top of Object adds/replaces keys in the target object
• Merging Array on top of Array results in a concatenated array
• Merging Object {"replace": Array} on top of Array replaces the array
• Merging Function on top of Q.Event adds a handler to that event
• Merging {"someKey": Function} on top of Q.Event adds event handler with key "someKey"
• Merging Q.Event on top of Q.Event adds all its handlers with their keys

You can read more about extending events on the Javascript Events page. Q.extend modifies its first parameter, so if you want to get a new object back, you would pass it as the first parameter, like this to extend it with options 2 levels deep: Q.extend({}, defaults, 2, options)

Functions

Many functions f implemented by the Qbix framework will accept an options argument. By convention, these functions also have an f.options property which contains the default values for these options, so that you can modify the defaults if needed.

You are encouraged to implement this convention in your own functions. Here is the simple pattern:

First.method = function (r1, r2, options) {
  // extend up to 10 levels deep
  var o = Q.extend(
    {}, First.method.options, 10, options
  );
  // now use o instead of options
};

// defaults
First.method.options = {
  max: 1,
  template: { ... },
  fields: { ... }
}

Helpers

The following is a list of helper functions found in Q.js, which you can find out more about in the API Reference:

String.prototype

toCapitalized, isUrl, encodeHTML, decodeHTML, quote, interpolate, replaceAll, queryField, parseUrl, sameDomain

HTMLElement.prototype

contains, isOrContains, isBefore, swap, computedStyle, copyComputedStyle, preventSelections, restoreSelection, addClass, removeClass, hasClass, Q (see here)

Qbix Utility functions

has, diff, take, first, firstKey, shuffle, isEmpty, isInteger, isPlainObject, setObject, getObject, mixin