@ Organize-se v beta # # Divulgação: http://rufspace.com/artigo/organize-se/ # Autor: Fellipe Cicconi - liperuf@gmail.com # # Metodologia usada na Agência Click desde 2004. # O uso e redistribuição desse modelo é livre. Mantenha os créditos originais. # A documentação está em desenvolvimento. Seu prosseguimento dependerá também de seu feedback. # Bom divertimento :) [Organize-se] 1. Estrutura de diretórios 1.1 css 1.2 img 1.3 inc 1.4 js 1.5 pt-br 1.6 swf & xml 2. Convenções (em contrução) 2.1 Ferramentas de terceiros 2.2 Includes 2.3 Organização por seções 2.3 Tecnologias empregadas/restritas 3. Expansibilidade (em contrução) 3.1 Multi-linguagem 3.2 Seções 3.3 Javascript e CSS modular 3.4 Inclusão de estrutura para BackEnd (back-office) ------------------------------------------------------- 1 Estrutura de Diretórios ----------------------- Os diretórios foram nomeados de acordo com o contexto tecnológico que abrigam. Desta forma, podemos expandir de forma organizada o desenvolvimento de um projeto orientado à web seja ele pequeno como um hotsite ou um portal escrito em Java. A divisão orientada às seções do site acontecem *dentro* de seu contexto tecnológico e se replicam em outros diretórios caso haja uma interdependência. Veja o exemplo Ex.1. Ex.1 : Quando cria-se uma seção "contato" dentro de [pt-br] (pasta que abriga os HTMLs em português-brasil) é bastante interessante criar um diretório equivalente em [img] para abrigar todas as imagens referentes à seção de contato, bem como criar uma css exclusiva para "contato" dentro de [css]. Caracteriza-se o cenário abaixo: \pt-br\contato\*.htm |html|jsp|asp... \img\contato\*.jpg |gif|png \css\contato.css ------------------------------------------------------- 1.1 css --- Diretório reservado à abrigar todas as CSSs do projeto. Deve-se criar todas as CSSs necessárias de acordo com a sua organização interna. Por padrão, este diretório contêm três arquivos: a) reset.css b) replacements-pt-br.css c) style.css que serão explicados à seguir. reset.css (a) refere-se à uma CSS comprimida de Eric Meyer que zera todos os valores default do browser. Ou seja, através dela é possível evitar todos margins e paddings incovenientes que vão acontecendo durante o desenvovlimento do layout do projeto. replacements-pt-br.css (b) é usada para abrigar todos os image-replacement em português no projeto. É útil mesmo em projetos que não são multi-language, pois agiliza nas trocas dos replacements, o que é muito comum de ocorrer nas versões posteriores ao lançamento. No pior cenário, ou seja, num projeto multi-language, pode-se criar a replacements-en-us.css ou replacements-es.css para abrigar todos os replacements por língua. Esse recurso é extremamente útil, mas é preciso ser zeloso com o desenvolvimento para que o uso desta CSS seja realmente eficiente. style.css (c) é sua CSS padrão para o projeto. Importa as duas outras CSSs (a reset e a replacements de acordo com a lingua). Ela pode ser usada para abrigar os créditos e estruturar as partes genéricas do site. ------------------------------------------------------- 1.2 img --- Diretório vazio que deve conter todas as imagens no projeto. É aconselhável que crie-se subdiretórios que para abrigar as imagens dentro do contexto das áreas do site, bem como na pasta [pt-br]. ------------------------------------------------------- 1.3 inc --- Utilizado para conter todos os objetos escritos em HTML que são comuns ao projeto. No nosso exemplo, temos os arquivos: a) taghead b) header c) nav d) footer e) init taghead (a) é usado para declarar todas as meta-tags, chamadas de script e de CSS comuns ao projeto. Deve ser chamado à partir de todos os documentos HTML entre a tag . header (b), nav (c) e footer (d) são trechos de código que descrevem as partes da estrutura do corpo do HTML que são comuns à todas as partes do site, como o cabeçalho, menu de navegação e rodapé, respectivamente. init (e) é usado para agregar namespaces em Java ou .Net. Dispensável caso você não use alguma tecnologia como essas. ------------------------------------------------------- 1.4 js -- Os Javascripts usados para definir o comportamento das páginas devem ser agrupados nesta pasta. Previamente ela já apresenta alguns arquivos: a) calls.js b) forms.js c) functions.js d) init.js e) metricas.js f) third\jquery-1.2.1.pack.js g) third\pngFix.js h) third\swfobject.js calls.js (a) e forms.js (b) são generalizações experimentais para controle de troca de dados entre cliente-servidor e validação de forms respectivamente. Dentro de calls eu abrigo todas as funções de chamadas AJAX que são necessárias no site. Forms abrigam funções de validação de todos os formulários no site. Ambos scripts podem ser carregados sob demanda, ou seja, serem carregados apenas se a página necessitar de tais funções; contanto, pode ser interessante "cachear" no cliente esses JSs caso não estejam muito grandes. Como sugestão, podemos contextualizar ainda mais a chamada AJAX / validação através da criação de arquivos de script exclusivos para uma situação, como exemplo, forms.clientes.js - um arquivo que contém todas regras de validação de uma só página (que NÃO deve ser chamado através do include taghead (veja o tópico 1.3.a). functions.js (c) contém todas funções genéricas do projeto e deve ser declarado no taghead (veja 1.3.a). init.js (d) deve ser usado para declarar a chamada de todas as funções que ocorrem após o window.onload da página. metricas.js (e) é uma particularidade dos projetos que têm sistemas de tracking de clicks. Todas as funções referentes devem ser colocadas neste arquivo, cuja a existência depende exclusivamente deste fato. jquery.js (f), pngfix.js (g) e swfobject.js (h) são scripts de terceiros agregados ao projeto de acordo com a necessidade. Como eu uso o jQuery como meu framework de javascript padrão, ele sempre estará incluso nessa pasta. É interessante manter o release no próprio nome do arquivo. O pngFix e o swfObject são ferramentas que sempre uso nos meus projetos também. O pngFix resolve o problema do IE6 quanto ao suporte de PNG e o SWFObject normaliza o uso de Flash entre os diferentes browsers. É interessante procurar pela documentação dos respectivos caso eles ainda não lhe sejam familiares. Todos os arquivos de terceiros (na pasta [third]) devem ser COMPRIMIDOS. Em outras palavras, você não vai alterar ou debugar esses scripts, portanto é ideal que vc compacte-os para que os Kbytes do site sejam reduzidos. A ordem de como esses scripts são chamados *importa*. É provável que seus scripts em functions.js usem funções do framework que você esteja utilizando (no nosso exemplo, o jquery), e por isso, se você declarar a chamada do functions (em taghead) ANTES da chamada do framework, nada funcionará como deveria. O certo é você declarar DEPOIS. Em taghead eu já coloquei a ordem que deve ser seguida preferencialmente. Veja abaixo: i) j) k) l) m) n) o) p) O item "p" (init.js) depende diretamente do item "l" (functions.js) que por sua vez depende do item "i" (jquery, nosso framework) e é por esse motivo que eles são carregados nessa ordem. O quadro abaixo descreve as dependências entre os projetos. p, o, n, m -> L (dependem de L) l -> I (depende de I) j, k, i (não dependem de ninguem) ------------------------------------------------------- 1.5 pt-br ----- Dentro dele deve-se abrigar o conteúdo do projeto preferencialmente contextualizados pelo assunto ao qual se referem. Paralelamente podem-se criar diretórios no mesmo nível de hierarquia que representem o mesmo conteúdo em outra língua, como Inglês (EUA): en-us ou Espanhol : es-es. A forma de organização dos arquivos de conteúdo fica a critério do desenvolvedor. Lembre-se que a forma de organização interna também conta bastante com a qualidade do desenvolimento. E lembre-se de replicar dentro de diretórios interdependentes, como [img] e [css] a forma de organização do conteúdo. ------------------------------------------------------- 1.6 SWF & XML --------- Caso o projeto necessite de objetos como SWFs e/ou XMLs, este é o lugar perfeito para guardá-los. A pasta [swf] deve ter uma estrutura semelhante ao de [img] para manter o projeto saudável. Geralmente, os SWFs fazem chamadas à XMLs em sites grandes ou que são exclusivamente feitos em Flash. A organização dos mesmos fica a critério do desenvolvedor. Em [xml] abrigam-se todos os XMLs que contém info necessária.