Um dos grandes problemas do JavaScript como linguagem de programação não é a falta de documentação mas a quantidade de maus exemplos e documentação desactualizada que existe na web.
Na última JSConf.eu o criador da JSConf original, Chris Williams, juntamente com outros membros da comunidade, decidiram lançar um esforço para tentar minimizar este problema.
Assim nasceu o PromoteJS, cujo propósito muito simples é gerar pequenas snippets de HTML que qualquer pessoa pode incluir no seu site, e que criam links para a Mozilla Developer Network, que é possivelmente o melhor recurso para documentação de JavaScript na web e, apesar de ser da Mozilla, muitas das páginas contemplam também as alternativas existentes noutros browsers.
Por isso vamos fazer a nossa parte e incluir também uma snippet para documentação de JavaScript. Sugerimos a todos os fãs da linguagem que façam o mesmo.
A LibSAPO.js possui, na sua página de projecto no SAPO Software Livre diversa documentação para aqueles que possam querer usar a LibSAPO.js. Apesar de a documentação para a API já estar disponível há algum tempo, começámos a publicar também guias para alguns componentes e um guia de uso básico da lib. Podem consultar a lista aqui.
Recentemente, decidimos que a LibSAPO.js iria deixar de ser baseada em Prototype, e por isso desenvolvemos alguns novos módulos que nos permitiram abandonar essa dependência. Com o passar do tempo, estamos a adaptar outros componentes e o código de alguns projectos para usar apenas o código presente na LibSAPO.js. Entre estes novos módulos encontram-se os seguintes:
Entre outras alterações em módulos já existentes. Muitos destes módulos possuem uma API semelhante à do Prototype para facilitar a transição e adaptação do código já existente. Além disso, existem também alguns novos componentes de UI na LibSAPO.js tais como: E alguns componentes antigos receberam melhorias: E podem encontrar guias de utilização para alguns destes componentes na página de guias.A classe SAPO.Utility.Date é um grande utilitário para trabalhar com datas em JavaScript.
Para usar esta classe basta incluir:
<!-- --> <script type="text/javascript" src="https://js.sapo.pt/SAPO/"></script> <script type="text/javascript" src="https://js.sapo.pt/SAPO/Utility/Date/0.1/"></script>
Inspirando-nos na função "date()" do PHP criámos o método get() com quase todas as funcionalidades, mas em JavaScript.
SAPO.Utility.Date.get();
Este método recebe dois parâmetros, sendo o segundo opcional.
O primeiro parâmetro é o formato da data, como na função "date()" do PHP.
O segundo é objecto Date com a data pretendida. Quando este parâmetro não é passado, é usada a data actual.
Exemplos para a data:
28 de Janeiro de 2010 às 13:03:51
<!-- --> SAPO.Utility.Date.get("Y-m-d H:i:s"); /* 2010-01-28 13:03:51 */ SAPO.Utility.Date.get("U"); /* 1264683831 */ SAPO.Utility.Date.get("r"); /* Thu, 28 Jan 2010 13:03:51 +0000 */
Passando o segundo parâmetro, podemos definir a data e formatar essa data como nos pretendermos.
<!-- --> SAPO.Utility.Date.get('Y-m-d H:i:s', new Date(1234567890000)); /* 2009-02-13 23:31:30 */ SAPO.Utility.Date.get('Y-m-d H:i:s', new Date("October 13, 1975 11:13:00")); /* 1975-10-13 11:13:00 */
Para ver o sample basta ir a:
Este post pretende dar uma pequena introdução ao uso da LibSAPO.js e aos seus componentes mais básicos.
A LibSAPO.js tem como dependência principal o objecto SAPO.
Deste objecto dependem todas as outras classes utilitárias e widgets do SAPO. Assim, para a utilização de qualquer outra classe, será necessário incluir o ficheiro https://js.sapo.pt/SAPO/
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() e bindObjEvent()
Para quem está familiarizado com o Prototype, estes métodos são semelhates ao bind() e ao bindAsEventListener().
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:
A Widget ShareThis permite partilhar via serviços de link, mail ou imprimir para pdf a uma página de um site.
A widget depende do Prototype e da libsapojs.
Para incluir a widget e as bibliotecas devem colocar as seguintes linhas no head do vosso html
<!-- --> <script type="text/javascript" src="https://js.sapo.pt/Prototype/1.8/"></script> <script type="text/javascript" src="https://js.sapo.pt/SAPO/"></script> <script type="text/javascript" src="https://js.sapo.pt/SAPO/Widget/ShareThis/0.1/"></script>
A widget tem 4 modos de funcionamento. Sendo que o modo pré-definido é o modo 3.
Os modos são os seguintes:
Para verem um exemplo dos modos de utilização e decidirem qual se adequa podem ver a sample
A chamada da widget pode ser feita inline ou para incluir num determinado elemento do DOM
* Widget inline
<!-- --> <script type="text/javascript"> new SAPO.Widget.ShareThis(); </script>
* Widget para um elemento do DOM
<!-- --> <script type="text/javascript"> /** * A chamada é feita no dom:loaded do prototype para o elemento já estar disponivel. */ Element.observe(document, 'dom:loaded',function(){ new SAPO.Widget.ShareThis({target: 'id_do_elemento'}); }); </script>
Como podem ver do exemplo da chamada da widget para um elemento DOM a widget recebe um objecto de inicialização para definição de algumas propriedades.
As opções que podem ser passadas à widget são:
<!-- --> <script type="text/javascript"> new SAPO.Widget.ShareThis({clickOutClose: true}); </script>
<!-- --> <script type="text/javascript"> new SAPO.Widget.ShareThis({mode: 0, cssURI: 'https://js.sapo.pt/Assets/Images/ShareThis/style.css'}); </script>
<!-- --> <script type="text/javascript"> new SAPO.Widget.ShareThis({mode: 1, exclude: ['stumbleupon','reddit']}); </script>
<!-- --> <script type="text/javascript"> new SAPO.Widget.ShareThis({mode: 2, pdf: false, email: false}); </script>
<!-- --> <div id="target"></div> <script type="text/javascript"> Element.observe(document, 'dom:loaded',function(){ new SAPO.Widget.ShareThis({mode:3, pageTitle: 'sapo_test_title', clickOutClose: true, target: 'target', language: 'en'}); }); </script>
UPDATE - Isto era a mentira do 1 de Abril. :)
Como toda a gente sabe, os widgets e alguns componentes da LibSAPO.js, são baseados em Prototype.
Depois e algum "brainstorming" da equipa, decidiu-se dar um passo em frente.
Este passo irá mudar completamente a estrutura da nossa lib.
Tudo que será feito, irá ser baseado em jQuery.
A "guerra" foi ganha por alguns e foi perdida por outros :)
Brevemente iremos apresentar aqui exemplos de código e como as nossas classes irão ficar organizadas
Para fazer a manipulação de cookies com JavaScript, o SAPO tem esse utilitário.
A classe "SAPO.Utility.Cookie" tem métodos para fazer o set, get e remove de cookies.
A source está em:
https://js.sapo.pt/SAPO/Utility/Cookie/
Existe um sample em:
https://js.sapo.pt/SAPO/Utility/Cookie/sample/
Para usarem basta incluir:
<!-- -->
SET:
/** * Fazer o set dum cookie: */ SAPO.Utility.Cookie.set(<string>, <string>, <number>, <string>, <string>); /** * Exemplo prático */ SAPO.Utility.Cookie.set('nome', 'valor', 3600); // ou SAPO.Utility.Cookie.set('nome', 'valor', 3600, '/', 'libsapojs.blogs.sapo.pt');
Parâmetros:
name: Nome do cookie;
value: Valor do cookie;
lifetime: Tempo de vida do cookie (em segundos). O tempo será somado à data actual;
path: (Opcional) Path à qual será feito o set do cookie (Default: /)
domain: (Opcional) Host ao qual será feito o set do cookie (Default: host da página)
GET:
Para fazer o get dos cookies para um objecto (nome => valor) basta usar o método "get".
/** * Fazer o get dos cookies. */ var cookieObject = SAPO.Utility.Cookie.get(); // Ficam com um objecto... alert(cookieObject.nome);
REMOVE:
Para apagar um cookie basta usar o método "remove" passando o nome do cookie que se quer remover. (Existem outros parâmetros opcionais que podem consultar em baixo)
/** * Apagar um cookie: */ SAPO.Utility.Cookie.remove(<string>, <string>, <string>); /** * Exemplo prático */ SAPO.Utility.Cookie.remove('nome'); // ou SAPO.Utility.Cookie.remove('nome', '/', 'libsapojs.blogs.sapo.pt');
Parâmetros:
name: Nome do cookie;
path: (Opcional) Path à qual foi feito o set do cookie (Default: /)
domain: (Opcional) Host ao qual foi feito o set do cookie (Default: host da página)
O código existente nos posts passou a ter "Syntax highlight"
Tudo com o plugin em JavaScript que podem consultar neste site
. LibSAPO.js - Documentação...
. SAPO