Appframe Knowledge Base

1 hits

JavaScript Conventions - Controls

/* First we create a function scope with two parameters, one is the scope ("this" in this context),
   the other is undefined, which will always be undefined even if someone does window.undefined = true; */
(function (scope, undef) {
    "use strict"; // This will enable ES5 strict-mode for browsers that support this

	/* Then we have this one line which should contain any needed references to other libraries
       and any shared variables that should be shared between instances of your control.
       af.common contains common functions used everywhere in web4, and should always be present */
    var w = scope.window, d = w.document, af =, c = af.common, shared = { instanceCount: 0 };
	// is using jQuery, you should add   $ = scope.jQuery,   as a variable above

    /* We capitalize first letter for constructors and use camelCasing for the rest
       If your constructor takes options, they should always be object literals:
       { myOption: "hello", important: true } */
	/* By including a comment using the format shown below, documentation can be automatically generated for your control */
    function MyControl(pOptions) {
         * A short description of your control, for use in documentation
         * or just so others know when looking at your code.
         * @param {object} pOptions An object literal containing options for your control
         * @return {MyControl} Returns an instance of MyControl when called using the new operator
         * @constructor

        /* "that" refers to the instance of this constructor, and is used for exposing or accessing public
           properties or functions. "priv" is an object literal containing any local variables. */
        var that = this, priv = {
			options: new c.Options({ // instantiate the common Options class
				defaults: {
					myOption: "hey",
					otherOption: 2
				required: ["important"], /* this will make your constructor throw an exception if the
                                           option called "important" is not passed to pOptions */
				// deepMerge: ["data"], // If you need to merge in depth
				// mergeDepth: 2, // you can use these two options
				passed: pOptions // this sends in the passed options to the Options class for checking
			eventHandler: new c.EventHandler(that, { // Include this if you need events for your control
                onSomething: { abortable: false } /* Setting abortable to true will allow an event to
                                                    stop execution of subsequent events by returning false. */
			element: null, /* If you are making a visual control, it is good to have a private variable
                              to keep a reference to the generated root element of your control. */
			someOtherVariable: 12345

		/* The three functions below are shortcut functions, and should be included and used when using events */
        function fireEvent(pEvent, pArgs, pModifiableArgs) { return, pArgs, pModifiableArgs); }
        function attachEvent(pEvent, pFunc) { return priv.eventHandler.attach(pEvent, pFunc); }
        function detachEvent(pEvent, pFunc) { return priv.eventHandler.detach(pEvent, pFunc); }

		/* All functions that are not constructors should be camelCased.
           Try to keep the size of a function under 40 lines if possible
           by refactoring into smaller functions and reusing code. */
        function someFunctionWeKeepToOurselves() {
			return 123;

		/* By including a comment using the format shown below, documentation can be automatically generated for your control */
		function someFunctionWeWantExposed(pSomeParameter) {
             * A function that returns a fixed string joined with the passed string using a dash.
             * @param {string} pSomeParameter The string you want appended to the fixed string
             * @return {string} A fixed string and the passed string joined with a dash.
			var vSomeVariable = "used only by code in this function";
			return [vSomeVariable, pSomeParameter].join(" - ");

		function initialize() { // Initialization code
			// Use of shared variable inside the instance

			// Use of private variable inside the instnace
			priv.myPublicVariable += 50;

		// Expose the functions you want available on the instance here
		that.someFunctionWeWantExposed = someFunctionWeWantExposed;
		// If you have many functions, use this method instead
		//c.expose(this, [attachEvent, detachEvent, someFunctionWeWantExposed, andSoOn];

		initialize(); // Finally we run the initialization code

	c.expose("af.someNameSpace", MyControl); // Expose you control to a namespace

}(this)); // This will refer to window when using a browser

components web · Perma link post comment Posted by: Jarl Erik Schmidt (08-mar-2012)