A nova versão 4.0 do Magic xpa já chegou, e com ela um horizonte infinito 
de possibilidades para soluções web based.
Vamos conhecer o novo “Web Client Framework” nesta nova versão, que integra o Angular ao Magic xpa e permite executar soluções Magic a partir de um web browser, em qualquer plataforma (Linux, Windows, Mac, iOS, Android, …) cujos browsers sejam compatíveis com o Angular.
O “Web Client Framework” do Magic xpa versão 4.0 é um engine Angular , escrito em TypeScript e publicado no Ninja Pirate Mutants (NPM).
Ele permite que uma aplicação Angular gerada no Magic xpa Studio conecte-se a um Magic xpa Server, e execute a solução Magic xpa tendo um web browsers como front end.
Livre de qualquer instalação do lado do cliente.
A aplicação Angular que o Magic xpa Studio gera, é composta das instruções do tipo “lado cliente” dos programas Magic.
Existe um novo tipo de programa disponível para implementar isso, chamado Web Client:
Já a parte das regras de negócio, acessos a dados e recursos externos ( o “lado servidor”), é toda gerenciada e executada pelo Magic xpa Server.
O “Web Client Framework” do Magic xpa possui inteligência e recursos built-in tanto para executar a aplicação Angular da parte “cliente” da solução, quanto para conectar-se e comunicar-se com o Magic xpa Server que executará a parte “servidora” da mesma solução.
E traz ainda a vantagem do decoupling dos elementos visuais.
Uma vez que a aplicação Angular foi gerada a partir do projeto Magic, pelo Magic xpa Studio, os seus componentes (arquivos CSS, HTML e TS) podem ser editados e trabalhados por uma equipe distinta, especializada em design, UI e UX por exemplo.
Considerando agora, que tivemos esta visão geral da arquitetura e propósito do “Web Client Framework“, e já baixamos (download) o Magic xpa 4.0, vamos ver um pouco disso tudo na prática.
Preparação – Pré-Requisitos
Uma vez que você tenha concluído a instalação do Magic xpa versão 4.0, você receberá uma aviso como este:
Estas são ferramentas auxiliares ao Magic xpa, para geração e execução de soluções com o “Web Client Framework“.
Node.js
Baixe por exemplo deste endereço (https://nodejs.org/en/download/) o pacote MSI e instale-o na sua máquina. Escolha a versão x64 ou x86, cfe. for a sua versão do MS-Windows.
Como diz ali, é um runtime JavaScript baseado no Chrome V8, e necessário para execução do engine Angular.
Instale-o em qualquer pasta, e adicione a pasta do ‘node.exe‘ ao PATH do seu MS-Windows:
NOTA: Pode ser necessário reiniciar a máquina para efetivar a alteração no PATH.
NOTA: Prefira o Node 12.19.0
Para confirmar se a instalação está ‘OK’, abra o prompt do CMD como ‘Administrador’ e digite:
node -v
Será exibida a versão atual.
NPM
A princípio, não é preciso fazer download e instalação deste package manager. Ele já vem dentro da pasta ‘nodejs\node_modules\npm‘:
Mas se estiver usando uma versão menor do ‘Node’que não tenha esta facilidade, faça o procedimento de instalação também para o NPM.
Para confirmar se a instalação está ‘OK’, abra o prompt do CMD como ‘Administrador’ e digite:
npm version
Será exibida a versão atual.
Angular/CLI
É um utilitário disponível como pacote NPM. Por isso, os dois pré-requisitos acima precisam ser resolvidos, antes de instalar este terceiro. Abra o prompt do CMD em modo ‘Administrador’ e execute:
npm install -g @angular/cli
Isso efetuará o download e instalação do Angular/CLI, na última versão disponível.
Você pode repetir esta ação várias vezes. Cada nova ação, na verdade estará fazendo uma atualização local, com a última versão disponível lá no repositório NPM.
Se quiser baixar uma versão específica, também é possível. Por exemplo, se quiser baixar especificamente a versão 6.1.4, use:
npm install -g @angular/cli@6.1.4
Independente ter ter ou não feito a instalação manual do NPM, acrescente a pasta C:\Users\<seu_usuario>\AppData\Roaming\npm ao PATH do MS-Windows. Nela está o programa ‘ng.cmd‘ que é utilizado pelo Magic xpa Studio.
NOTA: Pode ser necessário reiniciar a máquina para efetivar a alteração no PATH.
Digite também o comando:
ng doc magic
Será aberto o seu web browser com pesquisa pelo termo ‘magic‘ na página ‘https://angular.io/api‘
Visual Studio Code
Este é realmente opcional. Você não necessita dele, porém, é uma ferramenta muito utilizada no mundo Angular e pode lhe ajudar na inspeção e compreensão do projeto gerado pelo Magic xpa Studio.
Se optar por baixá-lo e instalá-lo, acesse o site: https://code.visualstudio.com/download e escolha a opção para MS-Windows:
Caso tenha optado pela instalação do VSCode, precisa instalar também as seguintes extensões através do prompt do CMD como ‘Administrador’:
code --install-extension Angular.ng-template code --install-extension christian-kohler.path-intellisense code --install-extension CoenraadS.bracket-pair-colorizer code --install-extension EditorConfig.EditorConfig code --install-extension eg2.tslint code --install-extension formulahendry.auto-close-tag code --install-extension formulahendry.auto-rename-tag code --install-extension johnpapa.angular-essentials code --install-extension johnpapa.Angular2 code --install-extension johnpapa.winteriscoming code --install-extension jtlowe.vscode-icon-theme code --install-extension JuanBlanco.solidity code --install-extension msjsdiag.debugger-for-chrome code --install-extension natewallace.angular2-inline code --install-extension PKief.material-icon-theme code --install-extension robertohuertasm.vscode-icons code --install-extension vincaslt.highlight-matching-tag code --install-extension web-dave.vsc-angular-cli
Magic xpa 4 em Ação
Pronto. Com os pré-requisitos resolvidos, vamos conhecer e executar uma aplicação “Web Client” do Magic xpa.
Vamos neste artigo testar a aplicação “WebSamples“, que vem instalada gratuitamente na pasta “SampleProjects\WebSamples”.
Abrindo nosso projeto Magic, temos um nove menu chamado “Web”, específico para uso em soluções com o “Web Client Framework“:
Web Application Settings
São configurações gerais deste projeto, para geração da aplicação Angular contendo os programas Web Client do Magic, pelo Magic xpa Studio. Cada projeto Magic xpa possuirá o seu equivalente em Angular, codificado com TypeScript, CSS e HTML. Esta versão Angular do projeto Magic é que será executada no web browser.
Aqui se informa a pasta de geração da aplicação, onde estão as imagens a serem usadas na web, se a aplicação deve seguir o padrão ‘Material Design‘ e muito importante, qual o programa inicial Magic a ser executado quando esta aplicação for acessada no web browser.
Estas configurações ficam gravadas no arquivo Source\ProjProps.xml do projeto Magic.
Generate Web Application
Aqui é a opção para a efetiva geração da aplicação Angular deste projeto Magic, com os metadados dos programas e tarefas Web Client convertidos para TypeScript, CSS e HTML.
Sempre que alterarmos (editarmos) algo nestes programas, devemos regerar a versão Angular do projeto, através deste menu. Isso porque a aplicação gerada é um ‘espelho’ do projeto Magic xpa, convertido, porém não sincronizado. O que alteramos em um lado, não reflete automaticamente no outro.
A aplicação deste artigo, “WebSamples”, já vem pronta (codificada).
Executar uma solução com o “Web Client Framework” requer dois passos: geração e compilação/execução da aplicação Angular.
Passo 1 – Geração da versão “Angular” do projeto Magic
O primeiro passo é certificar-nos que o Main Program do nosso projeto Magic está devidamente ajustado para o Web Client Framework. Isso é feito nas propriedades do programa, aba Interface:
Como mostrado, a geração é feita através do menu Web => Generate Web Application.
Ao clicarmos o botão “Generate“, o Magic xpa Studio exportará os metadados dos programas selecionados para uma pasta de cache chamada “input” (que será criada neste momento) e chamará o ‘Node.js‘ para a geração da aplicação na pasta “output” (que será criada neste momento):
NOTA: este passo pode demorar, especialmente da primeira vez quando não há ainda nenhum cache do projeto gerado, e o pacote magic-xpa/angular não foi ainda baixado e instalado a partir do NPM. A quantidade de programas a converter para Angular também influencia neste tempo.
Uma subpasta como o nome configurado no menu “Web Application Settings” é criada dentro da “output” e ali estão contidos todos os componentes TypeScript, CSS e HTML particulares deste projeto Magic, bem como os fundamentais para a execução da aplicação Angular.
Algumas coisas vale a penas destacar:
Na pasta “output\<app_name>” está o arquivo “angular.json“, ponto de partida da aplicação Angular.
Nas pastas “output\<app_name>\src\assets” e “output\<app_name>\magic-metadata” estão os arquivos “server-config.json“, que contém os dados de como a aplicação Angular conseguirá encontrar o Magic xpa Server para conectar-se e comunicar-se com ele:
Na pasta “output\<app_name>\src\app\magic” haverá uma subpasta para cada program Magic exportado em convertido em Angular, com seus respectivos códigos CSS, TypeScript e HTML:
Estes são os componentes que, como mencionado anteriormente, podem ser trabalhados por um equipe paralela de profissionais, especialistas em UI e UX por exemplo.
Enquanto isso, outra equipe pode focar nas implementação das regras de negócio diretamente no Magic xpa Studio. Implementando assim o decoupling entre as camadas de apresentação e de lógica de execução.
Passo 2 – Compilação/Execução
A aplicação gerada no passo anterior, precisa agora ser “compilada”. Para tando, usando o prompt do CMD em modo ‘Administrador’, temos de ir até a pasta “output\<app_name>” e rodar o comando.
ng serve (com opção para gerar o 'source map')
ou
ng serve --sourceMap false (sem a geração do 'source map' da aplicação)
Este comando invocará o ‘Node.js‘ para compilar, otimizar e executar a nossa aplicação Angular:
NOTA: este passo pode demorar, especialmente na parte da otimização e se o ‘source map’ estiver ativado. O parâmetro ‘serve’ é um comando para o ng que tanto compila a aplicação Angular, quanto inicia um servidor HTTP para atender os acessos a esta aplicação.
Ao final da compilação/otimização, um web server é iniciado na porta local tcp 4200, e inicia a execução da aplicação.
No Magic xpa Studio, devemos colocar o projeto em execução (modo desenvolvedor). Isso é feito através da tecla F7 num programa específico que queremos executar, ou com CTRL+F7 para o projeto todo e usar o programa inicial do “Web Application Settings” como ponto de partida.
Através de um web browser, podemos agora acessar o endereço ‘http://localhost:4200/’, para executar a aplicação Magic xpa Angular:
NOTA: Lembre-se de ter liberação para a porta 4200 no seu firewall
Veja que a tela que aparece no web browser é exatamente a tela do nosso programa Web Client do Magic:
A aplicação Magic xpa Angular conectou-se até o Magic xpa Server:
E no primeiro acesso, o Magic xpa Server verificou quem era o programa inicial (Web Application Settings), para saber como servir a esta requisição.
Na sequência, processou os metadados do programa que definem o seu comportamento e aparência, para execução local no web browser.
Nossa lógica desenvolvida neste programa define que o conteúdo do primeiro campo deve formar o ‘tooltip‘ do segundo campo:
E isso é exatamente o que acontece na interface (troque o conteúdo do primeiro campo, tecle <tab> e passe o mouse sobre o segundo).
Observe também que o layout da página web obedece rigorosamente ao layout desenhado no formulário do programa no Magic xpa Studio:
As telas no Magic xpa Studio conterão apenas o esqueleto básico, a estrutura da página web. Todos os adereços visuais referentes a UI e UX da interface, devem ser colocados diretamente nos componentes visuais:
Assumindo a característica visual que desejarmos (html e css alterados):
É o benefício do decoupling mencionado acima.
Se você já é conhecedor do Rich Client Framework do Magic xpa (aplicações RIA), vai perceber que toda esta nova estrutura é muito semelhante a anterior.
Na prática, é quase como estarmos trocando um client RIA nativo do Magic xpa (Windows/.EXE, Android/.APK, iOS/.IPA, Windows10Phone/.APPX) por um client (app) Angular Magic xpa que executa em qualquer web browser compatível, mantendo a mesma arquitetura, componentes e comportamento do lado “servidor” (Magic xpa Server).
Venha para o novo mundo Magic xpa Angular, e descubra a revolução que o Magic trouxe ao ecossistema Angular.
Mais detalhes sobre esta nova plataforma/tecnologia estão também disponíveis no próprio help do produto instalado:
e no site: http://magicweb.io/
Para receber os artigos do Blog Magic Brasil em primeira mão no seu email, registre-se aqui