Use a API do jQuery Mobile para obter um controle customizado de baixa granularidade

A API do jQuery Mobile fornece um nível extra de controle sobre a customização de seu website remoto. Tudo, desde a configuração personalizada das opções globais até a entrada em eventos de interação e o trabalho com métodos expostos, é possível com a API e é abordado neste artigo. Ao final deste artigo, você saberá como definir granularmente as opções personalizadas que deseja usar em seu website remoto e também como escrever um código customizado que interaja com a estrutura jQuery Mobile.

Este artigo cobre uma seleção de propriedades, eventos e métodos expostos úteis da estrutura jQuery Mobile. Cada seção explica as opções e fornece uma amostra de código para mostrar como se faz. Para executar quaisquer amostras de código, primeiro é necessário fazer o download da versão mais recente do jQuery e da estrutura jQuery Mobile ou acessar os arquivos diretamente da content delivery network (CDN) do jQuery, dentro de seu arquivo HTML (consulte Recursos).

Opções globais

As seguintes opções globais estão disponíveis por meio da API do jQuery Mobile e permitem que você altere o modo como o jQuery Mobile se comporta por padrão:

Extensão do evento de inicialização do jQuery Mobile
Criação de namespaces customizados
Inicialização da página
Customização da chave de URL da subpágina
Configuração das classes ativas de página e de botão
Configuração das transições padrão de página e de caixa de diálogo
Customização das mensagens de carregamento e erro

Extensão do evento de inicialização do jQuery Mobile

O jQuery Mobile inclui um evento de inicialização que é carregado antes mesmo do evento document.ready do jQuery carregar. Na verdade, o jQuery Mobile aciona seu evento de inicialização, chamado mobileinit, no próprio objeto do documento. Isso permite que você substitua e amplie as opções globais padrão do jQuery Mobile, o que é o ponto de partida para todo este artigo. Para ampliar o evento mobileinit , você precisa adicionar seu manipulador de evento customizado de JavaScript antes de o jQuery Mobile ser carregado e depois de a estrutura jQuery ter sido carregada (veja a Listagem 1).

Lista 1. Ampliando o evento mobileinit do jQuery Mobile

<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="custom-jqm-mobileinit.js"></script>
<script type="text/javascript" src="jquery.mobile.js"></script>

Para ampliar o evento mobileinit ~, primeiro é necessário conectá-lo a uma função customizada. A Listagem 2 mostra um exemplo que usa o método bind para ampliar o evento mobileinit .

Lista 2. Conectando com o evento mobileinit

$(document).bind("mobileinit", function() {
  // Override global options here
});

Ao se conectar de forma bem-sucedida ao evento mobileinit, você pode substituir as opções globais. Para substituir as opções globais, use o método extend do jQuery para expandir o objeto $.mobile (veja a Listagem 3) ou simplesmente substitua as propriedades individuais configurando-as diretamente.

Lista 3. Ampliando o objeto $.mobile

$(document).bind("mobileinit", function() {
  $.extend(  $.mobile , {
    property = value
  });
});

Se houver diversas propriedades que você deseja atualizar, o método extend é uma opção mais limpa, pois não é necessário escrever o objeto $.mobile diversas vezes. No entanto, se houver apenas uma propriedade para atualização, ocupa menos linhas de código simplesmente definir a propriedade individualmente (veja a Listagem 4).

Lista 4. Substituindo valores da propriedade individual

$(document).bind("mobileinit", function() {
  $.mobile.property = value;
});

O objeto $.mobile é o ponto de partida para a configuração de todas as propriedades.

Criando namespaces customizados

É possível customizar os atributos data- de HTML5, como data-role, por meio de namespaces. Um namespace permite que você adicione um nome personalizado que aparecerá entre as partes data- e -role do atributo data-role, por exemplo. A propriedade $.mobile que permite a customização do namespace é ns. A Listagem 5 mostra um exemplo de configuração de um namespace customizado usando a propriedade ns.

Lista 5. Crie um namespace customizado

$(document).bind("mobileinit", function() {
  $.mobile.ns = "my-custom-ns";
});

O namespace customizado usado na Listagem 5 produz data-my-custom-ns-role em vez de data-role, o que o permite ter como alvo esses namespaces por meio de seletores CSS. Ter como alvo os namespaces customizados por meio de seletores CSS permite outra maneira de projetar um tema customizado para widgets remotos que usam esses namespaces.

Inicialização da página

O jQuery Mobile inclui uma propriedade chamada autoInitializePage que determina se a página da web deve ser inicializada. Por padrão, o valor dessa propriedade está definido como verdadeiro, portanto, a página é sempre inicializada quando o documento está pronto. No entanto, ao ampliar o objeto $.mobile, você pode definir essa propriedade como falsa e lidar com a inicialização da página posteriormente. A Listagem 6 mostra um exemplo de como é possível atrasar temporariamente a inicialização da página, enquanto outros scripts são executados. Se você tiver uma grande quantidade de JavaScript do lado do cliente em execução na página da web, talvez seja uma boa ideia atrasar a inicialização, até que o carregamento do DOM seja concluído e o JavaScript do lado do cliente tenha a chance de ser executado.

Lista 6. Configurando a inicialização automática para páginas da web remotas

<!DOCTYPE HTML>
<html>
<head>
  <title>Understanding the jQuery Mobile API</title>
  <script type="text/javascript" src="jquery.js"></script>
  <script type="text/javascript">
    $(document).bind("mobileinit", function() {
      $.mobile.autoInitializePage = false;
    });
  </script>
  <script type="text/javascript" src="jquery.mobile.js"></script>
</head>

<body>

  <div data-role="page">
    <div data-role="content">
      <ul data-role="listview" id="my-list"></ul>
    </div>
  </div>

  <script type="text/javascript">
    $('#my-list').html('<li><a href="page-2.html">Link to another page</a></li>');
    $.mobile.autoInitializePage = true;
  </script>

</body>
</html>

Customizando a chave de URL da subpágina

Ao fazer referência a subpáginas, o jQuery Mobile usa uma chave de parâmetro de URL de ui-page por padrão. É possível alterar essa chave por meio de uma propriedade do objeto $.mobile chamada subPageUrlKey. Qualquer valor de cadeia de caractere atualizado nessa propriedade é refletido nas URLs de subpágina geradas por widget. Por exemplo, se você usar uma subPageUrlKey customizada de my-page, a URL padrão de web-page.html&ui-page=value se tornará web-page.html&my-page=value.

Além de fornecer uma maneira de criar URLs mais atrativas, as chaves customizadas de URL de subpágina também podem fornecer uma maneira de encurtar as URLs ou definir seus valores como algo mais específico para o website que as está usando.

Configurando as classes ativas de página e de botão

Quando uma página da web inclui a estrutura jQuery Mobile, há uma classe CSS padrão aplicada automaticamente ao elemento ui-page. Para alterar o valor padrão, que é ui-page-active, basta alterar a propriedade activePageClass do objeto $.mobile. Ao atualizar essa classe, o CSS padrão incluído com a estrutura não aplica mais seu estilo à classe ui-page-active, pois não existe mais. Portanto, é importante criar sua própria classe CSS customizada que corresponde ao valor fornecido para essa propriedade.

Configurando as transições padrão de página e de caixa diálogo

Por padrão, as páginas e caixas de diálogo incluem um efeito de transição no jQuery Mobile quando as alterações na página são manipuladas via Ajax. A transição de página padrão é slide, enquanto a transição de caixa de diálogo padrão é pop. Para alterar esses valores, você precisa ter como alvo a propriedade defaultPageTransition ou defaultDialogTransition. A Listagem 7 mostra como é fácil alterar os valores dessas propriedades.

Lista 7. Configurando as transições padrão de página e de caixa de diálogo

$(document).bind("mobileinit", function() {
  $.mobile.defaultPageTransition = "fade";
  $.mobile.defaultDialogTransition = "fade";
});

Nesse exemplo, a transição para as páginas e para as caixas de diálogo é um efeito de desvanecimento. A estrutura inclui seis efeitos de transição baseados em CSS: slide, slideup, slidedown, pop, fade e flip. É possível aplicar esses efeitos diretamente em hyperlinks incluindo o atributo data-transition.

Customizando as mensagens de carregamento e erro

Outras duas opções globais sobre as quais a estrutura oferece controle são as mensagens de carregamento e de erro. A mensagem de carregamento mostra um valor de cadeia de caractere de loading por padrão. Para atualizar essa propriedade, você simplesmente precisa ter como alvo a propriedade loadingMessage. Na Listagem 8, eu mudei a mensagem de carregamento padrão de loading para Please wait. Como resultado, quando o Ajax é usado para carregar páginas, uma pequena caixa de diálogo é exibida com minha mensagem de carregamento customizada.

Lista 8. Configurando a mensagem de carregamento padrão

$(document).bind("mobileinit", function() {
  $.mobile.loadingMessage = "Please wait";
});

O valor padrão de pageLoadErrorMessage é Error Loading Page. Eu atualizei essa mensagem a fim de alterá-la para algo mais simples na Listagem 9.

Lista 9. Configurando a mensagem de erro padrão

$(document).bind("mobileinit", function() {
  $.mobile.pageLoadErrorMessage = 'Sorry, something went wrong. Please try again.';
});

Entrando em eventos do jQuery Mobile

É possível ampliar os tipos de evento a seguir usando a API do jQuery Mobile:

Eventos de toque
Eventos de orientação
Eventos de rolagem

Eventos de toque

Há diversos eventos de toque que podem ser customizados no jQuery Mobile. No entanto, esses eventos ficam disponíveis somente quando o usuário que está interagindo com um dispositivo habilitado para toque acessa seu website do jQuery Mobile. Quando esses eventos estão disponíveis, é possível acionar qualquer JavaScript customizado como resposta a cinco eventos diferentes: tap, taphold, swipe, swipeleft e swiperight. Cada um deles é autoexplicativo, como você pode ver na Tabela 1.

Tablela 1. Eventos de toque customizáveis para jQuery Mobile

Evento	Descrição
tap	É acionado quando alguém toca rapidamente na tela.
taphold	É acionado quando alguém toca na tela e mantém o toque durante cerca de um segundo.
swipe	É acionado quando a página da web é arrastada horizontal ou verticalmente. Na verdade, esse é o único evento com propriedades associadas. Essas propriedades são scrollSupressionThreshold, durationThreshold, horizontalDistanceThreshold e verticalDistanceThreshold.
swipeleft	É acionado quando a página da web é arrastada para a esquerda.
swiperight	É acionado quando a página da web é arrastada para a direita.

Para conectar qualquer um desses eventos de toque, talvez seja necessário usar o evento document.ready. Quando o documento estiver pronto, você poderá acessar um elemento e conectar seu evento de toque selecionado (veja a Listagem 10).

Lista 10. Conectando-se a eventos de toque

<!DOCTYPE HTML>
<html>
<head>
  <title>Understanding the jQuery Mobile API</title>
  <link rel="stylesheet" href="jquery.mobile.css" />
  <script src="jquery.js"></script>
  <script type="text/javascript">
    $(document).ready(function(){
      $(".tap-hold-test").bind("taphold", function(event) {
        $(this).html("Tapped and held");
      }); 
    });
  </script>
  <script src="jquery.mobile.js"></script>
</head>

<body>
  <div data-role="page" id="my-page">
    <div data-role="header">
         <h1>Header</h1>
        </div>
        <div data-role="content">
            <ul data-role="listview" id="my-list">
             <li class="tap-hold-test">Tap and hold test</li>
            </ul>
    </div>
  </div>
</body>
</html>

Como você pode ver, o código conecta um evento de toque taphold a um item da lista. Quando o documento estiver pronto, o item da lista nesse exemplo estará disponível para como alvo via jQuery. Portanto, ele é alvo e está conectado ao evento taphold, que muda o HTML dentro do item da lista.

Eventos de orientação

Em smartphones e tablets, há apenas um evento de orientação chamado orientationchange. Esse evento é acionado quando o dispositivo é girado vertical ou horizontalmente. Para determinar para qual direção o dispositivo será girado, acesse a propriedade de orientação, que fornece um valor somente para leitura de portrait ou landscape. A conexão com o evento orientationchange exige ter como alvo o elemento body e usar o método bind para conectar o evento (veja a Listagem 11).

Lista 11. Conectando o evento orientationchange ao elemento body

$(document).ready(function(){
  $('body').bind('orientationchange', function(event) {
    alert('orientationchange: '+ event.orientation);
  });
});

Também é importante conectar o evento após o documento estar pronto. Caso contrário, você receberá resultados inconsistentes devido ao fato de o elemento body não estar disponível no momento da conexão. Também é possível levar esse código um nível acima acionando o evento orientationchange quando o documento estiver pronto (veja a Listagem 12).

Lista 12. Acionando o evento orientationchange quando o documento estiver pronto

$(document).ready(function(){
  $('body').bind('orientationchange', function(event) {
    alert('orientationchange: '+ event.orientation);
  });

  $('body').trigger('orientationchange');
});

O acionamento do evento quando o documento está pronto permite que você determine a orientação quando a página da web é carregada inicialmente. Isso é útil principalmente em situações nas quais você está exibindo conteúdo com base na orientação atual do dispositivo em uso. Os valores de orientação também podem ser acessados via CSS, pois são adicionados ao elemento HTML em sua página da web. Esses recursos avançados permitem que você modifique o layout de seu conteúdo com base na orientação do dispositivo.

Eventos de rolagem

O jQuery Mobile inclui eventos de rolagem que são acionados quando o usuário rola a página da web. O primeiro evento é o evento scrollstart, que é acionado ao começar uma rolagem de página. A Listagem 13 mostra como é possível conectar-se a esse evento e adicionar código JavaScript customizado que é executado quando a rolagem começa.

Lista 13. Conectando com o evento scrollstart

$(document).ready(function(){

  $('body').bind('scrollstart', function(event) {
    // Add scroll start code here
  });

});

Outro evento, chamado scrollstop, é aplicado quando a rolagem da página é interrompida. Como você pode ver na Listagem 14, a conexão com o evento scrollstop funciona da mesma maneira que a conexão com scrollstart.

Lista 14. Conectando com o evento scrollstop

$(document).ready(function(){

  $('body').bind('scrollstop', function(event) {
    // Add scroll stop code here
  });

});

A conexão de ambos os eventos precisa ser realizada quando o documento estiver oficialmente pronto. Isso garante que o elemento body existe e pode ser conectado com êxito aos eventos. Como exemplo, ambos os eventos podem ser úteis para a execução de um código JavaScript que revela opções nas partes mais baixas da página da web, à medida que a página é rolada – isso é chamado de carregamento lento, em que as imagens não são carregadas quando a página da web é originalmente carregada. Isso mantém o tempo de carregamento da página curto, ainda fornecendo o mesmo apelo visual de quando o conteúdo é acessado.

Trabalhando com memórias expostas

As seguintes funcionalidades são possíveis pelo uso dos métodos expostos disponíveis por meio da API do jQuery Mobile:

Alteração de páginas programaticamente
Carregamento silencioso das páginas
Trabalho com métodos de utilitário

Alterando as páginas programaticamente

Um dos diversos métodos expostos na estrutura jQuery Mobile permite que você altere as páginas programaticamente, além do uso padrão de hyperlinks e envios de formulário. Todos os efeitos visuais que ocorrem, desde o carregamento da página até a transição da página, são incluídos quando você altera as páginas programaticamente. A Listagem 15 mostra como alterar a página usando o método do objeto $.mobile, changePage.

Lista 15. Alterando a página usando o método changePage

<!DOCTYPE HTML>
<html>
<head>
  <link rel="stylesheet" href="jquery.mobile.css" />
  <script type="text/javascript" src="jquery.js"></script>
  <script type="text/javascript">
 $("#my-page").live('pagecreate', function(event) {
  $("#alt-link").bind("click", function(event) {
   $.mobile.changePage("page-2.html");
  });
 });
  </script>
  <script type="text/javascript" src="jquery.mobile.js"></script>
</head>

<body>

  <div data-role="page" id="my-page">
    <div data-role="content">
      <ul data-role="listview" id="my-list"></ul>
    </div>
  </div>

  <script type="text/javascript">
    $('#my-list').append('<li><a href="page-2.html">Link to another page</a></li>');
    $('#my-list').append('<li><a href="#" id="alt-link">Link to another
 page programmatically</a></li>');
  </script>

</body>
</html>

Há um argumento exigido, chamado to. Esse argumento pode ser uma cadeia de caractere ou um objeto. O argumento to pode ser uma URL absoluta ou relativa. O argumento do objeto precisa ser um objeto da coleção jQuery – em outras palavras, um elemento sequencial que está sendo usado como uma página adicional. Há também diversas propriedades opcionais que podem ser passadas como um objeto:

transition
reverse
changeHash
role
pageContainer
type
data
reloadPage

A Listagem 15 não usa nenhum dos argumentos opcionais. Em vez disso, ela simplesmente passa o nome de outro arquivo HTML.

Para usar o método changePage, é necessário adicionar algumas coisas. Primeiro você precisa criar um elemento div com um valor de data-role de page e adicione um ID a ele. Com esse ID, é necessário adicionar o evento pagecreate em vez do evento de jQuery, document.ready. Agora você pode adicionar seus eventos de clique. O jQuery Mobile recomenda que você conecte um link em vez de chamar o evento click diretamente. E, finalmente, é possível alterar a página usando o método changePage.

Carregando silenciosamente as páginas

Outro ótimo método do objeto $.mobile é loadPage. É possível usar o método loadPage para carregar páginas externas sem exibi-las. Essa é uma maneira útil de pré-carregar as páginas de modo que elas sejam exibidas com mais rapidez quando o usuário clicar em um link. Para usar este método, é necessário escrever um código de uma maneira bem parecida quando você usa o método changePage. Primeiro você precisa de um elemento page com um ID, de modo que possa acessá-lo para conectar o evento pagecreate. Em seguida, quando o evento pagecreate for acionado, você poderá chamar o evento loadPage (veja a Listagem 16).

Lista 16. Pré-carregando as páginas usando o método loadPage

<!DOCTYPE HTML>
<html>
<head>
    <link rel="stylesheet" href="jquery.mobile.css" />
    <script type="text/javascript" src="jquery.js"></script>
    <script type="text/javascript">
  $("#my-page").live('pagecreate', function(event) {
   $.mobile.loadPage("page-2.html");
  });
 </script>
   <script type="text/javascript" src="jquery.mobile.js"></script>
</head>

<body>

    <div data-role="page" id="my-page">
        <div data-role="content">
            <ul data-role="listview" id="my-list">
  <li><a href="page-2.html">Link to another page</a></li>
 </ul>
        </div>
    </div>

</body>
</html>

O método loadPage inclui um argumento de URL exigido que pode ser uma cadeia de caractere representando uma URL relativa ou absoluta ou você pode passar um objeto. Há também um argumento opcional que aceita um objeto com uma ou mais das propriedades a seguir:

role
pageContainer
type
data
reloadPage
loadMsgDelay

Trabalhando com métodos de utilitário

Há diversos métodos utilitários integrados que fornecem funcionalidades úteis ao desenvolver um website usando a estrutura jQuery Mobile (veja a Tabela 2).

Tablela 2. Métodos de utilitários integrados atuais para o jQuery Mobile

Método	Descrição
$.mobile.path.parseUrl	Analisa uma URL em um objeto com 16 propriedades
$.mobile.path.makePathAbsolute	Converte o arquivo ou diretório relativo em um caminho absoluto
$.mobile.path.makeUrlAbsolute	Converte uma URL relativa em uma URL absoluta
$.mobile.path.isSameDomain	Compara duas URLs
$.mobile.path.isRelativeUrl	Determina se uma URL é relativa
$.mobile.path.isAbsoluteUrl	Determina se uma URL é absoluta
$.mobile.path.base	Trabalha com o elemento base gerado

Conclusão

A estrutura jQuery Mobile é simples de usar, mas não deixe essa simplicidade enganar você. Há muita coisa acontecendo nos bastidores e há muitas formas de adicionar funcionalidades customizadas a fim de fornecer websites e aplicativos remotos avançados. Ao utilizar API, é possível dizer à estrutura como ela deve se comportar por padrão, acelerar o carregamento da página trabalhando com métodos expostos e até mesmo vincular cada interação que ocorre no lado do cliente.

Download

Descrição	Nome	Tamanho	Método de download
Sample jQuery Mobile web page with API code	jquery-mobile-api.zip	115KB	HTTP

Recursos

Aprender

Confira a documentação atual da estrutura jQuery Mobile.
Saiba mais sobre o jQuery no developerWorks.
Na Zona de desenvolvimento da web no developerWorks, encontre vários artigos de instruções e tutoriais, além de downloads, fóruns de discussão e diversos outros recursos para desenvolvedores da web.
Verifique a existência de atualizações remotas no blog Mobile development do developerWorks.
Você encontrará mais centenas de artigos relacionados a dispositivos móveis no developerWorks.
Fique por dentro dos eventos técnicos e webcasts do developerWorks com foco em uma variedade de produtos IBM e tópicos do segmento de mercado de TI.
Participe de um briefing ao vivo e gratuito do developerWorks para se atualizar rapidamente sobre produtos e ferramentas da IBM, bem como tendências do segmento de mercado de TI.
Acompanhe as demos on demand do developerWorks, que abrangem desde demos de instalação e configuração de produtos para iniciantes até funcionalidades avançadas para desenvolvedores experientes.
Siga o developerWorks no Twitter.

Obter produtos e tecnologias

Faça o download e consulte os arquivos JavaScript e CSS do jQuery Mobile.
Faça o download e experimente o IBM Mobile Technology Preview, um conjunto de amostras de código e serviços para ajudá-lo a começar a desenvolver aplicativos remotos que ampliam e se integram à sua empresa. A visualização inclui um serviço de notificação RESTful; PhoneGap, uma estrutura de software livre para o desenvolvimento de aplicativos híbridos remotos; um tempo de execução WebSphere Application Server leve; e amostras de código para que você possa ver como tudo funciona.
O IBM WebSphere Application Server Feature Pack para web 2.0 e Dispositivo móvel inclui o IBM Dojo 1.7 Toolkit, novos blocos de construção rich Internet application (RIA) e remoto e um componente de diagrama com base em Dojo. Com as ferramentas acompanhantes do Rational, o Feature Pack o ajuda e adaptar e implantar aplicativos WebSphere desenvolvidos originalmente para navegadores desktop em dispositivos móveis.
Avalie os produtos IBM da maneira que for melhor para você: faça download da versão de teste de um produto, avalie um produto on-line, use-o em um ambiente de nuvem ou passe algumas horas na SOA Sandbox aprendendo a implementar Arquitetura Orientada a Serviços de modo eficiente.

Discutir

Participe da comunidade do developerWorks. Entre em contato com outros usuários do developerWorks e explore os blogs, fóruns, grupos e wikis voltados para desenvolvedores.

Sobre o autor: Kris Hadlock é desenvolvedor da web e designer por contrato desde 1996. Ele trabalhou em projetos para empresas como SPIN Magazine, IKEA, United Airlines, JP Morgan Chase, GoDaddy Software e Fire Mountain Gems. Ele é autor de Ajax for Web Application Developers (Sams) e The ActionScript Migration Guide (New Riders), bem como um colunista de destaque e escritor de vários websites e revistas de design, incluindo Peachpit.com, InformIT.com e a revista Practical Web Design . Kris também é o fundador do www.studiosedition.com, um estúdio de desenvolvimento de software e design da web especializado na fusão de forma e função.

De 0 a 10, o quanto você recomendaria este artigo para um amigo?

Powered by: