Escolar Documentos
Profissional Documentos
Cultura Documentos
LRN
Treinamento em OpenACS
Contedo
Parte 1 OpenACS para todos
1. O que OpenACS?.....................................................................................6 1.1. Viso geral..........................................................................................6 Parte 2 Para Administradores 2. Funes administrativas do site.................................................................8 2.1. Diferena entre OpenACS e .LRN......................................................8 2.2. Importncia do conceito de espaos no .LRN: New-Portal................8 2.3. Configurando o meu espao.............................................................9 2.4. Diferena entre comunidades e disciplinas......................................9 2.5. Como criar uma comunidade..........................................................10 2.6. Pgina de administrao da comunidade.......................................10 2.7. Gerenciador de pacotes do OpenACS (APM)...................................10 2.8. Instalando / Atualizando pacotes....................................................10 2.9. Mapa do site...................................................................................11 2.10. Gerenciando permisses e parmetros.........................................11 2.11. Subsites.........................................................................................12 Parte 3 Para Desenvolvedores de Pacote 3. Criando um novo pacote.........................................................................14 3.1. Criando um pacote de aplicaes....................................................14 3.1.1. Criando um novo pacote..........................................................14 3.1.2. Mapa pretendido das pginas..................................................14 3.1.3. Viso geral...............................................................................14 3.1.4. Antes de comear....................................................................15
3.1.5. Usando o APM para inicializar o novo pacote...........................15 3.1.6. Adicionando uma instncia da aplicao ao servidor...............16 3.1.7. Inicializao rpida..................................................................16 3.2. Ajustando os objetos no banco de dados.........................................16 3.2.1. Construindo o data model........................................................19 3.3. Criando pginas para a Internet......................................................19 3.3.1. Instalando algumas API's.........................................................19 3.3.2. Mapa das pginas....................................................................19 3.3.3. Construindo a pgina Index..................................................20 3.4. Debug e testes................................................................................24 3.4.1. Debug......................................................................................24 3.4.2. Testes Manuais.........................................................................25 4. Template para designers..........................................................................26 4.1.Escrevendo um template, a parte ADP de uma pgina....................26 4.2.Referncias para marcaes em template........................................26 5. Template para desenvolvedores..............................................................29 5.1.Principais temas disponveis.............................................................29 5.2.Alterando o template de um tema....................................................29 Parte 4 Para Desenvolvedores da Plataforma 6. API's.........................................................................................................33 6.1.API doc..............................................................................................33 6.2.Ad_form............................................................................................33 6.3.List builder........................................................................................42 7. Permisses, API's avanadas...................................................................49 7.1.Sistema de permisses.....................................................................49 7.2.Estratgia de permisses.................................................................50 7.3.Processos agendados (ad_schedule_proc)........................................53 7.4.Colocando processos em cache (util_memoize)...............................53 8. Infra-estrutura necessria.......................................................................55 8.1. Instalao do Linux e softwares necessrios...................................55 8.2. Instalao do PostgreSQL................................................................55 8.3. Instalao do AOLServer..................................................................60 8.4. Instalao do OpenACS ..................................................................62 8.5. Descrio detalhada do arquivo config.tcl.......................................65 3 Autor: Eduardo Santos
8.6. Instalao via apt-get......................................................................71 9. Scripts de instalao automtica............................................................74 9.1. Criando e executando scripts..........................................................74 10. Configuraes iniciais............................................................................81 10.1. Como configurar o site no primeiro acesso....................................81 10.2. Instalando o .LRN no primeiro acesso............................................82 10.3. Parmetros importantes na criao do site...................................82 11. Futuro do OpenACS: Xowiki...................................................................84 11.1. Introduo......................................................................................84 11.2. Tipos de pgina.............................................................................84 11.3. Diretrios.......................................................................................85 11.4. Editando........................................................................................85 11.5. Diferentes tipos de pgina.............................................................91 11.6. Subsituies e variveis de template............................................91 11.7. Templates de pgina (Page Templates)..........................................92 11.8. Seletor de arquivos........................................................................92 11.9. Configuraes................................................................................93 12. Referncias............................................................................................97
Minhas comunidades Minhas notcias Meu calendrio Outros Meus Documentos Meu Calendrio Completo
O portal do usurio feito de meus aplicativos pessoais (portlets) mais os aplicativos das comunidades que fao parte. Assim, as notcias que vejo em minha pgina inicial so as notcias de todas as comunidades que fao parte. Contudo, existem alguns portlets que so especficos do usurio, como as minhas comunidades e meus fruns de discusso. Portal da Comunidade
Informaes da Comunidade Notcias Fruns Subgrupos Calendrio da comunidade Outros Calendrio completo Documentos Membros
Pgina 2 (Calendrio)
Pgina 4 (Pessoas)
atividades de ensino-aprendizagem. A disciplina tem um assunto especfico a ser tratado por um determinado tempo (normalmente o perodo da disciplina) com a inteno de estender ou substituir as atividades de sala de aula. A comunidade no tem necessariamente um tempo especfico, e os administradores podem variar com o tempo e a necessidade. Normalmente o assunto mais importante que as pessoas, enquanto a disciplina feita para aquele grupo especfico de pessoas. Em termos de plataforma o .LRN trata as duas de maneiras bastante distintas. Existem ferramentas especficas para as disciplinas e comunidades, como o mdulo dever de casa, exclusivo das disciplinas. As primeiras tm, necessariamente, dia e hora para terminar, e devem ser separadas em departamentos. O moderador normalmente no muda, e o sistema de acompanhamento mais importante. Quando o foco EAD, deve-se usar disciplinas, enquanto as comunidades so mais eficientes para gesto do conhecimento.
2.8.Instalando/Atualizando Pacotes
Quando vamos instalar ou atualizar os pacotes podemos faz-lo diretamente do repositrio do OpenACS ou do nosso sistema de arquivos. importante lembrar que para baixar um pacote diretamente do repositrio do OpenACS necessrio ter permisso de acesso. Normalmente no possvel 10 Autor: Eduardo Santos
acessar diretamente em sistemas de produo protegidos por firewall. Para instalar ou atualizar do sistema de arquivos, v para a pgina de administrao do OpenACS e clique em install software. Renomeie o arquivo antigo para o seu_pacote.bak ou seu_pacote.old e copie a nova verso para a pasta /packages. O OpenACS o reconhecer automaticamente e executar os scripts de atualizao ou instalao.
2.9.Mapa do Site
Todas as aplicaes e pacotes esto montadas de acordo com o mapa do site, que indica o ponto de montagem. Alguns j so montados automaticamente, no momento da instalao, mas outros precisam ser montados manualmente. Para montar uma nova aplicao basta indicar o nome do pacote e o nome do ponto de montagem, que tambm pode ser chamado de n.
2.11.Subsites
Tudo o que temos falado at agora baseia-se na premissa de estarmos montando apenas um site principal. Todavia, a estrutura do OpenACS permite que sejam montados vrios subsites dentro da mesma instalao. Vamos supor o caso de uma empresa comercial que mantenha um ambiente de comunidade para os seus clientes. Pode no ser do interesse dela que todas as pessoas que navegam pela rede tenham acesso ao ambiente de comunidades, mas certamente interessante que possam acessar sua rea comercial. Uma soluo seria montar um subsite com a parte comercial e outro com a rea do .LRN, onde ficaria hospedado o ambiente de comunidades.
12
13
3.1.3.Viso geral
Para iniciar o desenvolvimento de um novo cdigo no OpenACS construmos um pacote. Pacote uma coleo discreta de pginas da Internet, cdigo TCL, tabelas no banco de dados e procedimentos. Um pacote com interface interface para o usurio chamado de aplicao; um pacote que gera funes para outros pacotes e no tem interface direta chamado de servio. Um pacote pode ser instalado, atualizado e removido. Ele se comunica com os outros pacotes atravs de uma API. Este captulo mostra passo-a-passo como criar um pacote til, incluindo escrever documentao, ajustar tabelas e procedures, escrever pginas, debug e construir testes. Este tutorial usa o pacote content repository, o que simplifica radicalmente o trabalho do banco de dados, mas nos fora a trabalhar com suas limitaes, inclusive uma API TCL incompleta. Assim, o tutorial um pouco mais bagunado que o desejado. Cdigos que representam uma espcie de hack esto claramente marcados. Neste tutorial ns faremos uma aplicao para mostrar uma lista de notas. 14 Autor: Eduardo Santos
3.1.4.Antes de comear
Voc vai precisar de:
Um computador com uma instalao do OpenACS rodando. Arquivos de exemplo, que esto disponveis desde a verso 5.2.0d1 do OpenACS.
Vamos seguir as seguintes notaes para esta seo: Domnio completo do seu servidor URL do seu servidor Nome da conta de desenvolvimento Novo Package key yourserver.test http://yourserver.test:8000 $OPENACS_SERVICE_NAME myfirstpackage
Package Key: myfirstpackage Package Name: My First Package Package Plural: My First Package Initial Version: 0.1d Summary: Este o meu primeiro pacote
No final clique em Create Package Um novo pacote ser criado no diretrio /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage. Este o diretrio onde sero armazenados todos os arquivos.
15
3.1.7.Inicializao rpida
O resto do tutorial explica detalhadamente a funo de cada arquivo enquanto o pacote criado. Voc pode pular tudo isso e ter um pacote funcionando fazendo o seguinte:
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-coredocs/www/files/tutorial psql $OPENACS_SERVICE_NAME -f myfirstpackage-create.sql cp note-edit.* note-delete.tcl index.* ../../../../myfirstpackage/www/ mkdir ../../../../myfirstpackage/lib cp note-list.* ../../../../myfirstpackage/lib/ cp myfirstpackage-*sql ../../../../myfirstpackage/sql/postgresql/ cp myfirstpackage-procs.tcl ../../../../myfirstpackage/tcl/test/ cp note-procs.tcl ../../../../myfirstpackage/tcl/
Depois de reiniciar o servio a aplicao de teste estar instalada e funcionando na URL que voc selecionou no passo anterior.
create.sql, que ser acionado automaticamente quando o pacote instalado. Este arquivo deve criar todas as tabelas e views. Nosso pacote vai armazenar todas as informaes em uma nica tabela. necessrio, contudo, mais que um simples comando CREATE TABLE, pois queremos integrar nossa tabela com o OpenACS. Ao fazer com que cada entrada na tabela seja um objeto do OpenACS ganhamos acesso ao sistema de permisses e a outros servios integrados a eles, como general-comments e notification. O custo para faz-lo complicar bastante o cdigo, pois precisam ser includas muitas funes e procedimentos armazenados, o que pode ser um problema (at mesmo para tabelas simples). Existem muitos tipos de objeto no OpenACS (voc pode visualizlos com o seguinte comando: select object_type from acs_object_types;). Um deles o content_item, que parte do content repository. Para uslo, faremos com que nossos objetos sejam filhos do objeto content_revision, que por sua vez filho do content_item. Assim no somente teremos os benefcios dos objetos do OpenACS e dos content objects, como tambm usaremos algumas funes do content repository para simplificar a criao do banco de dados. Figura 3.2. Modelagem de dados do tutorial
A parte de cima de um dos arquivos sql tm alguns comentrios padro, incluindo tags de documentao, como @author, que ser interpretada pelo API browser. A string $Id:$ ser expandida automaticamente quando o arquivo for includo no cvs.
[$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/ [$OPENACS_SERVICE_NAME postgresql]$ vi myfirstpackage-create.sql
Copie o texto abaixo no arquivo, salve e feche. Figura 3.3 Script de criao do banco de dados
-- creation script --- @author joel@aufrecht.org -- @cvs-id &Id:$ -select content_type__create_type( 'mfp_note', -- content_type 'content_revision', -- supertype
17
'MFP Note', -- pretty_name, 'MFP Notes', 'mfp_notes', 'note_id', null ); -- necessary to work around limitation of content repository: select content_folder__register_content_type(-100,'mfp_note','t'); -- pretty_plural -- table_name
-- id_column
-- name_method
O script de criao chama uma funo em PL/pgSQL (PL/pgSQL uma linguagem procedural de extenso ao sql), content_type__create_type, que no caso cria as alteraes necessrias no banco de dados para suportar o nosso objeto de dados. Preste ateno ao uso de mfp. O nome vem de My First Package e garante que o nosso objeto nico e no causar conflito com objetos de outros pacotes. Crie um arquivo nico que jogar fora tudo se o pacote for desinstalado.
[$OPENACS_SERVICE_NAME postgresql]$ vi myfirstpackage-drop.sql
Como o script de criao, o de remoo chama uma funo PL/pgSQL: content_type__drop_type. Rode o script manualmente para adicionar suas tabelas e funes.
[$OPENACS_SERVICE_NAME postgresql]$ psql -f myfirstpackage-create.sql psql:myfirstpackage-create.sql:15: NOTICE: will crea psql:myfirstpackage-create.sql:15: NOTICE: implicit tr content_type__create_type CREATE TABLE / PRIMARY KEY CREATE TABLE will create
18
Uma vez que ambos os scripts estejam funcionando sem erros, rode o de criao mais uma vez e prossiga.
[$OPENACS_SERVICE_NAME postgresql]$ psql -f myfirstpackage-create.sql
Para tornar efetivo o arquivo v para o APM e escolha Reload Changed para My First Package.
19
20
Voc pode testar o seu cdigo visualizando a pgina. Basta digitar no seu navegador o endereo do ponto de montagem da aplicao. A pgina index contm um include para a pgina note-edit, que foi montada no diretrio /lib ao invs do /www. Assim o arquivo pode ser utilizado por outros pacotes e pginas.
[$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib [$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib [$OPENACS_SERVICE_NAME lib]$ vi note-list.tcl template::list::create \ -name notes \ -multirow notes \ -actions { "Add a Note" note-edit} \ -elements { edit { link_url_col edit_url display_template {
21
<img src="/resources/acs-subsite/Edit16.gif" width="16" height=" 16> } sub_class narrow } title { label "Title" } delete { link_url_col delete_url display_template { <img src="/resources/acs-subsite/Delete16.gif" width="16" height =16> } sub_class narrow } } db_multirow -extend { edit_url delete_url } notes notes_select { select ci.item_id, n.title from cr_items ci, mfp_notesx n where n.revision_id = ci.live_revision } { set edit_url [export_vars -base "note-edit" {item_id}] set delete_url [export_vars -base "note-delete" {item_id}] } [$OPENACS_SERVICE_NAME lib]$ vi note-list.adp <listtemplate name="notes"></listtemplate>
A prxima etapa cria uma pgina para adicionar/editar. Se um note_id fornecido, mostra aquela nota; se estiver no modo de edio, edita a nota. Se nenhuma das opes for satisfeita, mostra um formulrio para adionar notas.
[$OPENACS_SERVICE_NAME lib]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfistpackage/lib
22
[$OPENACS_SERVICE_NAME www]$ vi note-edit.tcl ad_page_contract { This is the view-edit page for notes. @author Your Name (you@example.com) @cvs-id $Id: note-edit.tcl,v 1.2 2004/02/04 16:47:34 joela Exp $ @param item_id If present, assume we are editing that note. Otherwise, we show the option to add a new note } { item_id:integer,optional } ad_form -name note -form { {item_id:key} {title:text {label Title}} } -new_request { auth::require_login permission::require_permission -object_id [ad_conn package_id] -privilege create set page_title "Add a Note" set context [list $page_title] } -edit_request { auth::require_login permission::require_write_permission -object_id $item_id mfp::note::get \ -item_id $item_id \ -array note_array set title $note_array(title) set page_title "Edit a Note" set context [list $page_title] } -new_data { mfp::note::add \ -title $title } -edit_data { mfp::note::edit \ -item_id $item_id \ -title $title } -after_submit { ad_returnredirect "." ad_script_abort }
23
[$OPENACS_SERVICE_NAME www]$ vi note-edit.adp <master> <property name="title">@page_title;noquote@</property> <property name="context">@context;noquote@</property> <property name="focus">note.title</property> <formtemplate id="note"></formtemplate>
Vamos adicionar agora a pgina para apagar a nota. Como ela no tem interface com o usurio, vamos criar somente um arquivo tcl. O adp no ser necessrio, pois no mostraremos nada.
[$OPENACS_SERVICE_NAME www]$ vi note-delete.tcl ad_page_contract { This deletes a note @author Your Name (you@example.com) @cvs-id $Id: note-delete.tcl,v 1.2 2004/02/04 16:47:34 joela Exp $ @param item_id The item_id of the note to delete } { item_id:integer } permission::require_write_permission -object_id $item_id set title [item::get_title $item_id] mfp::note::delete -item_id $item_id ad_returnredirect "." # stop running this code, since we're redirecting ad_script_abort
Observando o log do servidor. Para visualizar em tempo real o log de erros do AOLServer digite:
less /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/error.log F para mostrar novas entradas em tempo real (como tail -f). C-c para parar F comear de novo. G vai para o final. ? procura para trs. / procura para a frente.
3.4.2.Testes Manuais
Faa uma lista de testes manuais para ter certeza de seu funcionamento. Teste Nmero: 001 Ao: V para a pgina index sem ter efetuado o login quando existirem uma ou mais notas. Resultado Esperado: Nenhum dos links para editar ou adicionar notas deve aparecer. Teste Nmero: 002 Ao: V para a pgina index quando j tiver feito o login. Um link para editar deve aparecer. Clique sobre ele, preencha o formulrio e clique em enviar. Resultado Esperado: O texto adicionado no formulrio deve estar visvel na pgina index. Teste Nmero: API-001 Ao: Chame a procedure mfp::note::create com uma palavra especfica como o ttulo. Resultado Esperado: A procedure deve retornar um object_id. Teste Nmero: API-002 Ao: Fornecer um object_id da API-001 e chamar a procedure mfp::note::get. Resultado Esperado: A procedure retorna o ttulo. Teste Nmero: API-003 Ao: Dado o mfp::note::delete. object_id da API-001, chamar a procedure
Resultado Esperado: A procedure deve retornar 0 para indicar o sucesso. Outros testes: Tente apagar a note de uma outra pessoa. Tente apagar sua prpria nota. Edite sua nota. Procure por uma nota.
25
26
target:onevalue page_title:onevalue } -query { set user_id [ad_verify_and_get_user_id] db_1row user_name { select first_names || ' ' || last_name as user_name from users where user_id = :user_id } } set page_title "Add a note for $user_name" set submit_label "Add" set target "note-add-2" set note_id [db_nextval acs_object_id_seq] ad_return_template "note-add"
A procedure ad_page_contract sempre a primeira chamada num arquivo .tcl se estiver no diretrio www/ (isto , no uma biblioteca TCL). Ela valida os valores de entrada de uma requisio HTTP (isto , variveis de formulrio) e, neste caso, a clusula -properties usada para ajustar os data sources que passaro para o arquivo .adp. S usamos o tipo mais simples possvel de data source, chamado de onevalue, que contm uma varivel string simples. Mais tarde veremos como utilizar tipos mais poderosos de data source para representar mltiplas linhas, normalmente resultado de uma query SQL. Tambm possvel incluir a documentao da pgina no contrato, e o OpenACS tem ferramentas automticas para extra-la e torn-la navegvel. Depois de ser declarado no ad_page_contract, cada propriedade simplesmente uma varivel TCL. O sistema de template passa o valor final da varivel para o arquivo .adp, aps o processamento do arquivo .tcl. A chamada ad_return_template diz para o sistema de template que pgina .adp procurar e mostra todas as propriedades que foram processadas. Por padro o sistema de template buscar um arquivo com o mesmo nome do arquivo .tcl, mas com uma extenso .adp (Deprecated).
Agora vamos escrever o arquivo .adp correspondente, que gera o HTML para o formulrio. Ele pode conter marcaes cujos valores sero substitudos de acordo com as propriedades ajustadas pelo arquivo .tcl. Crie um arquivo chamado note-add.adp no seu editor e insira o cdigo abaixo:
<master src="master">
27
<property name="title">@page_title@</property> <property name="context_bar">@context_bar@</property> <form action=@target@> <p>Title: <input type="text" name="title" value=""> </p> <p>Body: <input type="text" name="title" value=""> </p> <p>
O principal aspecto a ser observado aqui : quando voc quiser substituir um valor numa pgina, coloque o nome do data source entre @. Outro ponto importante o uso de um template master: eles permitem centralizar o cdigo de display que ser usado por toda a aplicao num arquivo nico. No caso que estamos utilizando importante ter um template master que cria os headers e footers padro. Se voc quiser criar um arquivo master.adp, basta inserir o seguinte cdigo:
<%= [ad_header $title] %> <h2>@title@</h2> <%= [eval ad_context_bar $context_bar] %> <hr> <slave> <br clear="all"> <%= [ad_footer] %>
A parte mais importante do arquivo o cdigo TCL que constri as procedures que constroem header, footer, context bar, etc. note tambm que as substituies de propriedade que acontecem aqui so as que foram inseridas pelas tags <property> na pgina slave.
28
arquivo css a ser utilizado; o objetivo dar clareza ao usurio em que tipo de pgina ele est navegando. Existe ainda a possibilidade de inserir uma logo pessoal para cada instalao: basta definir seu caminho alterando o parmetro. A partir da podemos alterar o esquema do site. Cada arquivo responsvel por uma parte da pgina no tema, sendo os principais blankmaster, site-master e lrn-master. O esquema de distribuio pode ser melhor visto na figura: Figura 5.1 Esquema de arquivos de template
Na figura podemos ver que o blank-master praticamente no afeta o layout. Sua utilidade est na possibilidade de inserir propriedades importantes que devem estar em todas as pginas. o caso dos editores de texto, propriedades de navegao, enfim, tudo o que est por trs e no aparece para o usurio. Como ele est intrinsecamente ligado a funcionalidades do sistema, no alteramos o blank-master quando estivermos trabalhando com design. Ele um arquivo exclusivo para o sistema. Assim, toda a parte de design est presente no site-master; a est o arquivo que vamos trabalhar. no caso do Selva, o arquivo se chama tupi-sitemaster e est localizado na pasta theme-selva/www. Alis, todas as alteraes sero feitas nica e exclusivamente nesta pasta, e devemos tomar o cuidado de guardar uma cpia original do arquivo. Se alguma das alteraes feitas gerar instabilidade ou falha do sistema, deve ser possvel retornar ao original. Na figura, onde est explcito o contedo do site o ponto de entrada para o arquivo lrn-master (selva-lrn-master para o Selva). A importncia dessa parte est em fornecer as caractersticas para que as abas e o contedo sejam 30 Autor: Eduardo Santos
renderizados. Tentamos sempre no alter-lo, pois no a inteno mudar a forma do .LRN de mostrar contedo, mas pode ser necessrio dependendo da ocasio. As outras alteraes sero feitas na pasta www/resources. A temos a opo de utilizar o Selva ou o SelvaFlex, feitos com a inteno de separar o que padro do que alterao do usurio. Dentro da pasta Selva, temos as vrias opes de cor j fornecidas pelo tema. Se desejarmos, podemos alterar os parmetros de css do tema para alterar a cor de cada um dos portais; ainda possvel criar uma cor que no esteja presente atravs da criao de um novo diretrio e de um outro arquivo de estilo, que ser apontado para um determinado portal por parmetro. Tudo depende da vontade de cada um, mas uma observao importante ser feita: tente manter uma cpia dos arquivos padro intacta. Mais uma vez, uma forma de proteo contra qualquer instabilidade gerada pelo sistema.
31
32
6.API's
6.1.API doc
Para o desenvolvedor, a parte mais importante de programar em software livre est em saber onde buscar respostas para os questionamentos. No processo de conhecimento da plataforma, um grande aliado ser o API Browser, um navegador que processa, interpreta e explica todas as funes e procedures armazenadas no sistema. Quando na montagem do site, o navegador montado sempre no link /api-doc. Quando temos alguma dvida sobre sintaxe ou at mesmo sobre a existncia de determinada funcionalidade recorremos sua ajuda. O que ele faz observar todos os arquivos montados na pasta /tcl de todos os pacotes, l todas as procedures definidas pela API ad_proc e interpreta todos os parmetros fornecidos pelo desenvolvedor na criao da mesma. Assim, sempre que criamos uma procedure muito importante preencher a descrio de maneira completa e detalhada, pois facilita a vida de quem precisa us-la depois.
6.2.Ad_form
Dentre as principais API's que existem no OpenACS, sem sombra de dvidas as mais importantes so ad_form e list_builder. A primeira serve para construir formulrios e a segunda para criar listas, como os nomes dizem. Como so funcionalidades utilizadas amplamente pelo site, o objetivo padronizar e assim facilitar a criao de tais objetos em qualquer pgina sem a necessidade de reescrever cdigos desnecessariamente. possvel declarar blocos a serem executados quando o formulrio enviado, quando novos dados so inseridos ou os dados existentes so modificados. possvel ainda declarar blocos de validao do formulrio, similar os encontrados na API ad_page_contract. Vamos utilizar o gerador de formulrios do ATS e procedures para criao de elementos para ger-los e o seu cdigo de rastreamento de estado para determinar quando executar vrios blocos de cdigo. Assim, possvel utilizar qualquer widget ou tipo de dados do gerador de formulrios dentro da procedure, e estender sua funcionalidade uma maneira simples de implementar novos formulrios. Como o ad_form somente uma espcie de casca para o ATS, voc precisa conhecer ou ser capaz de utilizar o ad_form efetivamente. De modo geral todas as funcionalidades do gerador de formulrios so exploradas pelo ad_form, mas com uma interface mais amigvel para o usurio e uma sintaxe de mais fcil leitura, alm do gerenciamento automtico de estado. Nota importante sobre como o ad_form funciona: o ad_form opera em dois modos:
33
1. Declarando o formulrio 2. Executando o formulrio Atravs da switch -extend o formulrio pode ser declarado em mltiplos passos, adicionando elementos. Mas assim que voc adicionar um bloco de ao (on_submit, after_submit, new_data, edit_data, etc), o ad_form vai considerar o formulrio completo e execut-lo, o que significa validar os valores dos elementos e executar os blocos de ao. A execuo acontecer automaticamente na primeira vez que voc chamar o ad_form com um bloco de ao e, a partir da, voc no pode utilizar a clusula -extend. Se nenhum bloco de ao for fornecido, o formulrio nunca ser considerado finalizado, e assim a validao no ser executada. Neste caso, um erro ser visto quando o formulrio for renderizado. Concluso: 1. necessrio haver pelo menos um bloco de ao, mesmo que seja apenas -on_submit { }. 2. No possvel estender o formulrio depois de fornecer um bloco de ao. Para tornar possvel a utilizao do ad_form para construir pedaos de formulrio dentro de uma procedure, os blocos de cdigo so executados no nvel de renderizao do template. Isso necessrio se blocos de validao e outros blocos precisarem acessar o contedo do formulrio, mas pode causar surpresas indesejadas. Assim, tenha cuidado. Contudo, quando a substituio chamada, por exemplo, ao definir o valor de variveis para o formulrio, o nvel de chamada do usurio usado. Por qu? Uma procedure construindo um formulrio comum pode precisar construir uma lista de elementos vlidos selecionados, ou simplesmente computar valores que precisam ser definidos no formulrio, e estes devem ser computados localmente. Sim, talvez seja uma soluo um tanto quanto bizarra e no necessariamente bem pensada. At agora funcionou bem, ento o cdigo continua sendo propagado. Um exemplo adicionar/editar: simples de implementao para um formulrio de
ad_page_contract { Simple add/edit form } { } ad_form -name form_name -export {foo {bar none}} -form { my_table_key:key(my_table_sequence) my_table_key:optional
34
{value:text(textarea)
} -select_query { select value from my_table where my_table_key = :my_table_key } -validate { {value {[string length $value] >= 3} "\"value\" must be a string containing three or more characters" } } -new_data { db_dml do_insert " insert into my_table (my_table_key, value) values (:key, :value)" } -edit_data { db_dml do_update " update my_table set value = :value where my_table_key = :key" } -after_submit { ad_returnredirect "somewhere" ad_script_abort }
Neste exemplo o ad_form checar primeiro para ver se my_table_key foi passado ao script. Caso contrrio, o banco de dados ser chamado para gerar um novo valor chave da seqncia my_table_sequence (o nome padro para a seqncia acs_object_id_seq). Se for definida, a query definida como -select_query ser usada para preencher os elementos do formulrio com os dados existentes (um erro ser mostrado se a query falhar). A chamada ad_return_template renderiza a pgina responsabilidade sua renderizar o formulrio no seu template atravs do uso da marcao ATS formtemplate. No momento do envio o bloco de validao checa se o usurio preencheu uma textarea com pelo menos trs caracteres (sim, um exemplo simples). Se a validao falha o elemento value ser marcado com uma mensagem de erro, que ser vista quando o formulrio for renderizado. Se o bloco de validao retorna verdadeiro, um dos blocos de cdigo new_data ou edit_data sero executados, dependendo da chave my_table_key ter sido definida durante a chamada inicial. my_table_key foi enviada como uma varivel de formulrio escondida e assinada e verificada, reduzindo a oportunidade de roubo da chave. O exemplo inclui redirecionamentos invlidos para um script chamado somewhere, para tornar claro o fato de que depois da execuo do bloco new_data ou edit_data o ad_form retorna a quem chamou. Informaes gerais sobre parmetros Parmetros que tm name em sua definio (por exemplo, -name ou select_query_name) esperam um nome simples que no esteja entre chaves 35 Autor: Eduardo Santos
(em outras palavras, que no seja um elemento nico de uma lista). Todos os outros parmetros esperam uma lista simples. Segue abaixo uma lista completa de clusulas permitidas pelo ad_form: -extend Estende um formulrio que j exista, de tal forma que os formulrios possam ser construdos de maneira incremental. Formulrios so construdos no nvel do template, de tal forma que possvel escrever procedimentos utilitrios que usam a clusula -extend para construir pequenos pedaos para vrios formulrios de entrada de dados. Perceba que um bloco de formulrio completo precisa ser construdo (estendido) e completado antes que quaisquer blocos de ao, como select_query, new_request, edit_request, etc, sejam definidos. Deve ser a primeira clusula fornecido para o ad_form -name Declara o nome do formulrio. O valor padro o nome do script sendo utilizado. -action O nome do script a ser chamado quando o formulrio enviado. O valor padro o nome do script sendo utilizado. -actions Uma lista de listas de aes (por exemplo {{Delete delete} {Resolve resolve}}), que ser traduzida em botes no fim do formulrio. Voc pode descobrir o boto que foi pressionado com [template::form get_action form_id], normalmente no bloco -edit_request para executar as aes que achar apropriado. -mode { display | edit } Se definido como 'display' o formulrio visualizado no modo displayonly, onde o usurio no pode editar os campos. Cada widget sabe como mostrar seu contedo apropriadamente, isto , um widget tipo select mostrar o nome do campo, no seu valor. Se definido como 'edit' o formulrio visualizado normalmente para edio (comportamento padro). Mudar para o modo de edio quando um boto pressionado no modo disposio tratado automaticamente. -has_edit { 0 | 1 } Defina como 1 para suprimir o boto de edio adicionado automaticamente pelo gerador de formulrios. Use se quiser incluir seu prprio boto. 36 Autor: Eduardo Santos
-has_submit { 0 | 1 } Defina como 1 se quiser suprimir o boto OK adicionado automaticamente pelo gerador de formulrios. Use se quiser incluir o seu prprio boto. -method O atributo padro METHOD para especificar na marcao (tag) HTML FORM no incio do formulrio. O valor padro POST. -form Declara os elementos de formulrio (descrito com mais detalhes abaixo) -cancel_url URL para a qual o boto cancelar deve levar. Se for especificada, um boto cancelar aparecer no momento da edio. -cancel_label Nome para o boto cancelar. -html O cdigo html fornecido ser adicionado marcao form quando a pgina for renderizada. Usado normalmente para definir formulrios que lidam com arquivos com muitas partes. -export Similar funo export_vars. Pega uma lista de valores para inserir no formulrio como elementos tipo hidden. Cada valor um nome, no caso uma varivel TCL no nvel de chamada passada para o formulrio se existir, ou um par nome-valor. multiple, array, sign e flags similares no so permitidas, mas pode ser til no futuro. -select_query Define uma query que retorna uma nica linha contendo valores para cada elemento do formulrio de tal forma que possam ser modificados. S pode ser usada se um elemento do tipo key for declarado. Os valores fornecidos pela query esto disponveis no formulrio, mas no o template ADP (para tal, use -edit_request). -select_query_name Idntico -select_query, exceto que ao invs de especificar uma linha de cdigo, d o nome da query a ser localizada no arquivo XQL. Use 37 Autor: Eduardo Santos
-select_query_name ao invs de -select_query sempre que possvel, j que os arquivos XQL so os mecanismos que tornam possvel o suporte a mltiplos bancos de dados (RDMBS). -show_required_p { 0 | 1 } Se o template do formulrio deve mostrar os elementos obrigatrios, use 1. Caso contrrio, use 0. O valor padro 1. -on_request Um bloco de cdigo que define os valores para cada um dos elementos do formulrio que podem ser modificados pelo usurio quando o gerenciamento de chaves est sendo utilizado ou para definir opes para listas do tipo select, etc. Define os valores como variveis locais no bloco de execuo que podem ser utilizadas como valores para os elementos. O bloco executado todas as vezes em que o formulrio carregado exceto quando ele est sendo enviado (a o bloco -on_submit executado). -edit_request Bloco de execuo que define os valores para cada elemento do formulrio a ser alterado pelo usurio. Use quando uma query simples para pegar os valores dos campos insuficiente. Quaisquer variveis definidas num bloco -edit_request esto disponveis para o template ADP assim como para o formulrio, enquanto -select_query define variveis para o formulrio somente. S pode ser usado se um elemento tipo key definido. O bloco s executado se a pgina for chamada com uma chave (key) vlida, isto , um formulrio de auto-envio para adicionar ou editar um item for chamado para editar os dados. Define os valores como variveis locais no bloco de execuo, de tal forma que eles sero utilizados como valores dos elementos. -new_request Bloco de execuo que define os valores para cada um dos elementos do formulrio a serem modificados pelo usurio. Use quando uma query simples para buscar os valores no banco for insuficiente. S pode ser usada se um elemento do tipo key for definido. Complementa o bloco -edit_request, sendo necessrio somente definir os valores como variveis locais no bloco de execuo, de tal forma que sero usadas como valores para os elementos. -confirm_template Nome de um template de confirmao a ser chamado antes de qualquer bloco on_submit, new_data ou edit_data. Quando o usurio confirma a entrada o controle ser passado para o bloco de envio apropriado. O 38 Autor: Eduardo Santos
template de confirmao pode ser usado para fornecer uma pgina de prever/confirmar. Seu template de confirmao deve renderizar o contedo do formulrio de uma maneira amigvel ao usurio; assim, inclua o arquivo "/packages/acs-templating/resources/forms/confirmbutton". O template confirm-button no fornece apenas um boto confirma, mas tambm inclui uma mgica que diz ao ad_form que seguro chamar o bloco de envio proposto. -on_refresh Executado quando o formulrio volta aps ser atualizado depois de usar um javascipt com a marcao __refreshing_p ajustada. -on_submit Quando o formulrio enviado, este bloco executado antes de qualquer bloco new_data ou edit_data. Use se o seu formulrio no interage com o banco de dados ou se o tipo de banco envolvido inclui uma API TCL que trabalha tanto para os dados novos quanto para os j existentes. Os valores dos elementos de formulrio estaro disponveis como variveis locais. Chamar 'break' dentro deste bloco faz com que o processo de envio seja abortado, e nenhum bloco new_data, edit_data ou after_submit ser executado. til em combinao com template::form::set_error para mostrar um erro num elemento de formulrio. -new_data Ser executado quando um formulrio para uma nova linha no banco de dados enviado. O bloco deve inserir os dados no banco ou criar um novo objeto ou um item do content repository no banco contendo os dados. Chamar 'break' dentro do bloco causa a paralisao do processo de envio e o bloco after_submit no ser executado. til em combinao com template::form::set_error para mostrar um erro num dos elementos do formulrio. -edit_data O bloco ser executado quando um formulrio para uma linha j existente no banco de dados for enviado. Deve atualizar o banco ou criar uma nova content revision (reviso) para o item existente se os dados estiverem armazenados no content repository. Chamar 'break' dentro do bloco causa a interrupo do processo de envio, e o bloco after_submit no ser executado. til em combinao com template::form::set_error para mostrar um erro em qualquer dos elementos. -after_submit Ser executado aps os trs blocos: on_submit, new_data ou edit_data. til para colocar algo como ad_returnredirect que seja o mesmo para 39 Autor: Eduardo Santos
novos elementos e para editar. -validate Bloco que valida os elementos no formulrio, que so definidos como valores locais. O bloco tem a seguinte forma:
{nome_do_elemento {cdigo TCL que retorna 1 ou 0} "Mensagem que ser mostrada em caso de erro" } {...}
-on_validation_error Bloco a ser executado em caso de falha na validao. Pode ser utilizado para ajustar o ttulo para uma pgina ou qualquer ao similar.
Dois valores interessantes escondidos esto disponveis para o ponto de chamada do ad_form quando estiver processando um envio: __new_p Se uma chave para o banco de dados for declarada, __new_p ser definida como verdadeira se o envio for para um novo valor. Se for falsa, a chave se refere a valores j existentes. til para formulrios que podem processar facilmente qualquer operao num simples bloco on_submit, ao invs de usar separadamente os blocos new_data e edit_data. __refreshing_p Deve ser definido como verdadeira para widgets Javascript que alteram alguns dos elementos do formulrio e envia o formulrio para atualizar os valores. Declarando os elementos de formulrio O ad_form utiliza a procedure element create do gerador de formulrios para gerar elementos declarados no bloco -form. Uma checagem rudimentar de erros tambm feita para ter certeza que o tipo de dado e o widget existam e que as outras opes so legais. O bloco -form uma lista de elementos de formulrio, que so listas por si s compostas por um ou dois elementos: o primeiro membro de cada sub lista de elementos declara o nome do elemento, o tipo de dado, o widget, se o elemento no composto de mltiplas opes (um multi select, por exemplo) e argumentos opcionais de converso. O segundo e opcional membro consiste numa lista de parmetros de elementos de formulrio e valores. Todos os parmetros aceitos pela procedure form element create so permitidos. 40 Autor: Eduardo Santos
Tipos de dado. A procedure template::data::validate::float, por exemplo, implementa o tipo de dados float. Widgets. A procedure template::widget::radio implementa o widget 'radio'. Nem todos os widgets so compatveis com todos os tipos de dado. Parmetros e valores dos elementos de formulrio. O parmetro -label My label, por exemplo, escrito {label My label} na sublista de elementos do bloco -form para o ad_form.
Alguns tipos de dados criados pelo gerador de formulrios no correspondem aos tipos de banco; quando estiver usando o gerador diretamente eles so convertidos por chamadas datatype::get_property e datatype::acquire. J quando estiver usando o ad_form, "to_html(property)", "to_sql(property)" e "from_sql(property)" declaram as propriedades apropriadas a serem recuperadas ou definidas antes de chamar blocos de execuo que precisam dos valores convertidos. A operao to_sql executada antes que qualquer bloco on_submit, new_data ou edit_data seja executado. A operao from_sql realizada depois que um select_query ou select_query_name for executado. Nenhuma converso automtica feita para blocos edit_request (que definem manualmente os valores do formulrio). A operao to_html executada antes da execuo de um confirm_template. Atualmente s os tipos de dado data e dinheiro requerem as operaes de converso. No futuro o gerador de formulrios ser desenvolvido de tal forma que um ad_form possa determinar a operao de converso apropriada automaticamente, liberando o programador de ter que especific-las. Quando for implementado, a notao atual ser mantida para que a compatibilidade seja possvel. O ad_form define um pseudo tipo key. S um elemento do tipo key permitido por formulrio, para o qual um tipo inteiro atribudo. Somente chaves que so geradas de uma seqncia do banco de dados so gerenciadas automaticamente por um ad_form. Se o nome da seqncia no for especificado, acs_object_id_seq usado para gerar novas chaves. Exemplos:
my_key:key
41
Define um elemento select mltiplo com cinco escolhas, numa caixa de seleo de quatro linhas.
{hide_me:text(hidden) {value 3}}
Define o elemento opcional "start_date" do tipo "date", pega a propriedade sql_date antes de executar qualquer bloco new_data, edit_data ou on_submit, ajusta a propriedade sql_date depois de executar qualquer select_query.
{email:text,nospell {label "Email Address"} {html {size 40}}}
Define um elemento do tipo text com o spell-checking desativado. No caso spell-checking, mesmo ativado globalmente para o widget deste elemento (text, no exemplo), a flag nospell ir sobrescrever o parmetro e desativ-lo no elemento em particular. Atualmente pode ser ativado para os seguintes widgets: text, textarea e richtext.
6.3.List builder
List builder o nome dado a uma srie de API's que auxiliam a construo de uma lista a ser exibida em um template. A principal a ser estudada a template::list::create, que um comando utilizado na criao. A lista trabalha em conjuno com um multirow, que contm todos os dados necessrios. Pode ser inserida utilizando as marcaes de template <listtemplate> e <listfilters>, com ajuda de <listelement> e <listrow>. Segue o exemplo de uma lista padro:
template::list::create \ -name order_lines \ -multirow order_lines \ -key item_id \ -actions [list "Add item" [export_vars -base item-add {order_id}] "Add item to this order"] \ -bulk_actions { "Remove" "item-remove" "Remove checked items" "Copy" "item-copy" "Copy checked items to clipboard"
42
} \ -bulk_action_method post -bulk_action_export_vars { order_id } \ -row_pretty_plural "order items" \ -elements { quantity { label "Quantity" } item_id { label "Item" display_col item_name link_url_col item_url link_html { title "View this item" } } item_price { label "Price" display_eval {[lc_sepfmt $item_price]} } extended_price { label "Extended Price" display_eval {[lc_sepfmt [expr $quantity $item_price]]} } } db_multirow -extend { item_url } order_lines select_order_lines { select l.item_id, l.quantity, i.name as item_name, i.price as item_price from order_lines l, items i where l.order_id = :order_id and i.item_id = l.item_id } { set item_url [export_vars -base "item" { item_id }] }
Switches: -name O nome da lista que deseja construir. -multirow (opcional) O nome do multirow que voc quer percorrer. O valor padro o nome da lista. -key (opcional) 43 Autor: Eduardo Santos
O nome da coluna que contm a chave primria/identificador nico para cada linha. deve ser uma coluna simples presente no multirow. Esta clusula obrigatria quando houver bulk_actions. -pass_properties (opcional) Uma lista de variveis no ambiente de quem a chama, que deve estar disponvel para o display_template dos elementos. -actions (opcional) Lista de botes de ao a ser exibida no top da lista na forma (nome 1 url1 title1 nome2 url2 title2 ...). O boto de ao ser um simples link para a url. -bulk_actions (opcional) Lista de botes de ao em massa, operando nas linhas marcadas para mostrar no final da lista. O format (nome1 url1 title1 nime2 url2 title2 ...). Um formulrio ser enviado url contendo um lista dos valores chave das linhas marcadas. Por exemplo, se 'key' 'message_id' e as linhas com message_id 24 e 9 so marcadas, a pgina pegar as variveis message_id=2&message_id=4&message_id=9. A pgina que estiver recebendo deve declarar message_id:integer,multiple em seu ad_page_contract. Note que a varivel local 'message_id' ser uma lista TCL. -bulk_action_method (opcional) bulk_action deve utilizar o mtodo get ou post? O valor padro get. -bulk_action_export_vars (opcional) Lista de variveis adicionais a passar para a pgina que vai receblas, junto com as outras variveis para as chaves selecionadas. til se as linhas na lista esto todas sendo obtidas de uma linha numa tabela pai. Por exemplo, se a lista contm linhas com um ordenamento particular e a chave primria da tabela de ordenamento 'order_id,item_id', a chave seria 'item_id' e bulk_action_export_vars seria 'order_id', de tal forma que juntos eles constituem a chave primria. -selected_format (opcional) O formato de disposio selecionado. veja a opo 'formats'. -has_checkboxes (booleano, padro 0) (opcional) 44 Autor: Eduardo Santos
Ajuste este flag se sua tabela j incluir os checkboxes para as bulk_actions. Se no houver e sua tabela possuir bulk_actions, adiciona uma coluna de checkbox como a primeira coluna. -checkbox_name (opcional) Voc pode nomear explicitamente a coluna de checkbox aqui para que possa se referir a ela e coloc-la onde quiser quando especificar os formatos de disposio. O valor padro 'checkbox'. Veja a opo 'formats'. -orderby_name (opcional) O nome da varivel da query de paginao para o orderby selecionado normalmente 'orderby', mas se quiser, pode renomela aqui. -row_pretty_plural (opcional) O nome das linhas no plural. Por exemplo, 'itens' ou 'posts no frum'. Utilizada para gerar automaticamente a mensagem 'no_data' para dizer No h (row_pretty_plural)". O valor padro 'data'. Veja 'no_data' abaixo. -no_data (opcional) Mensagem mostrada quando o multirow no tem nenhuma linha. O valor padro 'No data'. -main_class (opcional) Classe de css a ser utilizada na lista. A construo deve ser feita combinando a classe_principal e a sub_classe com um trao entre elas, isto , a classe principal pode ser 'list' e a sub_classe pode ser 'narrow'. Assim, a classe css a ser utilizada seria 'list-narrow'. -sub_class (opcional) sub_classe do css a ser utilizada, conforme descrito na opo main_class acima. -class (opcional) A classe css pode ser indicada diretamente tambm. Caso isso acontea, ela substitui main_class/sub_class. -html (opcional) Atributos HTML para a sada da marcao 'table', por exemplo { align 45 Autor: Eduardo Santos
right style "background-color: yellow;" }. O valor deve ser uma lista TCL com {nome valor nome valor} -page_size (opcional) Nmero de linhas a mostrar em cada pgina. Se especificado, a lista ser paginada. -page_size_variable_p (booleano, padro 0) (opcional) Mostra uma caixa de seleo que permite ao usurio alterar o nmero de linhas a ser visualizado em cada pgina. Se especificado, a lista ser paginada. -page_groupsize (padro 10) (opcional) O tamanho do grupo de pginas para o paginador. til quando o resultado da query de paginao gera muitas pginas. Por exemplo,se voc tem 1000 resultados com 10 resultados por pgina, voc pode querer no mostrar os valores de 1-100 no grupo de pginas. Neste caso, ajustando o groupsize para 10 permitir visualizar primeiro as pginas 1-10, depois as de 11-20, e assim por diante. O valor padro 10. -page_query (opcional) Query que busca os ID's das linhas e contextos para todo o conjunto de resultados. Pode ser usado em conjunto com a procedure template::paginator::create. -page_query_name (opcional) Alternativamente pode ser especificado o nome de uma query, localizada num arquivo .xql que ser responsvel pela paginao. Pode ser usado em conjunto com template::paginator::create. -page_flush_p (booleano, padro 0) (opcional) Se for for chamada, executa um 'flush' quando a lista for renderizada. O valor padro zero. -ulevel (booleano, padro 1) (opcional) Nmero de nveis acima a percorrer quando estiver substituindo valores em elements, filters, groupbys, orderbys e formats abaixo. O padro um nvel acima, o que significa o nvel de chamada do escopo da template::list::create. -elements 46 Autor: Eduardo Santos
Os elementos da lista (colunas). Seu valor deve ser uma lista de arrays de pares (nome do elemento, spec) como no exemplo acima. Cada spec, por sua vez, uma lista de arrays de pares nome-dapropriedade/valor, onde o valor substitudo no ambiente de chamada, exceto para as propriedades *_eval, que so substitudas no contexto do multirow. -filters (opcional) Filtros para a lista. Normalmente utilizados para separar os dados, por exemplo, ver somente linhas de um usurio particular. Lista de array de pares (nome-do-filtro, spec), assim como os elementos. Cada spec, por sua vez, uma lista de array de pares nome-dapropriedade/valor, exceto pelas propriedades *_eval, que so substitudas no contexto do multirow. Para que os filtros funcionem necessrio especific-los no ad_page_contract da sua pgina, normalmente como nome_do_filtro:optional. O list builder os encontrar nas variveis locais de sua pgina. Filtros tambm so um mecanismo para exportar variveis de estado que precisam ser preservadas. Se for necessrio, por exemplo, manter o user_id para o filtro e outros links de ordenao, basta adicionar -filters {user_id {}}. -groupby (opcional) Itens pelos quais voc pode agrupar, isto , dia, semana, usurio, etc. Cria automaticamente um filtro chamado 'groupby'. Lista de array simples de pares nome_da_propriedade/valor, onde o valor substitudo no ambiente de chamada. Groupby somente um filtro com nome fixo, ento veja mais detalhes no item acima. -orderby (opcional) Itens pelos quais a ordenao pode ser feita. possvel especificar a ordenao diretamente nos elementos. Cria automaticamente um filtro chamado 'orderby', que uma lista de array de pares (nome-doorderby, spec), assim como os elementos. Cada spec, por sua vez, uma lista de array de pares nome_da_propriedade/valor, onde o valor substitudo no ambiente de chamada, exceto para as propriedades *_eval, que so substitudas no contexto do multirow. Se o nome do orderby for o mesmo de algum elemento, o cabealho daquele elemento ser transformado num link para ordenar por aquela coluna. -formats (opcional) Se nenhum formato for especificado, um padro criado juntamente com um filtro chamado 'formato'. Lista de array de pares (nome-doformato, spec) assim como os elementos. Cada spec, por sua vez, uma lista de array de pares nome-da-propriedade/valor, onde o valor substitudo no ambiente de chamada. 47 Autor: Eduardo Santos
Aqui esto descritas as principais funcionalidades da API e sua sintaxe de utilizao. Para mais informaes, consulte o API doc para template::list::create.
48
49
acs_privilege.add_child('admin', 'read'); acs_privilege.add_child('admin', 'write'); acs_privilege.add_child('admin', 'create'); acs_privilege.add_child('admin', 'delete'); commit; end;
Para conceder permisso a um usurio para realizar uma operao particular num objeto particular voc pode chamar a funo acs_permission.grant_permission assim:
acs_permission.grant_permission ( object_id => qualquer_object_id, grantee_id => qualquer_party_id, privilege => 'nome_do_privilgio' );
Os mecanismos so suficientes para que desenvolvedores administradores definam controles de acesso para cada objeto no sistema.
ou
7.2.Estratgia de permisses
Como vimos, todo o sistema de permisses de baseia em privilgios, grupos e contextos. Grupos tm uma definio recursiva e podemos ilustrar como eles funcionam com o modelo simplificado de dados abaixo. Primeiro, definimos a tabela parties, onde cada grupo tem um endereo de e-mail e uma URL para informaes de contato.
create table parties ( party_id integer not null references acs_objects(object_id),
Agora definimos dois subtipos de party, um para person e outro para groups:
create table groups ( group_id not null references parties(party_id),
50
group_name varchar(100) not null ) create table persons ( person_id not null references parties(party_id), first_names varchar(100) not null, last_name varchar(100) not null )
A tabela de usurios tambm e definida neste data model como um subtipo de person. Finalmente, definimos duas relaes: uma para associao ao grupo e outra para composio do grupo. A relao de composio nos permite expressar o fato de que cada membro do grupo A deve tambm ser um membro do grupo B. A relao de associao significa muito mais do que simplesmente fazer parte de um grupo; cada membro do grupo um grupo por si s, no somente um usurio. Assim, grupos consistem de membros que so ou pessoas ou um grupo inteiro, o que nos permite afirmar que os membros do grupo A devem ser membros de um outro grupo B. A modelagem de dados dos grupos agradavelmente recursiva. O fato de que grupos so modelados como sendo pessoas ou um grupo tem muito poder, pois nos permite modelar grupos hierrquicos complexos de pessoas e outros grupos. Tratando ainda da estratgia de permisses, vamos estudar o que um contexto de objeto (object context). Para iniciar, podemos dizer que ele uma generalizao do mecanismo de escopo, explicados pelo exemplo abaixo, uma tabela hipottica de endereos (address_book) ... escopo user group public user_id 123 456 group_id ...
A primeira linha representa um entrada no livro de endereo do usurio 123, a segunda representa uma entrada no livro compartilhado do grupo 456 e a terceira representa uma entrada no livro de acesso pblico do site. Desta maneira, as colunas do escopo identificam o contexto de 51 Autor: Eduardo Santos
segurana ao qual o objeto dado pertence, onde cada contexto uma pessoa, um grupo de pessoas ou o pblico em geral (tambm um grupo de pessoas). No OpenACS, ao invs de quebrar o mundo em um conjunto limitado de escopos, cada objeto vive num contexto simples, que nada mais que um outro objeto que representa o domnio de segurana ao qual o objeto pertence. Por conveno se um objeto A no tem nenhuma permisso definida explicitamente, o sistema buscar a coluna context_id na tabela acs_objects e checar o contexto do objeto por permisses. Duas coisas controlam o escopo da busca: a estrutura do contexto hierrquico por si s e o valor da flag security_inherit_p em cada objeto. Se o seu valor for 't', a busca automtica pelo contexto acontece, caso contrrio no. Voc pode definir esta flag como 'f' se quiser apagar todas as permisses padro numa sub-rvore de algum contexto. Um bom exemplo de como utilizar o conceito hierarquicamente a aplicao fruns. Com permisses somente no nvel de cada linha no bvio como inicializar racionalmente a lista de controle de acesso ao criar uma mensagem; no mximo temos que garantir explicitamente vrios privilgios de leitura e escrita quando quisermos criar uma mensagem, o que bastante tedioso. Algo razovel para se fazer no OpenACS criar um objeto representando um frum e apontar o campo context_id de uma nova mensagem para o frum. Suponhamos ento que seja garantido privilgio de leitura a qualquer usurio no sistema; por padro, eles tero automaticamente acesso de leitura nova mensagem que acabamos de inserir, j que o sistema automaticamente checa as permisses no contexto da mensagem. Para permitir ao criador da mensagem alter-la depois de ter sido postada, garantimos ao usurio privilgio de escrita na mensagem e pronto. O mecanismo permite a desenvolvedores e administradores definir uma hierarquia que combine com a estrutura que precisarem para controlar o acesso em sua aplicao. A foto a seguir mostra uma hierarquia de contexto tpica para um site hipottico:
52
7.3.Processos agendados
Existem vrias aes de rotinas que precisam ser realizadas pelo sistema dentro de uma certa periodicidade. Pode ser necessrio construir uma procedure que busque os e-mails no servidor dentro de um certo tempo, ou que faa alguma rotina de limpeza no sistema. Para agendar processos que rodam no OpenACS, vamos utilizar o AOLServer. A API que vamos utilizar ad_schedule_proc, que uma interface do OpenACS com o AOLServer. Se utilizarmos a flag -thread, faremos a procedure correr de maneira assncrona na sua prpria linha. Quase sempre parece uma boa idia especificar o switch, mas h um problema. Acontece que cada vez que uma tarefa agendada com ad_schedule_proc -thread t executada, o AOLServer cria uma nova linha e um novo interpretador, alm de reinicializar a tabela de procedures (basicamente carrega todas as procedures que foram criadas durante a inicializao do servidor no novo interpretador). Isso acontece todas as vezes em que a tarefa executada, o que torna o processo muito caro ao sistema. Assim, se o objetivo agendar um processo que roda frequentemente no utilize a switch -thread. Note ainda que a linha inicializada com uma cpia do que foi instalado durante o boot do servidor, de tal maneira que se a tabela de procedures mudou desde ento, a tarefa no ser afetada. Para fazer com que o processo seja agendado todas as vezes em que o sistema for iniciado, crie um arquiv -init.tcl na pasta /tcl do pacote. Se o pacote tiver o nome meu-pacote, e o procedimento agendado estiver no arquivo meupacote-procs.tcl, crie um que se chama meu-pacote-init.tcl e insira o ad_schedule_proc l dentro.
ao logo que a tela carregada, a tendncia que repita a ao inmeras vezes at atingir o resultado esperado. Isso pode gerar duplicao de chaves, inconsistncia no banco e uma grande dor de cabea para o usurio, portanto, tente utilizar o recurso com sabedoria.
54
8.Infra-estrutura necessria
8.1.Instalao do Linux e softwares necessrios
Para todo o tutorial de instalao utilizaremos um sistema Debian etch, a verso 5.2.3 do OpenACS, a 2.2.0 do .LRN, o banco de dados PostgreSQL e o servidor web AOLServer. O banco pode ser substitudo pelo Oracle, mas perdas por incompatibilidade em alguns pacotes podem acontecer. muito provvel que grande parte dos comandos funcione para qualquer sistema, e notas de compatilidade podem ser encontradas no site do OpenACS e no wiki da comunidade do OpenACS no Portal do Software Pblico Brasileiro. O primeiro passo instalar os pacotes bsicos de configurao do sistema, para os quais vamos usar o apt-get.
apt-get install locales dpkg-reconfigure locales (pt_BR.UTF-8 UTF-8) apt-get install imagemagick apt-get install unzip zip apt-get install bzip2 apt-get install patch apt-get install diff apt-get install gcc apt-get install libc6-dev apt-get install libreadline5-dev apt-get install zlib1g-dev apt-get install bison
8.2.Instalao do PostgreSQL
No link http://sourceforge.net/project/showfiles.php?group_id=9764&package_id=2138 42 podemos ver todas as verses disponveis para o PostgreSQL. A escolhida para instalao na mquina definitiva ser a 8.2.1, que a ltima estvel. Copiamos o arquivo para o diretrio /usr/local/src/ e o descompactamos. 55 Autor: Eduardo Santos
Criao do usurio postgres O prximo passo criar o usurio do banco de dados. Vamos criar um grupo de usurios chamado web e adicionar o usurio postgres a ele.
[root src]# groupadd web [root src]# useradd -g web -d /usr/local/pgsql postgres [root src]# mkdir -p /usr/local/pgsql [root src]# chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-8.2.1 [root src]# chmod 750 /usr/local/pgsql
O diretrio /usr/local/pgsql/ o diretrio onde ser criado o banco de dados. Importante que somente os usurios do grupo tenham acesso a ele.
No continue at que voc possa ver a sada correta no comando env | grep PATH
Compilar e instalar o PostgreSQL O que precisamos fazer ir at o diretrio do postgresql e compilar o source.
[root src]# su - postgres [postgres pgsql]$ cd /usr/local/src/postgresql-8.2.1 [postgres postgresql-8.2.1]$ ./configure creating cache ./config.cache checking host system type... i686-pc-linux-
56
gnu (many lines omitted> linking ./src/makefiles/Makefile.linux to src/Makefile.port linking ./src/backend/port/tas/dummy.s to src/backend/port/tas.s [postgres postgresql-8.2.1]$ make all make -C doc all make[1]: Entering directory `/usr/local/src/postgresql-8.2.1/doc' (many lines omitted) make[1]: Leaving directory `/usr/local/src/postgresql-8.2.1/src' All of PostgreSQL successfully made. Ready to install. [postgres postgresql-8.2.1]$ make install make -C doc install make[1]: Saindo do diretrio `/usr/local/src/postgresql-8.2.1/config' PostgreSQL installation complete.
Inicializar o banco de dados O comando initdb inicializa a base de dados. pg_ctl inicializa o PostgreSQL.
[postgres postgresql-8.2.1]$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data The files belonging to this database system will be owned by user "postgres". This user must also own the server process. (20 lines omitted) Success. You can now start the database server using: /usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data or /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start [postgres postgresql-8.2.1]$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start postmaster successfully started [postgres postgresql-8.2.1]$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start
Instalao do PL/SQL Configurar plpgsql e permitir o acesso por todos os usurios. plgsql uma linguagem parecida com PL/SQL. Vamos adicion-la ao template1, que o padro para todos os bancos criados.
[postgres postgresql-8.2.1]$ createlang plpgsql template1 [postgres pgsql]$ createlang -l template1 plpgsql | yes [postgres pgsql-8.2.1]$ createlang plpgsql template1 createlang -l template1
Teste do PostgreSQL
[postgres pgsql]$ createdb mytestdb CREATE DATABASE
57
[postgres pgsql]$ psql mytestdb Welcome to psql, the PostgreSQL interactive terminal. Type: \copyright for distribution terms \h for help with SQL commands \? for help on internal slash commands \g or terminate with semicolon to execute query \q to quit
mytestdb=# select current_timestamp; timestamptz ------------------------------2003-03-07 22:18:29.185413-08 (1 row) mytestdb=# create function test1() returns integer as 'begin return 1; end;' language 'plpgsql'; CREATE mytestdb=# select test1(); test1 ------1 (1 row) mytestdb=# \q [postgres pgsql]$ dropdb mytestdb DROP DATABASE [postgres pgsql]$ exit logout [root src]#
Inicializar o banco junto com o sistema Vamos copiar o script postgresql.txt que inicia e desliga o banco automaticamente no boot. Depois fazemos com que ele funcione de maneira automtica criando links simblicos de vrios arquivos no diretrio /etc/init.d para garantir que, quando o sistema mude o nvel de execuo, o postgresql tambm o faa.
[root ~]# wget http://cvs.openacs.org/cvs/*checkout*/openacs4/packages/acs-core-docs/www/files/postgresql.txt?rev=1.2 [root ~]# mv postgresql.txt\?rev\=1.2 postgresql.txt [root ~]# cp postgresql.txt /etc/init.d/postgresql [root ~]# chown root.root /etc/init.d/postgresql [root ~]# chmod 755 /etc/init.d/postgresql [root ~]# wget http://cvs.openacs.org/cvs/*checkout*/openacs-4/packages/acscore-docs/www/files/postgresql.txt?rev=1.2 mv postgresql.txt\?rev\=1.2 postgresql.txt cp postgresql.txt /etc/init.d/postgresql chown root.root /etc/init.d/postgresql chmod 755 /etc/init.d/postgresql
Testando o script
[root ~]# /etc/init.d/postgresql stop Stopping PostgreSQL: ok
58
[root ~]#
Se voc conseguir parar o banco, teste o script para ver se ele ser inicializado corretamente quando o sistema for iniciado ou desligado.
[root ~]# update-rc.d postgresql defaults Adding system startup for /etc/init.d/postgresql ... /etc/rc0.d/K20postgresql -> ../init.d/postgresql /etc/rc1.d/K20postgresql -> ../init.d/postgresql /etc/rc6.d/K20postgresql -> ../init.d/postgresql /etc/rc2.d/S20postgresql -> ../init.d/postgresql /etc/rc3.d/S20postgresql -> ../init.d/postgresql /etc/rc4.d/S20postgresql -> ../init.d/postgresql /etc/rc5.d/S20postgresql -> ../init.d/postgresql [root ~]# /etc/init.d/postgresql start Starting PostgreSQL: ok [root ~]#
Editar o arquivo de configurao do postgres (postgresql.conf) para que ele tenha todas as funcionalidades.
[root ~]# vi /usr/local/pgsql/data/postgresql.conf
No campo # VERSION/PLATFORM COMPATIBILITY editar os seguintes valores: add_missing_from = on regex_flavor = extended default_with_oids = on
Gerar a funo antes de instalar o OpenACS, ou seja, antes de criar um banco para a aplicao.
[root src]# su - postgres [postgres pgsql]$ psql template1
Copie e cole o seguinte trecho de cdigo no banco de dados: create or replace function bitfromint4 (integer) returns bit varying as ' begin return $1::bit(32); end;' language 'plpgsql' immutable strict; Saia do banco digitando \q
[postgres pgsql]$ exit
59
8.3.Instalao do AOLServer
A parte a seguir foi quase toda extrada do site da Cognovis, empresa do Gustaf Newman (http://www.cognovis.de/developer/en/aolserver_install). Vamos utilizar a verso 4.5.0 do AOLServer, que traz algumas propriedades importantes que queremos tratar. Primeiro vamos remover sua verso antiga do AOLServer
rm -rf /usr/local/aolserver45 rm -rf /usr/local/src/aolserver45 cd /usr/local/src mkdir aolserver45 cd aolserver45
Instalao do TCL
tar xzvf tcl8.4.14-src.tar.gz cd tcl8.4.14/unix ./configure --enable-threads --prefix=/usr/local/aolserver45 make install
Remoo do link simblico para a verso antiga do AOLServer. Se no for um link simblico, tome cuidado para que se torne um utilizando 60 Autor: Eduardo Santos
mv /usr/local/aolserver /usr/local/aolserver<suaverso>
rm /usr/local/aolserver ln -s /usr/local/aolserver45 /usr/local/aolserver
Instalao do mdulo nspostgres Antes de fazer a instalao, necessrio verificar se o seu postgres foi instalado via apt-get. Em caso positivo, necessrio criar alguns links simblicos para alguns importantes arquivos de configurao, caso contrrio a instalao no ser bem sucedida.
ln -s /usr/include/postgresql/ /usr/include/pgsql ln -s /var/lib/postgres /usr/local/pgsql ln -s /usr/include/pgsql /usr/local/pgsql/include
Instalao do tdom. Se voc usa bash31, ser necessria a aplicao de um patch. Veja a mensagem http://openacs.org/forums/messageview?message_id=369867 para mais detalhes
cd ../tdom/unix ../configure --enable-threads --disable-tdomalloc -prefix=/usr/local/aolserver45 --exec-prefix=/usr/local/aolserver45 --withaolserver=/usr/local/aolserver45 --withtcl=/usr/local/src/aolserver45/tcl8.4.14/unix make install
Instalao do TCLlib
cd /usr/local/src/aolserver45 tar xvfj tcllib-1.7.tar.bz2 cd tcllib-1.7 ./configure --prefix=/usr/local/aolserver45 make install cd /usr/local/src/aolserver45
Instalao do libthread
tar xfz thread2.6.4.tar.gz cd thread2.6.4/unix/ ../configure --enable-threads --prefix=/usr/local/aolserver45 --execprefix=/usr/local/aolserver45 --with-aolserver=/usr/local/aolserver45 --withtcl=/usr/local/src/aolserver45/tcl8.4.14/unix make make install cd /usr/local/src/aolserver45
Instalao do XoTCL
tar xvfz xotcl-1.5.3.tar.gz cd xotcl-1.5.3/
61
export CC=gcc ./configure --enable-threads --enable-symbols --prefix=/usr/local/aolserver45 -exec-prefix=/usr/local/aolserver45 --withtcl=/usr/local/src/aolserver45/tcl8.4.14/unix make make install-aol cd /usr/local/src/aolserver45
Tome o cuidado de chamar o arquivo nsd-postgres ao invs de nsd se estiver usando o banco de dados PostgreSQL
wget http://cvs.openacs.org/cvs/*checkout*/openacs-4/packages/acs-coredocs/www/files/nsd-postgres.txt cp nsd-postgres.txt /usr/local/aolserver45/bin/nsd-postgres chmod 755 /usr/local/aolserver45/bin/nsd-postgres
8.4.Instalao do OpenACS
O ltimo passo criar o usurio dono do servio e o diretrio onde ser baixada a verso do OpenACS.
62
Criar o diretrio padro onde sero instaladas as vrias instncias do OpenACS que podem ser montadas na mesma mquina.
[root [root [root [root mkdir chgrp chmod root]# mkdir /var/lib/aolserver root]# chgrp web /var/lib/aolserver root]# chmod 770 /var/lib/aolserver root]# /var/lib/aolserver web /var/lib/aolserver 770 /var/lib/aolserver
Baixar o OpenACS O prximo passo baixar a verso do OpenACS que ser utilizada.
[root root]# su - service0 [service0 ~]$ cd /var/lib/aolserver/ [service0 aolserver]$ svn co http://svn.softwarepublico.gov.br/svn/openacs/NOME_DA_VERSO su - service0 cd /var/lib/aolserver/ svn co http://svn.softwarepublico.gov.br/svn/openacs/NOME_DA_VERSO
No diretrio NOME_DA_VERSO/etc/ esto os arquivos de configurao do AOLServer. Vamos editar primeiro o arquivo config.tcl. Numa das primeiras linhas est a seo de configuraes gerais. Vamos definir o nome do servio e a porta onde ele vai rodar # change to 80 and 443 for production use set httpport 80 set httpsport 443 set server set servername set serverroot "spb" "Software Pblico Brasileiro" "/var/lib/aolserver/${server}"
importante que a varivel server possua o nome da verso baixada, que deve ser o nome do diretrio da verso para podermos partir para a configurao do banco de dados. # which database do you want? postgres or oracle set database postgres set db_name $server
if { $database == "oracle" } { set db_password "mysitepassword" } else { set db_host localhost set db_port "" 63 Autor: Eduardo Santos
set db_user }
service0
Note que o usurio padro o service0, mas pode ser alterado para qualquer outro. Ser necessrio depois adicionar o usurio definido no grupo daqueles que podem acessar o banco de dados. Por fim, vamos ter certeza de que a biblioteca libthread est no caminho certo editando a parte de mdulos: ns_section ns/server/${server}/modules ns_param nssock ${bindir}/nssock.so ns_param nslog ${bindir}/nslog.so ns_param nssha1 ${bindir}/nssha1.so ns_param nscache ${bindir}/nscache.so ns_param libthread /usr/local/src/aolserver45/thread2.6.4/unix/libthread2.6.4.so
Preparar o banco de dados para receber o OpenACS Vamos criar um usurio no banco de dados com o nome igual ao usurio dono do servio. Por padro adotamos o usurio do OpenACS como super usurio no PostgreSQL, o que significa que ele ter acesso a todos os bancos de dados na mquina.
[service0 etc]$ exit [root root]# su - service0 [postgres pgsql]$ createuser -a d service0 CREATE ROLE [postgres pgsql]$ exit logout [root root]#
Criando o banco de dados com o mesmo nome dado varivel server no arquivo config.tcl
[root root]# su - service0 [service0 service0]$ /usr/local/pgsql/bin/createdb -E UNICODE NOME_DO_BANCO CREATE DATABASE [service0 service0]$ su - service0 /usr/local/pgsql/bin/createdb -E UNICODE NOME_DO_BANCO
Criar a funo no banco de dados $ /usr/local/pgsql/bin/psql NOME_DO_BANCO create or replace function bitfromint4 (integer) returns bit varying as ' begin return $1::bit(32); end;' language 'plpgsql' immutable strict; 64 Autor: Eduardo Santos
O ltimo passo copiar o arquivo install.xml para a pasta raiz, pois assim quando iniciarmos o sistema e o instalarmos, o dotlrn tambm ser instalado.
[root root]# cp /var/lib/aolserver/NOME_DA_VERSAO/packages/dotlrn/install.xml /var/lib/aolserver/NOME_DA_VERSAO/
# Data structures ns_param dstringcachemaxentries 10 ;# Max no. of Dstrings to put on cache ns_param dstringcachemaxsize [expr 3*1024]
65
iobufsize
16000
;# Buffer size suitable for I/O ;# ;# ;# ;# ;# ;# Max time conn is kept alive (keepalive) (set to 0 to disable keepalive) Max length of pending conn queue Max no. of conns in keepalive state Warn when waiting on really long procs Secs to wait on shutdown if open conns Display logging with "Dev" severity Display logging with "Debug" severity true = double-spaced server.log Roll server.log every 24 hours. Max number of old server.log files PID of server (named "nspid.PORT") ;# Filename of server.log
# Server logging ns_param dev ns_param debug ns_param logexpanded ns_param logroll ns_param maxbackup ns_param pidfile ns_param serverlog
# DNS tuning ns_param dnscache true ns_param dnscachetimeout 60 # Miscellaneous ns_param checkexitcode ns_param crashcmd ns_param mailhost
false ;# Check exit code on forked process ns_crash ;# A Tcl command that dumps core. smtp.yourcompany.com ;# SMTP host for ns_sendmail
# # Thread library (nsthread) parameters # ns_section "ns/threads" ns_param mutexmeter true ;# measure lock contention ns_param stacksize [expr 128*1024] ;# stack size per thread (in bytes) # # MIME types. # # Note: AOLserver already has an exhaustive list of MIME types, but in # case something is missing you can add it here. # ns_section "ns/mimetypes" ns_param ".xls" "application/vnd.ms-excel" ns_param default "*/*" ;# MIME type for unknown extension ns_param noextension "*/*" ;# MIME type for missing extension ############################################################ # # Server-level configuration # # There is only one server in AOLserver, but this is helpful when multiple # servers share the same configuration file. This file assumes that only # one server is in use so it is set at the top. # ns_section "ns/servers" ns_param $server $servername ;# Name of virtual server.
66
# # Server parameters # ns_section "ns/server/${servername}" ns_param directoryfile $directoryfile ;# List of files to use (index.html) ns_param pageroot $pageroot ;# Directory under which all pages live # Tuning options ns_param connsperthread ns_param flushcontent ns_param maxconnections ns_param maxdropped ns_param maxthreads ns_param minthreads ns_param threadtimeout # Limits ns_param ns_param ns_param ns_param maxheaders maxline maxpost sendfdthreshold 0 false 100 0 20 0 120 16384 8192 65536 2048 ;# ;# ;# ;# ;# ;# ;# ;# ;# ;# ;# Normally there's one conn per thread Flush all data before returning Max connections to put on queue Shut down if dropping too many conns Tune this to scale your server Tune this to scale your server Idle threads die at this rate Max Max Max Min no. of headers from client line length from client bytes on a POST size of file descriptor to send
# Performance statistics gathering ns_param globalstats true ns_param urlstats true ns_param maxurlstats 1000
;# Enable built-in statistics ;# Enable URL statistics ;# Max number of URL's to do stats on
# Directory listings can be generated with an ADP or a Tcl proc. ns_param directoryadp $home/dirlist.adp ;# Choose one or the other ns_param directoryproc _ns_dirlist ;# ...but not both! ns_param directorylisting simple ;# Can be simple or fancy (for ns_dirlist) # Miscellaneous ns_param checkmodifiedsince true ns_param enableaolpress false ns_param headercase preserve # # Internal # ns_section ns_param ns_param # # Fastpath # ns_section ns_param ns_param ns_param ns_param redirects "ns/server/${servername}/redirects" 404 "/notfound.html" ;# Not Found error page 500 "/servererror.html" ;# Server Error page serves HTML "ns/server/${servername}/fastpath" cache true ;# Enable cache for normal URLs cachemaxentry 8192 ;# Largest file size allowable in cache cachemaxsize [expr 5000*1024] ;# Size of fastpath cache mmap false ;# Use mmap() for cache ;# Check url if no If-Modified-Since? ;# Enable extra features used by AOLpress ;# tolower, toupper, preserve
# # Tcl interpreter # ns_section "ns/server/${servername}/tcl" ns_param autoclose true ;# Close files the Tcl interp opened ns_param debug false ;# Names of files sourced is logged
67
ns_param nsvbuckets 8 ;# No. of buckets to hold nsv's ns_param statlevel 0 ;# How many levels deep to run tclstats ns_param statmaxbuf 100 ;# Maximum entries in tclstats table ns_param library \ "$home/servers/${servername}/modules/tcl" ;# Private tcl library for the server # # ADP (AOLserver Dynamic Page) configuration # ns_section "ns/server/${servername}/adp" # ADP features ns_param map "/*.adp" ;# ns_param map "/*.html" ;# ns_param enableexpire true ;# ns_param enabledebug true ;# ns_param debuginit "ns_adp_debuginit" # ADP tuning ns_param cache ns_param cachesize ns_param taglocks ns_param threadcache ns_param threadcache Extensions to parse as ADP's Any extension can be mapped Set "Expires: now" on all ADP's Turn on Tclpro debugging with "?debug" ;# Debug procedure of ADP's creation of ADP tags 7.6 (nsd76) 8.2 (nsd82)
true ;# In-memory cache [expr 5000*1024] false ;# Enable post-ini false ;# default for Tcl true ;# default for Tcl
;# Pretty-print ADP errors with an ADP ;# Page to include for all ADP's
# # ADP custom parsers -- see adp.c # ns_section "ns/server/${servername}/adp/parsers" ns_param adp ".adp" ;# The simple parser looks for <\% ... \%> ns_param fancy ".adp" ;# The fancy parser does a lot more. # # Socket driver module (HTTP) -- nssock # ns_section "ns/server/${servername}/module/nssock" ns_param port $httpport ;# Port for HTTP (typically 80) ns_param hostname $host ;# This is not the same as your hostname ns_param address $address ;# This is not the same as your host addr ns_param location "url" ;# URL for auto-redirects (trailing slash) # # Socket driver module (HTTPS) -- nsssl # ns_section "ns/server/${servername}/module/nsssl" ns_param port $httpsport ;# Port for HTTPS (typically 443) ns_param hostname $host ;# This is not the same as your hostname ns_param address $address ;# This is not the same as your host addr ns_param keyfile ${home}/servers/${servername}/modules/nsssl/keyfile.pem ns_param certfile
68
${home}/servers/${servername}/modules/nsssl/certfile.pem # # Control port -- nscp # ns_section "ns/server/${servername}/module/nscp" ns_param port 9999 ;# Control port listens on port 9999 ns_param address "127.0.0.1" ;# For security, use 127.0.0.1 only # Control port users ns_section "ns/server/${servername}/module/nscp/users" # The default password for nsadmin is "x". You should change it. # type "ns_crypt newpassword salt" and put the encrypted string below. ns_param user "nsadmin:t2GqvvaiIUbF2:" ;# sample user="nsadmin", pw="x". # # Access log -- nslog # ns_section "ns/server/${servername}/module/nslog" ns_param file "access.log" ns_param formattedtime true ;# true=common log format ns_param logcombined false ;# true==NCSA combined format ns_param maxbackup 5 ;# Max number to keep around when rolling ns_param rollhour 0 ;# Time to roll log ns_param rolllog true ;# Should we roll log? ns_param rollonsignal true ;# Roll log on SIGHUP # # CGI interface -- nscgi # # Note: CGI is *vastly* inferior to ADP's or even built-in Tcl libraries. # ns_section "ns/server/${servername}/module/nscgi" ns_param debug false ;# Be chatty in log ns_param gethostbyaddr false ;# Whether to do reverse DNS lookups ns_param limit 0 ;# Max number of concurrent CGI processes ns_param maxoutput 10240 ;# Max bytes allowed from external process ns_param buffersize 8192 ;# Buffer output from external process ns_param map \ "GET /cgi /usr/local/cgi" ;# Where your CGI executables live (GET) ns_param map \ "POST /cgi /usr/local/cgi" ;# Where your CGI executables live (POST) # CGI environment variable handling -- See admin guide ns_param systemenvironment false ;# Copies environment from nsd start shell # # Access control (permissions) -- nsperm # ns_section "ns/server/${servername}/module/nsperm" # # Unix domain socket driver -- nsunix # ns_section "ns/server/${servername}/module/nsunix" ns_param hostname "host" ;# Hostname used in response to client ns_param port "port" ;# Port to listen on ns_param socketfile "path.name" ;# UNIX domain socket driver
69
# # Virtual Hosting redirector -- nsvhr # ns_section "ns/server/${servername}/module/nsvhr" ns_param busyurl "url" ;# Redirect here if back-end times out ns_param errorurl "url" ;# Redirect here on proxy errors ns_param method "GET" ;# Methods allowed to proxy ns_param method "POST" ;# Methods allowed to proxy (can have >1) ns_param timeout 30 ;# Timeout waiting for back-end # Register ns_section ns_param ns_param hosts to proxy "ns/server/${servername}/module/nsvhr/maps" "www.tcpsocket.com" "http://127.0.0.0:2000" ;# HTTP proxy "www.domainsocket.com" "unix://somehost" ;# Domain socket
# # Database drivers # # Two pools are given here. Sybase uses the Sybase client libraries, # obtained from Sybase. Postgres is freely available at # www.postgresql.org. Sybase uses an external proxy daemon while # Postgres uses an internal driver. The Sybase driver requires some # configuration in ns/db/driver/sybase_driver to tell th "nsext.so" # driver where to find the nssybpd executable and some other things. # The Postgres driver doesn't need any of that because it's internal # and does not use nsext.so. # ns_section "ns/db/drivers" ns_param sybase_driver nsext.so ;# Use nsext.so for a proxy daemon ns_param postgres_driver nspostgres.so ;# An internal driver ns_section "ns/db/driver/sybase_driver" ns_param localdaemon nssybpd ;# Name of the proxy daemon executable ns_param param path_to_sybase ;# Usually the $SYBASE env var ns_section "ns/db/pools" ns_param sybase_pool ns_param postgres_pool ns_section ns_param ns_param ns_param ns_param ns_param ns_param ns_param ns_param ns_param ns_section ns_param ns_param ns_param ns_param ns_param ns_param ns_param ns_param "Sybase Pool" "Postgres Pool"
"ns/db/pool/sybase_pool" driver sybase_driver datasource SERVER_NAME:database_name user user_name password password connections 1 logsqlerrors true ;# Verbose SQL query error logging verbose false ;# Verbose error logging maxidle 600 ;# Max time to keep idle db conn open maxopen 3600 ;# Max time to keep active db conn open "ns/db/pool/postgres_pool" driver postgres_driver datasource HOSTNAME:PORT:database_name user user_name password password connections 1 logsqlerrors true ;# Verbose SQL query error logging verbose false ;# Verbose error logging maxidle 600 ;# Max time to keep idle db conn open
70
ns_param
maxopen
3600
# # Accessing DB pools # # In the case of virtual servers you can give different virtual # servers access to different databases, or you can let them access # them all. AOLserver 3.x does not use virtual servers so the only # useful value is "*", but if you use one config file for multiple nsd # processes, or you are using a version of AOLserver that supports # virtual servers, then you should list the pools you want to access. # ns_section "ns/server/${servername}/db" ns_param pools * ;# Wildcard gives access to all ns_param defaultpool sybase_pool # # Modules to load # # Note: Only load the modules you are actually going to use. # ns_section "ns/server/${servername}/modules" ns_param nssock nssock.so ns_param nsssl nsssle.so ns_param nscp nscp.so ns_param nslog nslog.so ns_param nscgi nscgi.so ns_param nsperm nsperm.so # # Loading a Tcl module # # This example shows a Tcl module, called "tcl_module", has its code # in the AOLserver Tcl library in either the modules/tcl/tcl_module # directory or servers/servername/modules/tcl/tcl_module directory. # ns_param tcl_module tcl
71
ou para a verso 8
apt-get install postgresql-8.1 postgresql-dev
1. Configurar o postgres-8 com todas compatibilidades no arquivo postgresql.conf: na sesso: # VERSION/PLATFORM COMPATIBILITY add_missing_from = on regex_flavor = extended default_with_oids = on 2. Gerar a funo antes de instalar o OpenACS, isto depois de criar o banco para a aplicao. Veja adiante: create or replace function bitfromint4 (integer) returns bit varying as ' begin return $1::bit(32); end;' language 'plpgsql' immutable strict;
automaticamente ser criado um usurio www-data que ser o dono do servio. O diretrio de trabalho padro neste tipo de instalao o /var/www. Instalando o OpenACS ou o .LRN
como postgres
# su - postgres #createlang plpgsql ct-gcie
como www-data
# su - www-data # psql ct-gcie create or replace function bitfromint4 (integer) returns bit varying as ' begin return $1::bit(32); end;' language 'plpgsql' immutable strict;
Configurando o servio : edite o arquivo /var/www/dotlrn2.2.0/etc/config.tcl e altere os valores de acordo com a aplicao
set httpport 80 #porta HTTP a ser usada set server "ct-gcie" #nome do servio. Esta varivel e usada como referncia em outros parmetros set servername "Cmara Tcnica de Gesto do Conhecimento" set serverroot "/var/www/${server}" set database ct-gcie set db_user www-data set homedir /usr/lib/aolserver4
73
Escrever um script que possa processar um tarball inteiro do OpenACS e transform-lo num pacote debian; Incluir uma chamada baseada no OpenACS que contm tudo do tarball, exceto os pacotes; Talvez criar uma outra chamada para o tarball do OpenACS que renomeia o diretrio que o contm; atualmente a localizao em /usr/share/openacs-tarballs. Escrever um script que constri um servio no local especificado; Escrever um script que copia um pacote simples em um servio existente; Escrever um front end para os dois scripts acima. Requisitos:
Para rodar o script sero necessrios os mdulos perl XML::DOM e File::Copy::Recursive. Os nomes dos pacotes debian para os mdulos acima so libxml-dom-perl e libfile-ncopy-perl; note tambm que o script vlido somente para o debian. Uma vez que o script for rodado, um pacote debian ser montado. Para constru-lo, ser necessrio ter o pacote debhelper instalado.
74
Como:
Extraia o pacote do OpenACS em algum lugar. digamos que esteja em /algum/lugar/foo; V par o diretrio onde deseja que o pacote seja montado; Execute /caminho/para/o/gerador /algum/lugar/foo. Um diretrio do tipo ./foo-1.0 ser criado e todo o cdigo do pacote ser jogado l dentro.
V para o diretrio ./foo-1.0 fakeroot debian/rules binary. Isso ir produzir um pacote .deb no diretrio (..). A localizao ser um link para foo-1.0.
use strict; # where are all the packages stored my $oacsPackageCollection = "/usr/share/openacs-tarballs"; # some browsing funcs # prints the tagnames of each child of the $parent XML::DOM::Node object sub printChildren { my ($parent) = @_; my $node;
75
foreach $node ($parent->getChildNodes()) { print $node->getNodeName() . "\n"; } } # prints the contents of a XML::DOM::NamedNodeMap (one app: attributes) sub printNamedNodeMapItems { my ($theMap) = @_; my $index = 0; my $node; for ($index = 0; $index < $theMap->getLength(); ++$index) { $node = $theMap->item($index); print $node->getName() . " = " . $node->getValue() . "\n"; }
# parse args (for now, make sure exactly one arg) if(scalar(@ARGV) != 1) { print STDERR "Usage: $0 <packageDirPath>\n"; exit 1; } my $packageDir = $ARGV[0]; use XML::DOM; my $theParser = new XML::DOM::Parser; # change this so that incoming arg is path to dir containing *.info; # read that file and determine package key from it. if(! opendir(PACKAGEDIR, $packageDir)) { print STDERR "E: can't open $packageDir: $^E\n"; exit 1; } my $infoFile = ""; # warning: this does not check for more than one info file while ( ($infoFile = readdir(PACKAGEDIR)) && ($infoFile !~ /\.info$/) ) { } closedir PACKAGEDIR; if ($infoFile eq "") { print STDERR "E: hmm, this doesn't look like an oacs package: no info file\n";
76
exit 1; } my $packageKey = ""; my $packageType = ""; my $packageURL = ""; my $versionName = ""; my $versionURL = ""; # add errcheck to this my $doc = $theParser->parsefile("$packageDir/$infoFile"); # do something with the internal rep of the info file ($doc) here # make sure this worked my @packageSpec = $doc->getElementsByTagName("package"); my $packageSpec = $packageSpec[0]; # get what's available in the <package> tag... this may need error checking $packageKey = $packageSpec->getAttribute("key"); $packageType = $packageSpec->getAttribute("type"); $packageURL = $packageSpec->getAttribute("url"); print "packageKey is |$packageKey|\n"; print "packageType is |$packageType|\n"; print "packageURL is |$packageURL|\n"; # make sure this worked my @versionSpec = $packageSpec->getElementsByTagName("version"); my $versionSpec = $versionSpec[0]; $versionName = $versionSpec->getAttribute("name"); $versionURL = $versionSpec->getAttribute("url"); print "versionName is |$versionName|\n"; print "versionURL is |$versionURL|\n"; # find some way to deal with these provides... debian doesn't do # versioned provides... so, put version in package name? my @providesSpec = $versionSpec->getElementsByTagName("provides"); my $ele; my @requiresSpec = $versionSpec->getElementsByTagName("requires"); my @requires; my $reqText; foreach $ele (@requiresSpec) { $reqText = $ele->getAttribute("url") . " (=" .
77
my $requires = join(", ", @requires); my @summarySpec = $versionSpec->getElementsByTagName("summary"); my $summarySpec = $summarySpec[0]; my $summaryNode = $summarySpec->getChildAtIndex(0); my $summary = $summaryNode->getData; my @descriptionSpec = $versionSpec->getElementsByTagName("description"); my $descriptionSpec = $descriptionSpec[0]; my @description = split("\n", $descriptionSpec->getChildAtIndex(0)->getData); $doc->dispose; # # # # # # # # # the path to the package dir to be examined is available in $packageDir it reads the package's info file and sets variables from it: $packageKey $packageType $packageURL $versionName $versionURL
# create the package dir tree my $sourcePackage = "$packageKey-$versionName"; if(-e $sourcePackage) { print STDERR "E: something called $sourcePackage exists -- cannot continue\n"; exit 1; } mkdir $sourcePackage; mkdir "$sourcePackage/debian"; mkdir "$sourcePackage/package"; # copy the package files into the tree use File::Copy::Recursive qw{rcopy}; rcopy($packageDir, "$sourcePackage/package"); qx{cd $sourcePackage/package && tar cfz ../$sourcePackage.tar.gz .}; qx{rm -rf $sourcePackage/package}; ######### # the main source control file #########
78
if(! open(SRC_CTRL, "> $sourcePackage/debian/control")) { print STDERR "E: couldn't create/open/write $sourcePackage/debian/control"; exit 1; } # first (generic/source) paragraph print SRC_CTRL "Source: $packageKey\n"; print SRC_CTRL "Maintainer: Jim Lynch <jwl\@debian.org>\n"; print SRC_CTRL "Build-depends: debhelper\n"; # paragraph separator print SRC_CTRL "\n"; # second and last paragraph (re: the package it builds) print SRC_CTRL "Package: $packageKey\n"; print SRC_CTRL "Architecture: all\n"; print SRC_CTRL "Depends: $requires\n"; print SRC_CTRL "Description: $summary\n"; my $descLine; foreach $descLine (@description) { print SRC_CTRL " $descLine\n"; } close SRC_CTRL; ######### # the changelog ######### my $rfc822date = qx{822-date}; chomp $rfc822date; if(! open(SRC_CHLOG, "> $sourcePackage/debian/changelog")) { print STDERR "E: couldn't create/open/write $sourcePackage/debian/changelog"; exit 1; } print print print print SRC_CHLOG SRC_CHLOG SRC_CHLOG SRC_CHLOG "$packageKey ($versionName) unstable; urgency=low\n"; " * new upstream version\n"; " -- Jim Lynch <jwl\@debian.org> $rfc822date\n"; "\n";
close SRC_CHLOG; ######### # the debian/rules script ######### rcopy ("rules", "$sourcePackage/debian/"); ######### # the debian/install file #########
79
if(! open(SRC_INST, "> $sourcePackage/debian/$packageKey.install")) { print STDERR "E: couldn't create/open/write $sourcePackage/debian/$packageKey.install"; exit 1; } print SRC_INST "./$sourcePackage.tar.gz " . substr($oacsPackageCollection, 1) . "\n"; close SRC_INST;
80
10.Configuraes iniciais
10.1.Como configurar o site no primeiro acesso
No primeiro acesso importante preencher os campos com bastante cuidado. Uma tela parecida com a que est descrita abaixo deve aparecer, e o texto de ajuda em portugus indica o significado de cada um dos campos. System Configuration We'll need to create a site-wide administrator for your server (like the root user in UNIX). Please type in the email address, first and last name, and password for this user. System Administrator Email: Username: First Name: Last Name: Password: Password (again): [*] [*]
http://eduardol:8000
[*] URL do sistema na forma que ser vista por todas as System URL: pessoas. Deve incluir a porta no caso da porta de seu servidor no ser a 80. System Name:
yourdomain Network
[*]
Nome do sistema
Yourdomain Network, Inc. [*] Publisher Name: Nome legal da pessoa ou corporao responsvel pelo site.
System Owner: Endereo de e-mail que assina as pginas visveis ao usurio. Admin Owner: Endereo de e-mail que assina as pginas administrativas. 81 Autor: Eduardo Santos
Host Administrator: Algum que pode ser contatado no caso de problemas tcnicos. Outgoing Email Sender: Endereo de e-mail que assinar todos os alertas enviados. New Registration Email: Endereo de e-mail para enviar notificaes de novos registros. importante ressaltar que os valores informados na criao do site sero os mesmos para sempre. Assim, preencha os campos corretamente para o sistema de produo.
o usurio ser aprovado no OpenACS e no no .LRN. O prximo passo fazer com que a confirmao do email seja requerida. Vamos definir para o parmetro RegistrationRequiresEmailVerificationP o valor 1. Ser enviada uma mensagem para o usurio solicitando a confirmao do email. A mensagem pode ser facilmente alterada, pois internacionalizada e o message key acs-subsite.lt_To_confirm_your_regis. Vamos agora configurar o e-mail que ficar no destinatrio. O parmetro NewRegistrationEmailAddress; note que esse dado tambm pode ser alterado nos parmetros do Kernel. Agora vamos configurar o sistema para decidir quais as primeiras pginas visualizadas pelo usurio. No link /admin/site-map, selecionamos l no final o pacote Kernel. Ao clicarmos sobre ele aparece a pgina dos parmetros do sistema. O primeiro importante o IndexRedirectUrl, que define qual url ser chamada quando o usurio digitar o endereo do seu site. Ex.: (http://www.softwarepublico.gov.br/<IndexRedirectUrl>). O prximo passo configurar o sistema. Os parmetros AdminOwner, HostAdministrator, OutgoingSender e SystemOwner podem ser preenchidos com o e-mail do Administrador do Site. O parmetro HomeURL diz a pgina para a qual o usurio ser encaminhado aps fazer o login (no caso /dotlrn/index), o PublisherName diz quem est fazendo o site (Ministrio do Planejamento) e o SystemName diz quel o nome do site. O ltimo e muito importante, SystemURL, diz qual o endereo do site que aparecer em quase todas as mensagens automticas geradas por ele. Nota: muito importante que a pgina a qual o usurio ser encaminhado aps o login seja /dotlrn/index. Por padro, o portal do usurio s criado a primeira vez em que ele clica sobre esse link. Se ele logar pela primeira vez sem acessar essa pgina, no aparecer nenhum link no site para ele navegar, nem mesmo as abas aparecero. Outros parmetros so muito importantes, pois coordenam servios tais como envio de e-mails, acesso e design. Mais informaes podem ser encontradas no site do OpenACS.
83
11.2.Tipos de pgina
Pginas wiki so armazenadas no content repository do OpenACS (CR), usando a classe genrica que parte do pacote xotcl-core. A classe CrClass permite definir de um modo geral diferentes tipos e subtipos de entradas no CR, que podem ter diferentes conjuntos de atributos. Dependendo do tipo, formas diferentes so geradas; conseqentemente possvel tambm definir diferentes tipos de pginas wiki, se necessrio. 84 Autor: Eduardo Santos
A Classe padro ::xowiki::Page definida como um item genrico do content repository (::Generic::CrItem) e se parece da seguinte forma:
::Generic::CrClass create ::xowiki::Page -superclass ::Generic::CrItem \ -pretty_name "XoWiki Page" -pretty_plural "XoWiki Pages" \ -table_name "xowiki_page" -id_column "page_id"
Atualmente o pacote Xowiki define 4 Crclasses: ::xowiki::Page, ::xowiki::PlainPage, ::xowiki::PageTemplate, ::xowiki::PageInstance, ::xowiki::Object and ::xowiki::File. As classes sero definidas mais tarde.
11.3.Diretrios
O XoWiki organiza as pginas em pastas baseadas no content repository do OpenACS, e h normalmente uma pasta para cada instncia. A organizao atravs de pastas do content repository faz com os nomes das pginas tenham que ser nicos por pasta e, conseqentemente, por instncia do XoWiki. Assim, uma instncia representa um namespace comum todas as entradas do wiki. possvel montar vrias instncias de wiki simplesmente montando o pacote vrias vezes no site map, ou ainda utilizar um wiki por comunidade quando for montado dentro do .LRN numa comunidade. Cada uma das instncias pode ser configurada por uma srie de parmetros que controlam seu comportamento e aparncia. O administrador pode determinar, por exemplo, a pgina inicial (procure por index_page na seo configurao), se os usurios podero comentar as pginas (atravs do pacote general comments) ou ainda se os marcadores de usurio del.icio.us devem ser permitidos. Nomes O administrador pode determinar tambm, como os nomes das pginas devem ser construdos. A partir da verso 0.30 todos eles so normalizados para transformar espaos em underscores para providenciar links melhores e para tornar a construo dos nomes mais fcil de controlar. A conveno dos nomes determinada pelo parmetro subst_blank_in_name. Revises O XoWiki guarda um histrico de revises para cada arquivo. Quando uma entrada atualizada, a verso antiga mantida no arquivo, o que torna possvel retornar para verses anteriores a qualquer momento. Dependendo da poltica de permisses, os usurios com direito de ver as revises ganham um link na barra de menu do XoWiki. A figura direita mostra o histrico de uma pgina.
11.4.Editando
As pginas no XoWiki so editadas normalmente atravs de um editor richtext, como rte ou xinha; assim, todas as pginas so HTML. Marcadores 85 Autor: Eduardo Santos
simples como palavras em negrito ou itlico podem ser fornecidos pelos controles do widget richtext. muito mais fcil ento importar contedos de textos populares processando os pacotes de software via drag and drop, utilizar tabelas, incluir imagens ou reutilizar o contedo html como documentao. Certas marcaes Wiki para o gerenciamento de pginas ou incluso de elementos so inseridos no widget richtext.
onde pageReference um nome de pgina (com ou sem o prefixo do idioma) ou uma pgina externa (comeando por http://). Cada pgina wiki tem dois caracteres no prefixo que denotam seu idioma natural. Se no houver nenhuma referncia no nome, o prefixo da pgina onde se deseja incluir a marcao usado por padro.
Um link interno de idiomas aponta para a mesma informao em um outro idioma. Sintaticamente se inicia com dois pontos. Se tal link estiver contido numa pgina, ele no ser renderizado o endereo, mas adicionado seo de idiomas. A marcao a seguir define que, para a pgina atual, h uma verso em ingls:
[[:en:GN]]
Um link interno de idiomas listado com uma pequena flag entre as outras referncias. Se a pgina no existir, pode ser criada clicando na flag e editando a pgina.
Ao clicar sobre um link de arquivos (visualizado por um pequeno cone), o arquivo baixado. Seus meta dados (tamanho, nome, tipo, descrio, etc) so mostrados atravs da interface de administrao ou atravs da abertura do arquivo com a opo download (padro). Quando inserido e o arquivo referenciado no existe, o XoWiki mostra os colchetes, como sempre, para permitir ao usurio enviar o arquivo na pasta da instncia.
Um link de imagem muito similar a um link de arquivos, mas referencia uma imagem (content-type image/*).
[[image:gustaf.png|On of the few nice Photos..]]
tambm .
O XoWiki d suporte tambm a um tipo experimental de links de tipo, onde o usurio pode definir qualquer tipo de relao a outra pginas wiki, como links a pginas externas ou internas. De maneira geral o exemplo pode ser utilizado para relaes entre os termos (sinnimos, antnimos, hiprboles, ...) de um dicionrio, entre outros. O tipo do link especificado antes do prefixo de idioma (opcional). Utilizamos a seguinte sintaxe:
[[tipo_do_link:?idioma:?nome?|nome do link?]]
Quando um novo tipo de link definido, possvel definir seu resolver e seu renderer, transformando a classe ::xowiki::Link em uma subclasse. A verso 0.24 vem com uma implementao simples de glossrio, que uma outra instncia do XoWiki chamada glosssary contendo todas as definies de palavras. Cada instncia pode se referir ao glossrio, alm de criar links para suas palavras. A figura abaixo contm um exemplo de link de tipo num popup para o PostgreSQL: Figura 11.1 Popup de um link de tipo
87
Para resolver o termo, o XoWiki utiliza um resolver especfico para links que localiza uma instncia chamada glossary. Ele procura nos site-nodes por ns irmos na instncia, depois procura no seu n parent pelos mesmos irmos, e assim por diante. Quando o resolver puder localizar a instncia glossary e a entrada PostgreSQL, ele vai renderizar a entrada com um smbolo especial, como visto na figura acima. Se a instncia glossary for localiza, mas no a palavra, o link mostrado entre colchetes para adicionar uma definio de dicionrio no glossary. Quando o link for ativado ele mostra a entrada xowiki numa janela popup. A pgina do glossary recuperada atravs de uma chamada AJAX em background (testado no Firefox, no Safari e no IE).
O XoWiki permite a incluso de pginas adp. A incluso definida na sintaxe do MediaWiki, entre chaves duplas. A especificao do include comea com adp seguido pelo caminho da pgina e por pares nome/valor de variveis passadas pgina adp. O exemplo a seguir inclui um mini-calendrio do pacote calendrio numa pgina wiki.
...text... {{adp /packages/calendar/www/mini-calendar /dotlrn/calendar/}}} ...text... {view day base_url
O XoWiki vem com um pacote de pginas adp pr-definidas, que so colocadas nos subdiretrios www/portlets. Alguns dos includes podem ser vistos nas sees posteriores, que incluem os seguintes exemplos:
{{adp portlets/rss-button}} {{adp portlets/categories open_page de:iMac}}} {name {Table {name of Contents} tree_name *toc* by
{Recently
Changed
Pages
{{adp portlets/recent {name {Recently Changed Pages}} }} {{adp portlets/last-visited {name {Last Visited} max_entries 10 }}} {{adp portlets/most-popular {name {Most Popular} max_entries 10 }}}
A incluso de arquivos adp pode ser utilizada para fazer pginas wiki aninhadas (pginas contendo outras pginas wiki, por exemplo). Quando o seguinte pedao de cdigo usado numa pgina do XoWiki, ele pode ser substitudo durante a renderizao pela pgina chamada en:GN.
{{adp portlets/wiki {name en:GN}}}
Na pgina renderizada qualquer um pode mudar para a pgina includa 88 Autor: Eduardo Santos
clicando no ttulo do item includo. A profundidade da incluso limitada para evitar bugs de recursividade e pginas muito caras ao sistema. Atualmente o XoWiki no guarda a estrutura de incluso atravs links part_of e no inclui as referncias das pginas includas para a que est recebendo.
Para controlar o estilo das pginas, o XoWiki permite marcadores de blocos similares aos encontrados em www.apfelwiki.de. Podem ser usados para marcar diferentes sees <div> sem ter que ir aos detalhes de uma pgina html. Os seguintes marcadores so permitidos em particular:
>>content<< >>side-bar<< >>left-col<< >>left-col30<< >>right-col<< >>right-col70<< >>box<<
Cada marcador de bloco tem que terminar com um marcador de bloco vazio:
>><<
A seo a seguir contm exemplos de pginas wiki aninhadas baseadas no mecanismo de incluso de adp apresentado. Exemplo: Pgina inicial do portal OpenACS.org modelado com o XoWiki Figura 11.2 Pgina inicial do portal modelada com XoWiki
89
A pgina utiliza basicamente uma coluna de 25% esquerda, outra de 25% direita, contendo tambm pginas XoWiki. O texto principal parte da pgina OpenACS home Page.
>>left-col25<< {{adp portlets/wiki {{adp portlets/wiki >><< >>right-col25<< {{adp portlets/wiki {{adp portlets/wiki >><< {name de:News}}} {name de:Recent\ Posts}}} {name de:About\ OpenACS}}} {name de:Recent\ Posts}}}
OpenACS (Open Architecture Community System) is a toolkit for building scalable, community-oriented web applications. OpenACS is the foundation for many products
90
and websites, including the .LRN e-learning platform. OpenACS is open source and is available under the GNU General Public License. ...
Exemplo: Implementao de Weblog com XoWiki A partir da verso 0.26, o XoWiki vem com uma implementao simples de weblog. As pginas do repositrio podem ser vistas num estilo weblog, onde cada uma tratada como um post. As entradas so paginadas (10 entradas por pgina como padro. A barra lateral contm um mini-calendrio, onde o nmero de posts por dias est incluso, Ao clicar em um dia possvel filtrar as entradas para ele. As categorias utilizadas so mostradas com o nmero de entradas; clicar sobre o nmero gera um filtro por categorias. Ao clicar no nome Weblog, o filtro removido.
>>content<< {{adp portlets/weblog {name Weblog}}} >><< >>sidebar<< {{adp portlets/weblog-mini-calendar}} {{adp portlets/categories {count 1 skin plain-include}}} >><<
Variveis de Template Os nomes das variveis permitidas para substituio so a unio dos campos de gravao da instncia desta pgina wiki e as variveis da instncia utilizada para a renderizao. Assim, se a classe pgina wiki especializada (sub classe) e estendida com mais variveis, elas estaro disponveis. Do ponto de vista do programador, mais fcil adicionar variveis da instncia ao objeto pgina antes de renderiz-la. O conjunto de variveis pode ser obtido pela varivel especial de substituio @__template_variables__@. No surpreendente, mas legal que as propriedades richtext aplicadas s variveis de substituio sejam aplicadas nos valores substitudos tambm.
11.8.Seletor de arquivos
O Xowiki fornece um seletor de arquivos baseado no OpenACS, que ativado atravs da interface com o xinha. O seletor de arquivos est usando um plugin recentemente desenvolvido para o xinha. Ele possui dois modos: 'arquivo' ou 'imagem'. No modo imagem, somente arquivos tipo imagem podem ser escolhidos (mime content type image/*); no modo arquivo qualquer tipo pode ser selecionado, ou arquivos de um certo tipo tambm. Para mais detalhes veja a API template::widget::richtext. O XoWiki utiliza um seletor de arquivos no modo imagem para inserir imagens, o no modo arquivo para gerar links internos no sistema de arquivos. No futuro deve ser possvel gerar mais segurana desativando do usurio 92 Autor: Eduardo Santos
comum todo o acesso a URL's, de modo que somente URL's seguras possam ser inseridas.
11.9.Configuraes
O XoWiki suporta (desde a verso 0.30) uma configurao em dois nveis de suas instncias:
Parmetros do pacote (como para todos os pacotes do OpenACS) O objeto pasta (detalhes depois)
Os parmetros do pacote so utilizados para parmetros padro e configuraes simples. Para configuraes avanadas ou para gerar valores multi-line, o objeto pasta utilizado. Alm disso o objeto pasta permite a valores computados, obtidos via herana, ler arquivos e outros. De um lado os valores do objeto pasta so mais poderosos do que a configurao via parmetros do pacote, mas por outro, requerem um conhecimento bsico de programao. Em geral os valores do objeto pasta tm uma prioridade maior que os valores nos parmetros do pacote. Os seguintes parmetros do pacote esto disponveis:
Parmetros gerais
use_gc: Usa o pacote general comments. use_tags: permite ao usurio inserir marcaes del.icio.us s pginas. use_user_tracking: Monitora a visualizao de pginas por usurio. use_notifications: Permite ao usurio registrar notificaes. top_portlet: Especifica um portlet do XoWiki (definido em ::xowiki::portlet::*) a ser includo na parte de cima de cada uma das pginas. Para ativar uma lista dos usurios ativos atualmente na sua instncia, por exemplo, ajuste o valor da parmetro para 'presence -interval "10 minutes"'. Os parmetros vlidos so definidos pelos portlets. template_file: Nome do arquivo adp a ser utilizado para visualizar as pginas do XoWiki. Para utilizar uma rvore de categorias esquerda pgina utilize o arquivo oacs-view. show_per_object_categories: Se ativado mostra numa pgina as categorias atribudas ao objeto. security_policy: Define as operaes vlidas para diferentes tipos de usurios. Atualmente duas polticas so definidas: ::xowiki::policy1 e Autor: Eduardo Santos
93
::xowiki::policy2. Policy1 requer que todas as operaes destrutivas (deletes, delete_revision) e operaes de programao (que envolvem cdigo TCL, como editar o ::xotcl::Objects) tenham privilgios de administrao do pacote. Policy2 requer tambm direitos de administrao geral do site para operaes destrutivas.
production_mode: Quando o parmetro est ajustado, edio criao de pginas so criadas no estado de produo, onde no esto visveis aos usurios. As pginas devem ser lanadas atraes das pginas de administrao.
subst_blank_in_name: Normaliza os nomes das pginas no estilo MediaWiki. De maneira geral espaos so transformados em vazios. package_prefix: Parte da URL utilizada antes da nome do idioma e do nome da pgina, quando uma URL computada. Quando uma instncia padro do XoWiki utilizada como uma pgina inicial do OpenACS, por exemplo, o package_prefix pode ser definido como / use_connection_locale: Quando a flag definida, o locale da conexo (dependendo do ajuste do browser) utilizado para determinar o idioma padro no qual a pgina apresentada, sempre que possvel. Usurios com locales diferentes vero diferentes contedos na mesma URL. A flag desligada por padro e o locale do pacote ou do sistema usado como padro.
index_page: nome da pgina a ser mostrada quando a instncia do pacote requisitada. weblog_page: noma da pgina para mostrar o weblog (quando clicar numa marcao del.icio.us)
Formatao da URL O XoWiki possui muitos recursos que controlam como os links so apresentados ao usurios. As URL's computadas depende de dois fatores: o package_prefix e o locale. Package_prefix Cada URL gerada contm o nome sob o qual o XoWiki foi montado no site-map por padro. Em certas situaes um administrador pode querer utilizar uma instncia do XoWiki tambm para pginas de alto nvel. Para conseguir realiz-lo, o parmetro package_prefix pode ser ajustado para / e um arquivo de redirecionamento pode ser providenciado. 94 Autor: Eduardo Santos
O redirecionamento pode ser alcanado atravs de um arquivo index.vuh. Um usurio pode colocar o arquivo sob o nome index.vuh no ../$YOUR_SERVICE_NAME/www/index.vuh para redirecionar requisies de alto nvel para as instncias do XoWiki especificadas. Note que ainda possvel utilizar por exemplo http://.../forums e outras entradas do site-map. O arquivo index.vuh s utilizado nos casos em que o caminho especfico no pde ser resolvido.
::xowiki::Package initialize -ad_doc { The script uses an XoWiki page as root page of the site. Here, the start page is /xowiki/ followed by the actual URL, as specified as the value after -url below. Replace this value, in case a different XoWiki instance name should be used. @author Gustaf Neumann (gustaf.neumann@wu-wien.ac.at) @creation-date July, 2006 @cvs-id $Id: index.vuh,v 1.5 2006/09/15 16:45:00 gustafn Exp $ } -parameter { {-m view} {-folder_id:integer 0} } -url /xowiki[ns_conn url] ::$package_id reply_to_user [::$package_id invoke -method $m] ad_script_abort
Locale O XoWiki permite duas aproximaes sobre como lidar com mltiplos idiomas no caso em que o idioma da pgina no tenha sido especificado. O comportamento padro utilizar o locale do sistema para resolver o idioma (ou mais precisamente, primeiro o locale especificado para o pacote. Se no for especificado, utiliza o do site).
locale do sistema: en_US locale da consexo: de_DE (ajuste do browser do usurio) url: xowiki/page resolvido como: /xowiki/en/page
Se o parmetro use_connection_locale do pacote estiver definido como 0 por um administrador, o comportamento se altera e o usurio pode ver um contedo diferente.
locale do sistema: en_US locale da conexo: de_DE (ajuste do browser do usurio) Autor: Eduardo Santos
95
Note que os dois usurios podem ver sob a mesa URL diferentes contedos, dependendo dos ajustes de seu navegador. Quando as referncias de uma pgina sem cdigos de idioma especficos so utilizadas, o idioma da pgina que contm o link utilizado como padro para ele. O XoWiki sempre tenta minimizar os links apresentados. O Objeto Pasta A partir da verso 0.20, o XoWiki cria um objeto por pasta como padro, atravs da qual a instncia pode ser configurada em detalhes. Todos os parmetros de pacote mencionados podem ser fornecidos como variveis TCL no objeto pasta. O objeto pasta um ::xowiki::Object, sendo nomeado depois como o folder_id precedido por ::. No possvel alterar o nome do objeto. Uma vez que pode conter cdigo executvel, permisses de administrador so necessrias para edit-lo. Para definir a index_page (pgina a ser mostrada quando o diretrio do pacote, como /xowiki, visitado) o objeto pasta pode ser editado e o cdigo TCL apropriado pode ser inserido.
set index_page de:2cols
O exemplo a seguir define a pgina ndice como de:2cols. Ela ser usada como index se existir. Podemos definir de:2cols criando por exemplo uma nova ::xowiki::Page com o contedo a seguir para apresentar uma disposio de duas colunas baseada em categorias. A coluna da esquerda mostra pginas de uma rvore com nome *toc* (uma table of contents), enquanto a da direita mostra pginas categorizadas por algum Purpose.
This is a repository with many nice examples of XoWiki pages. >>left-col<< {{adp portlets/categories {name {Table of Contents} tree_name *toc*}}} >><< >>right-col<< {{adp portlets/categories {name {Table of Contents} tree_name Purpose}}} >><<
96
12.Referncias
Todo o material utilizado para a confeco desta apostila baseado em livros pblicos encontrados na Internet e no manual oacs-5-2-0-draft disponvel no site da xarg. Assim como o material que a compe, a apostila de livre reproduo eletrnica, desde que respeitados os nomes de seus autores. Segue lista de links utilizados como fonte para criao da apostila: http://xarg.net/download/oacs-5.2.0-draft.pdf http://media.wu-wien.ac.at/download/xowiki-doc/index.html http://aolserver.com/docs/admin/config-reference.tcl.txt http://acspropel.com/acspropel/syllabus http://www.openacs.org/doc/openacs-5-2/ http://www.dotlrn.org/ http://www.cognovis.de/developer/en/aolserver_install
97