Namespace: cycligent

cycligent

The Cycligent namespace
Source:

Classes

Script

Members

(static) browser :object

Details the browser in which the code is running.
Type:
  • object
Properties:
Name Type Description
ie boolean True when the browser is Internet Explorer
chrome boolean True when the browser is Chrome
firefox boolean True when the browser is Firefox
safari boolean True when the browser is Safari
version float For IE holds the version number of the browser.
Source:
Example
if( cycligent.browser.ie ){
   alert( "I am running in Internet Explorer!" );
}

(static) classArgs

Arguments for cycligent.class.
Properties:
Name Type Attributes Description
name string The fully qualified dotted name fo the class.
extends string <optional>
 The fully qualified dotted name of the class to extend.
implements string <optional>
 The fully qualified dotted names of the interfaces required by the class. If the class implements multiple interfaces, separate them by commas.
definition object The object, usually from a code literal, that defines the class.
Source:
See:

(static) config :object

Configures the loading and debugging of Cycligent.

You define this yourself in a file named config.js since it's for application-specific configuration, see cycligent._loader for an explanation of where the config.js file is loaded from.
Type:
  • object
Properties:
Name Type Description
appName string The name of the application. Often displayed by the application.
appDescription string A description of the application. Often displayed by the application in an about box. Often contains copyright and/or licensing information.
appVersion string The version of the deployed application. Usually contains the value "M.m.B" (major, minor, build) on a developer's machine. Changed by the build and deploy process so that the deployed application can accurately display the currently running version.
production boolean When true this indicates that this is being served by a Cycligent server employing advanced caching mechanisms (the versioning of all static resources), otherwise we expect all resources to be served as is. Is is usually set by the build process.
minimizeSource boolean Typically set by the build process. When true .min files are served.
startupScript string The name and location of the startup script expressed as either a dotted name or URL. This is the main script that will import all other scripts and start the application. Once the Cycligent bootstrap process has completed, including the loading of all imported scripts, Cycligent calls the main() function. Typically the value of this property is "main" meaning that the file main.js is loaded from the same directory as the HTML file.
loader object
Properties
Name Type Description
libs Array.<string> A list of URLs that represent the base library scripts that must be loaded synchronously.
waitFor object Signals to wait for before starting the application (calling main()).
Properties
Name Type Description
dom boolean Wait for the DOM to be ready. If the cycligent script tag is placed at the end of the body element, waiting for DOM ready is unnecessary.
page boolean Wait for the page to be ready (window.onload).
timeout int The maximum time to wait for the application to become ready.
roots object Map of root namespaces and their associated URLs. Used to shorten dotted names. See example.
debug object Configures Cycligent Debugging. Properties are in a disabled state by default so that the framework will run as efficiently as possible by performing the fewest checks. You'll want to enable most of these during development, and disable most or all of them in production.
Properties
Name Type Description
on boolean When true Cycligent performs debugging functions, when false all debugging functions are disabled.
startup boolean When true Cycligent sends informational messages to the console during the startup process.
scripts boolean When true Cycligent sends informational messages to the console on the loading of each script (load started, load completed, redundant load avoided, etc).
private object Control for private function debugging.
Properties
Name Type Description
check boolean When true private functions containing cycligent.private are validated.
args object Control for function argument checking.
Properties
Name Type Description
check boolean When true arguments to functions containing cycligent.args are validated.
arrays object Control for how array arguments are validated.
Properties
Name Type Description
check boolean When true array arguments are validated.
allElements boolean When true all array elements are validated. This can be a very time consuming operation and is not recommended. When false only the first element of the array is validated.
interface object Control for interface validation.
Properties
Name Type Description
check boolean When true interfaces are validated.
Source:
Example
cycligent.config = {

    appName: "My Awesome Application",
    appDescription: "The most awesome application ever",
    appVersion: "M.m.B",

    production: false,
    minimizeSource: false,

    startupScript: "^main",

    loader: {
        libs: [
            '/app/lib/smart/js/libs/jquery-2.0.2.min.js',
            '/app/bower_components/angular/angular.min.js',
            '/app/bower_components/angular-route/angular-route.min.js'
        ],

        waitFor:{
            dom: true,
            page: false
        },

        timeout: (location.hostname == "localhost" || location.hostname == "" ? 7000 : 70000),

        roots: {
            cycligent: { root: "/app/lib/cycligent" }
        }
    },

    debug: {
        on: true,

        startup: false,
        scripts: false,

        private:{
            check: true
        },

        args: {
            check: true,
            arrays:{
                check: true,
                allElements: false
            }
        },

        interfaces: {
            check: true
        }
    }
};

(static) interfaceArgs

Arguments for cycligent.interface.
Properties:
Name Type Attributes Description
name string The fully qualified dotted name fo the class.
extends string <optional>
 The fully qualified dotted name of the class to extend.
definition object The object, usually from a code literal, that defines the class.
Source:
See:

(static) root :object

Holds information regarding the web application root structures of the application and the environment it runs in. This is automatically created by the Cycligent framework, but you can define it yourself before the framework loads if it's necessary to direct the framework to use non-standard locations for resources (for example, in some testing environments.)
Type:
  • object
Properties:
Name Type Description
app string The application root as an absolute URL
name string Just the application root name
client string Root directory for client-side resources as an absolulte URL. Typically used with server-side JavaScript environments where both server and client resources look the same but are placed in different directories. For other environments it is the same as app root.
deploy string Deployment directory absolute URL, used for accessing other deployed applications, often libraries.
context string Testing context provides tests with a context for realizing relative paths, essentially the same as what window.location would have been in the actual running code.
Source:
Example
app == "http://some.cloud.com/myApp"
name == "myApp"
client == "http://some.cloud.com/myApp/client"
deploy == "http://some.cloud.com"
context == "http://some.cloud.com/myApp/client/myPage"

Methods

(static) _loader()

Loads Cycligent and its dependencies.

Implemented as a function that executes immediately. _loader should not be called but is documented here to provide information about Cycligent's bootstrapping process and it associated configurations.

At startup the first file loaded by cycligent is config.js. Config.js contains the global configuration for cycligent.

By default config.js is loaded from the root directory for servers that do not have a concept of application root or from the application root for servers that do have the concept of an application root.

If the default method of guessing where config.js is doesn't work in your environment, the config.js location can be specified in the following ways:
  • config-location (or x-config-location or data-config-location) attribute on the script tag. (recommended)
  • config-depth (or x-config-depth or data-config-depth) attribute on the script tag. This attribute is the depth within the path hierarchy from the current HTML file (window.location), where a depth of zero is the root directory of the server.
  • Specifying a URL of the config location in window.cycligentConfigLocationOverride (often useful in testing.)
By default the application root is determined in the same manner as for the config.js file. If the default method of figuring out the app root doesn't work in your environment, the application root can be specified via the config-app-root (or x-config-app-roox or data-config-app-root) attribute. No trailing slash should be used when specifying the path.
Source:
Example
Example 1 (config-depth="0")
Requested URL: http://localhost:3680/app/myApp/myPage/index.html
<script id="cycligent-script" src="/app/lib/cycligent/cycligent.js" data-config-depth="0"></script>
config file will be read from /config.js.

Example 2 (config-depth="2")
Requested URL: http://localhost:3680/app/myApp/myPage/index.html
<script id="cycligent-script" src="/app/lib/cycligent/cycligent.js" data-config-depth="2"></script>
config file will be read from /app/myApp/config.js

Example 3 (config-location="/app/config.js")
Requested URL: http://localhost:3680/app/myApp/myPage/index.html
<script id="cycligent-script" src="/app/lib/cycligent/cycligent.js" data-config-location="/app/config.js"></script>
config file will be read from /app/config.js

Example 4 (window.cycligentConfigLocationOverride="/app/config.js")
Requested URL: http://localhost:3680/app/myApp/myPage/index.html
<script type="text/javascript">window.cycligentConfigLocationOverride = "/app/config.js";</script>
<script id="cycligent-script" src="/app/lib/cycligent/cycligent.js"></script>
config file will be read from /app/config.js

(static) args(argsIn, spec, ignoreExtraArgumentsopt)

Enhances and optionally validates the arguments passed to a function.

cycligent.args always takes the form cycligent.args(arguments, [ArgumentSpec]);

Argument specifications take the form of an object literal which contains one or more properties. Each of these properties represents an argument. Each of the argument properties contains another object literal that defines the attributes of the argument. The available argument attributes are type, required and defaultValue. See examples below for how to structure argument specifications.

The Cycligent Framework provides the following enhancement for function arguments:

  • Mapped or ordered arguments for the same function
  • Default values for optional arguments
  • Validation of supplied arguments (required, quantity and type)
  • Handling of advanced types (Arrays and HTML elements)
  • Reuse of argument specifications, especially useful with interfaces

    • cycligent.args supports either mapped or ordered arguments. When a single argument is passed to a function, and that argument is an object, and that object contains a property named the same as an argument, it is assumed to be an argument map. In all other cases the system treats the arguments as ordered. To pass a single object to a function that has a property with the same name as an argument it must be passed in as a map. (function( object ) will not work). The construct of function( {argumentName: object} ) must be used instead. When a map is not used the arguments must be passed in the order of their declaration.

    cycligent.args will also provide default values for optional arguments that are not supplied, if a default value for the optional argument has been provided.

    Supplied arguments can be validated for correctness. Validations are performed when cycligent.config.debug.on and cycligent.config.debug.args.check are true. When validation is active arguments are validated for the correct type, that all required arguments were supplied, and that the correct number of arguments were supplied.

    All required arguments must appear before any optional arguments. This conventions allows cycligent.args to successfully parse arguments which are passed to a function but are not in a map.

    cycligent.args supports advanced types. Array arguments can be specified by wrapping the type in square brackets, as in "[String]" (which indicates that the function takes an array of strings). When validation is on, cycligent.config.debug.args.arrays.check is true, then arrays are checked for the correct type. When cycligent.config.debug.args.arrays.allElements is true, elements of the array validated to contain the correct type. This can be very time consuming and is not recommended. Therefore, cycligent.config.debug.args.arrays.allElements defaults to false, in which case only the first element of the array is validated.

    In addition to arrays, cycligent.args supports special types. Specials types are passed as a string. Currently cycligent.args supports Document, HTML elements and XML nodes as special types. Document is a DOM/XML document. If an argument can take any HTML element then the argument specification would be "HtmlElement". Likewise for any XML node the argument would by "XmlNode". If an argument requires a specific type of HTML element or XML node, such as a div, then that is specified by postfixing the "HtmlElement" or "XmlNode" with a colon and the elements tag name (in all lowercase) as in "HtmlElement:div" or "XmlNode:item".

    Argument specifications can be stored in a variable and reused. This is especially helpful when interfaces are declared. When an interface is declared the signatures for its methods are stored in the interfaces prototype. This allows the developer to use these prototype properties in the creation of methods on an object that implements the interface.

    The convention when working with the cycligent framework is to use a variable named 'a' to hold the return value from cycligent.args. variable named 'a' to hold the return value from cycligent.args.
    Parameters:
    Name Type Attributes Default Description
    argsIn Array.<arguments> The arguments object that is passed/present in a function.
    spec Object The argument specification.
    ignoreExtraArguments Boolean <optional>
    		 false When true extra arguments are ignored. Typically used by base classes that are inherited to allow the super class to pass the argument list passed to it to the base class.
    Source:
    Example
    // Using examples from the Cycligent framework itself:

cycligent.class = function(){
    var a = cycligent.args(arguments, {
        name:{type: String},                         // The fully qualified name of the class being created
        definition:{type: Object},                   // The object literal that defines the class
        extends:{type: Object, required: false},     // The class from which this class inherits its methods and properties
        implements:{type: [Object], required: false} // The newly created class implements the interface class or classes specified
    });
    ...

********** OR VIA REUSABLE ARGS **********

cycligent.classArgs = {
    name:{type: String},                             // The fully qualified name of the class being created
    definition:{type: Object},                       // The object literal that defines the class
    extends:{type: Object, required: false},         // The class from which this class inherits its methods and properties
    implements:{type: [Object], required: false}     // The newly created class implements the interface class or classes specified
};

cycligent.class = function(){
    var a = cycligent.args(arguments, cycligent.classArgs);
    ...

********** OR VIA INTERFACE **********

cycligent.tracerMessageArgs = {
    message:{type: String},                          // The trace message.
    type:{type: Number, required: false, defaultValue: cycligent.traceTypes.information }, // The trace type (a value from cycligent.traceTypes).
    category:{type: String, required: false, defaultValue: ""}, // A string representing the category of the trace. Used for filtering (see cycligent.config.trace).
    ex: {type: Object, required: false}
};

cycligent.interface({
    name: "cycligent.TracerInt",
    definition:{
        getElement: {},                              // Gets the HTML element that holds the trace information.
        setElement: {element: {type: "HtmlElement:DIV"}}, // Sets the HTML element that holds the trace information.
        trace: cycligent.tracerMessageArgs                  // Issue a trace.
    }
});

...
trace: function(){
    cycligent.args(arguments,cycligent.TracerInt.prototype.trace);
...

    (static) class(map)

    Declares a class that supports classical inheritance and interfaces.

    cycligent.class allows a class to be created that extends (inherits from) another class. It also provides for the implementation of interfaces. To make class definitions easy to follow, it is recommended that calls to cycligent.class use mapped arguments in the following order: name, extends, implements, definition. See the example below. cycligent.class also validates that the first character of the class name is an uppercase letter, which is the common convention in JavaScript.

    cycligent.class definitions should be placed outside of functions. This allows them to be processed at startup. The processing of class definitions that are dependant on other class definitions that have not yet been processed are deferred until they can be processed. This allows race conditions during the asynchronous loading of scripts at startup to be avoided, and makes the order in which scripts are loaded unimportant.

    If enabled in the configuration settings (see cycligent.config.debug.interfaces) the interfaces implemented by the class are validated. This is done by checking the class's source to see if it is calling cycligent.args on the argument definition defined by the interface.
    Note that if you define a class, you can create it as a singleton using cycligent.singleton. Singleton classes can have an initSingleton that will be called when the class is instantiated as a singleton.
    Parameters:
    Name Type Description
    map object The object that specifies the class, typically from an object literal in code (see example, and cycligent.classArgs).
    Properties:
    Name Type Description
    cycligentClass string The name of the class as a property of the prototype.
    Source:
    See:
    Example
    cycligent.class({
    name: "cycligent.Tracer",
    extends: "cycligent.ExtendThisClassExample"
    implements: "cycligent.TracerInt, cycligent.anotherInterface",
    definition: {
        ...
    }
});

    (static) define(name, definitionopt, priorityopt)

    Allows the creation of identifiers in a way that takes into account dependencies and optionally allows for a function to be run when the identifier is created or during a prioritized startup.

    cycligent.define allows files to be loaded in any order and thus enables asynchronous loading of JavaScript files. The actual definition (creation) of the identifier does not happen until all of it dependencies are defined.

    If a definition function is defined and no priority is defined the definition function is called immediately upon the creation of the identifier (the identifier is defined when the function is called). If a definition function and priority are specified then the call of the definition function is delayed until all startup process have completed and then the definition function is called, in the order indicated by priority, just before main() is called.

    All priority 1 functions are called first, then all priority 2 functions, and so on and so forth. Please note that the order of calls within a priority are random. So, for instance, if you set three functions as priority 1 you are assured that these function will be called before any other definition functions, but you don't know which of these three functions will be called first, second or third.

    If after all scripts have been loaded the dependencies for a given define have not been created, then Cycligent creates those dependencies as blank objects. So, for instance, if there was a define of 'demo.something.here' and after all scripts had loaded only 'demo' was defined then Cycligent would define 'something' as a blank object and then define 'here' as well.
    Parameters:
    Name Type Attributes Description
    name string The fully qualified name/namespace to define
    definition * <optional>
    		 Value/object/definition to be assigned to the name
    priority number <optional>
    		 The priority order, if any. If zero or undefined the definition to be executed as soon as all dependencies are available. If a non-zero priority is defined then the definition is not executed until all scripts have been loaded and all definitions with a lower priority have been executed.
    Source:

    (static) definitionGet(dottedName) → {object}

    Finds a definition value, where the definition name is allowed to be a string that has dots in it, and will be properly found nested within a JavaScript object. It is common in Cycligent to define class names using a dotted syntax, such as cycligent.console. These names are stored as nested JavaScript objects, but the names are also commonly passed around as strings, which becomes difficult when you want to access them easily from the string name, this function and cycligent.definitionSet help make this very simple and easy. The definition is found starting from the window object. This function assumes that the nested structure you're trying to pull data out of exists.
    Parameters:
    Name Type Description
    dottedName string The dotted name to find.
    Source:
    Returns:
    - The value of the dotted name
    Type
    object
    Example
    cycligent.definitionGet("MyNamespace.MyClass");

    (static) definitionSet(dottedName, valueopt) → {*}

    Sets a definition to a value, where the definition name is allowed to be a string that has dots in it, and will be properly assigned to a nested JavaScript object. It is common in Cycligent to define class names using a dotted syntax, such as cycligent.Tracer. These names are stored as nested JavaScript objects, but the names are also commonly passed around as strings, which becomes difficult when you want to access them easily from the string name, this function and cycligent.definitionGet help make this very simple and easy. The definition is assigned starting from the window object. This function assumes that the nested structure you're trying to put data into exists.
    Parameters:
    Name Type Attributes Description
    dottedName string | object The dotted name to set. Or a map of the arguments.
    value * <optional>
    		 The value to set the dotted name to.
    Source:
    Returns:
    Type
    *
    Example
    cycligent.definitionSet("MyNamespace.MyClass", classDefinition);

    (static) import(dottedNameOrUrl, extensionopt)

    Dynamically imports a JavaScript file asynchronously via either a dotted name (ID) or a URL.

    The Cycligent Framework provides the following support for the loading of JavaScript files:

  • Dynamic loading
  • Asynchronous loading
  • Common configuration
  • Logging
  • Versioning
  • Advanced caching
  • Namespace root location specification
  • Loading of compressed or uncompressed scripts
    Scripts that depend on other scripts can import them using cycligent.import. These scripts are then loaded asynchronously and in parallel to the degree allowed by the browser.

    HTML files only need include the cycligent script tag. For more information on the Cycligent bootstraping process see cycligent._loader.

    Once Cycligent has successfully booted it loads the main.js that is in the same directory as the HTML file, or the startup script specified. It will also load any scripts imported by this script and any script they import and so on. Once the system has successfully loaded all scripts, any initialization code for the loaded file is run (see cycligent.define). Once all initialization code has completed the system calls main().

    Cycligent provides a logging mechanism that provides information on the loading of scripts and thier success or failure.

    The versioning feature of Cycligent not only supports the loading of the correct version of a code set, but also supports an advanced caching mechanism. For more information on versioning please see https://www.cycligent.com.

    Advanced caching allows the expires headers of all javascript files to be set such that they "never" expire. This not only eliminates the re-downloading of scripts but also the costly tcp/ip connection and communication around determining if an item in the cache is older than the current item on the server.

    Normally this technique would make it impossible to update the scripts once released. By using cycligent.import and by incrementing the version on a release the code sets will automatically refresh on the client as needed.

    The location from which a given code set is loaded can also be configured via the cycligent.config.roots section of the common configuration cycligent.config). For more information on how these root locations are specified see cycligent.root.

    Finally a configuration switch cycligent.config.minimizeSource can be thrown to either load the uncompressed or the compressed versions of the scripts. This is typically done by a production build process.

    Scripts to be imported can be specified either in the form of a dottend name or a URL. For more information on dotted name and URL usage see cycligent.url
    • Parameters:
    Name Type Attributes Default Description
    dottedNameOrUrl string The script to import, specified as either a dotted name or a URL. For more information on name and URL handling see cycligent.url
    extension string <optional>
    		 'js' The extenstion to be used with dotted names. Defaults to 'js'.
    Source:
    Example
    cycligent.import( "app.sub.myScript" );
   cycligent.import( "/myApp/mySubDirectory/myScript.js" );

    (static) interface(map)

    Declares a classic interface (for use with classical inheritance classes).

    cycligent.interface defines an interface that other classes can implement. It allows the methods of the interface, and their signatures, to be specified. It also allows for the method signature definition to be reused by cycligent.args. It is recommended that calls to cycligent.interface use mapped arguments in the following order: name, extends, definition. See the example below.

    cycligent.interface definitions should be placed outside of functions. This allows them to be processed at startup. The processing of interface definitions that are dependant on other interface definitions (for example, if you extend an interface to create a new one with more methods) that have not yet been processed are deferred until they can be processed. This allows race conditions during the asynchronous loading of scripts at startup to be avoided, and makes the order in which scripts are loaded unimportant.

    Depending on configuration settings (see cycligent.config.debug.interfaces) the implementation of interfaces by the class are validated.
    Parameters:
    Name Type Description
    map object The object that specifies the interface, typically from an object literal in code (see example, and cycligent.interfaceArgs).
    Source:
    Example
    // The Interface:
cycligent.interface({
    name: "cycligent.TracerInt",
    definition:{
        getElement: {},										// Gets the HTML element that holds the trace information.
        setElement: {element: {type: "HtmlElement:div"}},	// Sets the HTML element that holds the trace information.
        trace: cycligent.tracerMessageArgs							// Issue a trace.
}

// A class that implements that interface:
cycligent.Class({
    name: "cycligent.Tracer",
    implements: "cycligent.TracerInt",
    definition: {
        getElement: function() {
            cycligent.args(arguments, cycligent.TracerInt.prototype.getElement);
            // ... implementation ...
        },

        setElement: function() {
            cycligent.args(arguments, cycligent.TracerInt.prototype.setElement);
            // ... implementation ...
        },

        trace: function() {
            cycligent.args(arguments, cycligent.TracerInt.prototype.trace);
            // ... implementation ...
        }
    }
});

    (static) private(alwaysThis)

    cycligent.private is used during debugging to ensure that private methods are only called by methods of the object in which it is defined.

    To use cycligent.private simply place "cycligent.private(this);" at the top of the function. The cycligent framework will then throw an error if the call to the function was made from outside the object.
    Parameters:
    Name Type Description
    alwaysThis object the only parameter to cycligent.private is always the "this" keyword.
    Source:
    Example
    cycligent.class({
    name: "Person",
    definition:{
        init: function(){
            var a = cycligent.args(arguments, PersonArgs );
            	
            var name = a.name;
            
            this.getProtectedName = function Person_init_getProtectedName(){
                cycligent.private(this);
                return name;
            };
        },

        nameGet: function(){
            return this.getProtectedName();
        }
    }
});

    (static) singleton(name, …arguments) → {Object}

    Takes a class name and returns a singleton object. If the singleton object already exists it simply returns it, if not, it creates it.
    Parameters:
    Name Type Attributes Description
    name string The name of the class from which to construct the singleton
    arguments * <repeatable>
    		 Arguments to singleton constructor
    Properties:
    Name Type Description
    initSingleton function If initSingleton is defined by the class it is called when the singleton is instantiated.
    Source:
    See:
    Returns:
    Type
    Object
    Example
    cycligent.define("app");
cycligent.class({
    name: "app.Session",
    definition: {
        initSingleton: function() {
            cycligent.args(arguments, {});
            var me = this;
            $.get("/sessionData", function(data) {
                me.data = data;
            });
        },

        userName: function() {
            return this.data.username;
        }
    }
});

function main() {
    var session = cycligent.singleton("app.Session");
}

    (static) styleRequired(dottedNameOrUrl)

    Specifies that a particular stylesheet is required.

    Missing styles can make it appear as though code is not functioning. When code is dependent on styles in a particular stylesheet you can use cycligent.styleRequired to indicate the required dependency. If the stylesheet does not load successfully during application loading Cycligent throws an error.
    Parameters:
    Name Type Description
    dottedNameOrUrl string The script to import, specified as either a dotted name or a URL. For more information on name and URL handling see cycligent.url
    Source:
    Example
    cycligent.styleRequired( "app.common.css.myStyles" );
   cycligent.styleRequired( "/app/common/css/myStyles.css" );

    (static) url(dottedNameOrUrl, extensionopt) → {String}

    Converts a string, which can be either a URL, or a dotted name into a fully realized URL.

    If the string contains one or more slashes '/' it is treated as a URL.
    • If the string contains '//', then the string is treated as an absolute URL and is returned as is with an added extension if the extension was not present.
    • If the string begins with a '/', the URL is realized relative to the deploy directory.
    • If the string begins with '@/', the URL is realized relative to the current application root.
    • Otherwise, the URL is realized relative to the current HTML file.
    If the string does not contain a slash it is treated as a dotted name.
    • If the dotted name begins with a '^', the URL is realized relative to the deploy directory.
    • If the dotted name begins with '@', the URL is realized relative to the current application root.
    • If the dotted name begins with '.', the URL is realized relative to the current HTML (window.location) file.
    • Otherwise,
      • If a dotted name begins with a recognized root then the name is resolved relative to that root (this has the affect of making the '^' optional).
      • Otherwise, the dotted name is resolved relative to the current HTML file (window.location). This has the affect of making the '.' optional in all instances except where the first sub-directory was named the same as the root directory.
    Parameters:
    Name Type Attributes Default Description
    dottedNameOrUrl String The dotted name or URL to resolve.
    extension String <optional>
    		 'js' The file type (extension) of the file for which the URL is to be generated. Defaults to "js" for JavaScript. Only applies to dotted names, URLs must specify the extension.
    Source:
    Returns:
    - The fully realized (absolute) URL (the location on the server (URL) of the specified resource)
    Type
    String
    Example
    If we imported the JavaScript file "cycligent.startup.info",
  we would be referring to the script named "info.js" in the startup folder,
  of a root named "cycligent".
If we imported the JavaScript file "^cycligent.startup.info",
  we would be referring to the same thing as above, the "^" is a way of
  being explicit about the fact that "cycligent" is a root, and not a
  folder relative to where the user is. (since the Cycligent Framework
  will recognize roots in dotted names, the "^" is optional. You might
  want to specify it to be clear to others reading your code that what
  you are specifying is from an application root.)
If we imported the JavaScript file "@cmn.dashboard.graph",
  this refers to an file named "graph.js"  in the "cmn/dashboard"
  folder of the current application root. "@" means current
  application root.
If we imported the JavaScript file ".utils",
  we would be referring to a file named "utils.js" in the same folder as
  the current HTML file.
If we imported the JavaScript file "utils",
  it would do the same as above. Thus, if you are loading a file relative to
  the current HTML page, you do not need to use the "." in most cases, unless
  the file or folder you are loading from has the same name as an application
  root.
If we imported the JavaScript file //ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js
  that URL would be returned as-is.
If we imported the JavaScript file //ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min
  the extension, which defaults to .js, will be added to the URL.
If we imported the JavaScript file, /jquery.min.js
  and the application was deploy directory was www.cycligent.com, we would
  be referring to www.example.com/jquery.min.js
If we imported the JavaScript file, @/jquery.min.js
  and the current application root was www.example.com/app, we would
  be referring to www.example.com/app/jquery.min.js