Melhorar e arquivar o componente Web do Oracle JET

Introdução

Um componente Web é uma parte reutilizável da interface do usuário que você pode incorporar como um elemento HTML personalizado em seu aplicativo Web. Os componentes Web podem conter componentes do Oracle JavaScript Extension Toolkit (Oracle JET), outros componentes Web, HTML, JavaScript, TypeScript e Cascading Style Sheets (CSS). Você usa as ferramentas do Oracle JET para criar o componente Web e pode usar um modelo inicial do Oracle JET para gerar os arquivos HTML e Typescript ou JavaScript que você modifica para adicionar e configurar o componente Web.

No tutorial anterior, você criou um componente da Web que exibe quatro campos de texto de entrada. Neste tutorial, você aprenderá a alterar o campo ID do Item para um campo somente leitura, adicionar um conversor de moeda ao campo Preço do Item e adicionar um validador de tamanho ao campo Descrição do Item. Para transmitir valores a esses campos, defina os atributos para os quatro campos de texto de entrada na origem HTML do aplicativo Web. Os atributos usados devem ter uma propriedade correspondente definida no arquivo de metadados do componente Web. Você pode passar valores estáticos para os atributos ou usar a sintaxe de expressão vinculada a dados para a vinculação de dados unidirecional ou bidirecional entre o aplicativo Web e o componente Web.

Objetivos

Neste tutorial, você aperfeiçoará o componente Web com recursos adicionais em um aplicativo Web Oracle JET. Você também aprenderá a empacotar o componente Web e prepará-lo para compartilhar com outro aplicativo.

Pré-requisitos

Um ambiente de desenvolvimento configurado para criar aplicativos Oracle JET, com o runtime JavaScript, Node.js e a interface de linha de comando da release mais recente do Oracle JET instalada
Conclusão do tutorial anterior nesta programação de estudo, para que você tenha criado o componente Web demo-update-item na pasta JET_Web_Component_Application

Tarefa 1: Editar ID do Item para Somente Leitura

O campo ID do Item no seu componente da Web deve ser somente leitura. Para fins de acessibilidade, substitua o elemento HTML personalizado oj-input-text do campo ID do Item pelo elemento HTML personalizado oj-label-value. O elemento oj-label-value define um slot que usa o elemento oj-bind-text para modificar o campo ID do Item como somente leitura.

Navegue até o diretório JET_Web_Component_Application/src/ts/jet-composites/demo-update-item e abra o arquivo demo-update-item-view.html em um editor.

Localize o elemento HTML personalizado oj-input-text com o atributo value="ID number" e substitua o elemento oj-input-text pelo elemento oj-label-value.

<oj-form-layout id="form-container" label-edge="[[labelEdge]]">
  <oj-label-value>
    <oj-label slot="label">Item ID</oj-label>
    <div slot="value">
      <oj-bind-text value="ID number"></oj-bind-text>
    </div>
  </oj-label-value>
  <oj-input-text value="Name" label-hint="Item Name"></oj-input-text>
. . . 
</oj-form-layout>

Salve o arquivo demo-update-item-view.html.

Seu código demo-update-item-view.html deve ser semelhante a readonly-itemid.txt.
Navegue até o diretório JET_Web_Component_Application/src/ts/jet-composites/demo-update-item e abra o arquivo demo-update-item-viewModel.ts em um editor.

No arquivo demo-update-item-viewModel.ts, importe o módulo do carregador ojs/ojlabelvalue após a entrada que importa o módulo ojs/ojinputtext.

"use strict";

import * as ko from "knockout";
import componentStrings = require("ojL10n!./resources/nls/demo-update-item-strings");
import Context = require("ojs/ojcontext");
import Composite = require("ojs/ojcomposite");
import "ojs/ojknockout";
import * as ResponsiveUtils from "ojs/ojresponsiveutils";
import * as ResponsiveKnockoutUtils from "ojs/ojresponsiveknockoututils";
import "ojs/ojformlayout";
import "ojs/ojinputtext";
import "ojs/ojlabelvalue";

Salve o arquivo demo-update-item-viewModel.ts.
Na janela do terminal, altere para o diretório JET_Web_Component_Application e execute o aplicativo.
```
$ ojet serve
```
O browser exibe o componente Web com os quatro campos de texto de entrada na guia Painel do seu aplicativo Web. O campo ID do Item agora é somente para leitura.

Descrição da ilustração form-wc-itemid-readonly.png
Deixe a janela do terminal e a janela ou guia do browser que exibe seu aplicativo Web aberto.

O comando ojet serve permite fazer alterações no código do aplicativo que são refletidas imediatamente no browser.

Tarefa 2: Adicionar um Conversor de Moeda

Use um conversor de moeda para o campo Preço do item.

Navegue até o diretório JET_Web_Component_Application/src/ts/jet-composites/demo-update-item e abra o arquivo demo-update-item-view.html em um editor.

Localize o elemento HTML personalizado oj-input-text com o atributo value="Price" e atualize-o para usar um conversor de moeda que definiremos em uma etapa posterior. Inserimos 00 em vez de Price como o valor de espaço reservado da propriedade value porque o conversor requer um número válido em vez de uma string.

<oj-form-layout id="form-container" label-edge="[[labelEdge]]">
...
<oj-input-text value="Name" label-hint="Item Name"></oj-input-text>
<oj-input-text value="00" 
               help.instruction="enter an amount with or without grouping separator"
               converter="[[currency]]" 
               label-hint="Item Price">
         </oj-input-text> 
<oj-input-text value="Description" label-hint="Item Description"></oj-input-text>
</oj-form-layout>   

Salve o arquivo demo-update-item-view.html. Seu código demo-update-item-view.html deve ser semelhante a currency-code-html.txt.
Navegue até o diretório JET_Web_Component_Application/src/ts/jet-composites/demo-update-item e abra o arquivo demo-update-item-viewModel.ts em um editor.

Na parte superior do arquivo demo-update-item-viewModel.ts, importe IntlNumberConverter do módulo ojs/ojconverter-number:

"use strict";

import * as ko from "knockout";
. . .
import "ojs/ojinputtext";
import "ojs/ojlabelvalue";
import { IntlNumberConverter } from "ojs/ojconverter-number";

Na classe ViewModel, adicione um campo de moeda para o conversor de moeda que você inicializará na próxima etapa.

export default class ViewModel implements Composite.ViewModel<Composite.PropertiesType> {
   busyResolve: (() => void);
   . . . 
   currency: IntlNumberConverter;

constructor(context: Composite.ViewModelContext<Composite.PropertiesType>) {
. . .       

No método constructor() após o exemplo de entradas observáveis, adicione o conversor de moeda.

constructor(context: Composite.ViewModelContext<Composite.PropertiesType>) {        
   . . .
   this.res = componentStrings["demo-update-item"];

   this.currency = new IntlNumberConverter({
      style: "currency",
      currency: "USD ",
      currencyDisplay: "code",
   });

Salve o arquivo demo-update-item-viewModel.ts.

Seu código demo-update-item-viewModel.ts deve ser semelhante a currency-code-ts.txt.
Retorne ao browser para exibir as alterações no seu aplicativo Web.
Informe o preço no campo Preço do Item e pressione Enter para verificar as alterações.

Descrição da ilustração form-wc-currency-converter.png

O preço informado mostra um prefixo USD. Se você informar um valor não numérico, o campo Preço do Item exibirá um erro.
Deixe a janela do terminal e a janela ou guia do browser que exibe seu aplicativo Web aberto.

O comando ojet serve permite fazer alterações no código do aplicativo que são refletidas imediatamente no browser.

Tarefa 3: Adicionar um Validador de Tamanho

Use um validador de tamanho para o campo Descrição do Item.

Navegue até o diretório JET_Web_Component_Application/src/ts/jet-composites/demo-update-item e abra o arquivo demo-update-item-view.html em um editor.

Localize o elemento HTML personalizado oj-input-text com o atributo value="Description" e atualize-o para usar um validador de tamanho que definiremos em uma etapa posterior.

   
<oj-form-layout id="form-container">
...
<oj-input-text value="00" 
            help.instruction="enter an amount with or without grouping separator"
            converter="[[currency]]" 
            label-hint="Item Price">
      </oj-input-text> 
<oj-input-text
     value="{{lengthValue1}}" validators="[[validators]]"
     placeholder="Enter a description of 5-50 characters"
     label-hint="Item Description"
   ></oj-input-text>
</oj-form-layout>
   

Salve o arquivo demo-update-item-view.html.

Seu código demo-update-item-view.html deve ser semelhante a validator-code-html.txt.
Navegue até o diretório JET_Web_Component_Application/src/ts/jet-composites/demo-update-item e abra o arquivo demo-update-item-viewModel.ts em um editor.

Na parte superior do arquivo demo-update-item-viewModel.ts, importe AsyncLengthValidator do módulo ojs/ojasyncvalidator-length:

import * as ko from "knockout";
. . .
import { IntlNumberConverter } from "ojs/ojconverter-number";
import AsyncLengthValidator = require("ojs/ojasyncvalidator-length");

Na classe ViewModel, adicione campos para os observáveis Knockout que você inicializará na próxima etapa.

export default class ViewModel implements Composite.ViewModel<Composite.PropertiesType> {
 busyResolve: (() => void);
 . . . 
 currency: IntlNumberConverter;
 lengthValue1: ko.Observable<string>;
 validators: ko.ObservableArray<AsyncLengthValidator<string>>;

No método constructor após o conversor de moeda, adicione o validador de tamanho.

constructor(context: Composite.ViewModelContext<Composite.PropertiesType>) {        
   . . .
   this.res = componentStrings["demo-update-item"];

   this.currency = new IntlNumberConverter({
      style: "currency",
      currency: "USD ",
      currencyDisplay: "code",
   });

   this.lengthValue1 = ko.observable("");
   this.validators = ko.observableArray([
      new AsyncLengthValidator({ min: 5, max: 50 }),
    ]);

O validador de tamanho define um tamanho mínimo de caracteres de 5 caracteres e um tamanho máximo de 50 caracteres para o campo Descrição do Item.

Salve o arquivo demo-update-item-viewModel.ts.

Seu código demo-update-item-viewModel.ts deve ser semelhante a final-demo-update-item-viewModel-ts.txt.
Retorne ao browser para exibir as alterações no seu aplicativo Web.
Informe uma descrição no campo Descrição do Item e pressione Enter e pressione Tab para limpar a dica de ferramenta.

Descrição da ilustração form-wc-length-validator.png

Se a descrição for maior que o intervalo definido, o campo Descrição do Item exibirá um erro.
Deixe a janela do terminal e a janela ou guia do browser que exibe seu aplicativo Web aberto.

O comando ojet serve permite fazer alterações no código do aplicativo que são refletidas imediatamente no browser.

Tarefa 4: Definir os Metadados do Componente Web

O arquivo de metadados do componente Web define as propriedades obrigatórias do componente Web. Cada campo de texto de entrada do componente Web deve ter uma propriedade associada que fará write back de atualizações do componente Web.

Navegue até o diretório JET_Web_Component_Application/src/ts/jet-composites/demo-update-item e abra o arquivo component.json em um editor.

Defina as propriedades de metadados displayName e description.

{
"name": "demo-update-item",
"version": "1.0.0",
"jetVersion": "^12.0.0",
"displayName": "demo-update-item",
"description": "A Web Component with form layout",
...
}

Abaixo da propriedade de metadados description, use a convenção de nomeação de maiúsculas e minúsculas para definir as propriedades vinculadas aos campos na exibição do componente Web.
```
"description": "A Web Component with form layout",
"properties": {
   "itemId": {
      "type": "number"
   },
   "itemName": {
      "type": "string",
      "description": "Description for the item-name attribute",
      "writeback": true
   },
   "itemPrice": {
      "type": "number",
      "writeback": true
   },
   "itemDesc": {
      "type": "string",
      "writeback": true
   }
},
```
A propriedade writeback definida como true garante que essas propriedades receberão atualizações do componente Web que faz referência à propriedade em uma expressão de vinculação de dados bidirecional.
Salve o arquivo component.json.

Seu código component.json deve ser semelhante a component-json.txt.

Tarefa 5: Definir os Atributos e os Valores de Atributo

Os atributos do elemento do componente Web podem fazer referência às propriedades declaradas no arquivo de metadados do componente Web. Na origem HTML do aplicativo Web, as referências de propriedade aparecem como nomes de atributo de elemento HTML sem distinção entre maiúsculas e minúsculas com hifens.

Navegue até o diretório JET_Web_Component_Application/src/ts/views e abra o arquivo dashboard.html em um editor.

No elemento demo-update-item, defina os atributos com valores estáticos para os quatro campos de texto de entrada.

<div class="oj-hybrid-padding">
   <div class="oj-panel oj-sm-margin-2x demo-mypanel">
      <h1 class="oj-header-border">Update Item Details</h1>
      <div>
         <demo-update-item item-id="34" 
                           item-name="John" 
                           item-price="3434.55" 
                           item-desc="This is an updated item">
                     </demo-update-item>
      </div>
   </div>
</div>

Salve o arquivo dashboard.html.

Tarefa 6: Definir a Exibição do Componente Web

Você pode acessar qualquer propriedade definida no arquivo de metadados do componente Web usando a variável $properties do contexto de vinculação de exibição.

Navegue até o diretório JET_Web_Component_Application/src/ts/jet-composites/demo-update-item e abra o arquivo demo-update-item-view.html em um editor.

Nos elementos HTML personalizados do elemento oj-form-layout, vincule os atributos value às propriedades definidas no arquivo component.json usando a variável $properties.

   
<oj-form-layout id="form-container" label-edge="[[labelEdge]]">
. . .
<div slot="value">
      <oj-bind-text value="[[$properties.itemId]]"></oj-bind-text>
  </div>
</oj-label-value>  
   <oj-input-text value="{{$properties.itemName}}" label-hint="Item Name"></oj-input-text>
   <oj-input-text value="{{$properties.itemPrice}}" 
      help.instruction="enter an amount with or without grouping separator"
      ...> 
   </oj-input-text>
   <oj-input-text
      value="{{$properties.itemDesc}}"
      . . .>
   </oj-input-text>
</oj-form-layout>
   

Para definir valores de atributo, use a sintaxe [[]] para definir o bind de dados unidirecional e a sintaxe {{}} para o bind de dados bidirecional.

Salve o arquivo demo-update-item-view.html.

Seu código demo-update-item-view.html deve ser semelhante a final-demo-update-item-view-html.txt.
Retorne ao browser para exibir as alterações no seu aplicativo Web.

O navegador exibe o componente da Web com os valores estáticos nos quatro campos de texto de entrada.
Feche a janela ou guia do browser que exibe seu aplicativo Web em execução.
Na janela do terminal, pressione Ctrl+C e, se solicitado, digite y para sair do job em batch de ferramentas do Oracle JET. Feche a janela do terminal.

Tarefa 7: Arquivar o Componente Web

Depois de configurar seu componente da Web, prepare o componente da Web para outros aplicativos.

Abra uma janela de terminal, altere para o diretório JET_Web_Component_Application e execute o comando ojet package component com o nome do componente, demo-update-item, como parâmetro de comando:

$ ojet package component demo-update-item

O Oracle JET empacota o conteúdo do diretório JET_Web_Component_Application/src/ts/jet-composites/demo-update-item em um arquivo ZIP (demo-update-item_1-0-0.zip) que ele cria no diretório JET_Web_Component_Application/dist. Como parte da tarefa de empacotamento, o Oracle JET transfere o código TypeScript no diretório JET_Web_Component_Application/src/ts/jet-composites/demo-update-item para o código JavaScript. Se, por exemplo, você abrir o arquivo JET_Web_Component_Application/dist/demo-update-item_1-0-0.zip, perceberá que ele contém um arquivo demo-update-item-viewModel.js que o conjunto de ferramentas Oracle JET transpilou do arquivo demo-update-item-viewModel.ts no diretório JET_Web_Component_Application/src/ts/jet-composites/demo-update-item.

Você distribui o arquivo demo-update-item_1-0-0.zip do diretório JET_Web_Component_Application/dist para os consumidores que desejam reutilizar seu componente Web em seu aplicativo Web. Para usar o componente Web em seu aplicativo Web, os consumidores extraem o conteúdo do arquivo ZIP para um diretório demo-update-item em seu aplicativo Web. Vamos detalhar essa última tarefa no próximo tutorial.

Mais Recursos de Aprendizagem

Explore outros laboratórios em docs.oracle.com/learn ou acesse mais conteúdo de aprendizado gratuito no canal YouTube do Oracle Learning. Além disso, visite education.oracle.com/learning-explorer para se tornar um Oracle Learning Explorer.

Para obter a documentação do produto, visite o Oracle Help Center.

Título e Informações de Copyright

Enhance and archive the Oracle JET web component

F53211-01

February 2022