Frontend com KVision

Kotlinautas

Esse contedo oferecido e distribudo pela comunidade Kotlinautas, uma comunidade brasileira que busca oferecer contedo gratuito sobre a linguagem Kotlin em um espao plural.

O qu Kotlin/JS?

Com Kotlin/JS podemos escrever um cdigo totalmente em Kotlin, e esse cdigo em Kotlin ser transformado em Javascript. Com isso, poderemos criar uma pgina web, com estrutura (HTML), estilos (CSS) e interao (Javascript) unicamente com Kotlin.

Uma das vantagens do Kotlin/JS poder usar bibliotecas multi-plataforma dentro do Kotlin/JS, aumentando as combinaes entre bibliotecas que podem ser feitas.

O qu KVision?

KVision um framework para a plataforma Kotlin/JS. Com KVision poderemos escrever cdigo do Kotlin/JS de maneira mais simples, criando componentes, usando Bootstrap, estilizando elementos HTML com Kotlin,etc. Uma outra funcionalidade usar componentes React/Redux dentro do KVision.

Alm disso, KVision pode se integrar facilmente com Ktor, Spring, Quarkus e outros frameworks para Kotlin.

Materiais

Ser necessrio ter o IntelliJ instalado na mquina, conhecimento bsico sobre a linguagem Kotlin e conhecimento bsico sobre frontend (HTML, CSS e Javascript).

Instalando o plugin do KVision

Agora, vamos comear a criar o projeto, primeiro, vamos ao marketplace de extenses do IntelliJ. V ao menu de configuraes, com o atalho Ctrl+Alt+S, e ao menu Plugins:

Aps isso, v na barra de pesquisa e pesquise por kvision. Com isso, o plugin do KVision ir aparecer e voc poder instalar clicando no boto Install

Agora, caso voc clique no boto New Project, ter um novo menu no canto esquerdo, sendo o menu do KVision que acabamos de instalar.

Criando um projeto com KVision

Agora vamos criar um projeto com KVision. Primeiro, observe que o menu do KVision tem alguns campos, sendo:

• Project Type: Define o tipo de projeto que ser criado, podendo ser um projeto Ktor, Spring, Quarkus,etc. No caso, ser apenas um projeto de frontend, ento deixe na opo padro Frontend project

• GroupId: Define o grupo do pacote que ser criado, esse campo totalmente livre. Voc pode colocar algo como com.kvsion

• ArtifactId: Define o artifact do pacote que ser criado, esse campo totalmente livre. Voc pode colocar algo como kvision

• Kotlin/JS compiler: Define qual ser o compilador que vamos usar no projeto. Deixe como est, que o IR.

• Opitional Modules: So diversos mdulos que podem ser instalados de maneira opicional, primeiramente, vamos selecionar os dois primeiros, sendo o Bootstrap based components, e o Standard Bootstrap CSS styling

Aps fazer essas configuraes, clique no boto Next para continuar.

Agora preencha o nome, e a localizao do projeto, sendo de escolha completamente pessoal. Caso no tenha nenhuma ideia, pode nomear com algo como kvision ou kvisiondemo por exemplo.

Caso voc crie o projeto e d algum erro dizendo que a configurao da JDK do Gradle invlida, dessa maneira (texto e imagem):

Texto

Invalid Gradle JDK configuration found. Open Gradle SettingsUse JDK from project structure

Imagem

Para resolver isso, clique no boto Open Gradle Settings, e ir aparecer o menu de configuraes do Gradle

V opo Gradle > Use Gradle from: e mude essa opo de 'gradle-wrapper.properties' file para 'wrapper' task in Gradle build script.

Caso a opo abaixo Gradle JVM esteja em vermlho, mude para uma verso vlida. Clicando ser possvel de escolher uma verso da JVM especfica para esse projeto.

Clique em OK para aplicaras mudanas. Com isso, as dependncias do seu projeto sero carregadas no projeto.

Entendendo a estrutura de pastas do KVision

Os arquivos dentro da raiz do projeto so referentes configurao do projeto e do KVision. Esses no iremos mexer em nada por enquanto.

Dentro da pasta src temos todos os arquivos fonte da nossa aplicao, primeiramente temos duas pastas, sendo a main que guarda o cdigo principal da nossa organizao, e a test que ir guardar os testes da nossa aplicao.

Dentro da main, temos apenas duas pastas, kotlin que ir armazenar apenas cdigo Kotlin. Caso nosso projeto tivesse Java (que no o caso) teriamos uma pasta Java tambm. A outra pasta a web que guarda arquivos que sero usados por toda a aplicao. Agora temos apenas o arquivo index.html, que guarda um template HTML:

<!DOCTYPE html><html><head>    <meta charset="utf-8">    <meta name="viewport" content="width=device-width, initial-scale=1">    <title>KVision Template</title>    <script type="text/javascript" src="main.bundle.js"></script></head><body><div id="kvapp"></div></body></html>

A nossa aplicao est dentro de src/main/kotlin/com/kvision/kvision/App.kt, que por enquanto apresenta apenas um Hello World. Vamos ver mais sobre esse arquivo:

package com.kvision.kvisionimport io.kvision.Applicationimport io.kvision.CoreModuleimport io.kvision.BootstrapModuleimport io.kvision.BootstrapCssModuleimport io.kvision.html.divimport io.kvision.moduleimport io.kvision.panel.rootimport io.kvision.startApplicationclass App : Application() {    override fun start() {        root("kvapp") {            div("Hello world")            // TODO        }    }}fun main() {    startApplication(        ::App,        module.hot,        BootstrapModule,        BootstrapCssModule,        CoreModule    )}

• Linha 3 10 importa diversos componentes, classes, elementos HTML,etc que vamos usar na nossa aplicao;
• Linha 12 declara uma classe que ir representar a nossa aplicao;
• Linha 13 - declara a funo start, que ir guardar o cdigo dessa pgina web em especfica;
• Linha 14 - root uma funo que cria um novo container. Esse container ir armazenar todas as tags HTML da aplicao, apenas precisamos informar um ID que o ID do elemento que ir guardar todos esses elementos. No caso sendo kvapp;
• Linha 15 - cria um elemento div que apenas est escrevendo um hello world na tela. Servindo apenas como exemplo;
• Linha 21 - declara a funo main da nossa aplicao, sendo essa a funo principal;
• Linha 22 - Inicia a aplicao com a funo startApplication;
• Linha 24 27 - So passados os mdulos que baixamos para a aplicao, sendo o module.hot um mdulo que nos permite mudar uma pgina e automaticamente a mudana ocorrer no navegador, BootstrapModule e BootstrapCssModule que so mdulos relacionados Bootstrap, e o CoreModule que um mdulo padro do KVision;

Para iniciar a aplicao, clique na barra lateral Gradle, depois em Run Configurations, e em Run run duas vezes, para assim fazer que a aplicao seja iniciada na URL localhost:3000

Agora nossa aplicao est inciada, e na pgina localhost:3000 ir aparecer o Hello World do KVision.

Agora vamos fazer um exerccio bem simples, vamos mudar o texto de hello world para Ol, mundo!. Isso pode ser feito mudando o contedo da funo div:

class App : Application() {    override fun start() {        root("kvapp") {            div("Ol, mundo!")        }    }}

• Mudamos o contedo de dentro de div e tambm removemos o comentrio // TODO;

Agora, o novo contedo ser automaticamente atualizado e mostrado na pgina.

Criando elementos HTML

Agora, vamos ver alguns exemplos de elementos HTML que podem ser criados usando KVision.

Primeiro, vamos modificar uma importao do nosso cdigo. Pode ser visto na linha 7 que importamos apenas o elemento div:

import io.kvision.html.div

Vamos mudar esse import, para ao invs de importar apenas o elemento div, importar todos os elementos HTML suportados pelo KVision, e mais algumas funcionalidades relacionadas CSS e JS. Isso pode ser feito utilizando o caractere coringa *:

import io.kvision.* // Funes, classes,etc. do KVisionimport io.kvision.core.* // Funcionalidades relacionadas  CSS e JSimport io.kvision.html.* // Todas as tags HTMLimport io.kvision.panel.* // Importar todos os painis que podem ser criados (veremos mais adiante)import io.kvision.utils.* // Unidades de medida como px (pixel)

Listas

Uma lista em HTML uma srie de dados unidos em uma forma visual de uma lista, um exemplo de lista :

• Primeiro elemento
• Segundo elemento
• Terceiro elemento

Isso pode ser feito em HTML com dois elementos, sendo <ul>, que uma lista no ordenada, e <li> que um elemento de uma lista. Logo, em HTML a lista acima seria:

<ul>    <li>Primeiro elemento</li>    <li>Segundo elemento</li>    <li>Terceiro elemento</li></ul>

Isso pode ser feito no KVision usando a funo listTag, que representa uma lista em HTML.

na funo listTag, iremos precisar informar o tipo da lista, sendo ul para listas no ordenadas (s com as bolinhas por exemplo) e ol para listas ordenadas, e aps isso informar a lista. Um exemplo prtico disso esse:

...class App : Application() {    override fun start() {        root("kvapp") {            listTag(ListType.UL, listOf("Primeiro elemento", "Segundo elemento", "Terceiro elemento"))        }    }}...

• Informamos o tipo da lista usando o mtodo listType.UL, caso quisessemos que essa lista fosse uma <ol>, apenas iriamos mudar para listType.OL;
• Aps isso, passamos uma lista de strings usando a funo listOf, colocando os elementos da lista dentro;

Com isso, a lista ser mostrada na pgina.

Caso mudemos o argumento ListType.UL para listType.OL, com o cdigo ficar dessa maneira:

...class App : Application() {    override fun start() {        root("kvapp") {            listTag(ListType.OL, listOf("Primeiro elemento", "Segundo elemento", "Terceiro elemento"))        }    }}...

A lista ficar ordenada na pgina, seguindo assim a mudana feita de lista no ordenada para lista ordenada.

Links

No HTML, para criar links usamos a tag <a>, que representa uma "ncora" que cria um link para uma pgina. No caso da tag <a> vamos precisar informar um parametro href, que para onde aquele link ir levar, e tambm um texto ou outros elementos dentro da tag <a>. Dessa maneira:

<a href="https://dev.to/kotlinautas">Ver artigos da Kotlinautas</a>

Para criar links no KVision podemos usar a funo link, passando um placeholder, que um texto que ser clicvel, e o link. Dessa maneira:

...class App : Application() {    override fun start() {        root("kvapp") {            link("Ver artigos da Kotlinautas", "https://dev.to/kotlinautas")        }    }}...

Agora teremos um texto clicvel em nossa pgina, que quando clicado levar lista de artigos da Kotlinautas.

Quando o link clicado, a pgina atual substuida pela lista de artigos da Kotlinautas. Como posso mudar esse comportamento, e fazer que quando o link clicado, seja criada uma nova pgina com a pgina do link?

Olhando para a assinatura da funo link, podemos ver todos os argumentos que podem ser passados:

fun Container.link(    label: String,    url: String? = null,    icon: String? = null,    image: ResString? = null,    separator: String? = null,    labelFirst: Boolean = true,    target: String? = null,    className: String? = null,    init: (Link.() -> Unit)? = null): Link

Podemos ver que os nicos argumentos que usamos foram o label, que o texto do link, e o url que para onde o link est redirecionando. O argumento que precisamos adicionar para mudar o comportamento de redirecionamento desse link no target. Isso pode ser feito passando esse target na chamada dessa funo link, dessa maneira:

...class App : Application() {    override fun start() {        root("kvapp") {            link("Ver artigos da Kotlinautas", "https://dev.to/kotlinautas", target = "_blank")        }    }}...

• Passamos o target diretamente, usando o target =, e passando o valor _blank que ir fazer que uma nova pgina seja aberta.

Contedo dinmico

Podemos mudar o contedo de uma pgina dependendo de alguma interao que a pessoa usuria da pgina fizer. Isso pode ser feito usando a funo .onEvent, que ir executar algo se algum evento especfico, como um clique, o mouse passar por cima do elemento,etc. acontecer.

Vamos ver o exemplo abaixo:

...class App : Application() {    override fun start() {        root("kvapp") {            link("Link para o Twitter da Kotlinautas", "https://twitter.com/kotlinautas").onEvent {                mouseover = {                    self.label = "Link para o Twitter da Feministech"                    self.url = "https://twitter.com/feminis_tech"                }            }        }    }}...

• Temos um elemento link que leva ao twitter da Kotlinautas;
• Usamos a funo .onEvent, iniciando um bloco onde podemos colocar os eventos que podem ocorrer com esse link;
• Colocamos um evento dentro desse bloco, sendo o mouseover, que um evento que ocorre toda vez que o mouse passa por cima do elemento;
• Dentro desse mouseover, mudamos o texto e a url do link usando a varivel self que representa o elemento;

Agora, quando voc passar o mouse pelo link que levava ao twitter da Kotlinautas, o link ser automaticamente modificado, e ir te enviar ao twitter da Feministech no lugar.

H outros eventos que podem ser colocados no lugar, caso queira ver todos que podem ser usados, veja nessa lista da MDN

Rich Text

Podemos inserir um texto com tags HTML como seu contedo no KVision. Veja no exemplo abaixo:

...class App : Application() {    override fun start() {        root("kvapp") {            p(                "<strong>Texto em negrito</strong>"            )        }    }}...

Quando voc abrir a pgina, o contedos ser um texto <strong>Texto em negrito</strong>:

Isso aconteceu pois o texto na pgina est sendo mostrado apenas como texto, no como tags HTML. Para fazer que um texto seja interpretado como HTML, podemos passar um argumento chamado rich como verdadeiro. Dessa maneira:

...class App : Application() {    override fun start() {        root("kvapp") {            p(                "<strong>Texto em negrito</strong>",                rich = true            )        }    }}...

Agora, o texto mostrado na pgina ser interpretado como HTML:

Criando componentes

Um componente como se fosse uma tag HTML criada por ns mesmos. Onde podemos informar seu contedo, criar um estilo personalizado, misturar uma ou mais tags dentro de uma nica,etc.

Primeiro, vamos criar um novo arquivo em src/main/kotlin/com/kvision/kvision chamado Carto.kt. Esse arquivo ter algumas importaes:

package com.kvision.kvisionimport io.kvision.core.*import io.kvision.html.*import io.kvision.utils.*

Depois, vamos criar uma funo chamada Carto que ser o nosso componente. A dea criar um texto em negrito, com um fundo cinza. Formando como se fosse um retngulo. Primeiro, vamos criar a funo:

fun Container.Carto(texto: String? = null): Strong {}

• Essa interface Container foi usada pois todo componente (e tag HTML no KVision) precisa estar dentro dessa interface para ter alguns mtodos e propriedades disponveis;
• Recebemos uma varivel texto, que ser o contedo do componente;
• o retorno : Strong deixa claro que o elemento que iremos retornar ser um elemento em negrito (<strong></strong>)

Aps isso, vamos criar o elemento:

fun Container.Carto(texto: String? = null): Strong {    val elemento = Strong(content = texto, className = "carto")}

• Usamos o mtodo Strong(), que ir criar por sua vez, um elemento HTML <strong>
• Passamos apenas dois argumentos, sendo um content que o contedo do elemento, no caso ser a varivel texto. E um className que representa o nome da classe que poder eventualmente ser usado em um arquivo CSS ou JS;
• Guardamos tudo isso em uma varivel chamada elemento;

Agora, vamos fazer algumas modificaes no estilo desse elemento, para criar assim o estilo de um carto:

fun Container.Carto(texto: String? = null): Strong {    val elemento = Strong(content = texto, className = "carto")    elemento.background = Background(Color("#DDD"))    elemento.padding = 10.px    elemento.fontSize = 30.px}

• Modificamos o estilo do elemento acessando diretamente essas propriedades, usando .background, .padding,etc. e definindo o valor dessas variveis;
• Para definir o background, usamos dois mtodos, sendo o Background, que ir retornar o background, e um Color que ir retornar uma cor. Dentro do color passamos a cor em forma de hexadecimal, sendo #DDD;
• Para definir valores em pixel, inserimos um nmero, seguido de um .px indicando a unidade. Caso quissemos usar outra unidade como vh ou vw, apenas mudariamos o final, ficando 10.vw por exemplo;

Agora vamos terminar a funo adicionando esse elemento ao Carto e retornando esse elemento:

fun Container.Carto(texto: String? = null): Strong {    val elemento = Strong(content = texto, className = "carto")    elemento.background = Background(Color("#DDD"))    elemento.padding = 10.px    elemento.fontSize = 30.px    this.add(elemento)    return elemento}

Pronto, agora j temos o componente pronto.

Agora podemos usar o nosso componente Carto dessa maneira:

...class App : Application() {    override fun start() {        root("kvapp") {            Carto("Testando a criao de componentes")        }    }}...

• Como voc pode observar, usamos a funo Carto como qualquer elemento HTML do KVision. Com esse cdigo, a nossa pgina ficar assim:

Estilizando a nossa pgina

Agora vamos comear a estilizar a nossa pgina, adicionando CSS usando o prprio KVision como meio para criar esse CSS.

Primeiro, vamos mudar a pgina para algo mais simples, que apenas mostra diversos textos em tamanhos diferentes e com tags diferentes:

...class App : Application() {    override fun start() {        root("kvapp") {            h1("Texto maior")            h2("Texto menor")            strong("texto em negrito")            br()            i("texto em itlico")        }    }}...

• Criamos um ttulo com h1, um subttulo com h2, um texto em negrito com strong, quebramos a linha usando o br (Break Line), e ao final inserimos um texto em itlico com i.

Agora, vamos criar um arquivo chamado estilo.kt em src/main/kotlin/com/kvision/kvision. Esse arquivo ir armazenar os estilos que iremos aplicar.

Primeiro, vamos importar o KVision nesse arquivo:

package com.kvision.kvisionimport io.kvision.core.*import io.kvision.utils.*

Agora vamos inserir primeiro o estilo do h1. Isso pode ser feito definindo uma varivel que ir armazenar esse estilo, usando uma classe Style, e dentro dessa classe iremos colocar os estilos. Isso pode ser feito da seguinte forma:

package com.kvision.kvisionimport io.kvision.core.*import io.kvision.utils.*val estiloH1 = Style {    color = Color("blue")}

• Usamos a classe Style, e dentro dela determinamos que a cor do texto desse estilo fosse azul, mudando a varivel color, atribuindo com o retorno de uma funo chamada Color, que gera uma cor baseada em um texto (cdigo hexadecimal, nome,etc.).

Agora, vamos voltar ao arquivo App.kt e vamos adicionar esse estilo ao nosso h1. Isso pode ser feito da seguinte forma:

...class App : Application() {    override fun start() {        root("kvapp") {            h1("Texto maior") { addCssStyle(estiloH1) }            h2("Texto menor")            strong("texto em negrito")            br()            i("texto em itlico")        }    }}...

• Adicionamos ao corpo dessa funo h1, a funo addCssStyle. Que permite a adio de estilos ao elemento apenas informando a varivel que est guardando o estilo, no caso sendo a estiloH1.

Agora a nossa pgina est com o h1 estilizado com a cor azul, dessa maneira:

Podemos agora seguir o mesmo padro e estilizar cada elemento que criamos. Tente criar estilos para o h2, strong e i sem ajuda primeiramente.

Caso tenha ficado com algum problema, ou no teve idias de como estililzar esses elementos, voc pode seguir o exemplo abaixo de como ficaria o arquivo estilo.kt ao final:

package com.kvision.kvisionimport io.kvision.core.*import io.kvision.utils.*val estiloH1 = Style {    color = Color("blue")}val estiloH2 = Style {    background = Background(Color("#DDD"))}val estiloStrong = Style {    color = Color("green")}val estiloI = Style {    padding = 40.px}

• No estiloH2 usamos a funo background para gerar um background para o elemento. Esse background no caso um Color, que representa uma cor. Essa cor sendo #DDD que um cinza bem claro.
• No estiloStrong deixamos a cor do texto verde. O mtodo foi o mesmo que usamos para o estiloH1;
• No estiloI, temos apenas um padding de 40 pixels, usando o mtodo de colocar um nmero, um . e a unidade de medida;

Agora apenas precisamos aplicar esses estilos na pgina. Podemos fazer isso da mesma forma que fizemos com o h1:

class App : Application() {    override fun start() {        root("kvapp") {            h1("Texto maior") { addCssStyle(estiloH1) }            h2("Texto menor") { addCssStyle(estiloH2) }            strong("texto em negrito") { addCssStyle(estiloStrong) }            br()            i("texto em itlico") { addCssStyle(estiloI) }        }    }}

Pronto, agora nossa pgina ter vrios elementos com vrios estilos diferentes:

Botes

Para criar um boto no KVision, podemos usar a funo button e informar qual ser o texto do boto, como no exemplo abaixo:

...class App : Application() {    override fun start() {        root("kvapp") {            button("Boto feito com KVision")        }    }}...

Com esse exemplo acima, o cdigo gerado ser:

Podemos criar um boto com um estilo diferente, como um boto primrio, segundrio, boto de perigo,etc. Podemos mudar esse estilo passando um argumento style ao boto. Dessa maneira:

...class App : Application() {    override fun start() {        root("kvapp") {            button("Salvar alteraes", style = ButtonStyle.DANGER)        }    }}...

Informando o style sendo ButtonStyle.DANGER vamos criar um boto que representa uma ao perigosa, que deve ser tomada com cuidado,etc. Ficando dessa maneira na tela:

Podemos tambm inserir uma ao que ser feita quando esse boto for clicado. Isso pode ser feito adicionando um bloco onClick para a funo button. Dessa maneira:

...class App : Application() {    override fun start() {        root("kvapp") {            button("Salvar alteraes", style = ButtonStyle.DANGER) {                onClick {                    println("Alteraes salvas")                }            }        }    }}...

• Dentro do onClick, apenas mostramos no console que a alterao foi salva (apenas para ilustrar a funcionalidade). Isso pode ser feito usando a funo println que nesse contexto, ir mostrar algo no console do navegador.

H diversos estilos de botes que podem ser usados no KVision, sendo a lista completa sendo:

• PRIMARY
• SECONDARY
• SUCCESS
• INFO
• WARNING
• DANGER
• LINK
• LIGHT
• DARK
• OUTLINEPRIMARY
• OUTLINESECONDARY
• OUTLINESUCCESS
• OUTLINEINFO
• OUTLINEWARNING
• OUTLINEDANGER
• OUTLINELIGHT
• OUTLINEDARK

Tente mudar o estilo do boto que criamos se baseando na lista acima como exerccio.

Containers de Layout

Agora vamos usar um recurso chamado Containers de Layout (Layout Containers), que so tags do KVision que criam div's com um comportamento diferente, como por exemplo uma div onde os elementos dentro dela podem ser modificados em seu tamanho. Ou uma div onde cada elemento representa uma aba,etc.

Vamos ver por exemplo o splitPanel. Essa funo ir criar um painel que o tamanho das reas de dentro desse painel podem ser reajustadas pelo usurio. Esse painel pode ser criado da seguinte forma:

...class App : Application() {    override fun start() {        root("kvapp") {            splitPanel {                div("Primeira rea")                div("Segunda rea")            }        }    }}...

• Usamos o splitPanel como se fosse uma tag do KVision;
• Dentro dela, inserimos duas div's apenas para demonstrar o funcionamento, contendo apenas um texto;

Com o cdigo acima, a nossa pgina ficar assim:

Essa barra vertical pode mudar o tamanho de cada seo desses elementos, criando mais interao com a pessoa usuria.

Podemos tambm criar um Tab Panel que um layout em abas, mostrando um elemento filho por vez. Pode ser criado dessa maneira:

...class App : Application() {    override fun start() {        root("kvapp") {            tabPanel {                tab("Primeira aba") {                    div("Contedo da primeira aba")                }                tab("Segunda aba") {                    div("Contedo da segunda aba")                }                tab("Terceira aba") {                    div("Contedo da terceira aba")                }            }        }    }}...

• A funo usada para criar o painel a tabPanel, onde iremos colocar os elementos do painel dentro;
• Cada aba do painel criada usando a funo tab, que representa a aba;

Com esse cdigo, o resultado ser:

H outros painis que podem ser usados no KVision, mas esses dois so timos exemplos.

Finalizao

Nesse artigo vimos algumas funcionalidades interessantes do KVision, e como criamos HTML, CSS e Javascript com Kotlin. Tente criar um site simples usando KVision, como um portiflio ou algo do tipo.

Obrigada por ler