LibSAPO.js

This guide explains the basic usage and components of LibSAPO.js.

LibSAPO.js is contained in the object SAPO and inside this object exist all the other modules of LibSAPO.js. Therefore, if you want to use any other module, you need to include the file  http://js.sapo.pt/SAPO/


<script type="text/javascript" src="http://js.sapo.pt/SAPO/"></script>


This is a really small file which take cares of the initialization of the lib and includes some useful functions for basic usage.


The object SAPO and the s$ method, which is an alias for document.getElementById are the only global variables declared by LibSAPO.js. Even though we're not polluting the DOM, we still make available two more methods as extensions of the Function object:

  • bindObj()
  • bindObjEvent()

If you're used to Prototype, these methods are the same as bind() and bindAsEventListener().

More information about these methods here: bindObjGuideEn?


Base methods

Without loading any modules, the SAPO object supplies the following methods:

  • SAPO.namespace() - creates the given name space in the "SAPO" object
  • SAPO.Browser - Gives you browser information. This should only be used in very specific cases because it's not good practice to detect browser functionality by it's user agent. It should be done by feature detection instead. The properties you can find are:
    • SAPO.Browser.IE - (true/false)
    • SAPO.Browser.GECKO - (true/false)
    • SAPO.Browser.OPERA - (true/false)
    • SAPO.Browser.SAFARI - (true/false)
    • SAPO.Browser.CHROME - (true/false)
    • SAPO.Browser.KONQUEROR - (true/false)
    • SAPO.Browser.model - browser model (firefox, camino, etc)
    • SAPO.Browser.version - browser version
    • SAPO.Browser.userAgent - "user agent", same as navigator.userAgent
  • SAPO.extendObj(destination, source) - extends the destination object with the properties of the source object


Load JavaScript? at the right time

The SAPO.Dom.Loaded module generates a dom:loaded event which allows you to execute the JavaScript? code only when the DOM is already loaded. Attention: In case there's another JavaScript? library on the page, please look at the last part of this section.

To use this feature, you need to load the SAPO.Dom.Loaded and SAPO.Dom.Event modules:


<script type="text/javascript" src="http://js.sapo.pt/SAPO/Dom/Loaded/"></script>
<script type="text/javascript" src="http://js.sapo.pt/SAPO/Dom/Event/"></script>


After that, you need to observe the event:


<script type="text/javascript">
SAPO.Dom.Event.observe(document, "dom:loaded", function(){
    // execute javascript code here
});
</script>


Alternatively, you can execute the JavaScript? code in a correct way without this module. To do that, just place a script tag as the last page element, right before closing the </body> tag, and preferably inside a closure:


<body>
    <!-- page html -->
    <script type="text/javascript">
    (function(){
        // execute javascript code here
    }());
    </script>
<body>


In case there's another JavaScript? library on the page, you need to make a check due to the way this DOM verification is abstracted. That verification is just checking the name of the event to make sure it's the right one:


<script type="text/javascript">
SAPO.Dom.Event.observe(document, "dom:loaded", function(ev){
    if(ev.eventName == "dom:loaded"){
        // execute javascript code here
    }
});
</script>


SAPO.require()

This method allows you to load other modules dynamically, allowing you to load modules only when necessary and to execute a callback when the file loading is concluded.

In the future, this method will also take care of dependencies of a given module.

This method gets the following parameters:

  • SAPO.require(modules, callback, async)
    • modules - array of modules to be loaded or string with just one module.
    • callback - callback to be executed when the module loading is done
    • async - When true, executes the callback without waiting for the module loading. false by default.

In order to use this module you just need to load the base file of LibSAPO.js. The following example demonstrates the use of the SAPO.Component.Dialog module with SAPO.require:


<script type="text/javascript" src="http://js.sapo.pt/SAPO/"></script>
<script type="text/javascript">
SAPO.require(
    ['SAPO.Dom.Event', 'SAPO.Utility.Dimensions', 'SAPO.Component.Dialog'],
    function(){
        SAPO.Component.Dialog.confirm('testing');
    }
);
</script>