Ir para o conteúdo

Java Help

O JavaHelp, actualmente na versão 2.0, é simultaneamente uma API e um sistema que permite criar componentes de ajuda e documentação online. Baseando-se num conjunto de XML e HTML é possível, com o JavaHelp, criar uma solução de documentação única que seja multi-plataforma e multi-browser. Embora seja usada principalmente em aplicações Java, esta tecnologia poderá ser usada por qualquer aplicação e para criar documentação com qualquer fim, não apenas para sistemas de ajuda, por exemplo, criando livros online.

No artigo que se apresenta de seguida é dada uma explicação de como usar o sistema JavaHelp para criar a ajuda de uma aplicação Java.

O Sistema JavaHelp

A criação de um sistema de documentação com o JavaHelp tem por base a classe HelpSet. Esta classe representa toda a documentação compilada e que está visível ao utilizador.

O processo é definido em 3 fase:

  1. Criação de um conjunto de ficheiros HTML, que contêm a ajuda;
  2. Criação dos ficheiros XML que irão controlar o acesso aos ficheiros HTML, navegação, relação entre páginas, capítulos, etc.;
  3. Criação do ficheiro XML que define um HelpSet.

Ficheiros HTML, o conteúdo

Os ficheiros HTML usados poderão ser criados em qualquer editor HTML existente, desde que os marcadores usados correspondam apenas aos disponíveis na versão 3.2 do HTML. Isto significa que não podem ser usados scripts JavaScript. Podem, no entanto, ser criados componentes Java e adicioná-los aos ficheiro HTML usando a tag OBJECT.

Ficheiros XML

A maioria dos ficheiros XML a criar irá definir as entre o conteúdo e as vistas do sistema, que permitirá controlar o que o utilizador vê. Estes são os chamados ficheiros Map. Para se definir relações entre ficheiros XML e HTML utiliza-se um ficheiro que normalmente tem a extensão ".jhm", embora outra extensão possa ser usada. A tag raiz deverá ser sempre map, que contém várias outras tags mapID com os atributos target e url.

Além das relações acima indicadas é possível descrever várias vistas de utilização da ajuda, tais como:

  • Conteúdo
  • Índices
  • Procura
  • Glossário
  • Favoritos

O ficheiro de tabela de conteúdos tem como raiz a tag toc e inclui várias tags tocitem, tantas quantas as páginas a apresentar ao utilizador, com os atributos text e target. A propriedade do atributo target deve ser definida no ficheiro Map. O ficheiro de índices é semelhante, apenas se substitui toc por index, na definição do ficheiro.

Existem outros tipos de ficheiros, mas que apenas serão mencionados numa versão posterior deste texto.

HelpSet e XML que o define

A criação de um XML que defina o HelpSet irá permitir escolher os ficheiro Map e as vistas a utilizar, bem como outras especificações referemtes ao aspecto e apresentação do sistema. Este ficheiro normalmente tem como extensão .hs de HelpSet, sendo possível também definir outra extensão. A tag raiz deste ficheiro é helpset.

Este ficheiro contém o título, title, a definição do ficheiro Map, maps, com homeID e mapref, e várias vistas.

Depois de todos os ficheiros criados apenas falta criar o código Java que permita a utilização da documentação por um software:

        String path = "file:" + "helpset.hs";
        try {
            URL url = new URL(path);
            HelpSet set = new HelpSet(null,url);
            JHelp help= new JHelp(set);
            JFrame f = new JFrame();
            f.setContentPane(help);
            f.setTitle("Ajuda");
            f.setSize(400,450);
            f.setVisible(true);
        }
        catch(Exception e) {
            this.addLog("HelpSet " + path + " not found");
        }

A exposição da tecnologia está longe de ser completa e deverão consultar mais documentação sobre o sistema em http://java.sun.com/products/javahelp.