Logotipo WebingPro.
Menu
Background Image
Voltar para a página anterior

Magic Parte 2
Seus primeiros passos

Postado por Gabriel Felipe em 19/11/2014 às 04:52

Background Image

Antes de ler esse post esteja ciente de que ele é a continuação desse aqui, e portanto assume que você tenha conhecimento de alguns conceitos explicados anteriormente, porém se você for o tipo mais experimentalista / aventureiro pode seguir que acho que você vai entender algumas coisas instintivamente.

Nessa segunda parte da série bem vindo ao Magic, iremos criar um sisteminha extremamente simples, sério muito simples mesmo. O objetivo desse post é você ver na prática o Magic funcionando, então preparei um escopo bem pequeno para não termos muita complexidade lógica e podermos nos focar nas funcionalidades do framework.

“Ta mas o quê vamos desenvolver afinal? ~ Você, sobre o que eu disse acima”

Um gerenciador de tarefas que tem basicamente duas opções, inserir e deletar tarefas de uma lista. Essas funcionalidades serão atingidas via ajax e uma demonstração do resultado final pode ser vista aqui.

Compatibilidade

É bom informar que os testes com o Magic do repositório padrão só foi testado em Linux e Mac, ambos rodando apache. Porém, já instalei ele em ambientes Windows, e se não me engano as alterações são pequenas, caso você utilize Windows e queira executar esse tutorial e ele não funcione, deixe um comentário com o seu problema que iremos trabalhar na solução aumentando a compatibilidade do framework.

Quanto ao PHP, é recomendada a versão 5.5 ou superior, porém acredito que a 5.4 seja o suficiente.

Para os bancos de dados ele foi testado apenas utilizando o MySQL, fique a vontade para testar em outros bancos de dados e me contar o que acontece. Por utilizar pdo, talvez alguns bancos funcionem quase que imediatamente.

Organização do tutorial

Esse tutorial será dividido em 7 passos, listados abaixo:

  1. Baixar os arquivos necessários
  2. Configurar o Magic
  3. Criar o escopo Todo
  4. Configurando as Urls
  5. Configurações iniciais para exibir os templates
  6. Criando os models e interfaces de formulário
  7. Unindo tudo com Js

Bem, vamos lá!

Seus primeiros passos com o Magic

1 – Baixar os arquivos necessários

A primeira coisa que precisamos fazer é baixar os arquivos necessários, baixaremos duas coisas:

  1. O Magic, que pode ser baixado pelo github, tanto clonando o repositório como baixando o zip pela barra lateral.
  2. Templates e banco de dados para o nosso aplicativo, assim poderemos focar no framework, sem nos preocuparmos em criar os templates ou o banco de dados. Você pode clicar aqui para chegar no repositório dos recursos deste tutorial. Os meios para download são os mesmos citados acima.

Antes de continuar, é importante que você baixe os dois repositórios e coloque-os em duas pastas separadas, irei me referir a essas pastas como “magic” e “magicTutorial” respectivamente. Não esqueça que essas pastas devem estar acessíveis para rodarem php no navegador. Então, vai lá criar as pastas, eu espero!

2 – Configurar o Magic

A primeira coisa a fazer é criar um banco de dados com o nome da sua preferência, chamarei de “todo”  e importar o banco de dados contido no arquivo todoApp.sql, esse arquivo apenas contém a estrutura de uma única tabela, pode copiar o sql dela abaixo se preferir.

Criou o banco? Perfeito, continuemos então! Iremos fazer o aplicativo na pasta “magic”, onde colocamos o conteúdo do framework baixado no passo 1, então acesse ela pelo seu navegador. Caso tenha criado a pasta na raiz do seu localhost, a url deve ser algo como: http://localhost/magic quando você acessar essa url você deve ver uma tela similar a abaixo:

Interface Manager

 

Eu não vejo uma tela assim, enfrentei um erro ou similar

Caso você não esteja vendo uma tela similar a essa precisaremos identificar o ocorrido, deixe um comentário com o seu erro e vamos trabalhar nisso! Porém é provável que o problema esteja no arquivo “path_roots.php”, tente definir essas 3 constantes manualmente:

A constante base_url e path_base são iguais pois a base_url se refere à url base do sistema, então por exemplo, você poderia ter a instalação em localhost/magic mas querer que o site fosse acessado por localhost apenas.

Beleza, eu já vejo essa tela!

Parabéns! Você acabou de conhecer o Manager, a – por enquanto pequena – interface administrativa do Magic.

Existem duas partes que você precisa prestar atenção nesse momento, a seção “Database” referente ao banco de dados e seção à direita desta: “Pastas que precisam de permissão de escrita”. Na primeira você deve modificar o status do banco de dados para ativo, e preencher as informações de acordo com o seu banco de dados. Após fazer isso clique em salvar.

Já na parte das pastas, você deve verificar se alguma daquelas pastas esta sem permissão de escrita (status diferente de “ok”), se for o caso precisa adicionar permissão de escrita nelas para o apache. É importante verificar também se ele identificou corretamente o caminho até a instalação do Magic.

Pronto, agora estamos com o Magic configurado, prontos para começarmos nosso todoApp.

3 – Criar o escopo todo

Como você leu no artigo anterior, e também pode conferir pelo manager, o Magic por enquanto tem apenas 1 escopo, o próprio manager. Porém não faz sentido misturarmos o aplicativo que criaremos com o Manager, portanto precisamos criar um novo escopo, chamaremos de “todo”.

Para isso, você pode utilizar a primeira seção do Manager “Escopos que compõe o sistema”, basta digitar todo no campo de texto e clicar em adicionar. Você pode perceber o que ocorre no sistema quando cria um escopo, acompanhando o antes e depois da pasta magic/scopes.

4 – Configurando as Urls

Com o escopo criado precisamos criar o primeiro controller e criar uma url para ele. Vamos lá, ainda na tela do Manager, clique em: Adicionar Controller e preencha, sem as aspas, conforme escrito abaixo:

  • “app” no campo nome do controller
  • Selecione todo ao lado do nome, na lista de escopos
  • “app,salvar,deletar,getForm” no campo Métodos.

Feito isso clique em “Cadastrar”.

Agora vá na pasta scopes/todo/controller, deve ter um arquivo chamado app.php com o conteúdo similar ao abaixo:

Edite o método app() para:

Agora criaremos a url para essa action, de forma que possamos ver isso no browser. Abra o arquivo magic/config/routes.json o conteúdo atual deve ser algo semelhante a:

Edite de forma que fique assim:

Explicação:

As urls no Magic são gerenciadas através do arquivo config/routes.json, então precisamos editar esse arquivo para criar a url. Nesse arquivo as urls são separadas por escopo, então antes tinhamos apenas as urls do escopo manager, agora criamos uma seção para urls do escopo todo.

Após feito isso incluimos a linha: “todo” : {“route”:”app_app”} que significa que quando alguém acessar a url http://localhost/magic/todo deve ser servida a rota app_app. Para entender como funcionam os valores do parâmetro route, você pode checar a seção “A requisição” no primeiro post dessa série.

Teste:

Para testar se sua rota foi identificada corretamente acesse a url: http://localhost/magic/todo , lembrando que http://localhost/magic deve ser substituido pelo caminho que você extraiu o framework lá no começo.

Se tudo der certo você deve ver a mensagem “Bem vindo ao seu app” na tela. Caso isso não aconteça, cheque se o seu apache tem habilitado o módulo rewrite para permitir url’s amigáveis. Caso ele não tenha, configure o módulo e tente novamente.

Assim que ver essa mensagem, parabéns! Mais uma etapa concluída, a url já está configurada.

5 – Configurações iniciais para exibir os templates

Chegou a hora de exibirmos os templates baixados no passo 1. Para isso substitua a pasta magic/scopes/todo/views/default pela pasta magicTutorial/default . Isso fará com que os templates criados sejam colocados no aplicativo.

Agora abra o arquivo scopes/todo/controller/app.php que tem o método app da forma que deixamos antes:

Troque para:

Agora atualize a url http://localhost/magic/todo ou similar, aquela que tinha a mensagem antes. Quando atualizar deve ver algo como:

Template Magic

A explicação do código está nos comentários dentro do próprio código, porém gostaria que, antes de continuarmos, você visualizasse o código fonte gerado pela página e reparasse em algumas coisas:

  1. Em lugar nenhum escrevemos o código do HEAD do documento ou similares, isso foi gerado automaticamente para nós.
  2. Apesar de termos inseridos 2 css’s, common.css e lista.css o framework chamou apenas um css no código, com um nome bem esquisito. É uma versão cacheada e minificada de todos os css’s dessa action juntos. Sim, automaticamente.
  3. Se você ver o conteúdo dos arquivos lista.css e common.css, perceberá em vários lugares ocorrências de coisas como .grid4, .grid8 e assim por diante. Mesmo que não tenhamos definido nenhum grid em lugar nenhum. As classes de grid, configuração dele e outras classes auxiliares já vem prontas no framework, pelo arquivo magic/engine/css/common.css.
  4. Ainda analisando o conteúdo dos arquivos lista.css e common.css, percebemos que a sintaxe dele utiliza vários recursos do Less.css, mesmo que não tenhamos incluído o less em lugar nenhum. Essa função também é automática, o framework na hora de juntar os css’s automaticamente passa eles por um compilador less.

6 – Criando os models e interfaces de formulário

Bem, agora que já configuramos o template, podemos prosseguir para fazer isso tudo funcionar. Vamos editar primeiro o php e depois faremos o js para tudo funcionar.

Vamos começar pelo model, abra novamente o manager (http://localhost/magic ou similar) e clique em add DbModel e preencha o formulário conforme a seguir, sem as aspas novamente:

  • “task” no campo tabela, referente a tabela do banco de dados que esse dbModel irá gerenciar.
  • “tarefa” no campo single, referente ao apelido para um item sozinho da tabela task.
  • “tarefas” no campo plural, referente ao apelido para vários itens juntos da tabela task.
  • “todo” no selectbox referente ao escopo onde esse DbModel será criado.

Agora clique em cadastrar. Feito isso temos um arquivo scopes/todo/model/tarefa.php com o seguinte conteúdo:

Você não precisa editar ele, apenas deixe-o ai como está.

Sabe o arquivo controller/app.php? Vamos voltar para ele. Modifique ele para que ele fique dessa forma:

Agora precisamos fazer algumas modificações no arquivo magic/scopes/todo/views/default/template/lista.tpl, edite-o para que ele fique assim:

e agora crie um arquivo magic/scopes/todo/views/default/template/_tarefa.tpl com o conteúdo abaixo:

Acredito que os comentários nos arquivos de template expliquem as modificações que fizemos, mas apenas para deixar claro o que fizemos foi preparar o template para os dados que vão vir do banco de dados e criar um bloco de template responsável apenas pelo conteúdo de uma única linha do registro do banco de dados.

Ao fazer isso você concluiu tudo no php e nos templates, ao atualizar a página deve ver a lista de tarefas vazia agora, pois ainda não temos nenhum registro no banco de dados.

7 – Unindo tudo com Js

Agora precisamos fazer ser possível inserir e deletar as tarefas, faremos isso utilizando uma classe js chamada crud, ela deve ser utilizada em conjunto com a classe crud que utilizamos no arquivo app.php, inclusive quando você carregou o plugin crud, ele automaticamente inseriu o js necessário para utilizar essa classe em javascript também.

Para isso inclua o seguinte bloco no final do arquivo magic/scopes/todo/views/default/template/lista.tpl

Agora se você atualizar a url http://localhost/magic/todo e tentar inserir um registro pelo formulário vai ver que já está funcionando. Inclusive se tentar inserir um registro com apenas 2 letras no título ou com o nome repetido, verá que as regras de validação que definimos também já estão funcionando.

Perceberá também que o botão excluir ainda não funciona, porém se segurar ctrl e clicar na tarefa ele perguntará se você tem certeza que deseja excluir o item. Caso clique em sim, ele excluirá o registro.

Explicação

A classe crud do javascript utiliza vários recursos ajax do Magic para facilitar a manipulação de registros via ajax, abaixo está listado o comportamento padrão dela:

  1. É registrado um evento onSubmit no formulário passado a ela que sempre que ele for enviado é feita uma requisição ajax a rota save, no caso a action salvar do app.php. Caso o retorno seja positivo ele reseta o formulário e inclui o novo conteúdo gerado na lista de itens, no caso “.lista-tarefas”. Em caso de falha ele alerta a mensagem de erro.
  2. É registrado um evento click em cada um dos itens, que se o ctrl tiver segurado ele tenta deletar o registro. O id do registro é consultado por padrão no atributo data-id do item, no caso “.tarefa”. Então ele envia uma requisição a rota de remover (app_deletar) com o parâmetro pk (task_id) = atributo data-id. Em caso de sucesso nessa requisição, ele remove o item da lista, em caso de falha ele alerta a mensagem de erro.

Portanto com apenas uma linha de código javascript, você obtém as funcionalidades básicas para manipulação de registro.

Customizando o Crud.js

Porém esse comportamento padrão pode precisar ser alterado, então usaremos algumas facilidades e praticidades da classe crud do javascript, porém iremos customizar ela em alguns sentidos.

A primeira coisa a fazer é mudar a forma de deletar o registro. Para isso, inclua o seguinte código no final do bloco <script> em lista.tpl

Se você incluiu esse bloco de código no final, ao testar a página novamente verá que o botão de excluir agora funciona e não é mais possível excluir o item utilizando ctrl+click.

Agora para finalizar customizaremos a mensagem de erro para não ficar um alert tão feio. Para isso inclua mais esse bloco de código na tag <script>

Pronto, agora se você testar verá que os erros de validação aparecem de forma mais organizada. A explicação do código está nos comentários do mesmo.

Conclusão

Parabéns, você acabou de fazer seu primeiro aplicativo com o Magic. Eu espero que você esteja com várias perguntas na cabeça, no sentido de quem se interessou e quer saber mais, e não no sentido de quem não entendeu nada rsrs. Se você quiser saber mais ou até se não tiver entendido nada mesmo, pergunte nos comentários.

Eu sei que foi um aplicativo simples, mas espero que tenha dado para entender como o Magic funciona e espero que você tenha gostado do que viu.

Lembre-se sempre de que o Manager é um escopo para ajudar na fase de Desenvolvimento, quando o projeto está em produção algumas medidas devem ser tomadas, são elas:

  1. Bloquear o acesso a pasta config e seus arquivos
  2. Remover o escopo manager ou protegê-lo por uma senha

Por enquanto é isso pessoal, logo eu volto para começar a me aprofundar nos componentes exclusivos do Magic. Caso tenham se interessado por algum em especial, falem nos comentários assim quem sabe eu não comece por ele? Quer saber mais sobre as rotas? Sobre o componente html, que gera o head automaticamente e cuida dos assets? Do controller? Do gerenciamento de formulários? Ou alguma outra coisa?

Conheça o autor do post

Gabriel Felipe:
Notice: the_author_description está obsoleto desde a versão 2.8.0! Use the_author_meta('description') em seu lugar. in /home/webingpro/www/blog/wp-includes/functions.php on line 3830
Tenho foco em PHP, mas gosto de ficar de olho no que ta acontecendo no mercado. Já brinquei com: Python, Node.JS e Ruby on Rails. PHP ainda é minha paixão no entanto. Na formação, sou autodidata desde 2004. Aprendi o que eu sei com a internet e esse blog é uma tentativa de devolver um pouco disso. Eu gosto de opensource, e a maioria das coisas que você encontrar aqui vão estar licenciadas sobre beerware, ou licença da cerveja.

  • Gabriel Felipe

    teste