O bbUI é uma toolkit que fornece para as aplicações em HTML5 a experiência do OS do BlackBerry 10, desenvolvida pela equipe do Tim Neil, o bbUI possui elementos da User interface do BlackBerry 10 feitos HTML5 e JavaScript com uma ótima performance. A versão trabalhada neste tutorial será a versão 0.9.6.

Neste tutorial vou mostrar como utilizar o bbUI em seu projeto e listar as principais características referente a layout. Para trabalhar com bbUI será necessário instalar o SDK do WebWorks, caso não tenha instalado você pode conferir o seguinte post:

http://localhost/blackberrydeveloper/categorias/html5/instalando-webworks-sdk-para-desenvolver-html5-para-blackberry-10/

Em meus testes vou utilizar uma extensão para o Google Chrome, o Ripple. Se ainda não possui o Ripple, baixe aqui.

Inicialmente precisamos baixar o bbUI na página do git do projeto : https://github.com/blackberry/bbUI.js/

No git do projeto você irá encontrar, exemplos de como utilizar a biblioteca, documentação e o source do projeto. Baixei o ZIP de todo o projeto o link você encontra na imagem abaixo:

pagina-git-bbui

Baixe e descompacte o zip, no projeto tem as seguintes pastas ext, logos, pkg, samples e src. Nesse tutorial vamos trabalhar com dois arquivos presentes na pasta pkg: bbuui-min.css e bbui-min.js. além desses dois arquivos o meu projeto está organizado da seguinte forma :

Captura de Tela 2013-03-24 às 11.47.04

Mesmo a nível de teste nosso exemplo vai precisar do config.xml que vai ficar dessa forma :

<?xml version="1.0" encoding="utf-8"?>
<widget xmlns="http://www.w3.org/ns/widgets"
        xmlns:rim="http://www.blackberry.com/ns/widgets"
        version="2.0.0.1" id="tutorial">

  <author href="http://www.example.com/"
          rim:copyright="Copyright 1998-2012 Pessoal">Pessoal</author>

  <name>Tutorial BB10</name>

  <description>
	 Tutorial sobre bbUI
  </description>

  <rim:permissions>
    <rim:permit>access_shared</rim:permit>
  </rim:permissions>

  <icon src="img/dev-group.png"/>

  <content src="index.html" rim:allowInvokeParams="true"/>
  <feature id="blackberry.ui.dialog"/>
  <feature id="blackberry.app"/>
  <feature id="blackberry.app.event"/>
  <feature id="blackberry.ui.contextmenu"/>	
</widget>

No config.xml acima para garantir o funcionamento do bbUI, precisamos adicionar três propriedades: feature blackberry.app, blackberry.app.event e blackberry.ui.contextmenu.

Primeiro exemplo vamos criar uma arquivo index.html que carregar bbUI e quando ele for inicializado carregamos outro arquivo HTML e acionamos na tela:

<!DOCTYPE html>
<html>
	<head>

		<title>tutorial bbUI</title>

		<link rel="stylesheet" type="css/text" href="css/bbui-min.css"></link>
		<script type="text/javascript" src="js/bbui-min.js"></script>
		<script type="text/javascript" src="local:///chrome/webworks.js"></script>

		<script>
			document.addEventListener("webworksready", function(e){
					bb.init();
					bb.pushScreen("tutorial.html", "tutorial");
				},false);
		</script>
	</head>
	<body>
	</body>
</html>

No exemplo acima temos um HTML simples que chama os bbui-min.css, bbui-min.js e a chamada do webworks.js. após a chamadas dos arquivos necessários tem uma bloco de script que faz a seguinte:

Na linha 12 é adicionado um ouvinte para quando o WebWorks estiver pronto sera disparada uma função, o evento que é disparado no momento será “webworksready”. Dentro da função que é disparada é inicializa o bbUI com a função “bb.init()” na linha 13 e na linha abaixo é adicionada um tela chamada “tutorial.html” através da função.

Dentro da tela “tutorial.html” tem um markup simples:

<div id="tutorial">Meu primeiro teste</div>

Se em seu teste o apareceu a frase “Meu primeiro teste”, significa que tudo correu bem. Até agora só testamos a inicialização do bbUI. Para entender um pouco o funcionamento do bbUI, ele considera cada tela que ele adiciona via pushScreen(), uma view e cada tela que é adicionada ele vai armazenadas em um array, mas renderiza na tela a view atual para fazer a troca de tela de maneira eficiente.

Por isso para fazer acesso aos elementos via javascript tempos que fazer um tratamento especial em cada situação. Por os elementos são criados em tempo de execução, o bbUI localiza os atributos data- dentro das div’s para montar a tela seguindo o padrão do BB10.

Então agora vamos incrementar o nosso exemplo:

<div id="tutorial" data-bb-type="screen" data-bb-effect="fade">
	<div data-bb-type="title" data-bb-caption="Tutorial bbUI" ></div>

	Agora temos uma tela do bbUI
</div>

Screen

No exemplo acima adicionamos a nossa div a propriedade data-bb-type=”screen” sinalizando que dentro dessa div agora temos uma tela nos padrões do bbUI, além dessa propriedade temos a data-bb-effect=”fade” essa propriedade sinaliza o tipo de animação que a tela irá ser apresentada, além do efeito de fade temos o seguintes efeitos:

  • slide-left: entrada de tela da direita para esquerda
  • slide-right: entrada de tela da esquerda para direita
  • slide-up: entrada de tela de baixo para cima
  • slide-down: entrada de tela de cima para baixo

Title

Dentro da nossa div “screen” temos uma div com o atributo data-bb-type=”title”, sinaliza que esse item será a barra de título de nossa screen, o segundo atributo data-bb-caption=”Tutorial bbUI” define o texto que será exibido. E o resultado será o seguinte:

Captura de Tela 2013-03-24 às 23.40.07

Agora vamos evoluir o nosso arquivo tutorial.html, vou adicionar mais alguns elementos e criar uma navegação entre telas, para isso precisamos criar um novo arquivo “segunda-tela.html”.

Primeiro nosso arquivo tutorial.html atualizado:

<div id="tutorial" data-bb-type="screen" data-bb-effect="fade">
	<div data-bb-type="title" data-bb-caption="Tutorial bbUI" data-bb-img="img/icone-title.png" data-bb-accent-text="BlackBerry Dev Group"></div>
	<div data-bb-type="round-panel"> 
		<div data-bb-type="panel-header">Tipos de botões</div>

		<div data-bb-type="button" id="botao-texto">Botão só com texto</div>
		<div data-bb-type="button" data-bb-img="img/icone-botao.png" id="botao-imagem-texto">Botão com imagem e texto</div>
		<div data-bb-type="label-control-container">
			<div data-bb-type="row">
				<div data-bb-type="label">Botão sem texto:</div>
				<div data-bb-type="button" data-bb-img="img/icone-botao.png" id="botao-imagem"></div>
			</div>
		</div>
	</div>

	<div data-bb-type="round-panel">
		<div data-bb-type="panel-header">Botão com ação</div>
		<div data-bb-type="button" onclick="bb.pushScreen('tutorial-2.html', 'tutorial-2');" id="botao-com-acao">Carregar uma nova tela</div>
	</div>	
</div>

Vamos falar das primeiras mudanças do arquivo tutorial.html, primeiro div da barra de título(data-bb-type=”title”) adicionamos mais duas propriedades:

  • data-bb-img: onde é possível adicionar uma imagem na lateral da barra de título, o tamanho ideal para essa image é de 71×71 pixels
  • data-bb-accent-text: esta propriedade cria um subtítulo.

Round Panel

Foi adicionado um round-panel, esse elemento serve para agrupar informações em blocos e em cada bloco temos a possibilidade de adicionar headers. Logo após a abertura da round-panel adicionamos uma div com atributo data-bb-type=”panel-header”, o panel-header adiciona um título com uma linha abaixo seguindo o padrão de interface do BB10.

Button

Dentro do primeiro round-panel eu adicionei 3 botões, para criar um botão basta adicionar o atributo data-bb-type=”button” a div em que você deseja transformar em botão e dentro da div adicionamos o texto que será o conteúdo do botão.

Caso deseje adicionar uma imagem ao botão adicionamos o atributo “data-bb-img” e passamos o caminho da imagem como valor dessa propriedade. O tamanho ideal para essa image também é de 71×71 pixels. Para criar um botão com apenas uma imagem, basta não adicionar texto dentro da div do botão.

Label Control

Outra ferramenta que auxilia na construção de telas é o Label Control criado através da propriedade data-bb-type=”label-control-container”, esta propriedade trabalha em conjunto com a round panel e da a possibilidade de trabalhar com linhas e labels.

Como no código acima amarramos os itens que vão fazer parte daquele linha com uma div que contém a propriedade data-bb-type=”row” e antes de um elemento que queremos atribuir o label, adicionamos uma div com a propriedade data-bb-type=”label” e o texto que vai no label adicionamos dentro dessa div.

No último botão dessa tela um evento onclick, e passamos a função para chamar a próxima tela: bb.pushScreen(‘tutorial-2.html’, ‘tutorial-2’), onde passamos o caminho da nova tela que vamos enfileirar e o seu id.

Antes de passar para o código da segunda tela vamos ver o resultado da primeira tela:

Captura de Tela 2013-03-25 às 03.40.48

Na segunda tela temos o seguinte código:

<div id="tutorial-2" data-bb-type="screen" data-bb-effect="slide-left" data-bb-indicator="true">

	<div data-bb-type="title" data-bb-caption="Tutorial bbUI" data-bb-back-caption="Voltar" >
	</div>

	<div data-bb-type="round-panel"> 
		<div data-bb-type="panel-header">Segunda tela</div>
		Carregando uma segunda tela.
		<div data-bb-type="button" id="botao-voltar" onclick="bb.popScreen()">Voltar</div>
	</div>	

	<div data-bb-type="action-bar" data-bb-back-caption="Back"></div>
</div>

Nessa segunda tela adicionamos uma uma propriedade a screen: data-bb-indicator=”true” essa propriedade adiciona um loader para sinalizar o carregamento do conteúdo da tela. Nesta segunda tela adicionei três maneiras de voltar para tela anterior, primeira no título dessa screen foi adicionado a propriedade, data-bb-back-caption=”Voltar” ela adiciona um botão do lado esquerdo da barra de título. A segunda forma foi através do comando dentro do evento onclick do nosso botão, bb.popScreen() é uma função que remove a tela atual. No caso as telas são empilhadas em um array, então removendo a atual voltamos para a tela anterior.

Action Bar

A última forma foi com uma action-bar, ela permite adicionar uma barra inferior de nosso aplicativo, nela podemos adicionar botões para realizar determinadas ações ou simplesmente adicionar um botão de voltar. Como no exemplo abaixo:

Captura de Tela 2013-03-25 às 03.41.23

Em outros tutorias vamos abordar a action bar com mais detalhes.

O resultado da segunda tela foi o seguinte:

Captura de Tela 2013-03-25 às 03.41.15

Trabalhando com JavaScript

Em outros posts vamos trabalhar mais exemplos com javascript, mas uma dica importante para que está criando os primeiros apps com bbUI, como falei anteriormente a lib renderiza os elementos em tempo de execução ou seja, caso tente acessar qualquer elemento diretamente via javascript ou jQuery sem um tratamento específico muito provável ele ainda não está acessível no DOM. Dentro da função bb.init() podemos passar uma série de parâmetros e propriedades, no nosso caso para tratar o problema de acesso aos elementos gerados pela lib, trabalhamos com dois eventos onscreenready e ondomready esse eventos sempre são disparados quando chamamos a função pushScreen().

onscreenready: Esse evento é dispara antes do bbUI montar a tela através das div com os atributos de marcações, ou seja podemos manipular os elementos html antes de serem renderizados pelo bbUI, nesse momento o bbUI sabe o conteúdo do arquivo mas ainda não foi adicionado no DOM.

ondomready: é disparado quando o bbUI terminou de montar a tela, então nesse momento a barra de título, os botões e label já foram criados.

Para ficar claro vamos a um exemplo prático, abaixo vou mostrar o nosso arquivo index.html atualizado:

<!DOCTYPE html>
<html>
	<head>

		<title>tutorial bbUI</title>

		<link rel="stylesheet" type="css/text" href="css/bbui-min.css"></link>
		<script type="text/javascript" src="js/bbui-min.js"></script>
		<script type="text/javascript" src="local:///chrome/webworks.js"></script>

		<script>
			document.addEventListener("webworksready", function(e){
					bb.init({onscreenready : function(element, id, params) {
		                            if (id == 'tutorial') {
										if(document.getElementById('tutorial')){
											console.log("onscreenready: existe um elemento no DOM com id tutorial")
										}else{
											console.log("onscreenready: não existe um elemento no DOM com id tutorial");
											element.getElementById('tutorial').innerHTML += '<div data-bb-type="button" id="ready-screen"> botão com onscreenready</div>';
										}
		                            }
		                        }
         					, ondomready : function(element, id, params) {
		                            if (id == 'tutorial') {
		                            	if(document.getElementById('tutorial')){
											console.log("ondomready: Existe um elemento no DOM com id tutorial")
											document.getElementById('tutorial').innerHTML += '<div data-bb-type="button" id="ready-dom"> botão com ondomready</div>';
										}else{
											console.log("ondomready: Não existe um elemento no DOM com id tutorial")
										}
		                            } 
		                        }
         					});
					bb.pushScreen("tutorial.html", "tutorial");	
				},false);
		</script>
	</head>
	<body>
	</body>
</html>

O código acima anteriormente carregava apenas o arquivo tutorial.html, foi adicionado um teste simples para entender o funcionamento dos dois evento. Nosso arquivo tutorial.html tem uma div com id “tutorial” foi adicionar a cada evento uma função que dentro dessa função eu verifico se existe um elemento com id “tutorial” e em casa caso eu mando imprimir uma frase no console. E o resultado é o seguinte:

Captura de Tela 2013-03-27 às 03.20.00

Como podemos observar na chamada do onscreenready temos o seguinte retorno: não existe um elemento no DOM com id tutorial, isso significa que o elemento com id tutorial ainda não foi adicionado no DOM. Mas a função que é disparada quando evento é chamado passa três parâmetros: element, id, params.

  • element é o conteúdo da página ainda não executado.
  • id do elemento enviado
  • params caso tenha sido enviado algo na função pushScreen(), exemplo :bb.pushScreen(‘tutorial.htm’, ‘tutorial’, {nome: ‘Fellyph’, devGroup: “São Paulo”});

Se inspecionarmos a variável element, vamos ver que o conteúdo da tutorial.html estará ainda no forma original. No caso fiz um tratamento caso não encontrar o elemento com id “tutorial” no DOM, procure dentro da variável element o elemento com id tutorial e adicione um o seguinte html: ‘<div data-bb-type=”button” id=”ready-screen”> botão com onscreenready</div>’

Então o que vai ocorrer, o bbUI vai rederizar o conteúdo da tela com um botão como texto “botão com onscreenready”.

No evento ondomready, o elemento com id tutorial já está no dom, uso a seguinte condicional caso ache adicione o HTML ao conteúdo ‘<div data-bb-type=”button” id=”ready-dom”> botão com ondomready</div>’. Mas como podemos ver no resultado final esse botão não é renderizado porque no evento ondomready o conteúdo da tela já foi processado pelo bbUI.

Captura de Tela 2013-03-27 às 03.20.41

Então com o ondomready podemos acessar elementos de uma página especifica tanto para fazer tratamentos ou adicionar eventos.

Esse tutorial serviu de start para o bbUI.js, a ideia é dividir em outros posts todas as características dessa lib fantástica. os Arquivos do tutorial você confere aqui : https://github.com/fellyph/Tutorial-bbUI

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *