Ajuda:Predefinições

Da Thinkfn

Para articular todo o mecanismo de protecção, de documentação, de desenvolvimento e de testes das predefinições, cada predefinição pode ser dividida em várias páginas.

Em geral, na página da predefinição em si coloca-se somente o código da mesma. Todos os restantes elementos são colocados em subpáginas, que têm o mesmo nome da predefinição mais certos sufixos chave (terminações, adicionadas após o nome da página). Pode ver abaixo os sufixos em uso. Estas subpáginas são opcionais, podendo não existir para predefinições simples.

Um exemplo prático e completo desta separação em diversas páginas, pode ser visto na predefinição {{chamada para artigo (pp)}}. Ao ler esta página de ajuda, é aconselhável estudar a predefinição para melhor compreender o mecanismo subjacente.

Ligação entre as páginas

O elemento chave de ligação entre as páginas é a predefinição {{documentation}}, que deve ser colocada em todas as páginas de cada predefinição. Ela apresenta no topo das páginas uma caixa com links para todas as outras páginas, permitindo a navegação fácil entre todas elas. Também apresenta textos explicativos e algumas instruções úteis.

Os links apresentados nesta caixa funcionam como é normal na wiki, mostrando se a página de destino do link existe, ou não. Quando se segue um link para uma página que ainda não existe, essa página é pré-carregada com um modelo base, que deve ser seguido preenchendo os elementos pedidos, onde necessário. Para consultar e alterar estes modelos visite a página da predefinição.

Páginas das predefinições

Cada predefinição pode ser constituída por várias páginas, cujos nomes são:

  • Predefinição:<nome>
Página do código - esta é a página da predefinição, com o código da mesma.
  • Predefinição:<nome>/doc
Página da documentação - esta é a página de documentação da predefinição (identificada pelo sufixo /doc). Ela é incluída (transcluded) na página do código pela predefinição {{documentation}}.
  • Predefinição:<nome>/cat
Página da categoria - nesta página deve colocar a categoria, ou categorias, da predefinição. A predefinição {{documentation}} atribui as categorias que aqui colocar à página do código e categoriza automaticamente todas as restantes páginas noutras categorias próprias.
  • Predefinição:<nome>/par
Página dos parâmetros - esta página deve listar os parâmetros que a predefinição aceita. Para predefinições complexas pode apresentar as combinações mais comuns de parâmetros. A página deve ser incluída (transcluded) na página de documentação, para demonstrar como usá-la. Também pode ser apresentada aos utilizadores pela própria predefinição, quando esta detecta que os parâmetros foram incorrectamente usados.
  • Predefinição:<nome>/dev
Página de desenvolvimento - esta página normalmente contém o mesmo código que a página do código, mas este pode ser alterado. Assim, pode fazer experiências e testar melhoramentos, sem alterar o código da predefinição verdadeira. Os resultados podem ser verificados na página de testes antes de migrar o novo código para a página do código.
  • Predefinição:<nome>/tst
Página de testes - esta página deve conter casos de teste para verificar o comportamento da predefinição em diferentes cenários de utilização, incluindo os casos limite nos quais as predefinições devem, mesmo assim, ter um comportamento elegante. Cada caso de teste deve ser chamado duas vezes: uma usando a página do código e uma segunda usando a página de desenvolvimento. Os resultados são apresentados lado a lado, para fácil comparação entre a versão actual e a versão de desenvolvimnto. Isto permite verificar facilmente o efeito de qualquer alteração.

Vantagens do mecanismo de separação

Este mecanismo suporta o processo de desenvolvimento e melhoramento das predefinições, permitindo alterar o código na página de desenvolvimento e comparar os resultados do código novo com os do antigo na página de testes, sem que as novas versões sejam visíveis para os leitores da wiki até estarem finalizadas.

Para além de articular o mecanismo de desenvolvimento, a separação dos diferentes elementos permite que somente a página do código esteja protegida contra edições. Os utilizadores podem continuar a alterar as restantes páginas, por exemplo introduzindo melhorias na documentação ou experimentando alterações ao código na página de desenvolvimento, porque estas não estão protegidas. Para que uma alteração ao código, feita na página de desenvolvimento, seja adoptada na wiki, o utilizador deve pedir a um administrador que a migre para a página do código.

Um efeito final da separação dos elementos para fora da página do código, é que reduz o montante de processamento da wiki. Sempre que cada predefinição é usada, a wiki só precisa tratar a página do código, não tendo de processar todo o restante conteúdo, como teria se todos os elementos estivessem numa única página.