Module bea.wlp.disc

Class Catalog

public class Catalog

The Catalog class is an interface to a module's localization subsystem. A Catalog represents a set of localized data and is accessed by module-based code to convert default-text strings into localized versions of those strings when such localized versions are available.

 

Method Summary
public void	load(l10nData)           This method loads a module's catalog with the localization data specified in the l10nData parameter.
public string	localize(msg, [varargs])           Returns a localized version of the supplied message, if such a localization can be found.

 

Method Detail

load

public void load(l10nData) 

This method loads a module's catalog with the localization data specified in the l10nData parameter. The l10nData parameter should be an object mapping default message values to localized message values, as demonstrated in the following example:

     $MyModule.$meta.getCatalog().load({
         "default message value" : "localized message value",
         // ...
     });

A missing mapping in the l10n data object (or a mapping with a "falsy" value) will result in the use of the default message (the key) for a given lookup.

Explicit catalog localization will generally be used for purposes of l10n catalog aggregation, but may also be used to explicitly set or override l10n data on a per-catalog basis, as appropriate.

Parameters:

object l10nData - A mapping of default message values to localized message values

localize

public string localize(msg, [varargs]) 

Returns a localized version of the supplied message, if such a localization can be found. The search for a localized form of the message starts with this catalog instance's local l10n data, if any. If no match is found, the search then asks its associated module's parent's catalog to localize the value, when possible. The search continues on up the hierarchy until either a localized value is found or the top of the module hierarchy is reached.

This method also provides basic message formatting capabilities. Message formatting can be achieved by combining object tokens (matching the regexp: \{\d\}) in a message with additional var arg parameters. For example:

     var msg = myCatalog.localize("Some default message value with two args: {0} and {1}", "one", "two");

Parameters:

string msg - A default message value to attempt to localize

[varargs] - Any number of additional parameters to the method to be used as values for message formatting

Returns:

string - A formatted version of the message, localized if matching l10n data was found

Object Class

public singleton object Class

The Class helper provides functionality for declaring new "classes" in the Disc framework. These classes support single inheritance of instance and static member fields and methods (mixins may be used in place of multiple inheritance), public or internal initializers, super references, and dynamic injection and removal of members, as demonstrated below. Additionally, class body declarations may be expressed multiple ways.

Basic Example

This example demonstrates class and subclass declaration, basic inheritance, overrides, initializers, and super references. Additionally, it uses the concise object literal-notation to express its class body declarations.

     // Declare a base class
     var Person = bea.wlp.disc.Class.create({
         // Base class initializer
         initialize: function(name) {
             // Initialize internal instance variables
             this._name = name;
             this._greeting = "hi";
         },
         // Declare some instance methods
         greet: function(person) {
             return (this + " says '" + this._greeting + "' to " + person);
         },
         toString: function() {
             return this._name;
         }
     });

     // Declare the Cowboy subclass of Person
     var Cowboy = Person.extend({
         initialize: function(name) {
             // Call this class's super constructor (Person.initialize)
             this.sup(name);
             // Override the base class's greeting
             this._greeting = "howdy";
         },
         // Override the base class's toString method
         toString: function() {
             // Call the super class's toString and prepend the Cowboy designation
             return "Cowboy " + this.sup();
         }
     });

     // Example usage
     var john = new Person("John");
     var bill = new Cowboy("Bill");
     assertEquals("John says 'hi' to Cowboy Bill", john.greet(bill));
     assertEquals("Cowboy Bill says 'howdy' to John", bill.greet(john));

Advanced Example

This example demonstrates static field and method inheritance. Additionally, it uses the more expressive (but also more verbose) function style of class body declaration to provide convenient access to the class's static context.

     // Declare a base class
     var Shape = bea.wlp.disc.Class.create(function(Shape) {
         // Base class initializer
         this.initialize = function(x, y) {
             // Initialize internal instance variables
             this.x = 0;
             this.y = 0;
             this.translate(x, y);
             this._name = "Shape";
         };
         // Declare some instance methods
         this.translate = function(x, y) {
             this.x += (x || Shape.ORIGIN.x);
             this.y += (y || Shape.ORIGIN.y);
         };
         this.draw = function(x, y) {
             this.translate(x, y);
             return (this._name + ": x=" + this.x + ", y=" + this.y);
         };
         // Declare a public static field
         Shape.ORIGIN = { x: 0, y: 0 };
     });

     // Subclass Shape to create the Circle class
     var Circle = Shape.extend(function(Circle) {
         // Declare a private static variable
         var DEFAULT_RADIUS = 1;
         // Initializer
         this.initialize = function(x, y, r) {
             this.sup(x, y);
             this.r = (r || DEFAULT_RADIUS);
             this._name = "Circle";
         };
         // Override Shape's draw method
         this.draw = function(x, y) {
             // Indirectly reference the base class's ORIGIN static
             var containsOrigin = Circle.contains(this, Circle.ORIGIN);
             return (this.sup(x, y) + ", r=" + this.r + ", contains origin=" + containsOrigin);
         };
         // Static public method
         Circle.contains = function(circle, point) {
             var xd = point.x - circle.x;
             var yd = point.y - circle.y;
             return (Math.abs(Math.sqrt(xd * xd + yd * yd)) < circle.r);
         };
     });

     var circle = new Circle();
     assertEquals("Circle: x=0, y=0, r=1, contains origin=true", circle.draw());
     circle = new Circle(2, 2, 2);
     assertEquals("Circle: x=4, y=4, r=2, contains origin=false", circle.draw(2, 2));

Built-in Constructor Statics

The following static methods are automatically mixed in to class constructors created with Class.create:

extend(subdecl) {typeof subdecl == "object" or "function"; returns new class constructor}

The extend static method supports subclassing as demonstrated in the above examples. In the following example the extend method of the SuperClass constructor function is used to declare the SubClass subclass of SuperClass.

     var SuperClass = bea.wlp.disc.Class.create();
     var SubClass = SuperClass.extend();
     assertTrue(new SubClass() instanceof SuperClass);

The inject static method is used to insert a method or field into a class declaration after it has been created with Class.create. The following example shows the use of inject to do just that.

     var Cowboy = bea.wlp.disc.Class.create({
         initialize: function(name) {
             this._name = name;
         }
     });
     Cowboy.inject("lasso", function(target) {
         return "Cowboy " + this._name + " lassoed a " + target + "!";
     });
     assertEquals("Cowboy Bill lassoed a goat!", new Cowboy("Bill").lasso("goat"));

     var Cowboy = bea.wlp.disc.Class.create({
         initialize: function(name) {
             this._name = name;
         }
     });
     Cowboy.inject({ lasso: function(target) {
         return "Cowboy " + this._name + " lassoed a " + target + "!";
     }});
     assertEquals("Cowboy Bill lassoed a goat!", new Cowboy("Bill").lasso("goat"));

     var Cowboy = bea.wlp.disc.Class.create({
         initialize: function(name) {
             this._name = name;
         }
     });
     Cowboy.inject({
         lasso: function(target) {
             return "Cowboy " + this._name + " lassoed a " + target + "!";
         },
         shoot: function(target) {
             return "Cowboy " + this._name + " shot a " + target + "!";
         }
     });
     var bill = new Cowboy("Bill");
     assertEquals("Cowboy Bill lassoed a goat!", bill.lasso("goat"));
     assertEquals("Cowboy Bill shot a varmint!", bill.shoot("varmint"));

remove(name) {typeof name == "string" or "object"}

The remove static method is used to remove methods or fields from a class declaration. This method is the counterpart to the inject method, though it does not necessarily have to operate on members added to the class via injection. The following example shows the remove method removing members created through both declaration mechanisms.

     var MyClass = bea.wlp.disc.Class.create({
         one: function() { return "remove me"; }
     });
     MyClass.inject("two", function() { return "remove me, too"; });
     var instance = new MyClass();
     assertNotNull(instance.one);
     assertNotNull(instance.two);
     // ... later ...
     MyClass.remove("one");
     MyClass.remove("two");
     instance = new MyClass();
     assertUndefined(instance.one);
     assertUndefined(instance.two);

     var mixin = {
         one: function() { return "remove me"; },
         two: function() { return "remove me, too"; }
     }
     var MyClass = bea.wlp.disc.Class.create();
     MyClass.inject(mixin);
     var instance = new MyClass();
     assertNotNull(instance.one);
     assertNotNull(instance.two);
     // ... later ...
     MyClass.remove(mixin);
     instance = new MyClass();
     assertUndefined(instance.one);
     assertUndefined(instance.two);

 

Method Summary
public function	create([decl])           Create a new class.

 

Method Detail

create

public function create([decl]) 

Create a new class. New classes can be created with the create method in one of three main ways:

...with a body expressed in object literal notation:

This approach creates a new class whose body is defined by the object literal passed as the value of the decl argument.

     var MyClass = bea.wlp.disc.Class.create({
         myMethod: function() {
             return "some stuff I did";
         }
     });
     var myInstance = new MyClass();
     assertNotNull(myInstance.myMethod);
     assertEquals("some stuff I did", myInstance.myMethod());

...with a body declared as a static initializer function:

This approach creates a new class whose body is defined by the function passed as the value of the decl argument. Note that the term "static initializer function" is used to describe this function since it staticly initializes the class when constructing the class's actual constructor function. Any local variables over which closures are created in this context will act like class static variables since they will be shared by all instances of the class.

Also note the argument passed to the function used in this example: MyClass. This argument provides a static context for the class to which can be attached any public, inheritable, static members that maybe be appropriate for the class being created. The name of this argument should generally match the name of the class being created, for clarity, but this convention is not enforced by the create function.

     var MyClass = bea.wlp.disc.Class.create(function(MyClass) {
         this.myMethod = function() {
             return "some stuff I did";
         };
         MyClass.PI = 3.14;
     });
     var myInstance = new MyClass();
     assertNotNull(myInstance.myMethod);
     assertEquals("some stuff I did", myInstance.myMethod());
     assertEquals(3.14, MyClass.PI);

...or without a body:

This approach creates a bare new class without any unique members. Members can be added after declaration as needed using the newly created class constructor's inject method, as follows:

     var MyClass = bea.wlp.disc.Class.create();
     MyClass.inject("myMethod", function() {
         return "some stuff I did";
     });
     var myInstance = new MyClass();
     assertNotNull(myInstance.myMethod);
     assertEquals("some stuff I did", myInstance.myMethod());

This approach is discouraged in favor of the use of the more encapsulated forms described above but may still be useful in some scenarios, such as the dynamic application of mixins.

Parameters:

object|function [decl] - An optional object or static initializer function to serve as the class's body

Returns:

function - A constructor function for the new created class

Object Config

public singleton object Config

A basic configuration API for the core Disc module.

 

Method Summary
public string	getContextPath()           Returns the current context path setting.
public string	getScriptPath([scriptName])           Returns the current script path setting, with any additional path information (indicated by the optional scriptName argument) appended.
public void	setContextPath(contextPath)           This method should be used to set the webapp's context path.

 

Method Detail

getContextPath

public string getContextPath() 

Returns the current context path setting.

Returns:

string - The context path, if set; null otherwise

getScriptPath

public string getScriptPath([scriptName]) 

Returns the current script path setting, with any additional path information (indicated by the optional scriptName argument) appended. The script path is the result of combining the webapp's context path with the constant "framework/scripts/".

Parameters:

string [scriptName] - Additional path/filename information to be appended to this object's script path setting, if any; if not specified, the bare script path is returned

Returns:

string - The raw script path value or the union of said and the scriptName param or an empty string if neither value is defined

setContextPath

public void setContextPath(contextPath) 

This method should be used to set the webapp's context path. This setting effects all on-demand script loading done by Disc, and should therefore only be set once for a given document. Not setting this field to an appropriate value may result in unreliable on-demand script loading. On-demand script loading may occur for WLP server instances running in development mode.

Parameters:

string contextPath - The value to use as context path for on-demand module loading

Object Console

public singleton object Console

The Console object provides a simple abstraction over the well-known but not always present Firebug or Firebug Lite console global. Writing Firebug console operations to this object instead of the global Firebug console ensures that when that global console is not present, the operation will not fail due to the console object being undefined. When not available, the firebug-level operations on this object may execute as no-ops.

Listeners can be applied to this object as well, so that any time a message is sent to this object via one of the Firebug APIs, the message is routed to any configured listeners instead of to the default destination (the Firebug console, or lacking Firebug or Firebug Lite installed, the "no-op destination"). Adding one or more listeners to this object allows arbitrary message sinks to be set up, such as custom UI components or remote monitors, but the exact nature of such sinks is not defined in this scope.

In the absence of any of Firebug, Firebug Lite, or custom listeners, the default behavior of this object is to no-op all message operations, with the exception of error messages, which cause a standard alert dialog to be displayed with the contents of the error. Once a custom listener is added, the default error handler is suppressed.

See Also:

http://getfirebug.com

 

Method Summary
public void	addListener(listener)           This method allows listeners to be added to the global Disc console object.
public void	assert()
public void	count()
public void	debug()
public void	dir()
public void	dirxml()
public void	error()
public void	group()
public void	groupEnd()
public void	info()
public void	log()
public void	profile()
public void	profileEnd()
public void	removeListener(listener)           This method simply removes a listener from the Disc console object if previously added.
public void	time()
public void	timeEnd()
public void	trace()
public void	warn()

 

Method Detail

addListener

public void addListener(listener) 

This method allows listeners to be added to the global Disc console object. All operations (aside from addListener or removeListener) called on this object will cause registered listener callback functions to be invoked. Listener callback functions should accept two parameters: "op" and "args". The former is the name of the operation that was invoked (e.g. "log"), and the latter is the list of arguments with which it was called. Possible operation names include: "assert", "count", "debug", "dir", "dirxml", "error", "group", "groupEnd", "info", "log", "profile", "profileEnd", "time", "timeEnd", "trace", and "warn". Applying appropriate semantics to each operation is left as an exercise to each listener implementation.

For example, the following code would register a naive listener that routed all messages to an element named "myConsoleOutput", simply appending a new "line" for each routed message:

     bea.wlp.disc.Console.addListener(function(op, args) {
         var output = document.getElementById("myConsoleOutput");
         output.appendChild(document.createElement("br"));
         output.appendChild(document.createTextNode(op + ": " + args.join(",")));
     });

Parameters:

function listener - The listener callback function to be added

assert

public void assert() 

count

public void count() 

debug

public void debug() 

dir

public void dir() 

dirxml

public void dirxml() 

error

public void error() 

group

public void group() 

groupEnd

public void groupEnd() 

info

public void info() 

log

public void log() 

profile

public void profile() 

profileEnd

public void profileEnd() 

removeListener

public void removeListener(listener) 

This method simply removes a listener from the Disc console object if previously added. The function reference must be identical to the one added for it to be removed.

Parameters:

function listener - The listener function to be removed

time

public void time() 

timeEnd

public void timeEnd() 

trace

public void trace() 

warn

public void warn() 

Class Module

public class Module

The Module class comprises one of the most central facilities of the Disc core API: it provides a namespacing infrastructure for managing modularized code in the global execution context. While this class facilitates the creation of and interaction with namespace objects (modules), it does not impose a fixed structure upon them.

By convention Oracle WebLogic Portal owns anything in the bea.wlp.* namespace; any modifications to that namespace (and/or the constituents thereof) which are not supported through public APIs may result in undefined and unsupported behavior.

Modules are created via calls to the static Module.create function. Modules should be named to follow typical Java package naming conventions, that is, a '.' delimited list of valid JavaScript identifiers, typically composed of all lower-case letters.

Each module contains, at a minimum, a $meta field that provides a number of basic operations around the module itself, including accessors for this module's name, parent module, catalog, and an indication of whether or not the module has been formally defined (or if, instead, it exists purely for namepsacing purposes).

Modules support loading via either static script tag references (HTML) or dynamic loading via sync-XHR. The former should be used to deliver module source (or compiled module bundles) in production-mode scenarios. The latter can be a convenient tool for iteratively developing Disc-based JavaScript. Production-mode construction and deployment of module bundles is performed automatically for well-known Disc APIs; for custom Disc APIs, such construction and deployment is currently left as an exercise to the API developer. Dynamic module loading is driven through the use of the static Module.use method.

Dynamically loaded modules assume a specific file layout on the resource server. Each individual name-component of the overall module name (i.e. each identifier in the module name chain, delimited with '.' characters) is assumed to be a directory. The filesystem hierarchy of these directories must match the hierarchy specified by the overall module name. Each directory with a non-trivial module (that is, any bottom-level module for which one may call Module.use) must contain a file named module.js, containing an appropriate call to Module.create. Any module facets to be contributed to the dynamically loaded module must live in the module's directory, peer to it's module.js file. For example, the hypothetical module named "my.fancy.api" might look like this on the filesystem:

     + my
     |
     ----+ fancy
         |
         ----+ api
             |
             ----  module.js
             |
             ----  FacetOne.js
             |
             ----  FacetTwo.js

Lastly, each Module instance has an associated Catalog instance used for the organization of any given module's localizable messages. See the documentation for the Catalog class for more information.

Module instantiation should only be performed internally; use bea.wlp.disc.Module.create to explicitly create a new module. Directly contructing modules via the new operator is not supported.

See Also:

bea.wlp.disc.Module.create

bea.wlp.disc.Module.use

bea.wlp.disc.Catalog

Field Summary
public object	$meta             This field is a special member of all Module instances that provides some simple metadata getters.

 

Method Summary
public bea.wlp.disc.Catalog	$meta.getCatalog()           Returns this module's bea.wlp.disc.Catalog instance.
public string	$meta.getName([sub])           Returns the name of the current module.
public bea.wlp.disc.Module|window|object	$meta.getParent()           Returns the module's parent object.
public boolean	$meta.isDeclared()           Indicates whether or not this module has been explicitly declared, or is instead a placeholder module existing (so far) purely for namepsacing.
public static void	contribute(decl)           This method is used to contribute module facets to an existing module.
public static bea.wlp.disc.Module	create(name, decl)           Creates a new module.
public static bea.wlp.disc.Module|object	find(name)           Attempts to locate and return a module or an object child of a module.
public static boolean	isDefined(nameOrModule)           Determines whether or not the specified module both exists and has been declared.
public string	toString()           This method returns this module's name as a string.
public static bea.wlp.disc.Module	use(name)           Attempts to return a module instance by name; if the requested module does not yet exist or exists but has not yet been created, this method attempts to load the module from this script's host server, according to the setting(s) in bea.wlp.disc.Config.

 

Field Detail

$meta

public object $meta

This field is a special member of all Module instances that provides some simple metadata getters.

$meta.getCatalog

public bea.wlp.disc.Catalog $meta.getCatalog() 

Returns this module's bea.wlp.disc.Catalog instance.

Returns:

bea.wlp.disc.Catalog - This module's catalog; not null

$meta.getName

public string $meta.getName([sub]) 

Returns the name of the current module. e.g. bea.wlp.disc.$meta.getName() == "bea.wlp.disc". If passed the optional sub param, sub is appended to the module name returned in the no-args version; e.g. bea.wlp.disc.$meta.getName("foo") == "bea.wlp.disc.foo".

For example:

     bea.wlp.disc.Module.create("ns.mod", { });
     assertEquals("ns.mod", ns.mod.$meta.getName());
     assertEquals("ns.mod.sub", ns.mod.$meta.getName("sub"));

Parameters:

string [sub] - An additional string to append to the normal result of getName(), if any

Returns:

string - The module's name, with the sub param appended if specified

$meta.getParent

public bea.wlp.disc.Module|window|object $meta.getParent() 

Returns the module's parent object. This object will typically be an instance of bea.wlp.disc.Module, but may be another object type or the global window object if called on a root module, such as bea. Calls to this method should always check the type of the returned object before making assumptions about that object's properties.

For example:

     bea.wlp.disc.Module.create("ns.mod", { });
     assertEquals(ns, ns.mod.$meta.getParent());
     assertEquals(window, ns.$meta.getParent());

Returns:

bea.wlp.disc.Module|window|object - The value returned is one of bea.wlp.disc.Module, the global window object, or another object; the exact result depends on the environment in which the module was created

public boolean $meta.isDeclared() 

public static void contribute(decl) 

public static bea.wlp.disc.Module create(name, decl) 

public static bea.wlp.disc.Module|object find(name) 

public static boolean isDefined(nameOrModule) 

public string toString() 

public static bea.wlp.disc.Module use(name)