LibSAPO.js

Este guia explica o uso básico e os componentes base da LibSAPO.js.

A LibSAPO.js está contida no objecto SAPO, e dentro deste objecto existem todos os módulos da LibSAPO.js. Assim, para a utilização de qualquer outra classe, será necessário incluir o ficheiro  http://js.sapo.pt/SAPO/ 


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


Este é um ficheiro muito pequeno que apenas trata da inicialização da lib e inclui alguns utilitários básicos necessários para o uso da lib.


O objecto SAPO e o método s$, que é um alias para o método document.getElementById são as únicas variáveis globais declaradas pela LibSAPO.js. Mesmo assim, apesar não "poluirmos" o DOM, disponibilizamos mais dois métodos, como extensão do objecto Function:

  • bindObj()
  • bindObjEvent()

Para quem está familiarizado com o Prototype, estes métodos são semelhates ao bind() e ao bindAsEventListener().

Mais informação sobre estes métodos aqui: bindObjGuide?


Métodos base

Sem a adição de quaisquer módulos, o objecto SAPO fornece os seguintes métodos:

  • SAPO.namespace() - cria o namespace no objecto "SAPO"
  • SAPO.Browser - Objecto que nos dá a informação do browser. Deve apenas ser usado em casos muito específicos, pois não é boa prática detectar funcionalidades pela designação do browser, mas sim pela detecção da funcionalidade. As propriedades que podemos encontrar são:
    • 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 - modelo do browser (firefox, camino, etc)
    • SAPO.Browser.version - versão do modelo
    • SAPO.Browser.userAgent - "user agent", mesmo que navigator.userAgent
  • SAPO.extendObj(destination, source) - extende o objecto destination com as propriedades do objecto source


Carregar JavaScript? no momento correcto

O módulo SAPO.Dom.Loaded gera um evento dom:loaded que permite que se execute o código JavaScript? apenas quando o DOM está carregado. Atenção: caso exista outra library de JavaScript? na página é necessário ver o último ponto desta secção.

Para utilizar esta funcionalidade é necessário carregar os módulos SAPO.Dom.Loaded e SAPO.Dom.Event: 


<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>


E em seguida, observar o evento: 


<script type="text/javascript">
SAPO.Dom.Event.observe(document, "dom:loaded", function(){
    // executar código javascript aqui
});
</script>


Alternativamente, é possível executar o código JavaScript? de forma correcta sem usar este módulo. Para tal é necessário colocar uma tag script como o último elemento da página, exactamente antes do fecho do </body>, e preferencialmente dentro de uma closure: 


<body>
    <!-- html da página -->
    <script type="text/javascript">
    (function(){
        // executar código javascript aqui
    }());
    </script>
<body>


Caso exista outra library de JavaScript? na página é necessário fazer uma verificação devido à forma como esta verificação do carregamento do DOM é abstraída. Essa verificação consiste em verificar o nome do evento, para ter a certeza de que é o correcto: 


<script type="text/javascript">
SAPO.Dom.Event.observe(document, "dom:loaded", function(ev){
    if(ev.eventName == "dom:loaded"){
        // executar código javascript aqui
    }
});
</script>


SAPO.require()

Este método permite fazer o carregamento de outros módulos dinamicamente, permitindo assim que se carreguem módulos apenas quando necessário, e que se execute uma callback quando o carregamento é concluído.

Futuramente este método também fará a gestão das dependências de um dado módulo e poderá vir a ser utilizado para a construção de bundles.

Este método recebe os seguintes parâmetros:

  • SAPO.require(modules, callback, async)
    • modules - array de módulos que devem ser carregados, ou string com apenas um módulo
    • callback - callback a ser executada quando o carregamento dos módulos estiver concluído
    • async - Quando true, executa a callback sem esperar pelo carregamento dos módulos. false por definição.

Para utilizar este módulo basta apenas carregar o ficheiro base da LibSAPO.js. O seguinte exemplo demonstra a utilização do módulo SAPO.Component.Dialog com o 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('teste');
    }
);
</script>