JavaScript coding conventions - Revision history

Jerico.dev: Add link to the Google Closure project

2012-08-21T15:54:55Z

Add link to the Google Closure project

Jmacgreg: Undo revision 2363 by 116.197.0.166 (talk)

2011-10-31T16:56:56Z

Undo revision 2363 by 116.197.0.166 (talk)

116.197.0.166: /* JsDoc Comments */

2011-10-31T04:05:49Z

‎JsDoc Comments

Jerico.dev: rename "variables" to "properties" for class members

2011-03-04T16:42:22Z

rename "variables" to "properties" for class members

Jerico.dev: Move widget documentation to its own page.

2011-02-18T13:44:08Z

Move widget documentation to its own page.

Michael: namespace fixes

2011-01-25T00:57:07Z

namespace fixes

Michael: namespace fixes

2011-01-25T00:56:01Z

namespace fixes

Michael: small path fix

2011-01-25T00:02:51Z

small path fix

Michael: Object member ordering: fixes to naming conventions

2011-01-21T01:38:03Z

Object member ordering: fixes to naming conventions

Jerico.dev: typos

2011-01-07T23:42:15Z

typos

@@ Line 64: / Line 64: @@
 === Interfaces ===
-There is no syntactical correspondence for interfaces in JavaScript but we implement them conceptually as objects and enforce them with the Closure compiler. We have an "abstract" base object that declares the methods that go into an interface without implementing them. Then we let implementations of the interface inherit from these "abstract" objects. Please use the <code>@interface</code> and <code>@implements</code> annotations to declare interfaces.
+There is no syntactical correspondence for interfaces in JavaScript but we implement them conceptually as objects and enforce them with Google's [https://developers.google.com/closure/compiler/ Closure compiler]. We have an "abstract" base object that declares the methods that go into an interface without implementing them. Then we let implementations of the interface inherit from these "abstract" objects. Please use the <code>@interface</code> and <code>@implements</code> annotations to declare interfaces.
 Interfaces that share the same implementation across objects can be weaved into objects as aspects via the $.Helper.injectMixin() method which relies on our object factory to identify the right implementation of an interface and then introduces it into the target object via the mixin mechanism provided by jQuery's $.extend() function. This allows us to exchange interface implementations on runtime (e.g. for automated testing or different deployment environments) without having to change the object declarations, see the explanation of the object factory below.

← Older revision		Revision as of 16:56, 31 October 2011
Line 12:		Line 12:

	For the moment being we do not use curly braces ({}) around the object declared with <code>@extends</code>. This is for better tool support. The build script will introduce the braces for compilation.		For the moment being we do not use curly braces ({}) around the object declared with <code>@extends</code>. This is for better tool support. The build script will introduce the braces for compilation.
−
−	~~IP address:116.197.0.237~~

	== Whitespace ==		== Whitespace ==

← Older revision		Revision as of 04:05, 31 October 2011
Line 12:		Line 12:

	For the moment being we do not use curly braces ({}) around the object declared with <code>@extends</code>. This is for better tool support. The build script will introduce the braces for compilation.		For the moment being we do not use curly braces ({}) around the object declared with <code>@extends</code>. This is for better tool support. The build script will introduce the braces for compilation.
		+
		+	IP address:116.197.0.237

	== Whitespace ==		== Whitespace ==

@@ Line 133: / Line 133: @@
 We group object members by visibility and singleton ('static') vs. instance membership in the following order in our object definitions:
 # constructor (use <code>@constructor</code> annotation)
-# private static variables (end with underscore, use <code>@private</code> annotation)
+# private static properties (end with underscore, use <code>@private</code> annotation)
-# private instance variabes (end with underscore, use <code>@private</code> annotation)
+# private instance properties (end with underscore, use <code>@private</code> annotation)
-# protected instance variables (discouraged, better use private variables with protected accessors/mutators, use <code>@protected</code> annotation)
+# protected instance properties (discouraged, better use private variables with protected accessors/mutators, use <code>@protected</code> annotation)
-# no public static/instance variables - use public accessors/mutators instead!
+# no public static/instance properties - use public accessors/mutators instead!
 # public static methods
 # public methods

@@ Line 235: / Line 235: @@
 '''This is the only bit of JavaScript we allow in Smarty templates at all!''' If you feel the need to add anything more than this to your templates then you probably have a design error somewhere.
-= Standard Handler Library =
+= Standard Widget Controller Library =
-We have got many standard handlers that can be extended to provide functionality that is in line with our UI design language and elements.
+Please see our dedicated [[JavaScript widget controllers|JavaScript library wiki page]] that documents all widget controllers.
-−
-Please make sure that you think twice before you introduce a non-standard widget / handler. Often slight deviations in the UI specification from one of the standard handlers are not intended. Restricting elements to one of the standard widgets will considerably reduce our initial development effort as well as future maintenance.
-−
-== Modals ==
-−
-We currently implement two basic types of modals:
-* simple confirmation modals ($.pkp.controllers.modal.ConfirmationModalHandler)
-* AJAX-driven modals ($.pkp.controllers.modal.AjaxModalHandler)
-−
-The AJAX-driven modal exists as a wizard modal variant which provides default bindings for wizard events (see Wizards below).
-−
-== Forms ==
-−
-The standard form handler ($.pkp.controllers.FormHandler) should be bound to all forms. It provides automatic form validation and event binding and therefore reduces the probability for validation glitches or inconsistent form user experience.
-−
-The form currently emits three public events which other widgets can subscribe to:
-* formValid: This event will be generated whenever the form is checked and considered valid for submission. Forms are usually validated after every keyup or focusout event on one of the form elements.
-* formInvalid: The same as the previous event for a form with invalid form values.
-* formSubmitted: Emitted after the form has been successfully submitted.
-−
-== Wizards ==
-−
-The standard wizard handler ($.pkp.controllers.WizardHandler) provides a framework to implement wizards with a consistent user experience throughout the application. The wizard handler also deals with the details of wizard navigation.
-−
-The wizard handler emits events that other widgets within the wizard or outside of the wizard can subscribe to for their own purposes:
-* wizardAdvance: Triggered when the wizard advances to the next step.
-* wizardClose: Triggered when wizard advance is requested and the last step was reached.
-* wizardCancel: Triggered when the wizard's "cancel" button is clicked. The default implementation triggers a wizardClose event (see above).
-−
-The default implementation of the wizard does not do any validation checks. It provides default event handlers that automatically advance the wizard to the next step when the user clicks the "continue" button and closes the wizard after the last step.
 = Additional Resources =

@@ Line 218: / Line 218: @@
 == Callbacks ==
-If for some reason you really have to implement a callback rather than an event then $.pkp.Handler also provides a callbackWrapper() method that can be used to correctly wrap callbacks so that they are called in the handler context rather than in the context of the calling object.
+If for some reason you really have to implement a callback rather than an event then $.pkp.classes.Handler also provides a callbackWrapper() method that can be used to correctly wrap callbacks so that they are called in the handler context rather than in the context of the calling object.
 This approach should be '''used with care''' because the callbackWrapper() method creates a closure that points back to the handler. If you bind a callback returned by the callbackWrapper() method then you always have to make sure that the reference to the callback is deleted when you remove the handler from the GUI element. If you stick to the encapsulation rules, this should not be too difficult. But watch out!

@@ Line 206: / Line 206: @@
 == Event Management ==
-The $.pkp.Handler class implements an event dispatcher that will centrally handle and route all events emitted by its corresponding GUI widget. '''No events may ever be bound directly to a GUI widget!'''
+The $.pkp.classes.Handler class implements an event dispatcher that will centrally handle and route all events emitted by its corresponding GUI widget. '''No events may ever be bound directly to a GUI widget!'''
 This is necessary because we want to have a central checkpoint for events and we want to be able to garbage collect our event bindings centrally when we remove the handler. We also want to manage the context of an event handler call. The 'this' variable will always be set to the handler and not to the GUI widget that emitted the event (as is default in jQuery).
-The $.pkp.Handler class implements a bind() method. It binds events to the root HTML element of the GUI widget.
+The $.pkp.classes.Handler class implements a bind() method. It binds events to the root HTML element of the GUI widget.
 Whenever possible you should prefer events over callbacks! You often have a choice with jQueryUI for example. Use jQueryUI events rather than callbacks.

@@ Line 191: / Line 191: @@
 GUI widgets are HTML elements. Not all HTML elements need a handler attached but no HTML element can have more than exactly one handler attached.
-Controllers are JavaScript objects that inherit from $.pkp.Handler.
+Controllers are JavaScript objects that inherit from $.pkp.classes.Handler.
 == Strict Encapsulation of Widgets ==

@@ Line 133: / Line 133: @@
 We group object members by visibility and singleton ('static') vs. instance membership in the following order in our object definitions:
 # constructor (use <code>@constructor</code> annotation)
-# private static variables (start with underscore, use <code>@private</code> annotation)
+# private static variables (end with underscore, use <code>@private</code> annotation)
-# private instance variabes (start with underscore, use <code>@private</code> annotation)
+# private instance variabes (end with underscore, use <code>@private</code> annotation)
 # protected instance variables (discouraged, better use private variables with protected accessors/mutators, use <code>@protected</code> annotation)
 # no public static/instance variables - use public accessors/mutators instead!
@@ Line 141: / Line 141: @@
 # protected static methods (use <code>@protected</code> annotation)
 # protected methods (use <code>@protected</code> annotation)
-# private static methods (start with underscore, use <code>@private</code> annotation)
+# private static methods (end with underscore, use <code>@private</code> annotation)
-# private methods (start with underscore, use <code>@private</code> annotation)
+# private methods (end with underscore, use <code>@private</code> annotation)
 Sections are divided with a three line <code>//</code> style comment indicating the class member category.
 You are obviously not supposed to use a member outside its scope even if the visibility is not enforced by closure. Please run <code>lib/pkp/tools/buildjs.sh</code> on your code to make sure that you have not overlooked anything. This is also true for protected object members. While they are named like public methods they must not be used outside of the inheritance hierarchy of the current class.
 = Building and Checking JS Code =