wiki:Guias/HowTo/NovaAPI
Last modified 6 years ago Last modified on 10/04/13 11:40:59

  1. 1. Introdução
  2. 2. Criando um novo módulo ( Bundle )
    1. 2.1. Realizando a criação do módulo
  3. 3. Preparando o novo módulo para desenvolvimento
    1. 3.1. Chega de conceito e mãos à obra!!! :)
      1. 3.1.1. Com a pasta Resources aberta, crie duas pastas novas dentro de …
      2. 3.1.2. Na pasta EJS crie “nomedobundle.ejs.twig” e na JS crie …
      3. 3.1.3. Na pasta config, dentro de Resources, crie 2 arquivos: …
      4. 3.1.4. Na pasta Controller modifique o nome da classe e do arquivo …
    2. 3.2. Seguindo o padrão obrigatório
      1. 3.2.1. Abra o seu arquivo “Resources/views/JS/nomebundle.js.twig” e …
      2. 3.2.2. Abra seu browser e digite o seguinte link:
      3. 3.2.3. Abra o arquivo “Resources/views/EJS/nomebundle.ejs.twig” e digite …
      4. 3.2.4. Abra o arquivo “Resources/views/EJS/nomebundle.ejs.twig” e insira o …
  4. 4. Mãos à Obra ( Desenvolvendo )
    1. 4.1. Abrindo uma dialog a partir de um botão
    2. 4.2. Utilizando rotas para interação com o backend
    3. 4.3. Criando entidades
      1. 4.3.1. Entre no seu ambiente pelo console, em seguida entre na pasta …
      2. 4.3.2. Digite o nome do bundle sempre acompanhado por “ Prognus” e após os …
      3. 4.3.3. Escolha ANNOTATION como formato para mapear as informações
      4. 4.3.4. Escolha um nome, tipo, e pressione enter
      5. 4.3.5. Caso você não precise adicionar mais colunas, pressione enter
      6. 4.3.6. Mantenha “no” como padrão, e pressione enter.
      7. 4.3.7. Deixe “yes” como padrão para a confirmação da geração da entidade …
  5. 6. ApiResponse()
    1. 6.1 Declaração:
    2. 6.2 Métodos:
      1. 6.2.1 setData()
      2. 6.2.2 render()
  6. 7. Banco de dados
  7. 8. Tratamento de erros
  8. 9. LDAP
  9. 10. Grid
  10. 11. Javascript
    1. 11.1. Renderizar tela
    2. 11.2. Buttons
    3. 11.3. Forms
  11. 12. Roles
  12. 13. Internacionalização
  13. 14. Rotas
  14. 15. CSS
  15. 16. Notify
    1. 16.1. Success
    2. 16.2. Warning
    3. 16.3. Error
    4. 16.4. Confirm

1. Introdução

O objetivo principal dessa documentação é repassar o conhecimento necessário para a construção de um novo módulo utilizando a nova API do Expresso baseada no framework Symfony. Nessa documentação não haverá muitos detalhes sobre métodos isolados, e sim apenas os métodos utilizados com mais frequência na criação de um novo módulo. Haverá alguns links de referência de determinados métodos do symfony, mas caso você tenha alguma dúvida que não está presente nessa documentação, sugiro a realização de uma pesquisa mais avançada na própria página de documentação de seus respectivos autores.

Alguns links úteis:

2. Criando um novo módulo ( Bundle )

A nova API utiliza o framework Symfony como base, e isso quer dizer que cada módulo novo será considerado um Bundle. A criação de cada módulo novo será gerada através de um comando especifico.

Considerando que você esteja em um ambiente Linux e possua um terminal ( caso esteja em ambiente Windows, aconselho conectar-se a um ambiente Linux de desenvolvimento utilizando o aplicativo PUTTY ), e também que você já tem um ambiente configurado; entre no seu ambiente ( ex: /home/seunome/nomedoseuambiente ) e logo em seguida entre na pasta symfony.

2.1. Realizando a criação do módulo

Digite ( php app/console generate:bundle ) em seu console, e pressione Enter ( Caso você não lembra do segundo parâmetro “generate:bundle”, utilize apenas "php app/console" e pressione Enter ).

Criação de um novo bundle

Como padrão, deve ser informado primeiro o nome do projeto “Prognus”, em seguida “Bundle” e por fim o nome do novo modulo ( Ex: Prognus\Bundle\TesteBundle ):

Obs: A utilização "Bundle" após o nome do módulo é obrigatório.

Escolhendo um nome para o bundle

Em seguida, deixe como padrão “PrognusTesteBundle” e pressione enter:

Deixando o nome padrão para o bundle

Agora o symfony está sugerindo um caminho para o seu bundle, então novamente deixe o caminho “/home/thiago/expressoparceiros2/symfony/src” como padrão e pressione enter:

Diretório de onde ficará o bundle.

Agora escolha yml como formato de configuração dos seus arquivos ( isso será necessário principalmente ao editar rotas ) e pressione enter:

Formato para os arquivos de configuração.

Como o symfony é um cara prático, ele pergunta se você deseja a geração automática de uma estrutura de pastas. Lógicamente, como você que está começando a utilizar o symfony e logo será um cara prático, informe “yes” e pressione enter:

Gerar uma estrutura de diretório.

As próximas 3 perguntas serão em relação a geração de pastas e da realização de update do kernel e das rotas, deixe o padrão como “yes” e pressione enter:

Finalizando a criação do bundle

Parabéns, você acaba de criar um novo módulo! =D Continuando…

Agora vamos verificar se a estrutura de pastas está correta, para isso é necessário a abertura do módulo pela estrutura de pastas do seu ambiente

Estrutura de pastas do novo bundle.

3. Preparando o novo módulo para desenvolvimento

Após realizar a criação do novo módulo, vamos estrutura-lo para começar o desenvolvimento.

Em poucas palavras, todos os módulos são acessados pela rota “module/NomeBundle”, e obrigatoriamente devemos seguir alguns padrões na hora da criação de determinados tipos de arquivos e declarações de determinados objetos. Dentro do módulo existe a pasta Resources, e nela possui alguns diretórios importantes, entre eles: config, public, translations e views. Esses diretórios são bastante utilizados no decorrer do desenvolvimento do módulo, sendo cada um deles:

config - Possui o arquivo routing.yml e o arquivo services.yml. O arquivo routing será bastante utilizado, pois ele é responsável pelas rotas internas daquele determinado módulo.

public - Possui as pastas de css, images e js. Esses arquivos só entrarão em vigor após a realização do comando “php app/console assets:install”, onde basicamente serão enviados para uma pasta “temporária” dentro do seu symfony.

translations - Possuirá um arquivo yml que será responsável pela internacionalização de seu novo módulo ( mais adiante será comentando sobre este novo arquivo ).

views - Na pasta views haverá todos os js e ejs, sendo que os ejs serão utilizados apenas para nossos templates e o js será responsável por renderizar esses templates ( Por padrão, deverá existir uma pasta JS e EJS que serão criadas manualmente ). Controller - Haverá todas as classes que farão conexão com o banco de dados, ldap e imap. Na hora da criação desses controles, é necessário colocar o “Controller” após o nome da classe ( Ex. TesteController ) e também após o nome do arquivo ( Ex. TesteController.php ).

Entity - Haverá todas as entidades representando as tabelas do banco de dados. Para criar uma entidade, é necessário executar o comando “php app/console generate:doctrine:entity” ( adiante será abordado a criação de uma entidade ).

3.1. Chega de conceito e mãos à obra!!! :)

3.1.1. Com a pasta Resources aberta, crie duas pastas novas dentro de views: EJS e JS



Pastas JS e EJS.

3.1.2. Na pasta EJS crie “nomedobundle.ejs.twig” e na JS crie “nomedobundle.js.twig”



Arquivo js e ejs dentro das pastas.

3.1.3. Na pasta config, dentro de Resources, crie 2 arquivos: “app_routing.yml” e “module.yml”



Criação do "app_routing.yml" e "module.yml".

3.1.4. Na pasta Controller modifique o nome da classe e do arquivo “DefaultController” para “[NomeDoSeuBundle]Controller”



Modificando nome do arquivo controller

Modificando nome da classe controller

3.2. Seguindo o padrão obrigatório

O padrão obrigatório está presente em diversos tipos de sistemas “inclusive no framework symfony”, e até então, nós criamos apenas a estrutura necessária de pastas. Agora vamos estruturar nossos arquivos com o objetivo de atender conforme à padronização exigida do sistema.

Para que possamos abrir o módulo pelo Expresso precisamos estruturar corretamente o arquivo “js.twig”, pois ele será executado apenas se houver a padronização correta.

Confuso!? Sem problemas, vamos lá...

3.2.1. Abra o seu arquivo “Resources/views/JS/nomebundle.js.twig” e coloque este conteúdo, apenas trocando o nome do objeto “Teste” para o nome do seu módulo



Nesta imagem você consegue perceber que foi declarado um novo objeto chamado oTeste, e esse nome é dado de acordo com o nome do seu próprio módulo. Sempre devemos criar um objeto com o prefixo “o” e logo em seguida o nome em “camel case” do módulo: Ex.: oPreventive, oNewUL. Este padrão será reconhecido através do primeiro arquivo “module/index.php”, responsável por recolher as informações fornecidas pela rota.



Obs: Ao instanciar o objeto, está sendo enviado um seletor do container como parâmetro, e este container será recuperado no arquivo js.twig que você criou.

3.2.2. Abra seu browser e digite o seguinte link:

https://expressodev.prognus.com.br/{seu_nome}/{seu_repositório}/module/{Seu_Módulo}



Obviamente, nada além de uma página em branco, mas se caso todos os passos foram efetuados corretamente, seu js estará sendo carregado.

  • Agora vamos carregar uma EJS em nossa página…

3.2.3. Abra o arquivo “Resources/views/EJS/nomebundle.ejs.twig” e digite “Olá Expresso Parceiros”



Importante: A nova API trabalha com codificação de arquivos em UTF-8, então sempre que for salvar um arquivo é necessário verificar se o arquivo está em UTF-8.

3.2.4. Abra o arquivo “Resources/views/EJS/nomebundle.ejs.twig” e insira o código dentro da função load



Carregando um novo ejs



Agora sim é possível visualizar as alterações na página do módulo. :)

Agora já sou um expert no Expresso Parceiros =D? Não! Mas vamos trabalhar para que isso aconteça.

4. Mãos à Obra ( Desenvolvendo )

Agora que já possuimos todo o ambiente padronizado, podemos começar a codificar respeitando todas as boas práticas na parte de front-end ( javascript ).



“Resources/views/EJS/nomebundle.ejs.twig”

4.1. Abrindo uma dialog a partir de um botão

Para a criação da estrutura necessária para a abertura de uma nova dialog, é necessário existir 2 arquivos, um EJS e outro JS. O JS será responsável pela interação do usuário com a dialog ( ex.: um click, pressionar uma tecla, salvar as alterações ) e no EJS haverá apenas o template ( html ).

No EJS existe apenas o "body". Perceba que não existe nenhum botão de "salvar", "editar", "fechar", pois esses botões serão criados no JS.

“Resources/views/EJS/nomebundle.ejs.twig”

No JS, É necessário realizar a recuperação do layout com o código "API.render()".

“Resources/views/EJS/nomebundle.js.twig”

Detalhes de métodos utilizados:

API.render() - Este método será responsável de renderizar um novo template. Parametros:

1) O template a ser renderizado; obrigatóriamente é necessário colocar primeiro o nome do Bundle, e logo em seguida o nome do ejs ( sem colocar o .ejs.twig ).

2) Dado a ser enviado para o template; obrigatóriamente é necessário enviar um json.

Caso tenha alguma dúvida em relação às funções jQuery, veja alguns links abaixo:

http://api.jquery.com/empty/

http://api.jquery.com/append/

http://api.jquery.com/find/

http://jqueryui.com/dialog/

http://api.jquery.com/click/

http://jqueryui.com/button/

http://api.jquery.com/html/



“Resources/views/EJS/dialog.ejs.twig”

  • Caso você queira enviar um dado para o template, basta informar o segundo parametro no render.



“Resources/views/EJS/nomebundle.js.twig”



“Resources/views/EJS/dialog.ejs.twig”

4.2. Utilizando rotas para interação com o backend

Antes de começar a utilizar rotas, primeiro é necessário saber o que é uma rota. Em um resumo muito curto: Rotas são os identificadores dos recursos para uma interação do cliente com o servidor.

Considere o seguinte exemplo:

Ao se autenticar, o usuário necessita visualizar todas as informações pessoais que estão no banco de dados. Trabalhando com symfony podemos buscar essas informações utilizando apenas o servidor; e para existir essa busca, é necessário a utilização de rotas.

Vamos a um exemplo prático…



“Resources/views/JS/teste.js.twig”



"Resources/config/app_routing.yml"

  • Para ver mais detalhes sobre os parametros da rota, segue o link.



“Controller/TesteController.php”



Todas as vezes que realizar qualquer (GET, POST, DELETE e PUT) é necessário realizar uma validação de verificação de falha utilizando o API.hasError()

4.3. Criando entidades

Basicamente, entidades são classes de mapeamento das tabelas do banco de dados. Todas as entidades serão geradas a partir do comando “php console/log”. Para mais informações, acesse: http://symfony.com/doc/current/book/doctrine.html

4.3.1. Entre no seu ambiente pelo console, em seguida entre na pasta symfony e digite php app/console generate:doctrine:entity.



Comando para criar uma nova entidade

4.3.2. Digite o nome do bundle sempre acompanhado por “ Prognus” e após os dois pontos digite o nome da entidade com letra maiúscula



Nome da nova entidade

4.3.3. Escolha ANNOTATION como formato para mapear as informações



Formato para mapear as informações

4.3.4. Escolha um nome, tipo, e pressione enter



Formato para mapear as informações

4.3.5. Caso você não precise adicionar mais colunas, pressione enter



4.3.6. Mantenha “no” como padrão, e pressione enter.



Gerar um novo repositório

4.3.7. Deixe “yes” como padrão para a confirmação da geração da entidade usando o formato “annotation”



Finalizando a criação da entidade

Parabéns, você acaba de criar uma nova entidade! =D

6. ApiResponse()

Classe que é utilizada para enviar os dados do PHP para o JS, com essa classe você pode enviar ao JS dados recuperados do banco ou alguma mensagem de erro.



6.1 Declaração:

$response = new ApiResponse(); Para poder utilizar essa classe inserir no use o namespace “Prognus\API\Response\ApiResponse”

6.2 Métodos:

6.2.1 setData()

Seta valores que serão enviados ao JS.

Parâmetros:

$data: array do resultado gerado pelo PHP pode ser inserido uma mensagem de erro. $code: Caso esteja retornando um erro, inserir o código do erro. $error: Caso esteja retornando um erro, setar como true. Retorno: Retorna o próprio método. Exemplo de uso:



6.2.2 render()

Esse método serve para enviar os dados que foram setados no metodo setData() para o JS.

Parâmetros: Sem parâmetros. Retorno: Retorna o próprio método.

7. Banco de dados

Para persistir, inserir, modificar e realizar consultas no banco utiliza-se o framework Doctrine. O Doctrine é um framework de mapeamento objeto-relacional para PHP. É necessário instanciar um objeto do doctrine para toda ação que for realizada no banco de dados.

Instância do objeto doctrine

Após essa declaração, você possuirá uma gama de métodos que poderão ser utilizados a partir deste objeto “$db”.

Veja abaixo alguns dos principais métodos que poderão ser utilizados.

SELECT

SELECT utilizando o doctrine

DELETE

DELETE utilizando o doctrine

UPDATE

UPDATE utilizando o doctrine

INSERT

INSERT utilizando o doctrine

Para persistir no banco é necessário possuir entidades criadas. Para saber como criar uma nova entidade, segue o link.

8. Tratamento de erros

Todo código no PHP deve estar dentro das clausulas try-catch.

Código php dentro de try-catch

Todos os parâmetros passados pelos métodos POST e GET, mesmo realizando as devidas verificações no front-end, deve-se novamente fazer a verificação no back-end e retornar o erro caso ocorra.

Importante: Todos as mensagens utilizadas no sistema precisam estar internacionalizadas.

9. LDAP

Para realizar uma busca no Ldap pelo back-end, devemos primeiro chamar o serviço do Ldap com o método:

Instanciando método para o ldap

Após chamar o serviço do Ldap devemos setar o critério da busca e o contexto que será usado:

setando critérios

É utilizado o método search para realizar as buscas, passando o critério, um array de atributos, e também um contexto.

Método search do ldap

10. Grid

Para utilização da jqGrid, deve-se criar dois métodos na controller. Esses métodos realizam a busca no banco e cria um cache para que os itens da grid sejam trazidos para o usuário conforme ele interaja com a mesma.

Método POST da grid

Esse primeiro método realiza a busca dos itens que você deseja que apareça na grid. Para toda a grid, sempre é necessário realizar um POST e um GET. Na requisição POST será realizado uma consulta apenas retornando os ids. Esses ids serão salvos em um memcache, e o mesmo apenas poderá ser identificado através de um token. Esse token será utilizado apenas na segunda requisição “GET”, onde haverá mais uma consulta no banco trazendo todas as informações dos ids solicitados.

11. Javascript

11.1. Renderizar tela

Para renderizar uma tela é utilizado o método API.render(), passando como parametro uma string com o NomeDoSeuBundle.nome.do.seu.ejs lembrando que não deve-se colocar o .ejs.twig

Renderizando uma ejs

11.2. Buttons

Para gerar os buttons na tela deve-se utilizar o seguinte código

Aplicando button nos botões

11.3. Forms

Todos os formulários do sistema devem estar dentro das tags <form></form> com isso podemos utilizar um método para pegar todos os campos que estão dentro dessas tags e fazer as devidas verificações, veja o exemplo de utilização do form.

Recuperando informações de form

12. Roles

As roles servem para definir o que o usuário pode realizar dentro de um determinado modulo, por padrão utilizamos 3 roles “ACCESS”, “ADMIN” e “ROLES”. As roles devem ser definidas dentro do arquivo module.yml.

Roles padrão

Após a definição dessas roles no arquivo module.yml, utilizando o módulo Admin será possível identificar os usuários que terão acesso a essas roles.

Você também pode criar outras roles:

Roles padrão

Para verificar no front-end se um usuário tem determinada role, é necessário utilizar o seguinte método:

Verificar se a role em determinado usuário

Esse método retorna true se o usuário estiver a role. Para utilizar ele no back-end utilizasse:

Validação de role pelo back-end

13. Internacionalização

A utilização da internacionalização no symfony é muito simples, por padrão ele já está configurado para o português, porem todas as mensagem e textos do sistema precisam estar em inglês, para isso temos que serguir algumas etapas, primeiro tem que criar o arquivo que vai conter as traduções, esse arquivo fica localizado em:

Caminho do arquivo de tradução

Após criar o arquivo, vamos abrir ele:

Arquivo de tradução

Como podemos ver no exemplo acima, é muito simples criar as traduções, na primeira frase entre ‘’ escrevemos a frase ou palavra em ingles seguida de “:” e a frase ou palavra em português.

Para o symfony identificar no código que aquele texto tem que ser traduzido, temos que seguir algumas regras bem simples. No js e no ejs todo texto a ser traduzido precisa estar dentro das tags {% trans %} e {% endtrans %}. Obs: entre as tags não pode estar vazio.



Código no JS



Código no EJS

Já para utilizar no backend( PHP ) é um pouco diferente; temos que instanciar o serviço translator através do método get.

Após isso podemos usar o objeto $t com o método trans para utilizar as traduções.

14. Rotas

O Symfone trabalha com rotas e todas as requisições cliente-servidor precisa de uma rota, ou seja, cada action criada, no back-end, precisa de uma rota para que o cliente possa acessar. Todas as rotas que você for utilizar em seu modulo ficará no arquivo SeuModulo/Resources/config/app_routing.yml caso esse arquivo não exista, você deve criar ele.



Na imagem acima podemos ver como devesse criar uma rota, na primeira linha devesse dar um nome a rota, em no parâmetro pattern: colocasse o endereço para acessar o sua rota, em seguida devemos indicar com bundle essa rota pertence a controller e a action que essa rota vai chamar. E por ultimo o método que vai ser utilizado, se é POST, GET, PUT e DELETE, pode usar mais de um, para mais informações de como usar os métodos de requisições ver na sessão 8.5.

15. CSS

Para cada modulo podemos usar um arquivo css, esse arquivo deve ser criado na pasta SeuModulo/Resources/public/css/style.css todo css que for utilizar pode ser inserido nesse arquivo.



Para que o seu modulo comece a utilizar o css, é necessário executar um comando no console. Para executar os comando do symony, você primeiro tem que estar na pasta do symfony, os comandos precisam ser executados pelo usuário apache. Para usar o usuário apache execute o comando:

su apache

Irá pedir a senha digite 'prognus'. Pronto você está logado como apache, agora podemos executar o comando do symfony. O comando que devemos executar é para instalar o assets, então execute:

app/console assets:install --symlink

Esse comando cria os links simbólicos do seu modulo e o paramentro --symlink serve para que toda vez que você atualizar o seu css, não precisa executar o comando assets:install para que as modificações sejam visíveis.

16. Notify

Todas as mensagens do sistema de erros, warnnings e sucesso utilizamos o plugin do jQuery notify, por padrão para cada modulo criamos uma função para facilitar o uso do plugin. Segue o código da função:

Utilizamos 3 tipos de notificações no sistema, sucesso, erro e warnning.

16.1. Success

São notificações de sucesso, quando realizar alguma determinada ação de salvar ou remover.



16.2. Warning

São notificações de atenção, utilizadas em validações de formulários para notificar o usuário que algo não está preenchido corretamente.



16.3. Error

São notificações erros, ou seja, utilizadas para notificar o usuário que algum erro aconteceu ao tentar realizar determinado ação, exemplo ao tentar salvar determinado formulário, porem não foi possível salvar esse formulário, exibimos uma notificação de erro para o usuário informando que não foi possível salvar o formulário.



Obs. Podemos inserir essa função de notificação direto na API, assim não precisamos replicar a função em todo novo modulo que criamos, e para usa-la seria apenas chamar a função da api. API.notify();

16.4. Confirm

Utilizamos uma mensagem de confirmação de uma determinada ação, muito usada quando deseja excluir algum item do sistema, utilizamos uma mensagem de confirmação para que o usuário confirme aquela ação, utilizamos um dialog para apresentar a mensagem de confirmação, para utilizar ela, precisamos fazer 2 passos, o primeiro é criar a função no seu .js.twig.

Essa função recebe como parâmetro, a descrição do dialog, ou seja, a mensagem que será exibida para confirmação, e o segundo parâmetro é a ação que será executada, caso o usuário clique em confirm.

Para que possamos exibir a mensagem de confirmação, é precisar criar um arquivo ejs.twig, caso não saiba como criar, veja a seção …. O ejs deve ter o nome de confirm.dialog.ejs.twig

Com isso, só precisamos mudar na função que foi criada a cima, o layout para o seu modulo altere o ServiceCall, para o nome do seu modulo.

Obs. Essa função poderia ser colocada dentro da API, para que não precise replicar ela em todo modulo.

Attachments