ÍNDICE

01. VISÃO GERAL

Este documento tem como objetivo auxiliar na instalação, configuração das ferramentas necessárias para o desenvolvimento de telas em PO-UI e como abrir a tela desenvolvida em no Protheus. 

02. INSTALAÇÃO

2.1. NODE JS

O que é o Node JS? Falando bem resumidamente ele é um software que permite a execução de códigos JavaScript, ou seja, podemos criar aplicações Web e fazer com que o Node JS execute todos os nossos arquivos para verificarmos e testarmos o nosso desenvolvimento.

Para realizar a instalação baixe o instalador disponibilizado no link abaixo:
https://nodejs.org/pt-br/download/

Caso seja necessário utilizar uma versão antiga do Node, segue o link de donwload de outras versões:
https://nodejs.org/pt-br/download/releases
 

Realize a instalação normal de qualquer software, selecionando o local que será instalado e posteriormente clicando em next, next, next até chegar no final da instalação.

Para verificar se o Node JS foi instalado corretamente abra o Prompt ou utilize o terminal do VS Code e execute o comando "node -v".
Deverá ser exibida a versão do Node.
Por exemplo:
v16.15.1

Caso precisem entender um pouco mais sobre o Node.js, acesse os links abaixo:
https://nodejs.org/en/about/
https://nodejs.org/en/docs/guides/

2.2. ANGULAR CLI

O que é o Angular CLI? Basicamente ele é uma ferramenta que nos ajuda no desenvolvimento de aplicações Angular. E o que é o Angular? O Angular é um framework baseado em TypeScript de aplicações WEB.

Para instalar o Angular CLI, não existe um instalador, teremos que fazer a instalação através de comandos de linhas utilizando o terminar do VS Code ou o próprio Prompt.

Abra o Prompt ou utilize o terminal do VS Code e execute o comando abaixo para instalar o Angular CLI.
"npm install -g @angular/cli"
Para verificar se o Angular CLI foi instalado execute o comando "ng v". Deverá ser exibida os dados do Angular CLI, conforme a imagem abaixo:

Caso precisem entender um pouco mais sobre o Angular CLI, acesse o link abaixo:
https://angular.io/guide/what-is-angular#angular-cli

03. CRIANDO UM NOVO PROJETO

Com o Prompt aberto ou o terminal do VS Code seguiremos com os passos abaixo:

Quando criamos um projeto, automaticamente será criada uma pasta no diretório em que estamos posicionado com o nome do nosso projeto e mais alguns arquivos dentro que serão utilizado em nosso projeto. Por este motivo antes da instalação verifique se você está posicionado na pasta desejada para a criação do projeto. Por exemplo se você desejar criar o projeto com o nome PO-UI dentro da pasta C:/Totvs, utilize o comando "cd" para posicionar na pasta Totvs ("cd C:/Totvs") e posteriormente execute o comando abaixo:
"ng new PO-UI --skip-install"

O que está após o ng new será o nome do nosso projeto, no caso PO-UI.

Ao executar o ng new PO-UI --skip-install, teremos a seguinte pergunta "Would you like to add Angular routing? (y/N)", podemos responder com Sim (y).

Posteriormente teremos uma pergunta sobre os estilos "Which stylesheet format would you like to use?", utilizando a seta para cima ou para baixo, vamos selecionar a opção CSS.

Após responder as perguntas, a instalação continuará e para o nosso projeto criado teremos o seguinte diretório C:/Totvs/PO-UI, onde foi criada a pasta PO-UI e dentro dessa pasta teremos todos os arquivos necessários para a continuação da instalação de dependências (PO-UI, THF, rxjs e etc).

Agora será necessário alterar o arquivo Packge.json, localizado na raiz do nosso projeto, que no caso é a pasta C:/Totvs/PO-UI, para incluir ou alterar as versões do Angular e outros componentes para as versões compatíveis com o Protheus-Lib-Core. Para verificar as versões compatíveis com o Protheus-Lib-Core, acesse abaixo link na aba DEPENDENCIES:
https://npm.totvs.io/-/web/detail/protheus-lib-core/

A configuração deverá ficar semelhante ao trecho abaixo:
  "dependencies": {
    "@angular/animations": "^14.0.5",
    "@angular/common": "^14.0.5",
    "@angular/compiler": "^14.0.5",
    "@angular/core": "^14.0.5",
    "@angular/forms": "^14.0.5",
    "@angular/platform-browser": "^14.0.5",
    "@angular/platform-browser-dynamic": "^14.0.5",
    "@angular/router": "^14.0.5",
    "@po-ui/ng-components": "^14.0.5",
    "@totvs/po-theme": "^3.0.0",
    "latest-version": "^7.0.0",
    "rxjs": "~7.5.6",
    "rxjs-compat":"^6.6.3",
    "subsink": "^1.0.2",
    "tslib": "^2.4.0",
    "zone.js": "^0.11.4"
  },
  "devDependencies": {
    "@angular-devkit/build-angular": "^14.0.5",
    "@angular/cli": "^14.0.5",
    "@angular/compiler-cli": "^14.0.5",
    "@types/jasmine": "^3.7.7",
    "@types/node": "^15.12.4",
    "jasmine-core": "^3.7.1",
    "karma": "^6.3.12",
    "karma-chrome-launcher": "^3.1.0",
    "karma-coverage": "^2.0.3",
    "karma-jasmine": "^4.0.1",
    "karma-jasmine-html-reporter": "^1.6.0",
    "typescript": "4.6.2"
  }
  
^(versão) = Compatível com a versão definida, por exemplo "@angular/animations": "^14.0.5", ao executar o comando install o projeto poderá utilizar uma versão mais recente que seja compatível com a versão 14.0.5
~(versão) = Aproximadamente ou equivalente à versão definida, por exemplo "@angular/animations": "~14.0.5", ao executar o comando install o projeto poderá utilizar uma versão mais recente, como por exemplo 14.0.10, mesmo que exista a versão 15.x.x, ele irá respeitar a versão definida, no caso 14.x.x.

Se não existir qualquer sinal antes da versão do componente, será usada exatamente a versão definida.
  
Para mais informações de como preencher o packge.json acesse o link abaixo:
https://docs.npmjs.com/cli/v7/configuring-npm/package-json

04. INSTALANDO AS DEPENDÊNCIAS NO PROJETO 

Após a alteração do arquivo package-json devemos executar o comando "npm install" para que sejam instalados os componentes que serão utilizados em nosso projeto e o resultado será semelhante a imagem abaixo:

Após a execução do comando "npm Install" é recomendado executar o comando "npm audit fix" para corrigir alguns Warnings simples de resolver, caso exista.

05. IMPORTANDO O PO-UI E THF

Após a instalação do projeto, devemos importar os componentes do PO-UI e THF para dentro do nosso projeto e assim utilizarmos no desenvolvimento de novas telas em PO-UI para o Protheus.

5.1. PO-UI

O que é o PO-UI? Basicamente são componentes visuais que podemos utilizar em nosso projeto, por exemplo temos disponíveis diversos componentes como Menu, Campo de Data, Cards e etc, que já foram criados e que podemos utilizar em nossas telas. Para mais informações sobre o PO-UI acesse o link abaixo:
https://po-ui.io/guides/getting-started

Para realizar a importação do PO-UI em nosso projeto utilize o comando abaixo:
"ng add @po-ui/ng-components@^14.0.5"

Ao executar o comando será exibida uma mensagem avisando que será instalado e executado o po-ui/ng-components@^14.0.5 e perguntando se desejamos continuar. Responda a pergunta com "Y". Posteriormente será perguntado se desejamos incluir uma estrutura inicial em nosso projeto com menu lateral, página e toolbar, utilizando componentes do PO-UI, caso desejar, apenas informe: "Y".

5.2. THF

O PO-UI possui seu estilo próprio de cores, porém como iremos desenvolver uma tela para o Protheus, temos que utilizar as cores da Totvs e para isso iremos usar o tema do THF.

Para a instalação do THF utilize o comando abaixo:
"npm i --save @totvs/po-theme@^14.2.1"

Para mais informações do THF acesse o link abaixo:
https://thf.totvs.com.br/home

5.3. UTILIZANDO O PO-UI E THF

Após importar tanto os componentes do PO-UI como o tema do THF, teremos que dizer para o nosso projeto que ele deverá usar o tema do THF ao invés de utilizar do PO-UI, para isso basta alterar o arquivo angular.json, localizado na pasta raiz de nosso projeto, e alterar todas as tags "styles", colocando os seguintes conteúdos nela.
"./node_modules/@po-ui/style/css/po-theme-core.min.css",
"./node_modules/@totvs/po-theme/css/po-theme-default.min.css"

Exemplo:

06. PROTHEUS-LIB-CORE

6.1. INSTALAÇÃO

O Protheus-Lib-Core é uma biblioteca desenvolvida pelo frame que nos ajuda e muito em nosso desenvolvimento em telas em PO-UI que serão abertas no Protheus. Uma das funcionalidades principais seria o IP, porta e informações de autenticação do serviço Rest que são concatenados/incluídos com o nome de alguma API do Protheus ao tentar consumir a API. Dessa maneira não precisamos nos preocupar em saber qual é a configuração que o cliente está utilizando para o serviço Rest e enviar as informações de autenticação. O Protheus-Lib-Core irá buscar essas informações e sempre que a tela for chamar alguma API do Protheus, temos apenas que informar o nome dela, o restante será preenchido automaticamente pela lib-core ao chamar a API.

Para realizar a instalação do Protheus-Lib-Core, teremos que primeiro fazer uma autenticação no https://npm.totvs.io/ utilizando nosso usuário, senha da rede e nosso e-mail. Para isso execute o comando "npm login --registry https://npm.totvs.io --auth-type=legacy", será solicitado os dados mencionados anteriormente. 

Após o login, execute o comando 
"npm i protheus-lib-core --registry https://npm.totvs.io"

Caso não tenha gerado algum erro, o Protheus-Lib-Core foi instalado com sucesso, porém para ele pegar o endereço, porta
e informações de autenticação do serviço Rest configurado, teremos que fazer 2 coisas antes.

1º Criar o arquivo appConfig.json dentro da pasta /assets/data/, caso a pasta data não exista, ela deverá ser criada.
Exemplo do arquivo appConfig.json:
{
  "name": "RH-JORNADAS",
  "version": "1.1.0",
  "api_baseUrl": "/"
}

2º No módulo do Angular que for consumir as APIs do Protheus teremos que importar o Protheus-Lib-Core. No desenvolvimento de telas em PO-UI, nem sempre uma página irá consumir as APIs do Protheus, por este motivo não há a necessidade de importar o Portheus-Lib-Core no módulo principal de nosso projeto. Vamos supor que temos duas telas, Login e a Home, onde a Home diz apenas Hello World, neste cenário precisaremos apenas do Protheus-Lib-Core para o login, para autenticar no Protheus o usuário e senha informado, por isso no módulo da tela de Login iremos incluir o Protheus-Lib-Core e no módulo principal (app.module.ts) e da tela Home não precisaremos fazer essa importação.

Então no imports do módulo da tela de login, teremos a seguinte configuração:
  imports: [
    BrowserModule,
    AppRoutingModule,
    PoModule,
    RouterModule.forRoot([]),
    PoTemplatesModule,
    ProtheusLibCoreModule            --------> módulo do Protheus-Lib-Core
  ]

Após esse procedimento a tela em PO-UI já estará pronta para ser aberta pelo Protheus, sem a necessidade de informarmos o IP, Porta e informações de autenticação do serviço Rest, caso a tela desenvolvida consuma alguma API do Protheus.

Para mais informações sobre o arquivo appConfig.json acesse o link abaixo:
https://tdn.totvs.com/display/framework/FwCallApp+-+Abrindo+aplicativos+Web+no+Protheus

6.2. ERRO DE DEPENDÊNCIA

Como dito anteriormente temos que nos atentar com as versões do Angular, PO-UI e THF para que elas sejam compatíveis com o Protheus-Lib-Core. Caso seja apresentado algum erro de dependência, teremos a seguinte mensagem no terminal:

PS C:\Totvs\PO-UI> npm i protheus-lib-core --registry https://npm.totvs.io
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree    --------------> erro de depêndencia 
npm ERR!
npm ERR! While resolving: [email protected]
npm ERR! Found: @po-ui/[email protected]    --------------> Versão instalada em nosso projeto
npm ERR! node_modules/@po-ui/ng-components
npm ERR!   @po-ui/ng-components@"^5.22.7" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer @po-ui/ng-components@"5.4.0" from [email protected]    --------------> Versão compatível com o Protheus-Lib-Core
npm ERR! node_modules/protheus-lib-core
npm ERR!   protheus-lib-core@"*" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

Basicamente esse erro significa que, estamos com uma versão diferente da suportada pelo Protheus-Lib-Core e com isso a instalação
não foi finalizada. Neste exemplo estamos com a versão 5.22.7 do PO-UI, e o Protheus-Lib-Core é compatível com uma versão anterior,
no caso a 5.4.0.

Para resolver esse problema de compatibilidade iremos reinstalar as versões corretas dos componentes de nosso projeto. Para isso será necessário excluir a pasta node_modules, que está localizada na raiz do projeto, e excluir o arquivo packge-lock.json. Após isso teremos que alterar o arquivo o packge.json informando a versão correta, que neste exemplo ficaria dessa maneira:
"dependencies": {
"@angular/animations": "14.0.5",
"@angular/common": "14.0.5",
"@angular/compiler": "14.0.5",
"@angular/core": "14.0.5",
"@angular/forms": "14.0.5",
"@angular/platform-browser": "14.0.5",
"@angular/platform-browser-dynamic": "14.0.5",
"@angular/router": "14.0.5",
"@po-ui/ng-components": "5.4.0", ----------------> componente com erro alterado para a mesma versão suportada pelo Protheus-Lib-Core
"@po-ui/ng-templates": "5.4.0",
"@totvs/po-theme": "^3.0.0",
"latest-version": "^7.0.0",
"rxjs": "^6.4.0",
"tslib": "^2.1.0",
"zone.js": "^0.11.4"
},

Agora teremos que executar novamente o comando "npm install". Após finalizar a instalação, caso não aconteça algum erro, o arquivo packge-lock.json e a pasta node_modules com os arquivos instalados serão criados novamente. Podemos verificar se as versões que estão em nosso projeto acessando o arquivo packge-lock.json. Existe uma outra maneira de verificar, com mais precisão a versão instalada em nosso projeto, este outro jeito será útil quando não definimos exatamente a versão de algum componente que instalamos, como por exemplo quando utilizamos o "^" ou "~" antes da versão.

Para verificar a versão específica de um componente, basta utilizar o comando "npm ls nome do componente"

Exemplo:
"npm ls @angular/animations"

Resultado:
[email protected] C:\Totvs\PO-UI
├── @angular/[email protected]
├─┬ @angular/[email protected]
│ └── @angular/[email protected] deduped
├─┬ @po-ui/[email protected]
│ └── @angular/[email protected] deduped
├─┬ @po-ui/[email protected]
│ └── @angular/[email protected] deduped
└─┬ [email protected]
├── @angular/[email protected] deduped
└─┬ @angular/[email protected]
└── @angular/[email protected] deduped

Caso todos os componentes sejam compatíveis com o Protheus-Lib-Core, tente instalar novamente repetindo o processo de autenticação seguido do comando de instalação.

"npm login --registry https://npm.totvs.io --auth-type=legacy"
"npm i protheus-lib-core --registry https://npm.totvs.io"

Se acontecer algum erro de dependência novamente, todo o processo comentado neste tópico deverá ser realizado novamente.

07. VISUALIZANDO A TELA

Após realizar todo o processo de instalação, importação do PO-UI, THF e o Protheus-Lib-Core, iremos agora visualizar a nossa primeira tela, que foi criada automaticamente pelo PO-UI. Para isso execute o comando "ng serve --o", este comando (ng serve) indica para o Angular CLI que ele deve iniciar o nosso projeto, em outras palavras é como se a gente estivesse iniciando o appserver, e após o "ng serve" foi colocado o "--o" que indica que ao término na inicialização quero que o Angular CLI abra automaticamente no navegador nossa primeira tela.

Em caso de sucesso, ou seja, se não teve nenhum erro na inicialização do nosso projeto teremos o seguinte resultado:

E a página inicial do nosso projeto será aberta no navegador automaticamente graças ao "--o".

Agora já podemos realizar o desenvolvimento da tela. Como um exemplo simples, iremos alterar o conteúdo da página com o famoso e tradicional "Hello World". Para isso abra o arquivo app.component.html localizado no caminho "C:\Totvs\PO-UI\src\app".

Ao alterar e salvar qualquer arquivo de nosso projeto, o Angular CLI compila automaticamente e caso não exista um erro não teremos qualquer mensagem no terminal.

E ao voltarmos para a página, ela será recarregada automaticamente com o novo conteúdo.

08. COMPILANDO NOSSO PROJETO NO PROTHEUS

Após realizar todo o desenvolvimento da tela em PO-UI, então teremos que gerar um arquivo do nosso projeto, para que seja possível abrir o mesmo pelo Protheus. Basicamente iremos gerar um único arquivo contendo todos os programas criados no desenvolvimento do nosso projeto, para que ele seja compilado no RPO do Protheus e posteriormente conseguirmos abri-lo pelo ERP. Antes de tudo devemos verificar o arquivo angular.json, ele está localizado na pasta raiz de nosso projeto, no caso C:/Totvs/PO-UI. Neste arquivo json, teremos a propriedade "outputPath", basicamente o conteúdo dela irá informar para o Angular CLI onde deve ser salvo a pasta com todos os arquivos do nosso projeto e com qual nome.

No exemplo abaixo foi alterado apenas o nome da pasta com os arquivos que iremos gerar.

Uma outra alteração que teremos que fazer no arquivo angular.json, é alterar o tamanho limite definido na propriedade "budgets", basicamente o Angular preza por performance, então ao gerar o nosso projeto para que ele seja executado, o angular faz uma validação com o tamanho total de nosso projeto com os conteúdos do "budgets", caso ultrapasse ele não irá gerar nosso projeto. Por padrão a quantidade definida nos budgets é muito baixa, por isso iremos aumentar um pouco para que seja possível gerar o nosso projeto.

Localize a propriedade "budgets" no arquivo angular.json e altere o conteúdo do maximumWarning e maximumError.

maximumWarning: Limite que exibe um Warning ao gerar o nosso projeto. Caso nosso projeto ultrapasse 8 mb será exibido um warning, porém o projeto será gerado.
maximumError: Limite que dá erro ao gerar nosso projeto. Caso nosso projeto ultrapasse 10 mb será exibido um erro e nosso projeto não será gerado.

Após realizar todas as alterações no arquivo angular.json, iremos executar o comando "ng build".

Após o comando "ng build" podemos ver que nosso projeto inteiro tem 1.15mb e como não foram ultrapassados os limites do budgets não houve nenhum warning ou erro o gerar o projeto.

Ao abrir a pasta gerada pelo comando build, que foi definida na propriedade "outputPath" do angular.json, temos nosso projeto gerado.

Agora precisaremos zipar a pasta teste.

Posteriormente iremos alterar a extensão de .zip para .app.

Agora com o arquivo .app basta apenas compilarmos o arquivo no RPO do Protheus. Para isso teremos que realizar algumas alterações no VS Code para que seja possível realizar a compilação.

1º Acesse as configurações do VS Code (File→Preferences→Settings) e será aberta uma tela conforme a imagem abaixo:

2º Em Extensions localize o extensão da Totvs, localize a opção "Extensions Allowed" e clique em “Edit in settings.jason” 

3º No arquivo settings.json aberto inclua a extensão .app.

Pronto, após esse processo já é possível realizar a compilação do nosso projeto .app no RPO do Protheus.

09. ABRINDO O .APP NO PROTHEUS

Depois de compilado o .app no RPO, teremos que criar uma rotina que faça a abertura da tela em PO-UI no Protheus. Para isso temos que utilizar a função FwCallApp() passando como parâmetro o nome do .app.

Segue abaixo uma rotina criada apenas para exemplificar a chamada da função.

Rotina: POUI.PRX

#INCLUDE "PROTHEUS.CH"

Function POUI()
    FwCallApp("teste")
Return

Compilação da rotina POUI.PRX no RPO.

Incluída a rotina no Menu do Protheus.

Ao acessar a rotina pelo menu criado, nossa tela em PO-UI será aberta.

<!-- esconder o menu --> 


<style>
div.theme-default .ia-splitter #main {
    margin-left: 0px;
}
.ia-fixed-sidebar, .ia-splitter-left {
    display: none;
}
#main {
    padding-left: 10px;
    padding-right: 10px;
    overflow-x: hidden;
}

.aui-header-primary .aui-nav,  .aui-page-panel {
    margin-left: 0px !important;
}
.aui-header-primary .aui-nav {
    margin-left: 0px !important;
}
</style>