Kauri Documentation
 PreviousHomeNext 
21.1.5 Test hintsBook Index21.3 Subversion configuration

21.2 Coding style

Without getting religious about coding style guidelines, it is pleasant and productive if all code follows more or less the same style. Basically, just do the same as the current sources, and follow the standard Java conventions (ClassNamesLikeThis, static finals in uppercase, etc). Opening braces are on the same line. Use some whitespace, e.g. write x = 5 + 3, not x=5+3.

One special point that requires attention: use spaces for indentation, do not use tabs. For Java sources, we use 4 spaces, for XML 2 spaces.

For your convenience we provide a formatter-profile with the kauri conventions for java sources which you can import in your IDE (if supported).

For Javascript, please follow the Dojo style guide .

For CSS, use these coding conventions

Please use the following license header:

/*
 * Copyright 2008 Outerthought bvba and Schaubroeck nv
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

21.2.1 js guide

21.2.1.1 Intro

Getting started with Javascript we recommend O'Reilly's book with the Rhino on the cover

For people coming from Java, this blogpost might get some common misconceptions out of the way fast. Same is true for this (sit back and relax) "Youtube video of the Google Techtalk "Javascript the good parts"

In Javascript land there are a number of techniques that enable to achieve the same thing. This page lists the ones we opt for in the coding of the needed Kauri libraries.

21.2.1.2 jQuery.com

We have chosen to use the jQuery library as a base for the Javascript development. The parts we'll be using most have been combined in our jQuery crash-course which is mainly a list of direct pointers in to the well-done jQuery documentation.

21.2.1.3 Coding techniques

21.2.1.3.1 Cloning a js object

jQuery provides a built-in member copy strategy in its 'extend' function. It can be used to make shallow object clones easily by extending a new created object:

    var clone = jquery.extend({}, original);
21.2.1.3.2 OOP like inheritance
21.2.1.3.2.1 Prototype definitions

A more design-time (and better performing) way to let all object instances of a certain 'type' behave in the same way and share the same properties is achieved by creating actual 'classes' and subclasses.  The 'classes' are created through Javascript prototype definitions:

  function  Base() {
    ...
  }

  Base.prototype.methodX = function(...) {
    ...
  }

The usage of prototype is standard Javascript practice.

21.2.1.3.2.2 Subclassing

Creating a subclass that inherits from the above is then done like this:

  Sub.prototype = new Base();
  Sub.prototype.constructor = Sub;
  Sub.prototype['<super>'] = Base.prototype;
  function Sub() {
    ...
  }
  
  Sub.prototype.methodX() {
    ...
  }

The first two lines are standard Javascript way of working the '<super>' property we introduce so we can call upon super implementations from the subclasses.

This last feature is offered through two additional methods:

The '<super>' property and these last two methods are automatically added to any subclass object created through our own $.inherit() function that takes two constructor-functions as argument, the subclass-function, resp. the superclass-constructor.

With this in place we get constructs like this:

  $.inherit(Sub, Base);

  function Sub() {
    this['<super.init>'](...);
  }

  Sub.prototype.methodX() {
    ...
    this.['<super.call>']("methodX", [...]);
    ...
  }
21.2.1.3.3 Namespacing

Javascript libraries have to watch out claiming names when being loaded.  Since any declared function (like for class-constructors) can conflict on the global scope we recommend:

The pattern looks like this:

  (function($){
    $.my = $.my || {};

    function Base() {
       ...
    }

    $.my.Base = Base;
  })(jQuery);

In this way there could be a $.my.Base which is kept completely distinct from say $.yourown.Base.

Kauri introduces in this way the variable: $.org.kauriproject.forms

21.2.1.3.4 Type checking

Javascript provides two techniques for type-of checking:

  1. typeof variableName == 'lowercase-string-name-of-object-type'
    Recommended use for built in Javascript object structures: Array, Number, String, Date, Object
  2. variableName.constructor == namespace.constructorFunctionName
    Recommended for own defined classnames.

21.2.1.4 Documenting js

We use jsdoctoolkit.

The generation is triggered in the maven site building by

  1. configuration in the pom
    <reporting>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo.javascript</groupId>
        <artifactId>javascript-report-maven-plugin</artifactId>
        <version>1.0-alpha-1-SNAPSHOT</version>
        <configuration>
          <sourceDirectory>${basedir}/src/main/resources/KAURI-INF/js/</sourceDirectory>
        </configuration>
        <reportSets>
          <reportSet>
            <reports>
              <!-- include the desired reports -->
              <!-- <report>jslint</report>-->
              <report>jsdoc</report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>
    </plugins>
  </reporting>
  2. calling maven:
    mvn site

A reference of supported tags can be found here.

21.2.1.5 File name convention

We choose to keep the js file names all in lower case.

21.2.1.6 Testing

Debug code

The javascript-maven-plugin can be configured to filter out all lines starting with specified character string.

<configuration>
	<!-- .. -->
        <strip>/* _DEV_ */</strip>
	<!-- .. -->
</configuration>

With the current configuration, all lines starting with /* _DEV_ */ will be deleted at build time. This is handy for inserting debug code when using the unassembled code files.

jQuery Test Suite

Explained in this document.

Crosscheck

Chrosscheck is able to run js-tests without starting a browser, it's pure java.

The next example shows how to load the jQuery and Kauri-form libraries and run a simple test.

crosscheck.onSetup(function() {
    //loads the JavaScript library from the file
    //paths relative to modules/kauri-forms/kauri-forms-framework
    crosscheck.addPath('target/scripts/KAURI-INF/public');
    crosscheck.addPath('../kauri-forms-jquery/src/main/resources/KAURI-INF/js/');
    crosscheck.load('jquery-1.2.3.js');
    crosscheck.load('kauri-forms.js');
});


crosscheck.addSuite({
  test_jquery: function() {
    //any variables, objects or properties defined in 'jquery-1.2.3.js' will be accessible here.
    
    crosscheck.print("Test loaded libraries");
    assertNotNull($, "jQuery not loaded.");
    assertNotNull($.org, "namespace 'org' not registered.");
    assertNotNull($.org.kauriproject, "namespace 'org.kauriproject' not registered.");
    assertNotNull($.org.kauriproject.forms, "namespace 'org.kauriproject.forms' not registered.");
    
    crosscheck.print("Test ValidationResult");
    var errmsg = new $.org.kauriproject.forms.ValidationResult("{0} - {1}", "i18nkey", ["a", "b"]);
    assertTrue(errmsg.getMessage() == "a - b");
 
    crosscheck.print("Test jQuery extend");
    var newObj = {};
    assertNull(newObj.a);
    $.extend(newObj, {a: 5, b: 10});
    assertTrue(newObj.a == 5, 'object not extended.')
  }
});

To run:

java -jar crosscheck.jar [options] [test-file | test-directory]*

Options:

 PreviousHomeNext 
21.1.5 Test hints21.3 Subversion configuration