Capri

globalNamespace

Namespaces

Fields

$global

Global namespace
Assumes window within a web browser or global in nodejs.
Source:
module/core.js, Line: 15    ( Module: capri/core )

Methods

$class(name, members, [staticMembers]) -> {object}

Define new class using the classical approach
Supported Features:
  • Inheritance and Polymorphism
  • Object constructor
  • Static members
  • Static constructor
See
Source:
module/oop.js, Line: 191    ( Module: capri/oop )
Parameters
Name Type Argument Description
name string
Name of class (may optionally specify namespace)
members object
Per-instance methods, fields, etc.
staticMembers object <optional>
Static methods, fields, etc.
Returns:
Class reference
Type
object
Examples

Ex#1. Define class for product details

$class('ProductDetails', {
   __construct: function(type, title, price) {
      this.type = type;
      this.title = title;
      this.price = price;
   },
   toString: function() {
      return this.type + ': ' + this.title + ' ($' + this.price + ')';
   }
});

Ex#2. Usage of product details class

book = new ProductDetails('book', 'War of the Worlds', '4.99');
console.log(book.toString());

Ex#3. Mathematical vector with usage example

$class('mygame.Vector2d', {
   __construct: function(x, y) {
      this.x = x || 0;
      this.y = y || 0;
   },
   normalise: function() {
      var mag = this.magnitude();
      this.x /= mag;
      this.y /= mag;
   },
   magnitude: function() {
      return Math.sqrt(this.x * this.x + this.y * this.y);
   },
   dot: function(b) {
      return this.x * b.x + this.y * b.y;
   },
   smallestAngle: function(b) {
      // Convert from radians to degrees
      return Math.acos(this.dot(b)) * 57.2957795;
   }
},{//STATIC
   __static: function() { // static constructor
      // this is alias of mygame.Vector2d
      this.north = new this(0, -1);
   }
});

// Unit vector for velocity of entity
vel = new mygame.Vector2d(15, 0);
vel.normalise();

// Calculate angle of vector (in degrees 0-360) relative to north
angle = vel.smallestAngle(mygame.Vector2d.north);
angle = vel.x &lt; 0 ? 360 - angle : angle;

// angle ~ 90 degrees

$class(name, extends, members, [staticMembers]) -> {object}

Define new class by extending an existing class
See
Parameters
Name Type Argument Description
name string
Name of class (may optionally specify namespace)
extends string | object
Name or reference of class
members object
Per-instance methods, fields, etc.
staticMembers object <optional>
Static methods, fields, etc.
Throws:
Thrown on invalid parameter
Type
capri.Error
Returns:
Class reference
Type
object
Examples

Ex#1. Define class that represents a key entity

$class('mygame.Entity', {
   __construct: function(x, y) {
      this.x = x;
      this.y = y;
   },
   process: function() {},
   render: function(dc) {},
   distanceTo: function(x, y) {
      return Math.sqrt(Math.pow(x - this.x, 2) + Math.pow(y - this.y, 2));
   }
});

$class('mygame.Key', 'mygame.Entity', {
   __construct: function(x, y, doorName) {
      this.callSuper(mygame.Entity, '__construct', x, y);
      // Name of door that key can open
      this.doorName = doorName;
   },
   render: function(dc) {
      dc.fillStyle = 'yellow';
      dc.fillRect(this.x, this.y, 5, 5);
   }
});

Ex#2. Create instance of class

key = new mygame.Key(300, 400, 'yellow');
sceneNode.push(key);

Ex#3. Utilise instance method of object

d = key.distanceTo(0, 0); // 500

$class.add(class, [members], [static], [staticFilter]) -> {class}

Add instance and/or static members to existing class
Note: New members are also added to classes that inherit specified class.
Source:
module/oop.js, Line: 400    ( Module: capri/oop )
Parameters
Name Type Argument Description
class string | class
Name or reference of class
members object | null <optional>
New instance members
static object | null <optional>
New static members
staticFilter function <optional>
Callback that is used to filter static members
Returns:
Input class is returned
Type
class
Example

Add new functions to existing class

$class('Test', {
   foo: function() {
      return 'hey';
   }
});

var obj = new Test();
obj.baz; // undefined

$class.add(Test, {
   bar: function() {
      return this.baz;
   },
   baz: 42
});

obj.baz; // 42

$clientUri(uri, [query]) -> {string}

Resolve URI for use in client
Generate URI for use in client (web browser) by replacing tilde ~ character with base URI of website. Additional query arguments can be added to URI for convenience.
Source:
module/doc-manager.js, Line: 18    ( Module: capri/doc-manager )
Parameters
Name Type Argument Description
uri string
URI that must be resolved
query string | object <optional>
Query arguments
Returns:
Resolved URI
Type
string
Example

// Initialise base URI of website
capri.DocumentManager.setBaseUri('http://example.com/blog/');

// elsewhere...

uri = $clientUri('~/about', 'section=intro');
// "http://example.com/blog/about?section=intro"

uri = $clientUri('http://example.com/blog/about', 'section=intro');
// "http://example.com/blog/about?section=intro"

uri = $clientUri('~/about?section=intro', 'labels=off');
// "http://example.com/blog/about?section=intro&labels=off"

$include(uri, [callback], [force])

Dynamically include script or stylesheet
Note: Tilde ~ can be used in place of base URI of application if document base URI has been specified (see Ex#2).
See
Source:
module/doc-manager.js, Line: 98    ( Module: capri/doc-manager )
Parameters
Name Type Argument Description
uri string
URI
callback function | null <optional>
Callback executed once script has loaded
force boolean <optional>
Defaults to false.
  • true - force execution of script
  • false - avoid execution of script if previously executed
Examples

Ex#1. Include absolute URI

$include('http://example.com/js/myscript.js');

Ex#2. Include with Base URI

$include('~/js/myscript.js');

Ex#3. Includes with callback

$include('~/js/first.js');
$include('~/js/second.js', function() {
   // Callback invoked once both 'first.js' and 'second.js' have loaded.
   // Will not execute if script throwns an exception during loading.
});

Ex#4. Force re-inclusion of previously included script

$include('~/js/render-object.js', null, true);
$include('~/js/render-object.js', null, true);
$include.process();

$include.process()

Process queued script and stylesheet includes
Dynamic includes must be manually processed once initial startup has completed.
Source:
module/doc-manager.js, Line: 139    ( Module: capri/doc-manager )
Throws:
Cannot process includes until page has finished loading
Type
capri.Error
Example

Perform script inclusion

function setWindowSkin(skinName) {
   // Note: This is merely an example of how dynamic includes might be used!

   // Queue includes
   $include('~/skin/' + skinName + '/style.css');
   $include('~/skin/' + skinName + '/skin.js', function() {
      // Apply velvit skin to application window
      $('#app-window')
         .applyAppSkin(skinName);
   });

   // Process includes
   $include.process();
}

$namespace(ns, [extension]) -> {object}

Define or acquire access to namespace
Namespace will be defined if it doesn't already exist. Members can be added to a namespace by specifying extension object (see Ex#3).
Web applications often make extensive use of JavaScript to provide an extensive interactive experience. Some of these scripts will be custom written whilst others may be third-party libraries. Occasionally scripts will conflict with one another due to multiple use of the same identifier.
Conflicts can easily be avoided within custom written scripts by defining functions, classes and variables within a vendor specific namespace. This function aims to ease namespace usage.
Source:
module/oop.js, Line: 20    ( Module: capri/oop )
Parameters
Name Type Argument Description
ns string | object
Namespace to lookup
extension object <optional>
Extension members to add
Returns:
Namespace object
Type
object
Examples

Ex#1. Access namespace

$namespace('my.special').foo();

Ex#2. Ensure that namespace is defined

$namespace('my.special');

// The following would fail if "my" namespace had not been defined. Above use
// of $namespace avoids ReferenceError exception.
if (my.special.foo)
   my.special.foo();

Ex#3. Add members to namespace

$namespace('my.special', {
   foo: function() {
   }
});

Ex#4. Access global namespace

// Easy way to access global namespace:
$global.globalVar = 42;
$namespace($global, {
   globalFunction: function() {
      console.log('Global function!');
   }
});

// Alternative:
$namespace('').globalVar = 42;
$namespace('', {
   globalFunction: function() {
      console.log('Global function!');
   }
});

$namespace(ns, define) -> {object|undefined}

Acquire access to an existing namespace
Parameters
Name Type Description
ns string | object
Namespace to lookup
define boolean
false prevents namespace from being defined
Returns:
Namespace object or undefined if namespace is not defined.
Type
object | undefined
Example

Find out if namespace is defined

var ns = $namespace('my.special.namespace');
if (ns !== undefined)
   console.log('Namespace is defined');
else
   console.log('Namespace is NOT defined');

$namespace.getBaseId(ns) -> {string}

Get base ID of namespace
Source:
module/oop.js, Line: 134    ( Module: capri/oop )
Parameters
Name Type Description
ns string
Namespace to lookup
Returns:
Base ID as string
Type
string
Example

$namespace.getBaseId('my.special.namespace');
// "my.special"

$namespace.getId(ns) -> {string}

Get ID of namespace
Source:
module/oop.js, Line: 118    ( Module: capri/oop )
Parameters
Name Type Description
ns string
Namespace to lookup
Returns:
ID as string
Type
string
Example

$namespace.getId('my.special.namespace');
// "namespace"

$namespace.use(ns, fn) -> {mixed}

Use alias to access namespace
Shorter aliases can be used to access namespaces within a specified scope. This avoids repeatedly entering long namespaces.
Source:
module/oop.js, Line: 151    ( Module: capri/oop )
Parameters
Name Type Description
ns string
Namespace to lookup
fn function
Scope to use namespace within
Returns:
Value returned by scope fn
Examples

Ex#1. Use single namespace

$namespace.use('my.special.namespace', function($myns) {
   // Both of the following lines are equivalent:
   $myns.foo();
   my.special.namespace.foo();
});

Ex#2. Use multiple namespaces

$namespace.use([ 'my.special.namespace', jQuery ], function($myns, $) {
   // Both of the following lines are equivalent:
   $('#my-element').text($myns.foo());
   jQuery('#my-element').text(my.special.namespace.foo());
});

$startup(callback)

Execute callback upon startup
Callback is executed once both DOM and includes have been loaded.
Source:
module/doc-manager.js, Line: 50    ( Module: capri/doc-manager )
Parameters
Name Type Description
callback function | function[]
One or more callbacks
Example

$include('~/css/jquery/special.css');
$include('~/js/jquery.special.js');

$startup(function() {
   // Special plugin is available because includes have been processed
   $('#special-widget').specialPlugin();
});

<protected> $startup.process()

Process startup scripts explicitly
Note: Startup scripts are usually processed automatically.
Source:
module/doc-manager.js, Line: 72    ( Module: capri/doc-manager )
Throws:
Thrown when invalid startup script is encountered
Type
capri.Error
Documentation generated by CapriDoc (inspired by jsdoc) on Fri Oct 28 2011 00:35:05 GMT+0100 (BST)