Instalando o TWiki

Esse passo a passo é um resumo prático do Guia de Instalação do TWiki, focado no Debian GNU/Linux. As orientações abaixo podem ser usadas em outras distros GNU/Linux, adaptando-se as pequenas variações entre uma e outra, como o nome do usuário do Apache.

A leitura do guia original é fortemente recomendada, já que cada passo é explicado e são citadas formas alternativas de instalação caso o modelo padrão não seja adequado ao seu caso.

1. Instalação padrão do Apache 2
2. Baixe o pacote tgz de TWiki.org
3. Crie o diretório twiki em /var/www
4. Descompacte o pacote tgz em /var/www/twiki
5. Crie a configuração do Apache automaticamente em TWiki:TWiki.ApacheConfigGenerator
   Este gerador já tem uma boa preocupação com segurança, mas se seu seu servidor exige caracteristicas especiáis de configuração, peça ao administrador de rede que edite este arquivo.
   Na web Codev e TWiki do TWiki.org temos o dicas sobre configurações específicas, como o Shorter URL Cookbook, que nos mostra como ter um TWiki com URLs menores e mais amigáveis, como usamos no TWiki da Colivre.
6. Adicione a configuração do Apache em /etc/apache2/conf.d/twiki.conf
7. Modifique o dono dos arquivos recursivamente para www-data (o usuário do Apache)
   chown -R www-data:www-data TWikiDir
8. Instale as seguintes bibliotecas para garantir um bom funcionamento ao TWiki:
   • libalgorithm-diff-perl - garantia para o versionamento
   • libcgi-session-perl - mantem a sessão em scripts que não exigem autenticação
   • libhtml-parser-perl - dependência do script save
9. Finalmente visite o script configure (http://localhost/twiki/bin/configure) e confirme os paths automaticamente reconhecidos. Se sua instalação não for padronizada aqui você indica o caminho de cada diretório e garante o funcionamento do TWiki.
10. Clique em "Next" e defina uma senha para o configure, que também será usada pelo usuário TWikiAdminUser (Criado na versão 4.2)
11. Visite novamente o script configure para concluir a configuração.
12. Defina a varável $twikiLibPath = "/var/www/twiki/lib"; para informar o caminho absoluto das bibliotecas do TWiki a seus scripts em bin/LocalLib.cfg.txt - e renomeie este para bin/LocalLib.cfg caso contrário o TWiki não fará uso desta configuração.
13. Crie o script /etc/cron.daily/twiki para executar os scripts mailnotify e tick_twiki diáriamente. Usar os diretórios do cron é mais manutenível que apenas um arquivo cron de usuário, por isso não indico aqui o uso de cron -e.
14. Com a existência do usuário TWikiAdminUser a configuração do TWikiAdminGroup não é mais obrigatória, entretanto é interessante faze-lo para que todas as ações, inclusive as administrativas, sejam vinculadas a pessoas.

Ok! O TWiki está pronto para uso.

Script /etc/cron.daily/twiki

O script abaixo força a sua execução pelo usuário do Apache e executa os scripts temporais do TWiki.

#!/bin/bash

apache_user=www-data

if [ "$USER" != "$apache_user" ]; then
  # Working as the Apache user
  su $apache_user -c "$0" "$@"
  exit $?
fi

if ! cd /var/www/twiki; then
  echo Ups... The TWiki is not here. >&2
  exit 1
fi

perl -I bin tools/mailnotify -q >/dev/null

cd bin && perl ../tools/tick_twiki.pl >/dev/null

Instalando alguns Plugins

As extensões do TWiki podem ser baixadas em http://twiki.org/cgi-bin/view/Plugins . E são divididas nas seguintes categorias:
Add-on packages: Scripts independentes para importar e exportar informações, dentre outras coisas.
Plugin packages: Interage diretamente com o TWiki, provêndo novas funcionalidades.
Skin packages: Modifica a aparência do TWiki.
Contrib packages: Código compartilhável entre plugins.

PDF

1. Baixe o tgz de TWiki:Plugins.GenPDFAddOn
2. Abra o tgz na raiz da sua instalação do TWiki
3. Torne o GenPDFAddOn_installer executável e execute-o
   chmod +x GenPDFAddOn_installer  &&  perl GenPDFAddOn_installer
4. Modifique o dono dos arquivos:
   chown -R www-data:www-data bin/genpdf lib/TWiki/Contrib/GenPDF.pm data/TWiki
5. Instale o HTMLDOC: aptitude install htmldoc
6. Adicione a linha abaixo em lib/LocalSite.cfg:
   $TWiki::cfg{Extensions}{GenPDFAddOn}{htmldocCmd} = "/usr/bin/htmldoc";

Busca em Anexos

Instalando TWiki:Plugins.SearchEngineKinoSearchAddOn

1. Instale as dependências para que ele possa ler DOC, PDF e PPT:
   aptitude install antiword xpdf-utils ppthtml
2. Instale as dependências (Debian) que garantem o funcionamento do buscador:
   aptitude install libmodule-pluggable-perl libfile-mmagic-perl libhtml-tree-perl libspreadsheet-parseexcel-perl libencode-perl
3. Instale as dependências (CPAN) que garantem o funcionamento do buscador:
   perl -MCPAN -e "install KinoSearch"
perl -MCPAN -e "install CharsetDetector"
4. Execute o instalador:
   perl SearchEngineKinoSearchAddOn_installer
5. Torne o script executável:
   chmod +x bin/kinosearch
6. Corrija o dono do diretório de trabalho:
   chown -R www-data:www-data kinosearch
7. Copie a configuração do bin/LocalLib.cfg para kinosearch/bin/LocalLib.cfg
8. Adicione a linha abaixo em lib/LocalSite.cfg:
   $TWiki::cfg{KinoSearchLogDir} = '/var/www/twiki/kinosearch/logs';
$TWiki::cfg{KinoSearchIndexDir} = '/var/www/twiki/kinosearch/index';
9. Entre em kinosearch/bin e execute ./kinoindex
10. Corrija o dono: chown -R www-data:www-data ../index ../logs
11. Seia bom adicionar o kinoupdate, mas adicione kinosearch/bin/kinoindex, para garantir a indexação de novos campos de TWikiForm:
    cd /var/www/twiki/kinosearch/bin/ && ./kinoindex

Algo a mais sobre Notificação

O e-mail de notificação de modificação das páginas é lançado pelo script mailnotify. Entre no diretório raiz da insatalação do TWiki e execute:
perl -I bin tools/mailnotify
Neste momento você enviará notificações de todas as modificações feitas desde a última execução deste script para todos os inscritos em todas as webs.

Esse script aceita argumentos pela linha de comando para modificar sua forma de trabalho e filtrar webs.

Formas de cadastro no WebNotify

Pode-se cadastrar usuários, grupos ou simplesmente e-mails no WebNotify, cada um como item de uma lista. É possível informar ao TWiki sobre quais tópicos desejamos ser notificados, incluindo ou excluindo tópicos com ajuda do coringa *. Com os simbolos ! e ? informamos a necessidade do envio do conteúdo completo dos tópicos marcados.

Mais informações em MailerContrib.

Interfaces personalizadas para funcionalidades do TWiki

Veja TWikiScripts para conhecer os scripts da instalação padrão.

O importante é apontar o script corretamente e entregar cada parâmetro, seja via GET ou POST.

Apontando: %SCRIPTURL{script}%

Muitos scripts precisam rodar no contexto de um tópico. Podemos informar o tópico para esses casos adicionando Web/Tópico após o SCRIPTURL, ou enviamos o tópico via GET ou POST. Exemplos:

• URL completa: %SCRIPTURL{script}%/Web/Tópico
• Via GET: %SCRIPTURL{script}%/Web?topic=Tópico
• Via POST:

     <form action="%SCRIPTURL{script}%/Web">
       <input name="topic" value="Tópico" />
     </form>
     

Criando um Botão para Editar o Tópico Atual

<a href="%SCRIPTURL{edit}%/%WEB%/%TOPIC%" rel="nofollow">Edit</a>

Adicionando Elementos na Interface Padrão

Para adicionar o botão que gera PDF do tópico visitado, crie o tópico MinhaTemplate com o seguinte conteúdo:

%TMPL:INCLUDE{"view"}%

%TMPL:DEF{"top:toolbarbuttons"}%
<span><a href="%SCRIPTURL{genpdf}%/%WEB%/%TOPIC%?t=%GMTIME{$epoch}%" \
rel="nofollow" title="Baixar versão PDF deste tópico" accesskey="p">\
<span class="twikiAccessKey">P</span>DF</a></span>
%TMPL:P{"activatable_edit_or_create"}%%TMPL:P{"activatable_attach"}%%TMPL:END%

O bloco top:toolbarbuttons já existia e é parte da template padrão incluída em MinhaTemplate. Redefinimos este bloco para colocar o botão "PDF" ao lado do "Edit" e "Attach" no topo da página.

Criando Tópicos Automaticamente

O TWiki já lhe provê facilidades para criação de tópicos a partir de WikiWords sem tópicos. O interessante é poder criar nomes dinamicamente e até saltar a fase de edição dependendo da necessidade, para isso use os conhecimentos do tópico anterior. Podemos criar tópicos automaticamente de três formas: pedindo que o usuário informe um nome, usando auto incremento ou sufixando o valor de uma variável como a GMTIME.

Pedindo que o usuário informe o nome:

Crie um tópico a partir da submissão de um form, como vimos anteriormente. O usuário deverá adicionar o nome do novo tópico no campo de texto.

Via auto-incremento:

Referencie um tópico finalizado com AUTOINC<n> para o script edit ou save e estes criarão um novo tópico onde AUTOINC<n> será substituído pelo primeiro número natural não usado.

• BugAUTOINC0 >> Bug0, Bug1, Bug2, ..., Bug10, Bug11, ...
• RegAUTOINC000 >> Reg000, Reg001, Reg002, ..., Reg010, Reg011, ...

Exemplo:
[[%SCRIPTURL{edit}%/Web/TópicoAUTOINC0][Novo Tópico]]

Sufixando o valor de uma variável de valor dinâmico:

[[%SCRIPTURL{edit}%/Web/Noticia%GMTIME{$year$mo$day}%][Nova Notícia]]

Expressões Regulares

A orientação se baseia no material de Aurélio Jargas: http://guia-er.sourceforge.net

Use o form abaixo para testar suas expressões:

Criando TWikiApplications

Já dissemos o que são TWikiApplications no Tutorial TWiki, então acompanhe a prática que se baseará no conhecimento dos tópicos anteriores.

Ajax

Já existem várias extensões para usos variados de Ajax no TWiki.

O TWiki pode gerar qualquer gênero de informação textual, então se quiser criar sua própria busca baseada em Ajax, seria uma boa idéia gerar a resposta em JSON. Veja um exemplo de tópico que pode gerar respostas formatadas para buscas variadas:

{
%SEARCH{
"%URLPARAM{"search" encode="quote"}%"
web="%URLPARAM{"web" default="all" encode="quote"}%"
topic="%URLPARAM{"topics" default="*" encode="quote"}%"
excludetopic="%URLPARAM{"exclude" encode="quote"}%"
type="regex"
nonoise="on"
separator=",$n"
format="  '$web.$topic' : %URLPARAM{"format" default="$quot$date$quot" encode="quote"}%"
}% }
/*
   * Set SKIN = text
*/