documentation | tutorial
Please note, this is only a current draft of the online jsolait tutorial and is not complete.

# Object Oriented Programming using JavaScript o Lait

It is very simple to use jsolait for object oriented programming.
In this tutorial we will look at how we can integrate jsolait functionality in our projects.
Then we will create our first jsolait module. As we go on we will add classes and methods and will explore the OOP feautures of jsolai.
All example code can be tried using your own webpage or jsolait online.

## integrating jsolait▲

To use jsolait you will need to copy the library files to the location of your website. Add a refference to jsolait's initialization script( ./jsolait/init.js) in your page.
In HTML it will look like this:
...
<script type="text/javascript" src="./jsolait/init.js"></script>
...
After that you are ready to begin working with jsolait
An easy way to do so is to create a JavaScript file and refference it in the page after the init script.
The script can now use any jsolait functionality in addition to what is available in JavaScript alone.
Your HTML file should now contain somethign similar to the following:
...
<script type="text/javascript" src="./jsolait/init.js"></script>
<script type="text/javascript" src="./tutorial.js"></script>
...

## first script using jsolait▲

As an example we will now use jsolait's powerful string-formating methods.
var s1 = "Hello %s!".format(jsolait.name);
alert(s1);
var s2 = "The number %d as a hexadecimal is %X.".format(123456789,123456789);
alert(s2);
In the example all `%s, %f, %X` are replaced by converting the values passed into the `format` method to a desired format.
There are more formating specifiers than `%s, %f, %X`. Please see the documentation for the `stringformat` module.

## using modules▲

To use modules in your script jsolait provides a special method called `importModule`. Let us see how this works. For an example we will import the `codecs` module which provides e.g. base64 encoding of strings.
var codecs = importModule("codecs");
alert(codecs.listEncoders());
var s1 = "Hello jsolait";
var s2 = s1.encode("base64");
alert("'%s' encoded using base64 is '%s'".format(s1,s2));
The `codecs` module is loaded by jsolait and provided to the script calling the `importModule` function.
Depending on your browser jsolait loads the module source files on demand, i.e. the file is retrieved during the first call to `importModule`. A second call to `importModule` will only return the module object which has been loaded already by the first call, jsolait will not retrieve the file again. In some browsers the feauture of loading moudule files on demand is not available.
This does not mean you cannot uses jsolait. What you need to do is refference all module scripts in your web page.
For oure example our web page would contain something like:
...
<script type="text/javascript" href="./jsolait/init.js"></script>
<script type="text/javascript" href="./jsolait/lib/codecs.js"></script>
<script type="text/javascript" href="./tutorial.js"></script>
...
All module scripts depend on the initialization script `init.js` to be loaded first.
Depending on the module dependencies you must make sure the scripts are refferenced in the right order.
But more on that later.

## creating a jsolait module▲

You can easily create your own modules by using the `Module` constructor.
See the following code:
Module("tutorial", "0.0.1", function(mod){
var codecs = importModule("codecs");
mod.testCodecs = function(data){
alert(codecs.listEncoders());
var s1 = "Hello jsolait";
var s2 = s1.encode("base64");
alert("'%s' encoded using base64 is '%s'".format(s1,s2));
}
})
The module constructor is a function with 3 parameters. The first one is the module's name. This name is used when importing modules.
The second one is the modules version. It is good practice to give a module a version string.
The third parameter is a function object.
This function is called to construct the module. Once constructed the module is registered with jsolait and can be imported.
A special parameter `mod` is passed to that function wich represents the modul. It is very similar to the `this` object in JavaScript. All properties set on the `mod` object will become public properties of the module. In our example this would be the `testCodecs` method.
Variables declared with `var` are only visible inside the module constructor. One could say they are the private objects of the module. In our example this would be the `codecs` object.
If you declare a variable without the `var` keyword then this object will become global.
Only declare global objects if you realy intend to create global objects. In most cases you should never need them. The jsolait module for example defines two global objects: `importModule and reportException`.
At first, using a function object might seem a little awkward, but it allowes us to practice good data hiding.

## creating classes▲

Creating classes in jsolait is as simple as creating modules. Especially when it comes to inheritance jsolait will take care of all the work involved for creating subclasses in JavaScript.
Have a look at the following code:
Module("tutorial", "0.0.1", function(mod){
mod.SomeClass=Class(function(publ){
publ.foo = function(p1){
return this.bar * p1;
}
publ.bar = 3;
})
})
You can see we declared a public object in our module. This object is a class object created with the `Class` function.
The `Class` function accepts up to three parameters. For now we only need one, a function object. Similar to the function object passed to the module constructor it is used for data hiding.
The parameter passed to the function object is the `publ` object. All properties added to this object will become the public members of the class.
In our example we have two public members of the class: the method `foo` and the property `bar`.
To create objects of the class we use the JavaScript `new` keyword.
var tutorial = importModule("tutorial");
var obj = new tutorial.SomeClass();
alert(obj.foo(3));
Becase our class `SomeClass` is part of the module `tutorial` we need to import that module before we use it. Then we can create an object of our class and call methods of that objects.

## inheritence▲

Let us create another class and have it be a subclass of `SomeClass`.
Module("tutorial", "0.0.1", function(mod){
mod.SomeClass=Class(function(publ){
publ.foo = function(p1){
return this.bar * p1;
}
publ.bar = 3;
})
mod.SubClass = Class(mod.SomeClass, function(publ, supr){
publ.foo=function(p1){
var v1 = supr(this).foo(p1);
return v1 * 3;
}
})
})
In the above excample one can see that we added another class to our module. The difference to the first class is that we pass in another parameter to the `Class` method before the last parameter, the function object. This first parameter is the base class of our new class, i.e. our new class will inherit form that class.
You can also notice that we have another parameter `supr` in our function object. This parameter is a spechial function for calling overwritten methods of the base class. You can see how a base class method is invoked in the line `var v1 = supr(this).foo(p1)`.
`SubClass` overwrites the `foo` method of `SomeClass`. When the `foo` method is called then it calls it's base class's `foo` method first, then multiplying the return value by 3 and then returns the result.

## object initialization▲

Whenever an object is created form a class an initialization method is called with the parameters passed to the constructor. This method is named `init` and you may consider it to be the constructor of the class, though technically speaking it is not. You can overwrite the `init` method in your class. If you do so make sure you call the base class's `init` method. For example:
Module("tutorial", "0.0.1", function(mod){
mod.SomeClass=Class(function(publ){
publ.init = function(barVal){
this.bar = barVal;
}
publ.foo = function(p1){
return this.bar * p1;
}
publ.bar;
})
mod.SubClass = Class(mod.SomeClass, function(publ, supr){
publ.init = function(a, b){
supr(this).init(a * b);
}
publ.foo=function(p1){
var v1 = supr(this).foo(p1);
return v1 * 3;
}
})
})
You can see that both of our classes have different initialization parameters and that `SubClass` calls the `SomeClass`'s initialization method.
The code for the object creation would look like this:
var tutorial = importModule("tutorial");
var obj = new tutorial.SubClass(3,4);
alert(obj.foo(3));

## exception handling▲

coming soon

## module dependencies▲

coming soon