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,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