Commit 6cc68ec3abdce3d518d67e16bc72992b0c673f0b

Authored by Antonio Terceiro
1 parent 99c04eeb

Removing useless documentation

doc/noosfero_tabelas_article.png

43.9 KB

doc/noosfero_tabelas_category.png

26.8 KB

doc/noosfero_tabelas_environment.png

13.7 KB

doc/noosfero_tabelas_profile.png

57.9 KB

doc/noosfero_tabelas_schema.png

2.28 KB

doc/overview.pt_BR
... ... @@ -1,351 +0,0 @@
1   -= Menu
2   -
3   -* MVC
4   -* Como criar um Article?
5   -* Como criar um Block?
6   -* Como criar uma Task?
7   -* Visão Geral do Banco de Dados
8   -
9   -= MVC
10   -
11   -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.
12   -
13   -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.
14   -
15   -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.
16   -
17   -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.
18   -
19   -= Como criar um Article?
20   -
21   -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.
22   -
23   -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.
24   -
25   -Então basicamente o layout de um novo tipo de artigo ficaria assim:
26   -
27   -class NovoTipo < Article
28   - def description
29   - _('Este é um novo tipo de artigo')
30   - end
31   - def short_description
32   - _('Novo tipo de artigo')
33   - end
34   - def to_html
35   - #Algum código para gerar o html a partir de outras informações armazenadas
36   - end
37   -end
38   -
39   -Por padrão já existem alguns atributos que podem ser usados na geração do html para o artigo.
40   -
41   -* body - corpo do artigo
42   -* name - nome do artigo
43   -* created_at - quando o artigo foi criado
44   -* updated_at - quando foi alterado pela última vez
45   -
46   -Caso seja necessário armazenar alguma informação além destas pode-se adicionar campos personalizados com o método setting_items.
47   -
48   -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.
49   -
50   -app/model/texto_com_referencia.rb
51   -
52   -class TextoComReferencia < Article
53   - def description
54   - _('Este é uma artigo com referências em separado.')
55   - end
56   - def short_description
57   - _('Artigo com referêcias')
58   - end
59   - settings_items :referencias, :type => 'text'
60   - def to_html
61   - body + "<div>#{referencias}</div>"
62   - end
63   -end
64   -
65   -Então o html gerado iria adicionar ao fim do artigo as referêcias dentro de um div.
66   -
67   -Para a edição do nosso artigo criamos o partial em app/views/cms/_texto_com_referencia.rhtml contendo:
68   -
69   -<%= f.text_field('name') %>
70   -<%= f.text_area('body') %>
71   -<%= f.text_area('referencias') %>
72   -
73   -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
74   -
75   -= Como criar um Block?
76   -
77   -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.
78   -
79   -Um novo block é um model que herda da classe Block e tem que implementar os seguintes métodos:
80   -
81   -* description - retorna uma string que é a descrição do bloco (este é um método de classe)
82   -* short_description - retorna uma string que é uma descrição curta do bloco (esse é um método de classe)
83   -* default_title - é o título padrão do bloco que pode ser mudado pelo usuário depois
84   -* help - um texto de ajuda que aparece quando o usuário entra no modo ajuda e passa o mouse por cima do bloco
85   -* content - retorna o conteúdo a ser exibido dentro do bloco
86   -
87   -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.
88   -
89   -Se queremos, por exemplo, criar um bloco que mostra apenas as amigas de um usuário podemos usar o seguinte:
90   -
91   -class Amigas < Block
92   - def self.description
93   - _('Um bloco que mostra o nome de suas amigas')
94   - end
95   - def self.short_description
96   - _('Bloco de amigas')
97   - end
98   - def default_title
99   - _('Minhas amigas')
100   - end
101   - def help
102   - _('Um bloco que mostra minhas amigas')
103   - end
104   - def content
105   - '<ul>' +
106   - owner.friends.select {|f|f.sex == 'female'}.map do |friend|
107   - '<li>' + friend.name + '</li>'
108   - end +
109   - </ul>
110   - end
111   -end
112   -
113   -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.
114   -
115   -= Como criar uma Task?
116   -
117   -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.
118   -
119   -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:
120   - _________ ______ ________
121   - | | | | | |
122   - | Profile |1--------*| Task |*---------1| Person |
123   - |_________| |______| |________|
124   -
125   -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.
126   -
127   -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.
128   -
129   -* Adiciona requisitante como amigo do requisitado e;
130   -* Adiciona requisitado como amigo do requitante
131   -
132   -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.
133   -
134   -No exemplo de código abaixo vamos criar uma Task AddFriend onde o Person joão requisita amizade do Person josé:
135   -
136   -* joao = Person['joao']
137   -* jose = Person['jose']
138   -* AddFriend.create(:person => joao, :friend => jose)
139   -
140   -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.
141   -
142   -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.
143   -
144   -Vamos chamar esta task de SendArticle, para isto crie o arquivo app/models/send_article.rb com o seguinte conteudo:
145   -
146   -class SendArticle < Task
147   - validates_presence_of :requestor_id, :target_id
148   - acts_as_having_settings :name, :body, :field => :data
149   - def perform
150   - target.articles << TextileArticle.new(:name => name, :body => body)
151   - end
152   - def description
153   - _('%s enviou um artigo para você') % requestor.name
154   - end
155   -end
156   -
157   -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.
158   -
159   -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.
160   -
161   -app/controllers/public/send_article_controller.rb
162   -
163   -class SendArticleController < MyProfileController
164   - def new
165   - @person = Person.find(params[:target_id])
166   - @article = TextileArticle.new
167   - if request.post? && params[:confirmation]
168   - SendArticle.create!(:requestor_id => user.id, :target_id => @person.id)
169   - flash[:notice] = _('%s receberá solicitação de criação deste artigo.') % @person.name
170   - redirect_to :back
171   - end
172   - end
173   -end
174   -
175   -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.
176   -
177   -app/views/send_article.rhtml
178   -
179   -<h1><%= _('Sending article to %s') % @person.name %></h1>
180   -<% labelled_form_for 'article', @article, :html => { :multipart => true } do |f| %>
181   - <%= hidden_field_tag(:confirmation, 1) %>
182   - <%= hidden_field_tag(:target_id, @person.id) %>
183   - <%= render :partial => 'cms/textile_article', :locals => { :f => f } %>
184   - <% button_bar do %>
185   - <%= submit_button :save, _('Send') %>
186   - <%= button(:cancel, _("Cancel"), :controller => 'profile', :profile => profile.identifier) %>
187   - <% end %>
188   -<% end %>
189   -
190   -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.
191   -
192   -<li> <%= 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' %> </li>
193   -
194   -= Visão Geral do Banco de Dados
195   -
196   -O Noosfero é composto por 27 tabelas, listadas abaixo:
197   -
198   - +--------------------------------+
199   - | Tables_in_noosfero_development |
200   - +--------------------------------+
201   - | article_versions |
202   - | articles |
203   - | articles_categories |
204   - | blocks |
205   - | boxes |
206   - | categories |
207   - | categories_profiles |
208   - | comments |
209   - | consumptions |
210   - | domains |
211   - | environments |
212   - | favorite_enteprises_people |
213   - | friendships |
214   - | images |
215   - | product_categorizations |
216   - | products |
217   - | profiles |
218   - | region_validators |
219   - | role_assignments |
220   - | roles |
221   - | schema_info |
222   - | taggings |
223   - | tags |
224   - | tasks |
225   - | thumbnails |
226   - | users |
227   - | validation_infos |
228   - +--------------------------------+
229   - 27 rows in set (0.00 sec)
230   -
231   -A seguir, faremos um relato sobre o papel de cada tabela no funcionamento do sistema:
232   -
233   -== article_versions
234   -
235   -Os artigos posssuem controle de versão e cada versão é guardada nessa tabela.
236   -
237   -== articles
238   -
239   -Artigos são todo tipo de conteúdo que pode ser criado pelo usuário. Como textos, imagens e até mesmo pastas.
240   -
241   -== articles_categories
242   -
243   -Os artigos são classificados por categorias. Esta tabela guarda as associações entre artigos e categorias.
244   -
245   -== blocks
246   -
247   -Guarda as informações relativas aos blocos, que são apresentados em boxes na página do usuário.
248   -
249   -== boxes
250   -
251   -Representa as áreas onde os usuários podem anexar seus blocos.
252   -
253   -== categories
254   -
255   -São categorias do sistema, que incluem categorias de produto e regiões.
256   -
257   -== categories_profiles
258   -
259   -Esta tabela guarda a associação entre categories e profiles.
260   -
261   -== comments
262   -
263   -Esta tabela guarda os comentários feitos nos artigos.
264   -
265   -== consumptions
266   -
267   -Representa os tipos de produtos que o usuário consome.
268   -
269   -== domains
270   -
271   -Cada ambiente pode ter um ou mais domínios, nesta tabela está armazenado o domínio do ambiente.
272   -
273   -== environments
274   -
275   -Representa cada uma das redes sociais (ou ambiente) geridas pelo Noosfero.
276   -
277   -== favorite_enteprises_people
278   -
279   -Representa os empreendimentos favoritos de um usuário.
280   -
281   -== friendships
282   -
283   -Esta tabela apresenta todos as relações de amizade.
284   -
285   -== images
286   -
287   -Guarda as informações sobre todas as imagens armazendas no sistema.
288   -
289   -== product_categorizations
290   -
291   -Representa a associação entre produtos e categorias.
292   -
293   -== products
294   -
295   -Esta tabela guarda todos os produtos dos empreendimentos do sistema.
296   -
297   -== profiles
298   -
299   -É a entidade mais importante do sistema. Representa tanto pessoas, quanto comunidades, empreeendimentos e organizações.
300   -
301   -== region_validators
302   -
303   -Relaciona as organizações validadoras com a região em que ela opera.
304   -
305   -== role_assignments
306   -
307   -Associa um papel a um usuário, dando a ele permissões sobre um determinado recurso do sistema.
308   -
309   -== roles
310   -
311   -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á.
312   -
313   -== schema_info
314   -
315   -Guarda o número da migration no Rails.
316   -
317   -== taggings
318   -
319   -Associa uma tag a um artigo.
320   -
321   -== tags
322   -
323   -Esta tabela armazena uma tag que pode ser associada a artigos.
324   -
325   -== tasks
326   -
327   -Representa uma tarefa que pode ser atribuída a um usuário, comunidade ou empreendimento.
328   -
329   -== thumbnails
330   -
331   -Guarda informações sobre miniaturas de imagens.
332   -
333   -== users
334   -
335   -Esta tabela guarda informações de login de todos os usuários do sistema.
336   -
337   -== validation_infos
338   -
339   -Guarda a metodologia de validação de uma entidade validadora.
340   -
341   -== Abaixo segue modelagem do Noosfero
342   -
343   -link:../noosfero_tabelas_article.png
344   -
345   -link:../noosfero_tabelas_category.png
346   -
347   -link:../noosfero_tabelas_profile.png
348   -
349   -link:../noosfero_tabelas_environment.png
350   -
351   -link:../noosfero_tabelas_schema.png