From 013f15768322aca4db7524537cd9a1d107ee25c6 Mon Sep 17 00:00:00 2001 From: Antonio Terceiro Date: Mon, 1 Feb 2010 12:09:49 -0300 Subject: [PATCH] Reorganizing documentation --- HACKING | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ INSTALL | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ RELEASING | 39 +++++++++++++++++++++++++++++++++++++++ doc/README_FOR_APP | 175 +++---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- doc/README_FOR_APP.pt_BR | 351 --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- doc/overview.pt_BR | 351 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ script/sample-data | 2 ++ 7 files changed, 536 insertions(+), 523 deletions(-) create mode 100644 HACKING create mode 100644 INSTALL create mode 100644 RELEASING delete mode 100644 doc/README_FOR_APP.pt_BR create mode 100644 doc/overview.pt_BR diff --git a/HACKING b/HACKING new file mode 100644 index 0000000..f90bd71 --- /dev/null +++ b/HACKING @@ -0,0 +1,51 @@ += Noosfero instructions for developers + +This document provides useful information to those who want to help with +Noosfero development. + +== Requirements for development + +* Mocha: http://mocha.rubyforge.org/ +* Tidy: http://tidy.sourceforge.net/ +* Hpricot: http://github.com/whymirror/hpricot +* Imagemagick: http://wwwimagemagick.org/ + +You must install these packages to be able to run Noosfero tests. On Debian +GNU/Linux you install them with the following command: + + apt-get install libtidy-ruby libhpricot-ruby libmocha-ruby imagemagick + +== Boostraping a development/test environment + +You can copy and paste the commands below into a terminal (please review the +commands and make sure you understand what you are doing): + + # checkout the code from repository + git clone git://git.colivre.coop.br/noosfero.git + # enter the directory + cd noosfero + # copy a sample config file + cp config/database.yml.sqlite3 config/database.yml + # create the database: + rake db:migrate + # compile translations: + rake makemo + # create some test data: + ./script/sample-data + # run the automated test suite to make sure your environment is sane: + rake test + +You should now be ready to go. Issue the following command to start the Rails +development server: + + ./script/server + +The server will be available at http://localhost:3000/ . If you want to use +another port than 3000, you can use the -p option of ./script/server: + + ./script/server -p 9999 + +The above command makes the server available at http://localhost:9999/ + +The sample-data data scripts creates one administrator user with login "ze" and +password "test". diff --git a/INSTALL b/INSTALL new file mode 100644 index 0000000..bb0e9c5 --- /dev/null +++ b/INSTALL @@ -0,0 +1,90 @@ += Noosfero installation instructions + +Noosfero is written in Ruby with the "Rails framework":http://www.rubyonrails.org, +so the process of setting it up is pretty similar to other Rails applications. + +Below we have the instructions for installing Noosfero dependencies and setting +up a production environment. If you have problems with the setup, please feel +free to ask questions in the development mailing list. + +== Requirements + +* Ruby: http://www.ruby-lang.org/ +* Rake: http://rake.rubyforge.org/ +* Ruby-GetText: http://www.yotabanana.com/hiki/ruby-gettext.html?ruby-gettext (at least version 1.9.0) +* Ruby-sqlite3: http://rubyforge.org/projects/sqlite-ruby +* rcov: http://eigenclass.org/hiki/rcov +* Ferret: http://ferret.davebalmain.com/trac +* RMagick: http://rmagick.rubyforge.org/ +* RedCloth: http://whytheluckystiff.net/ruby/redcloth/ +* will_paginate: http://github.com/mislav/will_paginate/wikis +* iso-codes: http://pkg-isocodes.alioth.debian.org/ +* feedparser: http://packages.debian.org/sid/libfeedparser-ruby +* Daemons - http://daemons.rubyforge.org/ +* Mongrel: http://mongrel.rubyforge.org/ +* tango-icon-theme: http://tango.freedesktop.org/Tango_Icon_Library + +On Debian GNU/Linux, all of these packages are available through the Debian +archive. You can install them with the following command: + + # aptitude install ruby rake libgettext-ruby1.8 libsqlite3-ruby rcov librmagick-ruby libredcloth-ruby libwill-paginate-ruby iso-codes libfeedparser-ruby libferret-ruby libdaemons-ruby mongrel mongrel-cluster tango-icon-theme + +We do not have specific instructions for other plaforms yet. If you manage to +install Noosfero successfully, please feel free to contact the Noosfero +development mailing with the instructions for doing so, and we'll include it +here. + +=== Setting up a production environment + +* install memcached. Study whether you need to raise the ammount of memory it uses for caching, depending on the demand you expect for your site. +* copy config/ferret_server.yml.dist to config/ferret_server.yml.dist +* configure the mongrel cluster: `mongrel_rails cluster::configure` +** then edit config/mongrel_cluster.yml to suit your environment. Make sure your apache configuration matches the mongrel cluster configuration, specially in respect to the ports and numbers of mongrel instances. +* create needed temporary directories: + mkdir tmp + mkdir tmp/pids + mkdir log +* create database (example using PostgreSQL, YMMV) + + root user + ========= + # sudo apt-get install postgresql libpgsql-ruby + # su - postgres + + postgres user + ============= + postgres@HOST:~$ createuser noosfero + Shall the new role be a superuser? (y/n) n + Shall the new role be allowed to create databases? (y/n) y + Shall the new role be allowed to create more new roles? (y/n) n + + noosfero_user + ============= + createdb noosfero_production + createdb noosfero_development + createdb noosfero_test + +* configure database access in config/database.yml + +* test database access: +** first create the development database + rake db:schema:load +** if everything goes right, then create the production database: + RAILS_ENV=production rake db:schema:load + +* create sample data: + RAILS_ENV=production rake db:populate + +* compile the translations: + rake makemo + +* start the server: + ./script/production start + +* to stop the server: + + ./script/production stop + +* to restart the server: + + ./script/production restart diff --git a/RELEASING b/RELEASING new file mode 100644 index 0000000..052de4d --- /dev/null +++ b/RELEASING @@ -0,0 +1,39 @@ += Noosfero release tasks + +This file documents release-related activities. + +== Working with translations + +* Update translation files: rake updatepo. Then git commit them. +* Send the PO files to the translators. +* Get the PO files back from translators, put in po/ under the correct language + name (e.,g. po/pt_BR/) and git commit. +* test translations: rake makemo and browse the application on the web. + +== Releasing noosfero + +To prepare a release of noosfero, you must follow the steps below: + +* finish all requirements and bugs assigned to the to-be-released version +* make sure all tests pass +* write release notes at the version's wiki topic. +* generate package with rake package. Your tarball will be under the pkg/ + directory, named as noosfero-${VERSION}.tar.gz +* test that the package contains everything that is needed: explode the tarball + in a temporary directory, copy config/database.yml.sqlite3 to + config/database.yml, and make rake db:migrate and rake test. If + everything is ok, you are done. If not, maybe some files are not going into + the tarball. See lib/tasks/package.rake, probably you'll need to change it. +* Go to the version's wiki topic and edit it to reflect the new reality. +* Attach the generated package to that topic. Before attaching calculate the md5 of the package (with mu5sum and paste the MD5 hash as comment in the attachment form) +* Download the attached and verify the MD5 hash +* create a git tag for the released version with git tag. +* IMMEDIATELY change the version in lib/noosfero.rb to the next version. (e.g. + 0.2.0 -> 0.3.0) +* update an eventual demonstration version that you run. +* write an announcement e-mail to the relevant maimling lists pointing to the release notes, and maybe to the demonstration version. + +If you had any problem during these steps, you can do rake clobber_package to +completely delete the generated packages and start the process again. + + diff --git a/doc/README_FOR_APP b/doc/README_FOR_APP index d34679a..a15e0c6 100644 --- a/doc/README_FOR_APP +++ b/doc/README_FOR_APP @@ -1,175 +1,6 @@ = Noosfero: a free web-based social platform -== Setting up a Noosfero development/test environment +* Installation instructions: see INSTALL +* Developer instructions: see HACKING +* Licensing information: see COPYRIGHT and COPYING -Noosfero is written in Ruby with the "Rails framework":http://www.rubyonrails.org, -so the process of setting it up is pretty similar to other Rails applications. - -=== Requirements - -noosfero is intended to be run in Debian stable. It can work in other environments, but we do not test on them. - -You need to have git installed, as well as: - -* Ruby: http://www.ruby-lang.org/ -* Rake: http://rake.rubyforge.org/ -* Ruby-GetText: http://www.yotabanana.com/hiki/ruby-gettext.html?ruby-gettext (at least version 1.9.0) -* Ruby-sqlite3: http://rubyforge.org/projects/sqlite-ruby -* rcov: http://eigenclass.org/hiki/rcov -* Ferret: http://ferret.davebalmain.com/trac -* RMagick: http://rmagick.rubyforge.org/ -* RedCloth: http://whytheluckystiff.net/ruby/redcloth/ -* will_paginate: http://github.com/mislav/will_paginate/wikis -* contacts: http://github.com/cardmagic/contacts/tree/master -* iso-codes: http://pkg-isocodes.alioth.debian.org/ -* feedparser: http://packages.debian.org/sid/libfeedparser-ruby -* Daemons - http://daemons.rubyforge.org/ -* Mongrel: http://mongrel.rubyforge.org/ -* tango-icon-theme: http://tango.freedesktop.org/Tango_Icon_Library - -There are Debian packages available for all of them but contacts. Try: - - # aptitude install ruby rake libgettext-ruby1.8 libsqlite3-ruby rcov librmagick-ruby libredcloth-ruby libwill-paginate-ruby iso-codes libfeedparser-ruby libferret-ruby libdaemons-ruby mongrel mongrel-cluster tango-icon-theme - -contacts is bundled together with noosfero for now, so you don't need to install it. - -If you have problems with the setup, use the development mailing list. In -special its possible that the requirements list above is not complete. - -=== Setting up a production environment - -* install memcached. Study whether you need to raise the ammount of memory it uses for caching, depending on the demand you expect for your site. -* copy config/ferret_server.yml.dist to config/ferret_server.yml.dist -* configure the mongrel cluster: `mongrel_rails cluster::configure` -** then edit config/mongrel_cluster.yml to suit your environment. Make sure your apache configuration matches the mongrel cluster configuration, specially in respect to the ports and numbers of mongrel instances. -* create needed temporary directories: - mkdir tmp - mkdir tmp/pids - mkdir log -* create database (example using PostgreSQL, YMMV) - - root user - ========= - # sudo apt-get install postgresql libpgsql-ruby - # su - postgres - - postgres user - ============= - postgres@HOST:~$ createuser noosfero - Shall the new role be a superuser? (y/n) n - Shall the new role be allowed to create databases? (y/n) y - Shall the new role be allowed to create more new roles? (y/n) n - - noosfero_user - ============= - createdb noosfero_production - createdb noosfero_development - createdb noosfero_test - -* configure database access in config/database.yml - -* test database access: -** first create the development database - rake db:schema:load -** if everything goes right, then create the production database: - RAILS_ENV=production rake db:schema:load - -* create sample data: - RAILS_ENV=production rake db:populate - -* compile the translations: - rake makemo - -* start the server: - ./script/production start - -* to stop the server: - - ./script/production stop - -* to restart the server: - - ./script/production restart - -=== Boostraping a test environment - -You can copy and paste the commands below into a terminal (please review the -commands and make sure you understand what you are doing): - - # checkout the code from repository - git clone git://git.colivre.coop.br/noosfero.git - # enter the directory - cd noosfero - # copy a sample config file - cp config/database.yml.sqlite3 config/database.yml - # create the database: - rake db:migrate - # compile translations: - rake makemo - # create some test data: - ./script/populate - # install the test dependences: - aptitude install libtidy-ruby libhpricot-ruby libmocha-ruby imagemagick - # run the automated test suite to make sure your environment is sane: - rake test - -You should now be ready to go. Issue the following command to start the Rails -development server: - - ./script/server - -The server will be available at http://localhost:3000/ . If you want to use -another port than 3000, you can use the -p option of ./script/server: - - ./script/server -p 9999 - -The above command makes the server available at http://localhost:9999/ - -The populate script creates some test users, one of them has login 'ze' and -password 'test'. You can use it or you can register a new user. - -== Reporting bugs - -Use Noosfero Tracker application at http://www.colivre.coop.br/Noosfero. - -== Helping with development - -* It's recommended that you subscribe to the development mailing - list: http://ynternet.net/mailman/listinfo/noosfero -* If you have a patch, create an appropriate action item - (bugs/requirement/enhancement) in the Tracker web (see "Reporting bugs" - above) of type. - -== Releasing noosfero - -To prepare a release of noosfero, you must follow the steps below: - -* finish all requirements and bugs assigned to the to-be-released version -* make sure all tests pass -* write release notes at the version's wiki topic. -* generate package with rake package. Your tarball will be under the pkg/ - directory, named as noosfero-${VERSION}.tar.gz -* test that the package contains everything that is needed: explode the tarball - in a temporary directory, copy config/database.yml.sqlite3 to - config/database.yml, and make rake db:migrate and rake test. If - everything is ok, you are done. If not, maybe some files are not going into - the tarball. See lib/tasks/package.rake, probably you'll need to change it. -* Go to the version's wiki topic and edit it to reflect the new reality. -* Attach the generated package to that topic. Before attaching calculate the md5 of the package (with mu5sum and paste the MD5 hash as comment in the attachment form) -* Download the attached and verify the MD5 hash -* create a git tag for the released version with git tag. -* IMMEDIATELY change the version in lib/noosfero.rb to the next version. (e.g. - 0.2.0 -> 0.3.0) -* update an eventual demonstration version that you run. -* write an announcement e-mail to the relevant maimling lists pointing to the release notes, and maybe to the demonstration version. - -If you had any problem during these steps, you can do rake clobber_package to -completely delete the generated packages and start the process again. - -== Working with translations - -* Update translation files: rake updatepo. Then git commit them. -* Send the PO files to the translators. -* Get the PO files back from translators, put in po/ under the correct language - name (e.,g. po/pt_BR/) and git commit. -* test translations: rake makemo and browse the application on the web. diff --git a/doc/README_FOR_APP.pt_BR b/doc/README_FOR_APP.pt_BR deleted file mode 100644 index c5e1f16..0000000 --- a/doc/README_FOR_APP.pt_BR +++ /dev/null @@ -1,351 +0,0 @@ -= Menu - -* MVC -* Como criar um Article? -* Como criar um Block? -* Como criar uma Task? -* Visão Geral do Banco de Dados - -= MVC - -A sigla MVC vem de Modelo, Visão e Controle. Esta arquitetura sugere uma separação do código em três camadas distintas, com papéis bem definidos. - -A Visão é a camada que interage diretamente com o usuário, recebendo e disponibilizando os dados da aplicação. A camada de Visão tem o objetivo de apresentar o resultado do processamento da camada de Controle, formatada para ser usável pelo usuário, consituindo a parte visível do sistema. - -A camada de Controle é a responsável por processar todas as requisições feitas pelo usuário através da interface (Visão). Esta camada interpreta as ações do usuário e gerencia a execução das regras de negócios pelo Modelo. - -O modelo refere-se ao gerenciamento da informação e ao comportamento da aplicação. Em uma visão simplificada, a camada de modelo funciona como uma representação das entidades de domínio e suas regras de negócio. Possui a função de validar os dados vindos da interface do usuário com os dados da aplicação. - -= Como criar um Article? - -Um artigo é um tipo de conteúdo que um usuário pode criar e gerenciar através do botão "gerenciar conteúdo" no seu painel de controle. Ele também é listado no bloco "conteúdo recente" e em alguns outros lugares como no resultado das buscas por exemplo. Os artigos podem ser de vários tipos, artigos que usam marcação de texto textile é um tipo de artigo, artigos com edição visual WYSIWYG é um outro tipo, artigos também podem ser arquivos enviados pelo usuário ou um simplesmente um feed RSS. - -Cada um desses tipos de artigo são subclasses de Article que implementam métodos para editá-lo e exibi-lo. Os métodos que tem que ser sobrescritos são: to_html (para converter o conteudo em html), decription e short_decription (para indicar o que o artigo é para um usuário). Para cada Model que representa um tipo especifico de Article deve existir também um partial rhtml na pasta de views do controller cms em app/views/cms com o nome do tipo de artigo que é a interface de edição do artigo. - -Então basicamente o layout de um novo tipo de artigo ficaria assim: - -class NovoTipo < Article - def description - _('Este é um novo tipo de artigo') - end - def short_description - _('Novo tipo de artigo') - end - def to_html - #Algum código para gerar o html a partir de outras informações armazenadas - end -end - -Por padrão já existem alguns atributos que podem ser usados na geração do html para o artigo. - -* body - corpo do artigo -* name - nome do artigo -* created_at - quando o artigo foi criado -* updated_at - quando foi alterado pela última vez - -Caso seja necessário armazenar alguma informação além destas pode-se adicionar campos personalizados com o método setting_items. - -Para criar por exemplo um artigo que mostre um texto com uma lista de referêcias em separado pode-se adicionar um campo de texto usando settings_items para armazenar as referências. - -app/model/texto_com_referencia.rb - -class TextoComReferencia < Article - def description - _('Este é uma artigo com referências em separado.') - end - def short_description - _('Artigo com referêcias') - end - settings_items :referencias, :type => 'text' - def to_html - body + "
#{referencias}
" - end -end - -Então o html gerado iria adicionar ao fim do artigo as referêcias dentro de um div. - -Para a edição do nosso artigo criamos o partial em app/views/cms/_texto_com_referencia.rhtml contendo: - -<%= f.text_field('name') %> -<%= f.text_area('body') %> -<%= f.text_area('referencias') %> - -Que gera uma formulário html para que o usuário do artigo digite o nome do artigo, o texto principal e as referências - -= Como criar um Block? - -Um block no Noosfero é uma caixa de conteúdo que pode ser escolhida para ser mostrada na página de um usuário/comunidade/empreendimento. Existem blocks para várias funcionalidades distintas como listar links favoritos, listar amigos, mostrar informações do usuário entre outros. - -Um novo block é um model que herda da classe Block e tem que implementar os seguintes métodos: - -* description - retorna uma string que é a descrição do bloco (este é um método de classe) -* short_description - retorna uma string que é uma descrição curta do bloco (esse é um método de classe) -* default_title - é o título padrão do bloco que pode ser mudado pelo usuário depois -* help - um texto de ajuda que aparece quando o usuário entra no modo ajuda e passa o mouse por cima do bloco -* content - retorna o conteúdo a ser exibido dentro do bloco - -O método content pode retornar uma de duas coisas: uma string com o conteúdo que deve ser exibido ou uma função lambda com código que deve ser executado no contexto da requisição. A função lambda é útil para o caso de se querer utilizar um arquivo rhtml para gerar o html em vez de colocar tudo em uma string. - -Se queremos, por exemplo, criar um bloco que mostra apenas as amigas de um usuário podemos usar o seguinte: - -class Amigas < Block - def self.description - _('Um bloco que mostra o nome de suas amigas') - end - def self.short_description - _('Bloco de amigas') - end - def default_title - _('Minhas amigas') - end - def help - _('Um bloco que mostra minhas amigas') - end - def content - ' - end -end - -Depois disso é só adicionar o bloco na lista de blocos disponíveis aos usuários no controller app/controller/my_profile/profile_design_controller.rb. Se o bloco é para ser usado somente para usuários ou somente para comunidades deve ser adicionado em sua própria seção. - -= Como criar uma Task? - -Uma Task é um elemento do Noosfero utilizado para gerenciar tarefas pendentes. Essas tarefas são mostradas no painel de controle do usuário/comunidade/empreendimento que deve resolvê-la. Cada tarefa pode estar em 3 estados diferentes: pendente, resolvida ou cancelada. - -A classe Task provê a infra-estrutura básica para todas as tasks do sistema, o Noosfero hoje possui tasks para as seguintes funções: adicionar amigo, entrar em comunidade moderada, alteração de senha, entre outras. Esta classe contém relacionamento com Person e Profile da seguinte forma: - _________ ______ ________ - | | | | | | - | Profile |1--------*| Task |*---------1| Person | - |_________| |______| |________| - -A classe base Task possui toda a lógica necessária para a existencia de tasks como o estado da tarefa, métodos para criação e finalização, envio de notificação, envio de email caso necessário, entre outras funções. Então o que resta para as classes derivadas é implementar o método perform que fará o trabalho propriamente dito, e adicionar campos personalizados caso necessário. - -A task AddFriend por exemplo, que é uma task criada quando alguem requisita a amizade de outra pessoa, executa os seguintes passos no método perform ao ser finalizada. - -* Adiciona requisitante como amigo do requisitado e; -* Adiciona requisitado como amigo do requitante - -Para que o ciclo de criação, aceitação e finalização de uma task esteja completo é necessário implementar os controllers e as views. Para o AddFriend por exemplo temos o controller friends_controller que contém a lógica de criação da task. Para processamento desta e de todas as outras tasks temos o controller tasks_controller que contém a lógica necessária para finalizar uma task. Em views/tasks/ temos diversas views necessárias para a finalização de tasks, algumas tasks não necessitam campos especificos na sua finalização então usam a view _task.rhtml para a task AddFriend por exemplo temos o campo groups_for_friend usado para classificar um amigo no momento da aceitção da task. - -No exemplo de código abaixo vamos criar uma Task AddFriend onde o Person joão requisita amizade do Person josé: - -* joao = Person['joao'] -* jose = Person['jose'] -* AddFriend.create(:person => joao, :friend => jose) - -José receberá uma requisição para ser amigo de joão, se ele aceitar a requisição o método perform será executado e o relacionamento de amizade entre eles será criado. - -Vamos exemplificar como criar uma nova Task que simplesmente envia uma requisição para alguém e ao ser finalizada cria um artigo para quem aceitou a requisição. - -Vamos chamar esta task de SendArticle, para isto crie o arquivo app/models/send_article.rb com o seguinte conteudo: - -class SendArticle < Task - validates_presence_of :requestor_id, :target_id - acts_as_having_settings :name, :body, :field => :data - def perform - target.articles << TextileArticle.new(:name => name, :body => body) - end - def description - _('%s enviou um artigo para você') % requestor.name - end -end - -Esta é a infra-estrutura para nossa nova task, uma classe que herda de Task e implementa pelo menos o método perform. Este task possui 2 campos personalizados que serão utilizados para armazenar o nome e o corpo do artigo a ser criado. - -Para que seja possivel um usuario qualquer do sistema possa criar uma task dessa temos que implementar a lógica no controller e adicionar um botão na interface ou outro controle qualquer que possibilite o usuario criar, para isto vamos criar um controller. - -app/controllers/public/send_article_controller.rb - -class SendArticleController < MyProfileController - def new - @person = Person.find(params[:target_id]) - @article = TextileArticle.new - if request.post? && params[:confirmation] - SendArticle.create!(:requestor_id => user.id, :target_id => @person.id) - flash[:notice] = _('%s receberá solicitação de criação deste artigo.') % @person.name - redirect_to :back - end - end -end - -Cria uma view com o form para que o usuario possa preencher o nome e o corpo do artigo a ser enviado ao criar a task. - -app/views/send_article.rhtml - -

<%= _('Sending article to %s') % @person.name %>

-<% labelled_form_for 'article', @article, :html => { :multipart => true } do |f| %> - <%= hidden_field_tag(:confirmation, 1) %> - <%= hidden_field_tag(:target_id, @person.id) %> - <%= render :partial => 'cms/textile_article', :locals => { :f => f } %> - <% button_bar do %> - <%= submit_button :save, _('Send') %> - <%= button(:cancel, _("Cancel"), :controller => 'profile', :profile => profile.identifier) %> - <% end %> -<% end %> - -Falta apenas adicionar um controle na interface para o usuário acionar este ação, vamos adicionar um botão junto aos botões de acão como adicionar amigo, entrar em comunidade, etc. em app/views/blocks/profile_info_actions/person.rhtml adicione o código abaixo. - -
  • <%= link_to content_tag('span', _('Send article')), {:profile => user.identifier, :controller => 'send_article', :action => 'new', :target_id => profile.id}, :class => 'button with-text icon-menu-mail' %>
    • - -= Visão Geral do Banco de Dados - -O Noosfero é composto por 27 tabelas, listadas abaixo: - - +--------------------------------+ - | Tables_in_noosfero_development | - +--------------------------------+ - | article_versions | - | articles | - | articles_categories | - | blocks | - | boxes | - | categories | - | categories_profiles | - | comments | - | consumptions | - | domains | - | environments | - | favorite_enteprises_people | - | friendships | - | images | - | product_categorizations | - | products | - | profiles | - | region_validators | - | role_assignments | - | roles | - | schema_info | - | taggings | - | tags | - | tasks | - | thumbnails | - | users | - | validation_infos | - +--------------------------------+ - 27 rows in set (0.00 sec) - -A seguir, faremos um relato sobre o papel de cada tabela no funcionamento do sistema: - -== article_versions - -Os artigos posssuem controle de versão e cada versão é guardada nessa tabela. - -== articles - -Artigos são todo tipo de conteúdo que pode ser criado pelo usuário. Como textos, imagens e até mesmo pastas. - -== articles_categories - -Os artigos são classificados por categorias. Esta tabela guarda as associações entre artigos e categorias. - -== blocks - -Guarda as informações relativas aos blocos, que são apresentados em boxes na página do usuário. - -== boxes - -Representa as áreas onde os usuários podem anexar seus blocos. - -== categories - -São categorias do sistema, que incluem categorias de produto e regiões. - -== categories_profiles - -Esta tabela guarda a associação entre categories e profiles. - -== comments - -Esta tabela guarda os comentários feitos nos artigos. - -== consumptions - -Representa os tipos de produtos que o usuário consome. - -== domains - -Cada ambiente pode ter um ou mais domínios, nesta tabela está armazenado o domínio do ambiente. - -== environments - -Representa cada uma das redes sociais (ou ambiente) geridas pelo Noosfero. - -== favorite_enteprises_people - -Representa os empreendimentos favoritos de um usuário. - -== friendships - -Esta tabela apresenta todos as relações de amizade. - -== images - -Guarda as informações sobre todas as imagens armazendas no sistema. - -== product_categorizations - -Representa a associação entre produtos e categorias. - -== products - -Esta tabela guarda todos os produtos dos empreendimentos do sistema. - -== profiles - -É a entidade mais importante do sistema. Representa tanto pessoas, quanto comunidades, empreeendimentos e organizações. - -== region_validators - -Relaciona as organizações validadoras com a região em que ela opera. - -== role_assignments - -Associa um papel a um usuário, dando a ele permissões sobre um determinado recurso do sistema. - -== roles - -Apresenta todos os papéis que podem ser atribuídas aos usuários e agrega quais permissões um usuário com esse papel terá. - -== schema_info - -Guarda o número da migration no Rails. - -== taggings - -Associa uma tag a um artigo. - -== tags - -Esta tabela armazena uma tag que pode ser associada a artigos. - -== tasks - -Representa uma tarefa que pode ser atribuída a um usuário, comunidade ou empreendimento. - -== thumbnails - -Guarda informações sobre miniaturas de imagens. - -== users - -Esta tabela guarda informações de login de todos os usuários do sistema. - -== validation_infos - -Guarda a metodologia de validação de uma entidade validadora. - -== Abaixo segue modelagem do Noosfero - -link:../noosfero_tabelas_article.png - -link:../noosfero_tabelas_category.png - -link:../noosfero_tabelas_profile.png - -link:../noosfero_tabelas_environment.png - -link:../noosfero_tabelas_schema.png diff --git a/doc/overview.pt_BR b/doc/overview.pt_BR new file mode 100644 index 0000000..c5e1f16 --- /dev/null +++ b/doc/overview.pt_BR @@ -0,0 +1,351 @@ += Menu + +* MVC +* Como criar um Article? +* Como criar um Block? +* Como criar uma Task? +* Visão Geral do Banco de Dados + += MVC + +A sigla MVC vem de Modelo, Visão e Controle. Esta arquitetura sugere uma separação do código em três camadas distintas, com papéis bem definidos. + +A Visão é a camada que interage diretamente com o usuário, recebendo e disponibilizando os dados da aplicação. A camada de Visão tem o objetivo de apresentar o resultado do processamento da camada de Controle, formatada para ser usável pelo usuário, consituindo a parte visível do sistema. + +A camada de Controle é a responsável por processar todas as requisições feitas pelo usuário através da interface (Visão). Esta camada interpreta as ações do usuário e gerencia a execução das regras de negócios pelo Modelo. + +O modelo refere-se ao gerenciamento da informação e ao comportamento da aplicação. Em uma visão simplificada, a camada de modelo funciona como uma representação das entidades de domínio e suas regras de negócio. Possui a função de validar os dados vindos da interface do usuário com os dados da aplicação. + += Como criar um Article? + +Um artigo é um tipo de conteúdo que um usuário pode criar e gerenciar através do botão "gerenciar conteúdo" no seu painel de controle. Ele também é listado no bloco "conteúdo recente" e em alguns outros lugares como no resultado das buscas por exemplo. Os artigos podem ser de vários tipos, artigos que usam marcação de texto textile é um tipo de artigo, artigos com edição visual WYSIWYG é um outro tipo, artigos também podem ser arquivos enviados pelo usuário ou um simplesmente um feed RSS. + +Cada um desses tipos de artigo são subclasses de Article que implementam métodos para editá-lo e exibi-lo. Os métodos que tem que ser sobrescritos são: to_html (para converter o conteudo em html), decription e short_decription (para indicar o que o artigo é para um usuário). Para cada Model que representa um tipo especifico de Article deve existir também um partial rhtml na pasta de views do controller cms em app/views/cms com o nome do tipo de artigo que é a interface de edição do artigo. + +Então basicamente o layout de um novo tipo de artigo ficaria assim: + +class NovoTipo < Article + def description + _('Este é um novo tipo de artigo') + end + def short_description + _('Novo tipo de artigo') + end + def to_html + #Algum código para gerar o html a partir de outras informações armazenadas + end +end + +Por padrão já existem alguns atributos que podem ser usados na geração do html para o artigo. + +* body - corpo do artigo +* name - nome do artigo +* created_at - quando o artigo foi criado +* updated_at - quando foi alterado pela última vez + +Caso seja necessário armazenar alguma informação além destas pode-se adicionar campos personalizados com o método setting_items. + +Para criar por exemplo um artigo que mostre um texto com uma lista de referêcias em separado pode-se adicionar um campo de texto usando settings_items para armazenar as referências. + +app/model/texto_com_referencia.rb + +class TextoComReferencia < Article + def description + _('Este é uma artigo com referências em separado.') + end + def short_description + _('Artigo com referêcias') + end + settings_items :referencias, :type => 'text' + def to_html + body + "
    #{referencias}
    " + end +end + +Então o html gerado iria adicionar ao fim do artigo as referêcias dentro de um div. + +Para a edição do nosso artigo criamos o partial em app/views/cms/_texto_com_referencia.rhtml contendo: + +<%= f.text_field('name') %> +<%= f.text_area('body') %> +<%= f.text_area('referencias') %> + +Que gera uma formulário html para que o usuário do artigo digite o nome do artigo, o texto principal e as referências + += Como criar um Block? + +Um block no Noosfero é uma caixa de conteúdo que pode ser escolhida para ser mostrada na página de um usuário/comunidade/empreendimento. Existem blocks para várias funcionalidades distintas como listar links favoritos, listar amigos, mostrar informações do usuário entre outros. + +Um novo block é um model que herda da classe Block e tem que implementar os seguintes métodos: + +* description - retorna uma string que é a descrição do bloco (este é um método de classe) +* short_description - retorna uma string que é uma descrição curta do bloco (esse é um método de classe) +* default_title - é o título padrão do bloco que pode ser mudado pelo usuário depois +* help - um texto de ajuda que aparece quando o usuário entra no modo ajuda e passa o mouse por cima do bloco +* content - retorna o conteúdo a ser exibido dentro do bloco + +O método content pode retornar uma de duas coisas: uma string com o conteúdo que deve ser exibido ou uma função lambda com código que deve ser executado no contexto da requisição. A função lambda é útil para o caso de se querer utilizar um arquivo rhtml para gerar o html em vez de colocar tudo em uma string. + +Se queremos, por exemplo, criar um bloco que mostra apenas as amigas de um usuário podemos usar o seguinte: + +class Amigas < Block + def self.description + _('Um bloco que mostra o nome de suas amigas') + end + def self.short_description + _('Bloco de amigas') + end + def default_title + _('Minhas amigas') + end + def help + _('Um bloco que mostra minhas amigas') + end + def content + ' + end +end + +Depois disso é só adicionar o bloco na lista de blocos disponíveis aos usuários no controller app/controller/my_profile/profile_design_controller.rb. Se o bloco é para ser usado somente para usuários ou somente para comunidades deve ser adicionado em sua própria seção. + += Como criar uma Task? + +Uma Task é um elemento do Noosfero utilizado para gerenciar tarefas pendentes. Essas tarefas são mostradas no painel de controle do usuário/comunidade/empreendimento que deve resolvê-la. Cada tarefa pode estar em 3 estados diferentes: pendente, resolvida ou cancelada. + +A classe Task provê a infra-estrutura básica para todas as tasks do sistema, o Noosfero hoje possui tasks para as seguintes funções: adicionar amigo, entrar em comunidade moderada, alteração de senha, entre outras. Esta classe contém relacionamento com Person e Profile da seguinte forma: + _________ ______ ________ + | | | | | | + | Profile |1--------*| Task |*---------1| Person | + |_________| |______| |________| + +A classe base Task possui toda a lógica necessária para a existencia de tasks como o estado da tarefa, métodos para criação e finalização, envio de notificação, envio de email caso necessário, entre outras funções. Então o que resta para as classes derivadas é implementar o método perform que fará o trabalho propriamente dito, e adicionar campos personalizados caso necessário. + +A task AddFriend por exemplo, que é uma task criada quando alguem requisita a amizade de outra pessoa, executa os seguintes passos no método perform ao ser finalizada. + +* Adiciona requisitante como amigo do requisitado e; +* Adiciona requisitado como amigo do requitante + +Para que o ciclo de criação, aceitação e finalização de uma task esteja completo é necessário implementar os controllers e as views. Para o AddFriend por exemplo temos o controller friends_controller que contém a lógica de criação da task. Para processamento desta e de todas as outras tasks temos o controller tasks_controller que contém a lógica necessária para finalizar uma task. Em views/tasks/ temos diversas views necessárias para a finalização de tasks, algumas tasks não necessitam campos especificos na sua finalização então usam a view _task.rhtml para a task AddFriend por exemplo temos o campo groups_for_friend usado para classificar um amigo no momento da aceitção da task. + +No exemplo de código abaixo vamos criar uma Task AddFriend onde o Person joão requisita amizade do Person josé: + +* joao = Person['joao'] +* jose = Person['jose'] +* AddFriend.create(:person => joao, :friend => jose) + +José receberá uma requisição para ser amigo de joão, se ele aceitar a requisição o método perform será executado e o relacionamento de amizade entre eles será criado. + +Vamos exemplificar como criar uma nova Task que simplesmente envia uma requisição para alguém e ao ser finalizada cria um artigo para quem aceitou a requisição. + +Vamos chamar esta task de SendArticle, para isto crie o arquivo app/models/send_article.rb com o seguinte conteudo: + +class SendArticle < Task + validates_presence_of :requestor_id, :target_id + acts_as_having_settings :name, :body, :field => :data + def perform + target.articles << TextileArticle.new(:name => name, :body => body) + end + def description + _('%s enviou um artigo para você') % requestor.name + end +end + +Esta é a infra-estrutura para nossa nova task, uma classe que herda de Task e implementa pelo menos o método perform. Este task possui 2 campos personalizados que serão utilizados para armazenar o nome e o corpo do artigo a ser criado. + +Para que seja possivel um usuario qualquer do sistema possa criar uma task dessa temos que implementar a lógica no controller e adicionar um botão na interface ou outro controle qualquer que possibilite o usuario criar, para isto vamos criar um controller. + +app/controllers/public/send_article_controller.rb + +class SendArticleController < MyProfileController + def new + @person = Person.find(params[:target_id]) + @article = TextileArticle.new + if request.post? && params[:confirmation] + SendArticle.create!(:requestor_id => user.id, :target_id => @person.id) + flash[:notice] = _('%s receberá solicitação de criação deste artigo.') % @person.name + redirect_to :back + end + end +end + +Cria uma view com o form para que o usuario possa preencher o nome e o corpo do artigo a ser enviado ao criar a task. + +app/views/send_article.rhtml + +

    <%= _('Sending article to %s') % @person.name %>

    +<% labelled_form_for 'article', @article, :html => { :multipart => true } do |f| %> + <%= hidden_field_tag(:confirmation, 1) %> + <%= hidden_field_tag(:target_id, @person.id) %> + <%= render :partial => 'cms/textile_article', :locals => { :f => f } %> + <% button_bar do %> + <%= submit_button :save, _('Send') %> + <%= button(:cancel, _("Cancel"), :controller => 'profile', :profile => profile.identifier) %> + <% end %> +<% end %> + +Falta apenas adicionar um controle na interface para o usuário acionar este ação, vamos adicionar um botão junto aos botões de acão como adicionar amigo, entrar em comunidade, etc. em app/views/blocks/profile_info_actions/person.rhtml adicione o código abaixo. + +
  • <%= link_to content_tag('span', _('Send article')), {:profile => user.identifier, :controller => 'send_article', :action => 'new', :target_id => profile.id}, :class => 'button with-text icon-menu-mail' %>
    • + += Visão Geral do Banco de Dados + +O Noosfero é composto por 27 tabelas, listadas abaixo: + + +--------------------------------+ + | Tables_in_noosfero_development | + +--------------------------------+ + | article_versions | + | articles | + | articles_categories | + | blocks | + | boxes | + | categories | + | categories_profiles | + | comments | + | consumptions | + | domains | + | environments | + | favorite_enteprises_people | + | friendships | + | images | + | product_categorizations | + | products | + | profiles | + | region_validators | + | role_assignments | + | roles | + | schema_info | + | taggings | + | tags | + | tasks | + | thumbnails | + | users | + | validation_infos | + +--------------------------------+ + 27 rows in set (0.00 sec) + +A seguir, faremos um relato sobre o papel de cada tabela no funcionamento do sistema: + +== article_versions + +Os artigos posssuem controle de versão e cada versão é guardada nessa tabela. + +== articles + +Artigos são todo tipo de conteúdo que pode ser criado pelo usuário. Como textos, imagens e até mesmo pastas. + +== articles_categories + +Os artigos são classificados por categorias. Esta tabela guarda as associações entre artigos e categorias. + +== blocks + +Guarda as informações relativas aos blocos, que são apresentados em boxes na página do usuário. + +== boxes + +Representa as áreas onde os usuários podem anexar seus blocos. + +== categories + +São categorias do sistema, que incluem categorias de produto e regiões. + +== categories_profiles + +Esta tabela guarda a associação entre categories e profiles. + +== comments + +Esta tabela guarda os comentários feitos nos artigos. + +== consumptions + +Representa os tipos de produtos que o usuário consome. + +== domains + +Cada ambiente pode ter um ou mais domínios, nesta tabela está armazenado o domínio do ambiente. + +== environments + +Representa cada uma das redes sociais (ou ambiente) geridas pelo Noosfero. + +== favorite_enteprises_people + +Representa os empreendimentos favoritos de um usuário. + +== friendships + +Esta tabela apresenta todos as relações de amizade. + +== images + +Guarda as informações sobre todas as imagens armazendas no sistema. + +== product_categorizations + +Representa a associação entre produtos e categorias. + +== products + +Esta tabela guarda todos os produtos dos empreendimentos do sistema. + +== profiles + +É a entidade mais importante do sistema. Representa tanto pessoas, quanto comunidades, empreeendimentos e organizações. + +== region_validators + +Relaciona as organizações validadoras com a região em que ela opera. + +== role_assignments + +Associa um papel a um usuário, dando a ele permissões sobre um determinado recurso do sistema. + +== roles + +Apresenta todos os papéis que podem ser atribuídas aos usuários e agrega quais permissões um usuário com esse papel terá. + +== schema_info + +Guarda o número da migration no Rails. + +== taggings + +Associa uma tag a um artigo. + +== tags + +Esta tabela armazena uma tag que pode ser associada a artigos. + +== tasks + +Representa uma tarefa que pode ser atribuída a um usuário, comunidade ou empreendimento. + +== thumbnails + +Guarda informações sobre miniaturas de imagens. + +== users + +Esta tabela guarda informações de login de todos os usuários do sistema. + +== validation_infos + +Guarda a metodologia de validação de uma entidade validadora. + +== Abaixo segue modelagem do Noosfero + +link:../noosfero_tabelas_article.png + +link:../noosfero_tabelas_category.png + +link:../noosfero_tabelas_profile.png + +link:../noosfero_tabelas_environment.png + +link:../noosfero_tabelas_schema.png diff --git a/script/sample-data b/script/sample-data index 04eff4c..fecb15b 100755 --- a/script/sample-data +++ b/script/sample-data @@ -1,6 +1,8 @@ #!/usr/bin/env ruby require File.dirname(__FILE__) + '/../config/environment' +system('rake db:populate') + people = [] NAMES = %w[ José João Antonio Paulo Maria Joana Paula Angela ] -- libgit2 0.21.2