Introdução

Este framework tem por objetivo oferecer maior agilidade e praticidade na hora de desenvolver os códigos sem perder a flexibilidade. Ele oferecer diversos recursos robustos prontos que auxiliam na criação de sites, aplicações e plataformas.

Estrutura

Sua estrutura é dividida por pastas, nas seguintes partes:

  • Config - Arquivos de configurações, onde estão os dados de todos os módulos.
  • Models - Estruturas de Banco de Dados.
  • Methods - Métodos que podem ser acessados externamente através de ajax.
  • Modules - Módulos padrões e personalizados com todos os recursos do Framework.
  • public - Pasta pública, onde deverão ser colocados todos os arquivos que terão acesso externo, tais como CSS, JS, Imagens, etc.
  • Modules - Módulos padrões e personalizados com todos os recursos do Framework.
  • Resources - Recursos adicionais como arquivos de línguas e templates de e-mail.
  • Var - Pasta com dados extras, tais como armazenamento temporário e logs.
  • vendor - Módulos do Composer.
  • View - Páginas e blocos de visualização.

Cada aplicação web deverá ter 4 frentes diferentes.

  • Modules/Custom - Um módulo próprio com todas as suas funções principais.
  • Methods - Os métodos que extendem os módulos acima e serão acessíveis pelas views.
  • Models - As estruturas de Banco de Dados.
  • Views - As páginas de conteúdo.

Em geral, por se tratar de uma ferramenta muito flexível, pode-se utilizar apenas os Methods e Views para projetos menores. Contudo, para projetos grandes, recomenda-se o uso de todas as estapas para garantir maior solidez e evitar redundância.

Passo a Passo

O Framework possui um caminho bastante simples de funcionamento. Em geral, para desenvolver qualquer tipo de aplicação, basta seguir os passos abaixo.

  1. Instale o Framework;
  2. Realize as configurações iniciais descritas na tela de Boas-Vindas;
  3. Crie seus Blocos e Rotas para suas páginas;
  4. Crie o conteúdo de suas páginas seguindo o guia de recursos;
  5. Crie seus Módulos e Métodos principais;
  6. Configure o Banco de Dados e utilize o Icecream para criar consultas ágeis em seus módulos;
  7. Vincule seus Métodos em suas páginas;
  8. Crie módulos para seu CMS (opcional).

Fluxo de funcionamento

Instalando

Para iniciar um projeto, basta baixar toda a estrutura de arquivos para um servidor. O primeiro passo é editar o arquivo Config > navigation.config, inserindo nele todas as configurações necessárias.

domain: string "site.com.br" Deve receber o domínio, sem barras e sem procotolo (http)\n path: string "/blog/" Caminho padrão do site, caso o mesmo esteja dentro de um outro diretório. Deixar em branco caso não haja\n protocol: string "https" Procolo padrão do site (HTTP ou HTTPS)\n force: string "url" Força a URL ser sempre a definida. Pode ser domain (para forçar apenas o domínio), procotol (para forçar apenas o protocolo) ou url (para forçar que domínio e protocolo sejam iguais)\n

A partir disso você já deverá ver a página de boas vindas ao acessar o site. Lá você encontrará todos os detalhes de como prosseguir para continuar a configuração.

Em resumo, os próximos passos serão: configurar os módulos que deseja utilizar, criar seus métodos, módulos e views.

Rotas
Modules > Classes > Navigation

O sistema de rotas do Framework é baseado em blocos e páginas. Para criar uma rota, deve-se acessar o arquivo Config > page.config e criar os blocos que contenham as informações desejadas.

Um bloco é uma estrutura que contém quaisquer tipo de informações e pode ser unido a outros blocos ou páginas.

Uma página é uma estrutura identica ao bloco, porém, que pode ser acessada através de uma URL.

Ambas as estruturas são executadas em arquivos .php que são colocados na pasta View e mapeados em Config > page.config.

Criando blocos

Abaixo estão as principais instruções sobre a criação de um bloco

file: string "index.php" Nome do arquivo que está dentro da pasta view\n includeAfter: array "[header]" Inclui blocos no início da página\n includeBefore: array "[blog, footer]" Inclui blocos no final da página\n using: array "[Clientes,Produtos]" Métodos a serem incorporados na página\n data: array "pageTitle:Página de Produtos" Dados estáticos a serem incorporados na página\n contentType: string "text/html" Tipo de Dados para a resposta no Cabeçalho\n

Todos os bloco devem obrigatoriamente ter um "nome" único pelo qual serão chamados. No exemplo abaixo, o bloco criado se chama "bloco_topo".

Como o bloco não possui nenhum caminho de acesso, por isso, poderá somente ser incorporado a outras páginas e blocos.

{ "bloco_topo" : { "file": "topo.php", "using": "NomeDoMetodo", "contentType": text/html", "includeBefore": ["popup_promocao"] } }

Caminhos de acesso

Para criar um acesso ao bloco, basta inserir qual o caminho irá até a página, conforme as opções abaixo.

pattern: string "produtos/#/?" Padrão de URL (ex: site.com/produtos/12345/nome-do-produto)\n static: string "produtos" URL estática que não recebe nenhum dado\n match: string "/produtos\/([0-9]+)\/([A-z-_]+)/" Padrão de URL em Expressão Regular (ex: site.com/produtos/12345/nome-do-produto)\n variables: array "[id, titulo]" Define o nome das variáveis recebidas nos comandos pattern e match (ex: id='12345', titulo='nome-do-produto') \n

Exemplo de Página de Produtos

site.com/produtos/42987/Cafeteira-Nespresso

{ "produtos" : { "file": "produtos.php", "pattern": "produtos/#/?", "variables" : ["idProduto", "urlProduto"], "includeAfter": ["header"], "includeBefore": ["footer"] } }

Nesse caso, o sistema irá dispor o seguinte conjunto de dados:

{ "idProduto": "42987", "urlProduto": "Cafeteira-Nespresso" }

Exemplo de Landing Page (Fixa)

site.com/promocao-15-desconto/

{ "cabecalho-ldpage" : { "file": "cabecalho-ldpage.php" }, "ldpage-15" : { "file": "landing-page-15-desconto.php", "pattern": "promocao-15-desconto", "includeBefore": ["cabecalho-ldpage"] } }

Nesse caso, cadastramos um Cabeçalho próprio para Landing Pages cabecalho-ldpage que pode ser usado para colocar um código de coversão, por exemplo.

Em seguida, foi criada a landing page com um caminho fixo que inclui esse cabeçalho.

Padrões de URL (patterns)

Os padrões de URL são utilizados para direcionar o usuário para as páginas determinadas.

Static

Permite inserir um caminho estático e fixo do usuário. Para acessar o caminho site.com.br/produtos, por exemplo, o caminho deve ser:

{ "static" : "produtos" }

Nesse padrão de URL não se faz uso de dados dinâmicos

Match

Permite reconhecer a URL através de uma expressão regular. Caso queria pegar partes exclusivas da URL, utilize parenteses para capturar os dados.

{ "match" : "/produto/([0-9]+)/", "variables" : ["idProduto"] }

Um exemplo de URL que se enquadra na definição acima é: site.com.br/produto/1234.

No exemplo acima, o dado capturado é um número que poderá ser resgatado dentro da página como $this->variables['idProduto'];.

Pattern

Permite reconhecer a URL através de uma expressão simples. Abaixo estão as instruções para a montagem de expressões

#: número "0123456789" Exige apenas dígitos numéricos\n #0,2: quantificado "12" Exige apenas dígitos numéricos e delimita a quantidade de caracteres: entre 0 e 2, no exemplo\n $: qualquer "abc123@" Exige qualquer caractere\n $3,: quantificado "abc123@" Exige qualquer caractere e delimita a quantidade de caracteres: 3 ou mais, no exemplo\n ?: qualquer "abc123@" Resgata qualquer caractere e reconhece a URL mesmo que nenhum caractere esteja presente\n %a-f: específico "abcdef" Exige um determinado tipo de caracteres. No exemplo ao lado, reconhece caracteres de A a F\n

Abaixo, segue o exemplo de como reconhecer: site.com.br/produto/1234.

{ "pattern" : "/produto/#", "variables" : ["idProduto"] }

No exemplo acima, o dado capturado é um número que poderá ser resgatado dentro da página como $this->variables['idProduto'];.

Para reconhecer um link uma informação que pode estar presente ou não, tal como o nome do produto: site.com.br/produto/1234/nome-do-produto-para-melhorar-seo.

{ "pattern" : "/produto/#/?", "variables" : ["idProduto","tituloProduto"] }

No exemplo acima, os dados capturados poderão ser resgatado como $this->variables['idProduto']; e $this->variables['tituloProduto']; .

Redirecionamentos

É possível também criar redirecionamentos, permitindo que uma determinada URL definida leve o usuário até outro local.

redirect: string "http://site.com" Caso seja necessário redirecionar a página para outra\n redirectCode: integer "301" Código do redirecionamento\n

O código de redirecionamento pode ser 301 (permanente) ou 302 (temporário).

Renderização de Páginas
Modules > Classes > Navigation > Page

Sempre que uma página é acessada, o sistema realiza a renderização dessa página e seus blocos, ou seja, ele executa as funções da página e pode alterar seu conteúdo.

O processo de renderização ainda fornece algumas funcionalidades que facilitam o desenvolvimento do frontend.

Caminhos de URL

Para facilitar a criação de URLs de caminho absoluto, basta utilizar o símbolo ~ antes de qualquer URL para que o sistema a complete com a URL padrão do site, como configurado na navegação.

Exemplo de aplicação

Ao incluir o seguinte código no corpo do bloco ou página...

\n \n

... irá gerar o seguinte resultado ao executar a página.

\n \n

Super Tags

Você pode usar Super Tags para resgatar um valor do backend. Assim que a página for executada, as tags serão substiuídas pelos valores que elas recuperarem.

Para utilizá-la, basta criar uma tag com o nome su: e colocar os parâmetros que deseja trazer.

Variável

Tag que recupera o valor de uma variável declarada em "data" no arquivo de configuração de blocos ou inserida posteriormente.

<su: var="NomeDaVariavel"/>

O código acima é o mesmo que executar:

echo $this->variables["NomeDaVariavel"];

Tradução

Tag que recupera um conteúdo na língua atual.

<su: write="Products List" language="pt_BR" scope="website"/>

O código acima é o mesmo que executar:

echo $this->write("Products List", "website", null, "pt_BR");

O parâmetro language é opcional.

Para preencher o parâmetro scope consulte a seção sobre internacionalização.

Você também pode usar as funções de super tag dentro de uma tag comum. Basta incluir o parâmetro su:funcao="variavel", sendo que "funcao" representa a função que você deseja chamar e "variavel" é o conteúdo que deseja buscar.

Variável

<a href="site.com.br" su:var="NomeDaVariavel"></a>

O código acima irá gerar a seguinte tag:

<a href="site.com.br"/>Valor da Variável</a>

Tradução

Tag que recupera um conteúdo da língua atual.

<p su:write="Products List" su:scope="website" su:language="pt_BR"></p>

O código acima irá gerar a seguinte tag:

<p>Lista de Produtos</p>

O parâmetro language é opcional.

Para preencher o parâmetro scope consulte a seção sobre internacionalização.

Tags dinâmicas

As Tags Dinâmicas permitem que módulos e outros blocos possam inserir tags dentro do seu código HTML de maneira dinâmica. Isso é útil para módulos que precisam inserir códigos CSS ou JS na página sem que você tenha que copiar e colar todos esses códigos.

Basicamente, a Tag Dinâmica é uma Super Tag que inclui outras Tags no código. Elas são chamadas através da declaração <su: tags="TagList"/>, sendo que "TagList" é a lista de Tags que serão inclusas.

Por padrão, existem duas lista de Tags importantes a serem colocadas em seu código. são elas:

<su: tags="Header"/>

Deve ser colocado logo ao final do cabeçalho, antes do fechamento da tag <head>. É responsável por incluir, em geral, códigos JS, CSS e Meta Tags ainda no cabeçalho.

<su: tags="Footer"/>

Deve ser colocado logo ao final do corpo, antes do fechamento da tag <body>. É responsável por incluir, em geral, códigos JS e CSS que serão carregados ao final da página.

Para utilizar os recursos de todos os módulos e transações, é obrigatória a inserção das tags acima. Os arquivos de Footer e Header que vêm com a instalação do Framework contêm a indicação correta do uso de ambas as Tags.

Inserindo Tags Dinâmicas

Você pode inserir Tags Dinâmicas facilmente. Para isso basta utilizar uma das seguintes funções.

Todas as funções recebem os seguintes parâmetros:

$path Caminho no qual se encontra o arquivo a ser incorporado

$publiPath Se true inclui o caminho da pasta "public" no início do caminho acima.

$options Parâmetros a serem inseridos na tag

$content Conteúdo da tag

$this->addTagJS()

Adiciona tag JS no Footer

$this->addTagHeadJS()

Adiciona tag JS no Header

$this->addTagCSS()

Adiciona tag CSS no Footer

$this->addTagHeadCSS()

Adiciona tag CSS no Header

Exemplo de aplicação

$this->addTagHeadJS("https://code.jquery.com/jquery-3.4.1.slim.min.js", false, ["crossorigin" => "anonymous"]);

Tag gerada

<script src="https://code.jquery.com/jquery-3.4.1.slim.min.js" crossorigin="anonymous"></script>

Funções de página

$this->getURL()

Obtem URL do site

$this->getCurrentURL($array = false)

$array Se true retorna relatório detalhado em array, senão, retorna a URL pronta

Busca a URL atual do site

$this->getPageURL($pageId = '', $variables = array())

$pageId ID da página (se vazio, retorna URL da página atual)

$variables Variáveis a serem incluídas na URL

Resgata a URL de uma página ou da página atual

$this->getPublicURL($path)

$path (Opcional) Concatena o nome do arquivo/caminho se enviado

Obtem URL da pasta Public.

$this->redirectTo($url, $code = 302)

$url URL para a qual deve ser redirecionada

$code (Opcional) Código do redirecionamento (301, 302)

Redirecionar a página através do cabeçalho location.

$this->checkCookie($cookieName, $cookieContent = null, $cookieMatch = null)

$cookieName Nome do Cookie

$cookieContent Conteudo esperado do Cookie. Se não enviado, espera-se que o cookie não exista

$cookieMatch (Opcional) Expressão regular a ser checada.

Checar a condição de um cookie.

$this->redirectOnCookie($url, $cookieName, $cookieContent = null, $cookieMatch = null)

$url URL para a qual deve ser redirecionada

$cookieName Nome do Cookie

$cookieContent Conteudo esperado do Cookie. Se não enviado, espera-se que o cookie não exista

$cookieMatch (Opcional) Expressão regular a ser checada.

Redirecionar a página caso um cookie não satisfaça as necessidades passadas.

$this->block($blockName)

$blockName ID do bloco

Retorna o conteúdo de um bloco

SEO
Modules > Classes > SEO

Robots

Modules > Classes > SEO > Robots.php

O arquivo de Robots é gerado automaticamente através desse módulo e pode ser configurado no arquivo Config/SEO.config

Para que o mesmo seja exibido, é necessário que ele esteja devidamente configurado no arquivo page.config, no qual estará declarado com caminho físico de robots.txt.

{ "robots":{ "agents":{ "*" : { "allow" : "/", "disallow": [] } }, "sitemap": true } }

Configurações do Robots

Dentro da chave agents você pode colocar vários user-agents diferentes e incluir os parâmetros allow e disallow.

Para ambos os parâmetros você pode passar uma string que contém o caminho fixo, ou um array de caminhos. Caso passe vazio, o mesmo será ignorado.

O parâmetro sitemap define se o mesmo deve ser incluído no arquivo de robots. Caso for TRUE, o arquivo será incluído de acordo com seu caminho declarado no arquivo Config/page.config. Caso for FALSE, o sitemap não será incluído.

Você pode ainda passar um outro caminho para o sitemap casa deseja. Basta passar uma string com a URL desse sitemap.

Sitemap

Modules > Classes > SEO > Sitemap.php

O arquivo sitemap.xml também é gerado automaticamente. O módulo irá analisar seu arquivo Config/page.config para listar as páginas declaradas e irá inserir as páginas automaticamente no sitemap.

Você ainda poderá colocar opções personalizadas para cada página.

Páginas com caminho estático serão incluídas automaticamente

Páginas com padrão (pattern) serão incluídas apenas se tiverem uma fonte de variáveis

Páginas com match serão incluídas apenas se tiverem um parâmetro "loc" declarado.

Personalizando o sitemap

Ao declarar sua página no arquivo Config/page.config, você poderá incluir instruções específicas para o valor de sitemap de cada página.

"sitemap" : { "loc":"https://site.com.br/pagina", "changefreq":"daily", "lastmod":"2019-12-09 09:23:00", "priority":"0.5", "locVariablesSource":"Metodo/Funcao" }
loc: string "https://site.com.br/pagina" URL fixa para a página. Deve ser declarado caso queira que o caminho da página seja outro que o declarado ou caso haja match ou pattern.\n changefreq: string "daily" Frequência de mudança da página, pode ser: (always, hourly, daily, weekly, monthly, yearly, never)\n lastmod: mixed "true" Data da última vez em que essa página foi alterada. Se for "true", o código insere a data de modificação do arquivo em questão. Pode ser passado também uma data fixa em uma string.\n priority: string "0.5" Prioridade da página dentro do site. Pode ter um valor de 0 a 1\n locVariablesSource: string "Metodo/Funcao" Fonte de dados para URLs com pattern\n

Criando fonte de dados

Para páginas que são declaradas com patterns, certamente elas recebem variáveis na URL. Para "montar" essa URL no sitemap é necessário indicar os valores que irão preencher essas variáveis. Isso é útil para quando você possui uma página que exibe dados dinâmicos, como página de produto ou posts. Através dessa funcionalidade, você pode fornecer dados dos seus produtos de modo que todos os links apareçam.

Configuração da página

{ "pattern": "produtos/#/?", "variables": ["idProduto", "nomeProduto"], "sitemap" : { "locVariablesSource":"Produto/FuncaoDoSitemap" } }

Caso prefira, ainda pode passar um array com as variáveis fixas diretamente nesse pârametro, sem necessidade do uso de uma função.

Criação do método

O método abaixo deve fornecer as variáveis para a criação das URLs baseadas no pattern

class Produto extends _dbQuery { public function FuncaoDoSitemap () { return $this->produtosSelect(['idProduto', 'nomeProduto']); } }

Você também pode fornecer as informações de sitemap para cada um dos valores, como abaixo

class Produto extends _dbQuery { public function FuncaoDoSitemap () { return ['sitemap' => [], 'variables' => [] ]; } }

Módulos e Métodos
Modules > Custom
Methods

Para disponibilizar funções e dados a todos os seus blocos e páginas é necessário criar módulos. Os módulos são, basicamente, o backend do seu site.

Criando Módulos

Os módulos são arquivos que conterão todas as funções principais de uma aplicação web ou site. Em geral, um site possui apenas um módulo e diversas classes, porém, você poderá criar quantos quiser.

Crie a pasta do seu módulo dentro da pasta "Custom", por exemplo: Modules > Custom > MeuSite.

Em seguida, você poderá começar a criar as classes que precisar. Essas classes conterão as funções que você utilizará em seu site. As funções devem ser agrupadas por assunto ou seção, sempre dentro da pasta do seu módulo.

Por exemplo, se você tiver um sistema de Produtos em seu site, precisará de várias funções relacionadas a esse sistema, tal como listagem, busca, etc. Para isso, crie uma classe class Produtos dentro do seu módulo e então você poderá criar todas as funções que precisar.

Exemplo

Sempre que você criar uma classe, você deverá utilizar o mesmo nome para o arquivo e para a classe, inclusive mantendo as letras maíusculas e minúsculas!

Modules > Custom > MeuSite > Produtos.php
Por padrão, todas as funções devem estender a classe _Core. Caso você esteja estendendo um outro módulo, basta assegurar de que esse módulo já estenda a classe _Core.
namespace MeuSite;\n\n use \_Core;\n\n class Produtos extends _Core{\n public function buscarProduto () { }\n\n public function listarProdutos () { } }

Criando Métodos

Um método nada mais é do que a interface entre o backend e o frontend. Basicamente, o módulo possui todas as funções mais completas, e tem intuito de fornecer as funções de cada parte do seu site. Já o método tem por objetivo preparar os dados e disponibilizá-lo para cada uma das páginas.

Imagine que, como no exemplo acima, temos um sistema de produtos em nosso site. Provavelmente, você precisará exibir produtos em diversas páginas: na página inicial, na listagem de produtos, na página do produto, no carrinho de compras, etc. Os módulos terão essas funções básicas, enquanto que os métodos irão utilizar as funções dos módulos para resgatar informações espefícicas para cada página.

Exemplo

O arquivo criado abaixo terá um conteúdo demonstado ao lado.

Methods > Produtos.php

Perceba que ele estende o módulo criado e utiliza uma mesma função para retornar dados diferentes para cada ocasião.

class Produtos extends MeuSite\Produtos{\n public function buscaRapidaDeProduto () { return $this->buscarProduto(); }\n\n public function buscaCompletaDeProduto () { return $this->buscarProduto(); } }
Se você estiver criando um site de pequeno porte, ou uma aplicação que não exija tantos recursos, você pode optar por criar apenas Métodos. Eles funcionarão normalmente e de maneira igualmente segura, porém, tenha em mente que expandir seu site poderá ser um pouco mais trabalhoso no futuro.

Utilizando Métodos

Assim que você criar uma página (View), você poderá utilizar métodos dentro dela. Para isso, você pode declarar o nome do método na opção "using" na declaração da sua página no arquivo Config > page.config. Se preferir, você também pode chamar o método diretamente no arquivo PHP da página, através da função $this->using('Produtos');

Acessando recursos

Assim que você vincular a página a um método, você poderá acessar todas as funções desse método dentro da página através da instrução $this->Produtos->buscaRapidaDeProduto();

Intervindo na página

Quando um método é vinculado à uma página, o método também poderá "intervir" na criação da página, ou seja, no momendo da criação daquela página, o método poderá inserir tags ou executar funções necessárias.

Para isso, na função function __construct do método, você deve receber uma variável com o tipo Navigation\Page. Essa variável irá receber toda o objeto responsável por construir a página. A partir disso, você poderá manipular os dados desse objeto.

Exemplo

Ao lado, o método inclui uma tag com o script do JQuery em todas as páginas que esitverem usando esse método.

class Produtos extends MeuSite\Produtos{\n public function __construct (Navigation\Page $page) { $page->addTagJS('js/jquery.js'); }\n\n }

Métodos e Transações
Modules > Classes > Navigation > JsonTransaction

Uma outra maneira de acessar dados de um método é utilizando transações assíncronas. As transações são scripts automáticos que conectam o frontend ao backend, para ser mais exato, conectam as Views aos Métodos através de uma conexão Ajax.

As transações fornecem um jeito rápido e seguro para resgatar dados do backend, além disso, ficam totalmente integradas com os métodos que você cria, evitando que você tenha que escrever todo o código duas vezes (uma no PHP e outra no Javascript).

Para utilizar os recursos de transações, sua estrutura de página deve conter Tags Dinâmicas configuradas corretamente.

Método Transacional

Um método transacional é uma função que contém instruções específicas que permitem que ela seja acessada através do javascript posteriormente.

Para criar um método transacional, basta criar uma função do tipo "public" que recebe duas variáveis, sendo que, a segunda variável, deve receber um objeto do tipo "Navigation\JsonTransacion".

$data contém todos os dados enviados pela View.

$transaction contém a instância da transação atual.

class Produtos extends MeuSite\Produtos{\n public function buscaProdutoPorNome ($data, Navigation\JsonTransaction $transaction) { return $this->buscarProduto(); }\n\n }

Funções transacionais

Através da instância $transaction é possível executar algumas funções próprias da transação.

$transaction->data($dados) retorna dados para a view. Pode ser trocada pela declaração return $dados. Caso a função seja chamada várias vezes, concatena os valores em um array. Também suporta uma instância de Fault para retornar um erro ao usuário.

$transaction->transactionSecurity() exige que a transação tenha sido chamada por uma view.

$transaction->requireAdmin() exige que a função tenha sido chamada por um usuário logado no painel.

$transaction->addRequestToResponse() adiciona os dados recebidos na resposta para fins de debug.

$transaction->status($status) define um status de retorno da transação.

$transaction->output($data) encerra o script e retorna dados personalizados ($data).

$transaction->validateRequest($mapa) valida os dados recebidos comparando-os com o mapa passado ($mapa).

Chamando Métodos

Assim que você incorporar esse método através da função $this->using('Produtos');, as funções transacionais serão automaticamente inseridas na Página, podendo ser chamadas através do Javascript do seguinte modo: Produtos.buscaProdutoPorNome();

Iniciando a transação

Dentro da sua View, chame o código Javascript correspondente ao seu método e função.

MeuMetodo.funcao(dados, callback, download, upload, load)

As variáveis a serem enviadas para a função são:

dados (Obrigatório mesmo que vazio) são os dados a serem enviados à função e resgatados na variável $data do método. Pode ser um Objeto, Array ou um Formdata.

callback (Obrigatório) função do Javascript que receberá os dados que o servidor retornou. A função de callback receberá 2 parâmetros: os dados e o objeto XHR.

dowload (Opcional) função do Javascript que receberá os dados de andamento do processo de download

upload (Opcional) função do Javascript que receberá os dados de andamento do processo de upload

load (Opcional) função do Javascript que receberá os dados ao final do processo.

Já há uma função padrão que realiza a leitura de dados ao final do processo. Apenas substitua uma função caso queira receber o retorno diretamente.

Retorno da transação

Assim que a transação for concluída, a função de callback receberá a seguinte estrutura de dados:

{ "status" : 200, "data" : {}, "executionTime" : 0.001 }

Caso a tranação tenha retornado um erro, você receberá a seguinte estrutura de dados

{ "status" : 400, "error" : { "message": "Houve um erro", "code": "genericError" }, "local": true, "executionTime" : 0.001 }

O índice "local" apenas é exibido quando a resposta foi realizada diretamente pelo Javascript, sem ter se conectado ao backend. Isso pode ocorrer quando há perda de conexão ou quando o método verifica que há campos inválidos.

Sempre que a transação retornar dados para uma função, verifique se houve qualquer erro antes de prosseguir.

Processando um formulário

Você pode processar formulários através da função request.parseForm(formulario, callback, MeuMetodo.funcao, download, upload, load), basta passar as seguintes variáveis:

Variáveis da função

formulario (Obrigatório) objeto com formulário já instanciado

callback (Obrigatório) função do Javascript que receberá os dados que o servidor retornou. A função de callback receberá 2 parâmetros: os dados e o objeto XHR.

MeuMetodo.funcao (Obrigatório) método para o qual você deseja enviar

dowload (Opcional) função do Javascript que receberá os dados de andamento do processo de download

upload (Opcional) função do Javascript que receberá os dados de andamento do processo de upload

load (Opcional) função do Javascript que receberá os dados ao final do processo.

Já há uma função padrão que realiza a leitura de dados ao final do processo. Apenas substitua uma função caso queira receber o retorno diretamente.

Processar ao submeter

Você pode processar um formulário diretamente através da propriedade "onsubmit", como mostrado abaixo.

Ao executar o submit do formulário, o mesmo será processado e será chamado método indicado MeuMetodo.funcao(), retornando os dados para a função declarada em "callback".

Mapas de Requisição

Os Mapas de Requisição são arrays associativos que contêm instruções para validar uma determinada quantidade de dados.

Eles servem para garantir que uma requisição receba dados corretos, permitindo que o sistema verifique se um array de dados está no padrão desejado

Esses dados...

{ "name" : "Maria da Silva", "idade" : 23, "telefoneDDD": "(19)", "sabores": ["morango", "abacaxi", "maracuja"] }

...podem ser validados por esse mapa

{ "name": { "name": "Nome do Usuário", "mandatory": true, "type": "string" }, "idade": { "name": "Idade do Usuário", "mandatory": true, "type": "integer" }, "telefoneDDD": { "mandatory": true, "match": "/\(0-9\)/" }, "sabores": { "mandatory": true, "type": "array", "minArray": 3 } }

Os mapas de requisição podem receber diversos tipos diferentes de instruções dependendo do tipo de validação que você deseja fazer.

Validação de Transação

Para realizar a validação de uma transação através de um Mapa de Requisição basta criar um array com as instruções.

Para validar uma transação dentro de um método, você deve utilizar a função $transaction->validateRequest($mapa);, passando como parâmetro o mapa de requisição.

Integrando mapas de transação ao frontend

Caso queria integrar esse mapa à requisição, crie uma variável pública com o mesmo nome da função adicionando o termo "_map" no final do nome. Desse modo, o mapa também será integrado à página e a requisição será validada ainda pelo frontend.

class Produtos extends MeuSite\Produtos{\n public $buscaProdutos_map = array();\n\n public function buscaProdutos ($data, Navigation\JsonTransaction $transaction) { $transaction->validateRequest($this->buscaProdutos_map); }\n\n

Validação de Dados

name: string "email" Nome do campo\n mandatory: bool "true" Define se esse valor é obrigatório\n type: string "integer" Define qual o tipo do valor (integer, bool, array, string)\n addslashes: bool "true" Utiliza a função addslashes para manter a segurança do banco de dados\n match: string "/[a-z]@/" Verifica se o valor passado dá match na expressão regular\n notMatch: string "/[a-z]@/" Verifica se o valor passado NÃO dá match na expressão regular\n minLenght: integer "5" Define a quantidade mínima de caracteres do campo (apenas quando o campo for string)\n maxLenght: integer "10" Define a quantidade máxima de caracteres do campo (apenas quando o campo for string)\n minArrayCount: integer "5" Define a quantidade mínima de elementos dentro do campo (apenas quando o campo for array)\n maxArrayCount: integer "10" Define a quantidade mínima de elementos dentro do campo (apenas quando o campo for array)\n map: array "{ name:titulo }" Mapa de validação dos elementos desse campo (apenas quando o campo for array)\n defaultValue: mixed "0" Valor padrão do campo, caso ele não tenha sido enviado\n reCaptcha: bool "true" Realiza a verificação de captcha do campo.\n replaceBefore: string "onlyNumbers" Realiza uma limpeza de dados ANTES das outras verificações baseada em uma função da ReplaceLibrary.\n replaceAfter: string "onlyNumbers" Realiza uma limpeza de dados APÓS as outras verificações baseada em uma função da ReplaceLibrary.\n

Validação de Arquivos

É possível também realizar a validação de arquivos enviados através de upload numa transação. Todos os argumentos podem ser combinados

type: string "file" Informa que é um arquivo\n multiple: bool "true" Permite que seja enviado multiplos.\n maxMultiple: integer "4" Número máximo de arquivos\n minMultiple: integer "2" Número mínimo de arquivos\n format: string "text/json" String com o formato permitido de arquivos. Pode ser enviado um array com os formatos.\n extension: string "jpg" Extensão esperada de arquivos. Pode ser enviado um array com as extensões\n maxSize: integer "1024" Tamanho máximo de cada arquivo (em bytes)\n minSize: integer "1024" Tamanho mínimo de cada arquivo (em bytes)\n maxSizeAll: integer "2048" Tamanho máximo de todos os arquivos enviados nesse campo (em bytes)\n minSizeAll: integer "2048" Tamanho mínimo de todos os arquivos enviados nesse campo (em bytes)\n maxDimension: array "[500,600]" Dimensões máximas da imagem [Largura, Altura]\n minDimension: array "[500,600]" Dimensões mínimas da imagem [Largura, Altura]\n

Mapas em Banco de Dados

Para executar funções de banco de dados, é possível informar um mapa de requisição, informando detalhes específicos para cada campo.

update: bool "true" Informa se o campo deve ser atualizado\n insert: bool "true" Informa se o campo deve ser inserido\n defaultValue: mixed "0" Valor padrão do campo, caso ele não tenha sido enviado\n columnName: string "product_id" Nome da coluna na planilha\n

Dados dinâmicos
Modules > Classes > Dynamic

Ao exibir informações em um site é comum que você crie listas de resultados dinâmicos. Essas listas resgatam informações do backend e são exibidas para o usuário das mais diversas formas, podendo inclusive utilizar a paginação dessas informações de maneira prática.

O módulo de dados dinâmicos permite que você resgate esses dados e exiba de maneira prodecural e rápida.

Implementando no backend

Primeiramente é importante criar um método transacional que irá receber as solicitações e retornar os dados necessários.

Para isso, dentro da função você deve instanciar o módulo Dynamic\Dynamic() que receberá os dados e retornará os dados necessários.

Exemplo de aplicação

public function listarProdutos ($data, Navigation\JsonTransaction $transaction) { $dynamic = new Dynamic\Dynamic($data);\n\n $tabelaDeDados = new Icecream('tabela');\n $tabelaDeDados->columns(["nome", "id"]);\n\n $dynamic->setSource($tabelaDeDados);\n\n return $dynamic->getDynamic();\n }

Explicação

  1. Inicialmente é instanciado o módulo Dynamic\Dynamic();
  2. Em seguida, é criada uma instância de uma tabela do Banco de Dados onde serão buscados os dados;
  3. A tabela é filtrada para retornar apenas as colunas "nome" e "id";
  4. A tabela é inserida como fonte do Dynamic através da função setSource($tabelaDeDados);
  5. Os resultados são retornados através da função getDynamic().

No exemplo mostrado acima, o módulo Dynamic\Dynamic() recebe todos os dados solicitados pelo usuário, tais como filtros de pesquisa, filtros de ordenação e paginação. Esses dados são automaticamente processados pelo módulo.

Filtragem

Antes de enviar a fonte de dados para o módulo através da função setSource(), você pode fazer uma pré-filtragem desses dados, selecionando as colunas a serem buscadas, ordens específicas, e condições.

Ao criar filtros específicos no frontend, você pode lê-los através da função getFilters() que retornará um array com todos os filtros. Isso é útil para quando você desejar realizar condições ou filtros específicos.

Se preferir, você também pode enviar uma lista de resultados prontos através da função setResults($results), porém, tenha em mente que a lista deve contar o formato esperado pelo Dynamic. Caso você tenha feito paginação, por exemplo, deve-se seguir o mesmo modelo de paginação.

Para resgatar outros filtros e informações do Dynamic, utilize as seguintes funções:

getPage()

Resgata a página atual

getPerPage()

Resgata a quantidade de itens por página solicitada

getSearch()

Resgata a coluna e termo a ser buscado

getOrder()

Resgata a ordem de dados selecionada

getFilters($filterId = null)

$filterId (Opcional) Recebe o ID de um filtro a recuperar.

Resgata os filtros solicitados (com exceção das páginas). Caso você NÃO passe um ID, retornará um array com todos os filtros. Ao passar um ID, retornará o valor daquele filtro, ou, caso o filtro não tenha sido enviado, retorna false.

Implementando no frontend

Para implementar no frontend, você deve executar inicialmente o comando Dynamic\Dynamic::addTag($page), fazendo com que os códigos Javascript e CSS necessários para o funcionamento sejam inseridos na página.

Em seguida, crie uma <div> que irá receber esses dados. Basta agora executar a função dynamic() no elemento através do Javascript.

Assim que a função for executada, ela irá fazer o seguinte caminho:

  1. Se não houver dados declarados em data, irá buscar os dados para exibição.
  2. Ao resgatar os dados, irá enviar um a um para a função declarada em template.
  3. Se a opção infiniteLoader for false, irá excluir todos os dados existentes da <div>.
  4. O resultado retornado da função acima irá ser inserido na <div> criada.

Aplicação

Para instânciar, basta executar o comando blocoDeDados = $("#bloco").dynamic(options); sendo "#bloco" o id da <div> que irá receber os dados. A variável options deve receber dados do seguinte formato:

data: array "{results:{}}" (Opcional) Dados iniciais.\n transaction: function "Produtos.lista" Função/objeto da transação\n template: function "modeloProdutos" Função que irá renderizar cada elemento\n onLoading: function "loading" (Opcional) Função chamada quando estiver carregando. Recebe true ao iniciar o carregamento e false ao finalizar\n onError: function "error" (Opcional) Função chamada caso haja erro\n onPlot: function "plot" (Opcional) Função chamada após os dados serem exibidos\n onData: function "changeData" (Opcional) Função chamada ao receber dados. Você pode manipular os dados e retorná-los\n onLoad: function "loading" (Opcional) Função chamada ao iniciar o carregamento da requisição XMLHttpRequest\n onDownload: function "loading" (Opcional) Função chamada ao baixar o carregamento da requisição XMLHttpRequest\n onUpload: function "loading" (Opcional) Função chamada ao subir o carregamento da requisição XMLHttpRequest\n infiniteLoader: bool "false" (Opcional) Se ativado não exclui os dados já exibidos\n filters: array "{}" (Opcional) Recebe dados de filtros\n paginate: array "{}" (Opcional) Recebe dados de paginação\n

Opções de filtragem

Você pode realizar a filtragem de dados diretamente nas opções, incluindo a ordem inicial ou pesquisa.

order: array "['coluna', 'ordem']" Ordenação\n search: array "['coluna','conteudo']" Pesquisa de palavra em uma determinada coluna\n

As duas chaves acima (order e search) são padrões do Dynamic e funcionam automaticamente, contudo, você pode criar outros filtros e realizar a leitura dos mesmos em seu método.

Opções de paginação

Se quiser paginar resultados, você deve declarar as variáveis currentPage e perPage. A paginação será realizada automaticamente.

onPage: function "paginar" Função a ser chamada ao paginar. Irá receber os dados da paginação.\n currentPage: number "1" Página inicial\n perPage: number "20" Valores por página\n

Exemplo de aplicação no Javascript

function template (item){ return "<li>" + item.id + " - " + item.nome + "</li>"; }\n $("ul#bloco").dynamic(options);
options = { transaction: Produtos.Listar, template: template, filters: { order: ["nome","ASC"] } }

Exemplo de aplicação no PHP

class Produtos extends _Core {\n public function Listar ($data, Navigation\JsonTransaction $transaction) { $dynamic = new Dynamic\Dynamic($data);\n\n $tabelaDeDados = new Icecream('tabela');\n $tabelaDeDados->columns(["nome", "id"]);\n\n return $dynamic->getDynamic($tabelaDeDados);\n }\n }

Templates HTML

Você pode utilizar uma função para renderizar o template caso precise de exibições avançadas, contudo, se preferir, pode também criar um HTML com tags especiais. O Dynamic irá ler o HTML e renderizar de acordo com o modelo criado.

Exemplo de aplicação

<div id="lista_de_itens">
   <div class="item" id="$id">
      <h2>$nome_produto</h2>
      <p>${ $preco_produto * 0.05 }</p>
      $if( $estoque < 1 ){
         <p>Produto esgotado</p>
      }
   </div>
</div>

Tipos de indicadores

$varivel Inclui o valor de uma variável

${ 1+1 } Renderiza o conteúdo das chaves como conteúdo de Javascript e retorna o resultado.

$if(1=1){ conteudo } Renderiza a condição descrita no if e exibe o conteúdo caso o resultado for true

Nesse caso, basta não declarar a chave template nas opções do Dynamic. Assim, o código irá ler o conteúdo do bloco e repetí-lo de acordo com os dados.

Ao utilizar a renderização de HTML, lembre-se de sempre priorizar a execução do Dynamic para que ele possa ler o conteúdo o mais rápido possível, evitando que seu usuário veja os códigos criados acima.

Se não for possível carregar rapidamente, prefira o uso de funções de template.

Funções de Dados

get()

Consulta o backend e coloca os dados

clear()

Apaga todos os dados da exibição da lista.

refresh()

Apaga todos os dados da exibição da lista e coloca-os de novo.

reload()

Apaga todos os dados da exibição da lista, consulta novamente o backend e coloca os dados novamente.

Acionando filtros

Há dois tipos de filtros automáticos que você pode solicitar.

Ordem

Para alterar a ordem de dados, basta chamar a função order("coluna", "ordem"), passando o nome da coluna a ser ordenada e a direção da ordem (DESC para decrescente ou ASC para crescentes).

Veja um exemplo de uma aplicação abaixo, na qual, ao mudar o select, a pessoa irá escolher a data em ordem Crescente ou Decrescente.

<select onchange="bloco.order('data', this.value)">\n    <option value="DESC">Decrescente</option>\n    <option value="ASC">Crescente</option>\n </select>\n

Busca

Para realizar a busca de um termo em uma coluna, utilize a função search("coluna", "termo").

Veja um exemplo de uma aplicação abaixo, na qual, ao acionar o botão, o conteúdo do input é enviado como pesquisa da coluna "nome".

<input type="text" id="busca">\n <input type="button" onclick="bloco.search('nome', $('#busca').val())" value="Buscar">\n

Filtros personalizados

Você pode incluir também filtros personalizados para que sua função no backend leia e interprete. Para isso, basta executar a função: filter("id", "valor"), no qual você deverá passar um identificador desse filtro e o valor que ele conterá.

Filtros personalizados não são processados automaticamente pelo Dynamic, porém, você poderá utilizá-los em sua função. Veja mais em implementando no backend.

Funções de Paginação

Caso você tenha habilitado as funções de paginação, a mesma será feita sozinha pelo Dynamic. Para interagir com a paginação, você poderá utilizar as seguintes funções:

page(pag)

pag(Opcional) Recebe o número da página

Se enviado um número de página, realiza a troca da página. Caso não envie a função retorna a página atual.

perPage(prp)

prp(Opcional) Recebe a quantidade de itens por página

Se enviado um número, realiza a troca da quantidade de itens por página. Caso não envie a função retorna a quantidade atual.

nextPage()

Busca a próxima página. Caso essa seja a última página, retorna false e não realiza operações.

previousPage()

Busca a página anterior. Caso essa seja a primeira página, retorna false e não realiza operações.

lastPage()

Busca a última página.

firstPage()

Busca a primeira página.

shiftPage(qtd)

qtd Quantidade de páginas a ser puladas. Pode ser um número positivo ou negativo (para voltar os resultados).

Pula um determinado número de páginas.

resetPage()

Retorna a opção "página" e o "itens por página" para seu estado inicial.

Todas as funções acima realizam a alteração da página e recarregam os dados. Se você desejar apenas alterar os valores, sem recarregar os dados, utilize a função com um _ no início do nome.

Botões de paginação

Em muitos casos você precisará incluir botões de paginação para que o usuário possa alterar as páginas. Nesse caso, você pode criar uma função que irá receber os dados de paginação, passando-a na variável onPage.

Assim que ocorra qualquer mudança de página, essa função será chamada e receberá dois parâmetros. O primeiro é uma instância do módulo de paginação, o segundo é o próprio objeto do dynamic.

Para criar automaticamente a sequencia de botões, você pode utilizar a função paginateOn(block, separator, delta).

paginateOn(block, separator, delta)

block Elemento (uma div, por exemplo) que receberá os botões.

separator (Opcional) Separador entre o espaçamento de números (Padrão é ...).

delta (Opcional) Quantidade de botões antes e depois da página atual.

Exemplo de aplicação

function definirPaginacao (paginate) { paginate.paginateOn($("#bloco-de-botoes"), "...", 3); }

Personalizando os botões

Os botões gerados possuem uma estrutura padrão de classes CSS. Para editar, basta alterar as classes:

Exemplo de renderização

<div>\n    <div class="paginate-item-page">1</div>\n    <div class="paginate-item-page current-page">2</div>\n    <div class="paginate-item-separator">...</div>\n    <div class="paginate-item-page">120</div>\n </div>

Classes CSS

.paginate-item-page Item comum, clicável.

.current-page Item comum, atualmente ativo, não clicável.

.paginate-item-separator Separador, não clicável.

Funções do módulo de paginação

Dentro de sua função de paginação, você poderá resgatar outros dados da página também.

shiftPage(qtd)

qtd Quantidade de páginas a ser puladas. Pode ser um número positivo ou negativo (para voltar os resultados).

Pula um determinado número de páginas.

size()

Quantidade de itens no geral

totalResults()

Quantidade de itens neste resultado

currentPage()

Página atual

totalPages()

Quantidade de páginas

itemsPerPage()

Itens por página

resultsFrom()

Início dos resultados

resultsTo()

Final dos resultados

isFirst()

Verifica se a página atual é a primeira

isLast()

Verifica se a página atual é a última

paginate()

Retorna a sequência de paginação caso você queira utilizar um layout personalizado

Storm (CRUD)
Modules > Classes > Storm

O Storm é um módulo que permite a criação de CRUDs automáticos, sem a necessidade de criar rotinas repetitivas de seleção (select), inserção (insert), edição (update) e exclusão (delete) para formulários.

O Storm, assim como o Dynamic, é um módulo que deve ser implementado no backend e no frontend, assim, ambas as interfaces se conversam e podem trocar dados facilmente.

Você deve criar um formulário no frontend e instanciá-lo com o Storm. Assim, cada vez que executar uma ação (selecionar, inserir, editar, excluir) o módulo do Storm no backend irá ler sua ação e processar automaticamente aquilo que você precisa sem que você tenha que criar uma função específica para cada uma dessas ações.

Implementando no backend

Primeiramente é importante criar um método transacional que irá receber as solicitações e retornar os dados necessários.

Para isso, dentro da função você deve instanciar o módulo Storm\Storm() que receberá os dados e retornará os dados necessários.

Exemplo de aplicação

public function formularioProdutos ($data, Navigation\JsonTransaction $transaction) { $storm = new Storm\Storm($data);\n\n $tabelaDeDados = new Icecream('produtos');\n $storm->setSource($tabelaDeDados);\n\n return $storm->getStorm();\n }

Explicação

  1. Inicialmente é instanciado o módulo Storm\Storm();
  2. Em seguida, é criada uma instância de uma tabela do Banco de Dados de onde serão buscados/inseridos/editados/excluídos os dados;
  3. A tabela é inserida como fonte do Storm através da função setSource($tabelaDeDados);
  4. Os resultados são retornados através da função getStorm().

No exemplo mostrado acima, o módulo Storm\Storm() recebe todos os dados solicitados pelo usuário. Esses dados são automaticamente processados pelo módulo, contudo, você poderá intervir nesse processamento caso julgue necessário.

Intervenção de Resultados

Antes de enviar a fonte de dados (tabela) para o módulo através da função setSource(), você pode fazer uma pré-filtragem desses dados, selecionando as colunas a serem buscadas, por exemplo.

Você também pode resgatar e alterar diversos dados dessa transação através das seguintes funções:

getValues()

Retorna os valores enviados no formulário

setValue($key, $value)

Altera um valor enviado pelo formulário, sendo $key o nome do campo e $value o valor que ele deverá conter.

getKey()

Resgata o nome do campo chave, que contém o ID

getKeyValue()

Resgata o valor da chave (ID)

Em alguns casos, pode ser que você precise configurar ações a serem executadas dependendo da ação solicitada (seleção, inclusão, edição, exclusão). Para resgatar a ação, basta executar a função $storm->getAction().

Exemplo de aplicação

public function formularioProdutos ($data, Navigation\JsonTransaction $transaction) { $storm = new Storm\Storm($data);\n\n $tabelaDeDados = new Icecream('produtos');\n $storm->setSource($tabelaDeDados);\n\n if($storm->getAction() == "delete")\n { $tabelaDeImagens = new Icecream("produtos_imagens");\n $tabelaDeImagens->where("produtos_id", $storm->getKeyValue());\n $tabelaDeImagens->delete();\n }\n\n return $storm->getStorm();\n }

No exemplo acima o código checa se a ação é de excluir um produto. Se for, ele apaga também todos os registros da tabela "produtos_imagens" que tiverem o ID da tabela de produtos que está sendo excluída.

Implementando no frontend

Arquivos

Uploads

Modules > Traits > FileTrait.php

Para incorporar as funcionalidades de arquivo à sua classe, basta declarar use FileTrait dentro da sua classe.

Upload de arquivos

Ao receber um arquivo dentro do método, basta chamar a seguinte função para realizar o upload

$this->saveUploadFiles($folder, $files, $method, $overwrite, $ignoreOnOverwrite);

$folder (Obrigatório) pasta na qual serão salvos os arquivos.

$files (Obrigatório) Arquivos vindos da requisição.

$method (Opicional - falso como padrão) Método para renomeação automática dos arquivos.

$overwrite Caso true, permite sobrescrever arquivos com nomes iguais.

$ignoreOnOverwrite Caso true, continua seguindo sem retornar erro caso haja um arquivo com nome duplicado.

Método de renomeação de arquivo

A função "saveUploadFiles" permite o uso automático da função "renameUploadFiles" que tem por objetivo renomear os arquivos ao salvá-los.

Essa prática é importante para garantir que os arquivos salvos não tenham caracteres especiais e que sejam salvos de maneira padrão.

Abaixo estão os tipos de métodos disponíveis

"md5_file" Hash MD5 do arquivo.

"md5_time" Hash MD5 da data/hora.

"date" Data YYYY-MM-DD.

"serial_date" Data YYYYMMDD.

"date_time" Data e hora YYYY-MM-DD_HH-MM-SS.

"serial_date_time" Data e hora YYYYMMDDHHMMSS.

"name" Apenas normalizar o nome (retira espaços e caracteres especiais)

"name_date" Nome normalizado + data .

"name_date_time" Nome normalizado + data e hora.

"name_serial_date" Nome normalizado + data (sequenciado).

"name_serial_date_time" Nome normalizado + data e hora (sequenciado).

Recursos prontos

Biblioteca de tamanhos

Modules > Libraries > FileLibrary.php

Na biblioteca de tamanhos você encontra tamanhos prontos de arquivos para usar como medida. São eles

FileLibrary::SIZE_100KB Referente a 100KB (102400 bytes).

FileLibrary::SIZE_300KB Referente a 300KB (307200 bytes).

FileLibrary::SIZE_500KB Referente a 500KB (512000 bytes).

FileLibrary::SIZE_800KB Referente a 800KB (819200 bytes).

FileLibrary::SIZE_1MB Referente a 1MB (1048576 bytes).

FileLibrary::SIZE_2MB Referente a 2MB (2097152 bytes).

FileLibrary::SIZE_5MB Referente a 5MB (5242880 bytes).

FileLibrary::SIZE_8MB Referente a 8MB (8388608 bytes).

FileLibrary::SIZE_10MB Referente a 10MB (10485760 bytes).

Biblioteca de MimeType

Modules > Libraries > MimeLibrary.php

Na biblioteca de MimeType você encontra os mimetypes para vários tipos de arquivo, facilitando a validação

Manipulando imagens

Modules > Traits > ImageTrait.php

O módulo de imagens permite manipular diversas imagens facilmente. Para incorporar as funcionalidades de arquivo à sua classe, basta declarar use ImageTrait dentro da sua classe.

Converter formato

$this->convertImage($imagePath, $newImagePath, $quality);

$imagePath (Obrigatório) caminho do arquivo atual. (ex: images/foto.jpg)

$newImagePath (Obrigatório) novo caminho do arquivo. (ex: images/foto.png)

$quality (Opcional) Qualidade da imagem de 0 a 100.

Cortar em círculo

$this->cropCircle($imageBasePath, $newPath, $quality)

$imageBasePath Caminho da imagem base.

$newPath Caminho onde a nova imagem será salva.

$quality (Opcional) Qualidade da imagem de 0 a 100.

Redimensionar

$this->resizeImage($imagePath, $dimension, $newImagePath, $forceStretch, $forceIncreaseSize, $quality)

$imagePath Caminho da imagem a ser convertida.

$dimension Array com Lagura e Altura desejadas / Porcentagem para redimensionamento.

$newImagePath Caminho a ser salva a nova imagem (deve receber a extensão desejada).

$forceStretch (Opcional) Se TRUE força a imagem a ficar no tamanho definido.

$forceIncreaseSize (Opcional) Se TRUE permite que a imagem seja ampliada se necessário.

$quality (Opcional) Qualidade da imagem de 0 a 100.

Fundir/Sobrepor imagens

$this->mergeImage($imageBasePath, $imageOverPath, $newPath, $quality, $dimension, $position, $opacity)

$imageBasePath Caminho da imagem base.

$imageOverPath Caminho da imagem de sobreposição.

$newPath Caminho onde a nova imagem será salva.

$quality Qualidade da imagem de 0 a 100.

$dimension Array com Lagura e Altura desejadas / Número de porcentagem para redimensionamento.

$position (Opcional) Array com posição (x,y) da sobreposição na base. Pode conter um valor numérico, 'center', 'right', 'left', 'top' ou 'bottom'.

$opacity (Opcional) Opacidade do elemento. Evitar para arquivos PNG com transparência.

Escrever sobre imagem

$this->writeOnImage($imageBasePath, $newPath, $text, $fontSize, $hexColor = "#000000", $fontPath = null, $position = array('center', 'center'), $quality = 100)

$imageBasePath Caminho da imagem base.

$newPath Caminho onde a nova imagem será salva.

$text Texto a ser escrito.

$fontSize Tamanho da fonte.

$hexColor Cor em hexadecimal.

$fontPath Caminho do arquivo fonte (.ttf).

$position Array com posição do texto (x,y). Pode conter um valor numérico, 'center', 'right', 'left', 'top' ou 'bottom'.

$quality Qualidade da imagem de 0 a 100.

Gerando imagens em lote

É possível gerar várias imagens em lote, criando diversas características para cada uma através de um mapa

$this->batchImage($imageBasePath, $map, $folder, $filenameReplace = null)

$imageBasePath Caminho da imagem base.

$map Mapa de manipulação

$folder Caminho onde serão salvas a imagens.

$filenameReplace Aceita sobrepor imagens.


Dentro do parâmetro $map deverá ser enviado um array com as instruções de manipulação a imagem, chamado de mapa de imagem.

O mapa é um array sequencial que contém arrays associativos com as operações a serem executadas na imagem.

Converter e Salvar

convert: string "jpg" Novo formato da imagem\n quality: int "100" Qualidade da imagem de 0 a 100.\n appendFilename: mixed "true" Se true, inclui descrições no final do nome do arquivo de acordo com as operações realizadas. Pode ser passado uma string também a adicionar no final do nome do arquivo\n

Se appendFilename estiver habilitado, a opção quality inclui "_quality" ao final do nome do arquivo.

Redimensionar

maxDimension: array "[500,500]" Dimensão máxima da imagem\n minDimension: array "[500,500]" Dimensão mínima da imagem\n

Se appendFilename estiver habilitado, inclui "_WidthXHeight" ao final do nome do arquivo.

Fundir

merge: array "map" Array com as abaixo:\n    overImage: string "public/img.jpg" Caminho da imagem de sobreposição.\n    dimension: mixed "[500,500]" Lagura e Altura desejadas / Número de porcentagem para redimensionamento.\n    position: mixed "center" (Opcional) Array com posição (x,y) da sobreposição na base. Pode conter um valor numérico, 'center', 'right', 'left', 'top' ou 'bottom'.\n    opacity: int "100" (Opcional) Opacidade do elemento. Evitar para arquivos PNG com transparência.\n

Se appendFilename estiver habilitado, inclui "_merged" ao final do nome do arquivo.

Escrever na imagem

write: array "map" Array com as abaixo:\n    text: string "Texto" Texto a ser escrito\n    fontSize: int "10" Tamanho da fonte\n    color: string "#000000" Cor em hexadecimal\n    fontPath: string "Texto" Caminho do arquivo fonte (.ttf)\n    position: mixed "center" (Opcional) Array com posição (x,y) da sobreposição na base. Pode conter um valor numérico, 'center', 'right', 'left', 'top' ou 'bottom'.\n

Se appendFilename estiver habilitado, inclui "_text" ao final do nome do arquivo.

Cortar imagem

crop: array "map" Array com as abaixo:\n    dimension: mixed "[500,500]" Lagura e Altura desejadas / Número de porcentagem para redimensionamento.\n    position: mixed "center" (Opcional) Array com posição (x,y) da sobreposição na base. Pode conter um valor numérico, 'center', 'right', 'left', 'top' ou 'bottom'.\n

Se appendFilename estiver habilitado, inclui "_text" ao final do nome do arquivo.

Exemplo de mapa

[ {"convert" : "png", "quality": 70,"appendFilename":"_original"}, {"maxDimension" : [300,300], "quality": 50 }, {"write" : { "text" : "Marca d'agua", "fontSize": 15, "position": "center"}, "quality": 100} ]

Executando

Ao executar a função $this->batchImage() com o exemplo descrito, serão salvos 3 arquivos com as seguintes caracterísicas:
  1. imagem_original.png no formato PNG e qualidade 70.
  2. imagem_300x300_quality50.jpg no formato padrão, qualidade 50 e redimensionada para 300 x 300.
  3. imagem_text_quality100.jpg no formato padrão, qualidade 100 e com o texto "Marca d'água" escrito ao centro.

E-mail
Modules > Classes > Mail

O módulo de e-mail possui diversas ferramentas práticas para envio de emails através de uma conexão SMTP, comum à maior parte dos e-mails. Você poderá instancíá-lo através da chamada new Mail\Mail();

Ao enviar e-mails esteja ciente de que o seu servidor SMTP pode ter diversos limites que influenciam no envio de e-mails, tais como:
  • Limite de mensagens por dia ou por mês
  • Limite de destinatários
  • Limite de conexões
  • Filtro de SPAM para mensagens de saída
  • Entre outros..
Caso sua aplicação realize envios em massa, recomenda-se utilizar serviços de SMTP especializados.

Configurando

Você pode configurar mais de uma conta de e-mail para envio de e-mails. Para isso, você deverá ter os dados de SMTP dessa conta. No arquivo Config > mail.config insira em "accounts" os dados de cada conta.

Variáveis de configuração

host: string "localhost" Servidor SMTP\n port: int "587" Porta de conexão SMTP(geralmente 587 ou 465)\n username: string "email@dominio.com" Nome do usuário SMTP\n password: string "123456" Senha do usuário SMTP\n charSet: string "UTF-8" Charset da mensagem\n encoding: string "base64" Tipo de codificação da mensage,\n SMTPAuth: bool "true" Requer autenticação de SMTP\n SMTPSecure: mixed "SSL" Requer segurança (Pode ser false ou um valor como SSL ou TLS)\n SMTPDebug: int "0" Habilita o debug do PHPMailer (1,2 ou 3)\n fromEmail: string "no-reply@dominio.com" E-mail do Remetente padrão\n fromName: string "Site X" Nome do Remetente padrão\n

Utilizando múltiplas contas

Ao configurar mais de uma conta, deve-se sempre inserir o ID que será responsável pelo envio. No exemplo ao lado, é possível encontrar dois bancos cadastrados, um chamado noreply e outro chamado marketing.

Ao chamar uma função de Email, o módulo passará a utilizar por padrão o primeiro banco declarado. No exemplo ao lado, passará a utilizar o banco noreply.

Para alterar a conta de envio, basta passar o id da conta na construção do objeto de Email:

new Mail\Mail('marketing');

Você também pode usar posteriormente a função defineCredentials('marketing').

Exemplo de aplicação

"accounts":{ "noreply" : { "host" : "localhost", "port" : "25", "username" : "noreply@site.com.br", "password" : "123456", "charSet" : "UTF-8", "encoding" : "base64", "SMTPAuth" : true, "SMTPSecure" : false, "SMTPDebug" : 0, "fromEmail": "noreply@site.com.br", "fromName": "Não responda" }, "noreply" : { "host" : "localhost", "port" : "25", "username" : "marketing@site.com.br", "password" : "123456", "charSet" : "UTF-8", "encoding" : "base64", "SMTPAuth" : true, "SMTPSecure" : false, "SMTPDebug" : 0, "fromEmail": "marketing@site.com.br", "fromName": "Promoções" } }

Ao utilizar uma conta de e-mail do Gmail, lembre-se de habilitar a opção "Acesso a app menos seguro" nas Configurações de Segurança da sua conta Google.

Criando templates

Templates de e-mail são arquivos HTML que contém o layout a ser enviado nas mensagens. Esses templates facilitam o envio de mensagens com conteúdo HTML.

Para criar um template basta criar um arquivo .html na pasta Resources > Mail > Templates. Esse template poderá ser chamado posteriormente através do nome do seu arquivo, sem a extensão .html.

Buscando um template

Para resgatar o conteúdo de um template, basta utilizar a função $mail->template("nome_do_template");. Essa função retornará todo o conteúdo HTML do template pronto para ser enviado ou exibido.

Inserindo variáveis no template

É possível inserir varíáveis dentro de um template a fim de incluir dados dentro da mensagem que você está enviando. Para isso, basta incluir os nomes das variáveis no HTML com a seguinte estrutura .

Ao chamar a função $mail->template(); inclua no segundo parâmetro um array com as variáveis e seus valores. Veja no exemplo de envio.

Funções de e-mail

setFrom($address, $name)

$address Endereço de email do remetente.

$name (opcional) Nome do remetente.

Altera o remetente da mensagem. Caso a função não seja chamada, o remetente será o definido no arquivo de configuração.

addAddress($addresses, $name)

$addresses Endereços de email do destinatário. Pode ser um array com vários endereços.

$name (opcional) Nome do destinatário.

Inclui um ou mais destinatários

Caso deseje enviar a mensagem para vários destinatários, passe um array no parâmetro $addresses com o seguinte formato:

[ { "address" : "cliente1@dominio.com", "nome" : "cliente1" }, { "address" : "cliente2@dominio.com", "nome" : "cliente2" } ]

addBcc($addresses, $name)

$addresses Endereços de email do destinatário. Pode ser um array com vários endereços.

$name (opcional) Nome do destinatário.

Inclui um ou mais destinatários ocultos

Caso deseje enviar a mensagem para vários destinatários ocultos, passe um array no parâmetro $addresses com o seguinte formato:

[ { "address" : "cliente1@dominio.com", "nome" : "cliente1" }, { "address" : "cliente2@dominio.com", "nome" : "cliente2" } ]

send($subject, $content, $html = true)

$subject Assunto

$content Conteúdo da mensagem

$html (opcional) Indica que o conteúdo da mensagem está em formato HTML.

Realiza o envio do e-mail.

Exemplo de Envio

Exemplo de template

O template abaixo é um exemplo de envio de cupom para usuários de um site. Ele pode ser criado no caminho Resources > Mail > Templates > cupom.html

Olá !

\n

Você tem um cupom de 5% em compras em nosso site.

Código do cupom:

Envio da mensagem

$mail = new Mail\Mail();\n $variaveis = array(\n    "nome_usuario" => "Murilo"\n    "codigo_cupom" => "A1F38C25C"\n );\n $mensagem = $mail->template("cupom", $variaveis);\n $mail->addAddress("murilo@dominio.com", "Murilo");\n $mail->send("Cupom de 5%", $mensagem);

Internacionalização
Modules > Classes > Culture

O sistema de internacionalização permite criar aplicações web com diferentes culturas dentro de um projeto. Cada cultura é configurada com um tipo de moeda, língua e fuso horário.

Você deve criar um registro para cada um dos tipos acima, assim, cada cultura poderá compartilhar determinados pontos.

Configurando

Para configurar esses registros, acesse o arquivo de configuração Config > culture.config. Nele haverão os seguintes registros:

timezones: array "{}" Tipos de fuso horário\n currencies: array "{}" Tipos de moeda\n languages: array "{}" Tipos de língua\n cultures: array "{}" Lista de culturas\n default: string "Brasil" Nome da cultura padrão\n

Cultura

Uma cultura contém um ID de cada um dos tipos, ou seja, é um conjunto que reúne um tipo de fuso, um tipo de moeda e um tipo de língua. Uma cultura deve ser configurada do seguinte modo:

Variáveis

timezone: string "America" Tipo de fuso horário dessa cultura\n currency: string "USD" Tipo de moeda dessa cultura\n language: string "en" Tipo de língua dessa cultura\n

Cada um dos valores acima deve conter um índice de seu tipo. Por exemplo language deve receber um índice declarado em languages.

Exemplo

{ "cultures":{ "Brasil":{ "timezone": "Brasilia", "currency": "BRL", "language": "pt-BR" }, "EUA":{ "timezone": "Washington", "currency": "USD", "language": "en" } } }

Fuso-horário

Um fuso horário é utilizado para gerar e ler datas de acordo com o local em que a pessoa está localizada. Para isso, você deve configurar um fuso-horário do seguinte modo:

Variáveis

label: string "UTC-3" Etiqueta padrão\n timezone: string "America/Sao_Paulo" Identificação do fuso horário (no padrão PHP)\n dateFormat: string "d/m/Y" Formato de data (no padrão PHP)\n hourFormat: string "H:i:s" Formato de hora (no padrão PHP)\n dateTimeFormat: string "d/m/Y H:i:s" Formato de data e hora (no padrão PHP)\n

Exemplo

{ "timezones" :{ "Brasilia":{ "label" : "UTC-3", "timezone": "America/Sao_Paulo", "dateFormat": "d/m/Y", "timeFormat": "H:i:s", "dateTimeFormat": "d/m/Y H:i:s" } } }

Funções

Moeda

Um tipo de moeda permite que você gere valores no formato de moeda desejado. Para ser utilizado, você deve configurar um formato de moeda, como mostrado abaixo:

Variáveis

label: string "BRL" Etiqueta padrão\n name: string "Real Brasileiro" Nome da moeda\n symbol: string "R$" Símbolo da moeda\n symbolPlacing: string "$ #" Formato de colocação da moeda e número\n thousandMark: string "." Separador dos milhares\n decimalMark: string "," Separador decimal\n

A variável symbolPlacing tem por objetivo informar como o símbolo do dinheiro deve ser incluído. No exemplo acima "$ #", $será substituido pelo simbolo R$, e o # será substituído pelo número, fazendo com que seja exibido R$ 100, por exemplo.

Exemplo

{ "currencies" :{ "BRL":{ "label" : "BRL", "name" : "Real Brasileiro", "symbol":"R$", "symbolPlacing": "$ #", "thousandMark": ".", "decimalMark": "," } } }

Língua

Você pode configurar as culturas para uso no arquivo Config > language.config, inserindo as línguas em "languages" e a língua padrão em "default".

Variáveis

label: string "pt_BR" Etiqueta da língua padrão HTML\n name: string "Português Brasileiro" Nome da língua\n direction: string "ltr" Ordem de escrita da página\n charset: string "UTF-8" Tipo de dados do banco\n suitableFor: array "[pt-BR, pt]" Define para qual tipo de exigência essa língua é adequada (verifique mais em Sites multilíngue)\n

Utilizando múltiplas línguas

Ao configurar mais de uma língua, deve-se sempre inserir um ID para cada uma. O ID não precisa receber o nome de uma língua padrão, mas funciona como identificador.

Exemplo

{ "languages" :{ "pt_BR":{ "charset" : "UTF-8", "direction" : "ltr", "name" : "Português Brasileiro", "label" : "pt_BR", "timezone": "America/Sao_Paulo" "currency":"R$", "currencyFormat": "$ #.###", "decimalMark": "," "suitableFor": ["pt-BR", "pt"], "datetimeFormat": "d/m/Y H:i:s" } } }

Funções de língua

currentLanguage($language )

Resgata o código da língua padrão do momento.

checkLanguageAvailability($languages)

$languages Códigos de língua (string com um código ou array com vários)

Retorna se a língua passada está disponível. Se passado um array, retorna a primeira das línguas que estiver disponível.

getLanguage($language = null)

$language (Opcional) Código da língua. Se não for passado, a língua exibida será a definida na cultura "default".

Resgata todos os valores de uma determinada língua.

getLanguageCharset($language = null)

$language (Opcional) Código da língua. Se não for passado, a língua exibida será a definida na cultura "default".

Retorna o Charset da língua em questão

getLanguageName($language = null)

$language (Opcional) Código da língua. Se não for passado, a língua exibida será a definida na cultura "default".

Retorna o Nome da língua em questão

getLanguageDirection($language = null)

$language (Opcional) Código da língua. Se não for passado, a língua exibida será a definida na cultura "default".

Retorna a Direção de Escrita da língua em questão

getLanguageLabel($language = null)

$language (Opcional) Código da língua. Se não for passado, a língua exibida será a definida na cultura "default".

Retorna a Etiqueta da língua em questão

Arquivos de Língua

Os arquivos de língua ficam disponíveis em Resources > Languages. Dentro dessa pasta estão as pastas com o ID de cada língua e, dentro delas, estão os arquivos de tradução.

Cada arquivo representa um "escopo" diferente, ou seja, cada um possui traduções de uma determinada parte do sistema.

validation.json Erros e validações.

admin.json Textos e termos do CMS.

console.json Mensagens do Console.

icecream.json Textos do módulo Icecream.

Cada módulo específico poderá ter um arquivo de traduções em formato .json. O nome do arquivo deve corresponder ao seu escopo, enquanto que a pasta corresponde ao ID da Config > language.config.

O arquivo é composto por uma chave e um valor. A chave contém o valor "padrão" em inglês, enquanto que o valor irá conter a tradução respondente na língua do arquivo.

Exemplo simples

{ "Welcome":"Bem-vindo", "Good Morning": "Bom dia", "Good Afternoon": "Boa tarde", "Good Evening": "Boa noite" }

Variáveis

Para inserir uma variável dentro de uma tradução, utilize o demarcador %s no local onde a palavra será inserida.

{ "Your order number is %s":"O número do seu pedido é %s", "Hello %s how are you?":"Olá %s como vai?" }

Traduzindo

Sites que contêm internacionalização exigem que todos ou a maior parte dos contéudo do seu site e requisições seja escrito em diferentes línguas. Para isso, utilize a seguinte função:

$this->write($content, $scope = null, $values = null, $language = null)

$content Conteúdo a ser traduzido (correspondente à chave)

$scope (Opcional) Escopo da tradução.

$values (Opcional) Array de valores a serem incluídos no conteúdo traduzido (substituindo os %s).

$language (Opcional) Código da língua. Se não for passado, a língua exibida será a definida em "default".

Exemplo de texto simples

echo $this->write("Welcome");

Bem vindo

Exemplo de texto com variáveis

echo $this->write("Hello %s how are you?", "website", ["Maria"]);

Olá Maria como vai?

Se desejar utilizar textos traduzidos dentro do seu HTML, você poderá utilizar Super Tags para facilitar o desenvolvimento.

Sites multilíngues

É comum que sites multilíngues possuam mecanismos de troca de língua, assim, seus usuários poderão acessar o site de diferentes localidades e escolher uma língua adequada.

Você poderá disponibilizar dois métodos de seleção de cultura: manualmente, na qual seu usuário pode escolher a língua/cultura que deseja ou automaticamente, na qual o sistema detecta a cultura a ser utilizada para aquele usuário.

Detectando a cultura

Os navegadores atuais trabalham com um valor de cabeçalho chamado Accept-Language, pelo qual informam a língua em que o usuário costuma ver sites. Essa função realiza a checagem desse cabeçalho e define como padrão a primeira das línguas solicitadas que estiver disponível.

Para conhecer mais sobre esse cabeçalho, seus usos e boas práticas, acesse a documentação.

A função abaixo resgata o valor do cabeçalho Accept-Language e busca a cultura que possui aquela língua. A partir disso, define como padrão aquela cultura.

autoAssignCulture($clearCulture = true)

$clearCulture (Opcional) Se definido como true, sobrescreve todas as informações: língua, moeda e fuso horário.

Mesmo que você utilize a função acima é importante permitir que seu usuário escolha por si mesmo a língua, moeda e/ou fuso que ele deseja utilizar. Para isso, você pode passar o parâmetro $clearCulture como false, assim, mesmo que a cultura seja alterada, os demais tipos serão preservados como estavam.

Exemplo

Imagine que seu site tenha as línguas: Espanhol e Inglês disponíveis. Um usuário tenta acessar seu site com o cabeçalho Accept-Language exigindo as línguas "Francês" ou "Inglês". A função irá buscar primeiramente se a língua "Francês" está disponível, como não está, procura a próxima (Inglês), e assim por diante até encontrar uma língua disponível.

Em último caso, ele mantém a língua padrão.

Disponibilidade de língua

A checagem de "disponibilidade" da língua se dá pelas variáveis suitableFor ou, em sua ausência, label. A variável suitableFor deve receber um array de códigos de língua contendo as línguas as quais essa configuração atende. Por exemplo: Para português brasileiro usa-se o código pt-BR, contudo, caso alguém de Portugal acesse, a mesma língua pode ser exibida. Nesse caso, deve-se colocar que essa língua está disponível tanto para pt-BR quanto para pt.

Você pode checar a disponibilidade de uma língua através da seguinte função:

checkLanguageAvailability($languages)

$languages Código da língua. Pode também ser um array do qual ele retornará a primeira ocorrência de língua disponível

Em sites multilíngua, lembre-se de sempre utilizar uma língua padrão que seja inteligível ao seu público, como o inglês ou o espanhol, assim, caso você não tenha disponível a língua específica daquele usuário, ele ainda poderá navegar pelo seu site.

É importante também assegurar que seu usuário possa trocar de língua em algum momento, mesmo que você esteja utilizando a função de detecção de línguas.

Banco de Dados
Modules > Classes > Databank

O Framework vem com um módulo pronto de Banco de Dados que possui todas as funções necessárias para facilitar o desenvolvimento.

Apesar da facilidade, o módulo de é mais comumente utilizado por outros módulos que o estendem.

Configurando

Você pode configurar mais de um banco de dados para acesso no arquivo Config > db.config insira em "server" os dados de cada banco.

Variáveis de configuração

user: string "root" Nome de Usuário\n password: string "123456" Senha\n database: string "dados_site" Nome da Database\n host: string "localhost" Endereço/IP do servidor\n query_limit: integer "250" Limite de inserções em um insert\n charset: string "UTF-8" Tipo de dados do banco\n

Utilizando múltiplos bancos

Ao configurar mais de um banco, deve-se sempre inserir um ID para cada banco. No exemplo ao lado, é possível encontrar dois bancos cadastrados, um chamado site e outro chamado blog.

Ao chamar uma função de Banco de Dados, o módulo passará a utilizar por padrão o primeiro banco declarado. No exemplo ao lado, passará a utilizar o banco site.

Para alterar a banco, basta utilizar a função $banco->setServer('nome_do_banco');.

Exemplo de aplicação

"servers":{ "site": { "user" : "root", "password" : "123456", "database" : "dados_site", "host" : "localhost", "query_limit":250, "charset" : "utf8" }, "blog": { "user" : "root", "password" : "123456", "database" : "dados_blog", "host" : "localhost", "query_limit":250, "charset" : "utf8" } }

Icecream
Modules > Classes > Icecream

O Icecream é um ORM (Object-relational mapping) responsável por realizar consultas de Banco de Dados de maneira estruturada.

Estrutura Básica

Assim que o banco de dados foi configurado, basta instanciar o módulo Icecream para realizar uma requisição ao banco de dados.

use Icecream\ Icecream;\n $db = new Icecream($table, $alias);
$table: string "nome_da_tabela" Recebe o nome da tabela\n $alias: string "tb" (Opcional) Recebe o alias da tabela\n

No exemplo acima, basta utilizar a variável $db para executar funções relacionadas a essa tabela para receber os resultados, podendo linkar várias opções num mesmo banco.

Exemplo 1

use Icecream\ Icecream;\n $db = new Icecream($table, $alias);\n $db->where("idade", "50" );\n $db->orderBy("nome", "ASC");\n $resultado = $db->select();

Exemplo 2

use Icecream\ Icecream;\n $db = new Icecream($table, $alias)\n $resultado = $db\n   ->where("idade", "50" )\n   ->orderBy("nome", "ASC")\n   ->select();

Models

Ao utilizar Models você cria um caminho mais fácil para acesso às tabelas. Para criar um novo Model, basta criar um arquivo dentro da pasta Models com o mesmo nome de sua classe. O model deverá extender a classe IcecreamModel.

Criando um Model

Abaixo você pode verificar a maneira mais rápida e simples de criar um Model.

use Icecream\ IcecreamModel;\n\n class TabelaModel extends IcecreamModel { const TABLE = "nome_da_tabela"; }

Caso precise executar funções adicionais, basta utilizar a função function __construct.

use Icecream\ IcecreamModel;\n\n class TabelaModel extends IcecreamModel { const TABLE = "nome_da_tabela";\n\n public function __construct() { parent::__construct();\n $this->setServer('nome_outro_servidor'); } }

Sempre que utilizar o método construir em seu Model, você deve chamar a função parent::__construct() para que as funções padrão do módulo sejam executadas.

Utilizando o Model

Você poderá instanciar seu Model para ter uma estrutura de dados...

$tabela = new TabelaModel();\n $resultados = $tabela->select();\n return $resultados;

...ou pode também utilizar uma instância rápida

$resultados = TabelaModel()::open()->select();\n return $resultados;

Gerar Models automaticamente

Se já tiver criado seu banco de dados, você pode utilizar o método automático do Icecream para gerar suas Models. Basta abrir o console na pasta do seu projeto e inserir o comando php console Icecream/Icecream:generateModels. Lembre-se de que essa função irá deletar quaisquer Models criados.

Condição

Existem diversos tipos de condições que podem ser aplicadas. Elas são equivalente à clausula WHERE do SQL.

Funções

where($column, $operator, $value);

$column Recebe o nome do campo

$operator Operador de comparação (=, >, <, !=, etc)

$value Recebe o nome do campo

Query SQL correspondente

WHERE column = '$value' AND ...

Caso o operador seja "=", pode-se passar apenas os dois parâmetros como $column e $value.

orWhere($column, $operator, $value);

$column Recebe o nome do campo

$operator Operador de comparação (=, >, <, !=, etc)

$value Recebe o nome do campo

WHERE column = '$value' OR ...

whereNot($column, $value);

$column Recebe o nome do campo

$value Recebe o nome do campo

WHERE column != '$value' AND ...

orWhereNot($column, $value);

$column Recebe o nome do campo

$value Recebe o nome do campo

WHERE column != '$value' OR ...

whereBetween($column, $valueFrom, $valueTo);

$column Recebe o nome do campo

$valueFrom Valor inicial

$valueTo Valor final

WHERE column BETWEEN ('$valueFrom','$valueTo') AND ...

orWhereBetween($column, $valueFrom, $valueTo);

$column Recebe o nome do campo

$valueFrom Valor inicial

$valueTo Valor final

WHERE column BETWEEN ('$valueFrom','$valueTo') OR ...

whereNull($column);

$column Recebe o nome do campo

WHERE column IS NULL AND ...

orWhereNull($column);

$column Recebe o nome do campo

WHERE column IS NULL OR ...

whereNotNull($column);

$column Recebe o nome do campo

WHERE column IS NOT NULL AND ...

orWhereNotNull($column);

$column Recebe o nome do campo

WHERE column IS NOT NULL OR ...

whereLike($column, $statement);

$column Recebe o nome do campo

$statement Recebe o nome do campo

WHERE column LIKE '$statement' AND ...

orWhereLike($column, $statement);

$column Recebe o nome do campo

$statement Recebe o nome do campo

WHERE column LIKE '$statement' OR ...

whereNotLike($column, $statement);

$column Recebe o nome do campo

$statement Recebe o nome do campo

WHERE column NOT LIKE '$statement' AND ...

orWhereNotLike($column, $statement);

$column Recebe o nome do campo

$statement Recebe o nome do campo

WHERE column NOT LIKE '$statement' OR ...

whereIn($column, $list);

$column Recebe o nome do campo

$lista Recebe os valores em array ou uma instância de outra tabela do Icecream

WHERE column IN (0,1,2,3) AND ...

Ao enviar uma instância de outra tabela do Icecream:

WHERE column IN (SELECT column FROM table) AND ...

orWhereIn($column, $list);

$column Recebe o nome do campo

$lista Recebe os valores em array ou uma instância de outra tabela do Icecream

WHERE column IN (0,1,2,3) OR ...

Ao enviar uma instância de outra tabela do Icecream:

WHERE column IN (SELECT column FROM table) OR ...

whereNotIn($column, $list);

$column Recebe o nome do campo

$lista Recebe os valores em array ou uma instância de outra tabela do Icecream

WHERE column NOT IN (0,1,2,3) AND ...

Ao enviar uma instância de outra tabela do Icecream:

WHERE column NOT IN (SELECT column FROM table) AND ...

orWhereNotIn($column, $list);

$column Recebe o nome do campo

$lista Recebe os valores em array ou uma instância de outra tabela do Icecream

WHERE column NOT IN (0,1,2,3) OR ...

Ao enviar uma instância de outra tabela do Icecream:

WHERE column NOT IN (SELECT column FROM table) OR ...

Sub-Condição

É possível criar uma sub-condição, permitindo vários filtragens mais detalhadas de dados. Para isso, basta instanciar a classe new Icecream\Condition() e incluir as seleções de Where, como mostrado acima.

Para aplicar a sub-condição numa consulta, utilize a função $db->condition($condition);

Essa código...

$db = new Icecream("produtos");\n $db->where("ativo", 1);\n\n $condition = new Condition();\n $condition->where("categoria", 2);\n $condition->orWhere("categoria", 3);\n\n $db->condition($condition);

...gerará a seguinte consulta

SELECT * FROM produtos WHERE ativo = 1 AND (categoria = 2 OR categoria = 3)

Filtros

columns($columns);

$columns Recebe o nome das colunas a serem consultadas. Pode ser um array ou uma string

SELECT $columns FROM ...

orderBy($column, $sort);

$column Recebe o nome da coluna

$sort (opcional) Recebe a ordem de organização

... ORDER BY $column $sort

Caso não informe $sort, o padrão será ASC

limit($limit);

$limit Inteiro com o limite de dados

... LIMIT $limit

offset($offset);

$offset Inteiro com o deslocamento de dados

... LIMIT $limit OFFSET $offset

Para utilizar o Offset, é necessário incluir também o Limit, de acordo com as necessidades do SQL.

groupBy($columns);

$columns Recebe o nome das colunas a serem agrupadas. Pode ser um array ou uma string

... GROUP BY $columns

distinct();

Inclui a cláusula DISTINCT no início da query

DISTINCT SELECT ...

União

As funções de união também são práticas para a criar a cláusula JOIN nas tabelas.

Todas as funções de join possuem a mesma estrutura, como demonstrado abaixo:

join($table, $column, $operator, $column2);

$table Recebe o nome da tabela ou uma instância de tabela Icecream.

$column Recebe o nome da coluna da tabela a ser unida.

$operator (Opcional) Recebe o operador de comparação entre as duas colunas.

$column2 Recebe o nome da coluna da tabela atual correspondente.

JOIN $table ON $table.$column = tabela.$column2

Caso o operador seja "=", pode-se passar apenas os dois parâmetros como $column e $column2 (no lugar de $operator).

Utilizando oeprador padrão (=)

$join("tabela2", "colDaTabela2", "colDaTabela1");

JOIN tabela2 ON tabela2.colDaTabela2 = tabela.colDaTabela1

Utilizando operador diferente

$join("tabela2", "colDaTabela2", "!=", "colDaTabela1");

JOIN tabela2 ON tabela2.colDaTabela2 != tabela.colDaTabela1

Perceba que o código SQL gerado automaticamente inclui o nome da tabela juntamente do nome da coluna. Você ainda poderá atribuir um alias que preferir.

Unindo tabelas em sub-queries

Caso você passe uma instância de um outro banco para a tabela do join, o mesmo será adicionado como uma subquery.

Essa instrução...

$tabela1 = new Icecream("tabela1");\n $tabela2 = new Icecream("tabela2");\n $tabela1->join($tabela2, 'id', 'id');\n

... gera essa query

SELECT * FROM tabela1 JOIN (SELECT * FROM tabela2) AS tabela2 ON tabela2.id = tabela1.id

Outros tipos de Join

leftJoin($table, $column, $operator, $column2);

LEFT JOIN $table ON $table.$column = tabela.$column2

rightJoin($table, $column, $operator, $column2);

RIGHT JOIN $table ON $table.$column = tabela.$column2

outerJoin($table, $column, $operator, $column2);

OUTER JOIN $table ON $table.$column = tabela.$column2

innerJoin($table, $column, $operator, $column2);

INNER JOIN $table ON $table.$column = tabela.$column2

Busca

A função search() tem por objetivo realizar uma busca mais profunda de dados dentro de uma coluna. A partir dela, os resultados podem ser buscados inteiramente, separadamente e em várias partes dos valores.

search($columns, $term, $types);

$columns Recebe o nome das colunas nas quais o termo deve ser buscado

$term Termo a ser buscado

$types (Opcional) Tipos de busca a ser realizada

Tipos de busca

É possível passar um ou mais tipos (através de array) para realizar a busca.

Icecream::SEARCH_EQUAL Campo com o valor identico ao termo pesquisado.

Icecream::SEARCH_START Busca pelo termo no início do valor do campo.

Icecream::SEARCH_END Busca pelo termo no fim do valor do campo.

Icecream::SEARCH_ANY Busca pelo termo em qualquer parte do valor do campo.

Inserção

insert($values, $map);

$values Array sequencial ou associativo de valores

$map (opcional) Mapa de valores. Clique aqui para verificar mais detalhes sobre o mapa

INSERT INTO tabela...

A variável $values poderá receber um array associativo ou array sequencial, do seguinte modo:

Array Associativo

{ nome:"Eduardo", idade : 21}

INSERT INTO tabela (nome, idade), VALUES ('Eduardo', 21)

Array Sequencial

[{ nome:"Eduardo", idade : 21}, { nome:"Lucas", idade : 25}]

INSERT INTO tabela (nome, idade), VALUES ('Eduardo', 21), ('Lucas', 25)

Você também pode passar uma instância do Icecream no parâmetro $values. O código irá resgatar os valores da tabela que você passou e irá inseri-los dentro da tabela selecionada.

Alteração

update($values, $map);

$values Array associativo de valores

$sort (opcional) Mapa de valores. Clique aqui para verificar mais detalhes sobre o mapa

UPDATE tabela... WHERE

A execução de um update requer a inclusão de pelo menos uma condição do tipo where.

Inserção condicional

A função place() tem por objetivo alterar um registro caso o mesmo já exista, ou inserí-lo caso não exista

place($values, $map);

$values Array de valores

$sort (opcional) Mapa de valores. Clique aqui para verificar mais detalhes sobre o mapa

Se o registro não existir, insere

INSERT INTO tabela...

Se o registro existir, atualiza

UPDATE tabela... WHERE

A execução dessa função requer a inclusão de pelo menos uma condição do tipo where.

Exclusão

delete();

Remove valores de acordo com o WHERE declarado.

DELETE FROM ...

Para utilizar essa função é obrigatório utilizar ao menos uma condição.

truncate();

Zera todos os dados da tabela

TRUNCATE ...

Use essa função com cautela.

Seleção

select();

Retorna um array sequencial com todos os dados.

[ {nome:"José"}, {nome:"Vinícius"}, {nome:"Cláudia"} ]

selectFirst();

Retorna num array associativo apenas o primeiro registro

{nome:"José"}

selectLast();

Retorna num array associativo apenas o último registro

{nome:"Cláudia"}

selectMax($column);

$column Recebe o nome da coluna

Busca o valor máximo de uma coluna.

SELECT MAX($column) FROM ...

selectMin($column);

$column Recebe o nome da coluna

Busca o valor mínimo de uma coluna.

SELECT MIN($column) FROM ...

selectCount($column);

$column Recebe o nome da coluna

Busca a contagem a partir de uma coluna.

SELECT COUNT($column) FROM ...

selectSum($column);

$column Recebe o nome da coluna

Busca a soma dos valores de uma coluna.

SELECT SUM($column) FROM ...

Lista de Resultados

Esta função permite reorganizar os resultados de uma consulta para torná-los mais convenientes.

resultList($column, $value, $merge);

$column Recebe o nome da coluna a se tornar o índice

$valor Recebe o nome da coluna a se tornar o valor

$merge (Opcional) Caso haja valores com a mesma chave (coluna), fundí-los

Dado o seguinte resultado, verifique abaixo exemplos de uso

[ {nome:"José", id:1, idade:36}, {nome:"Vinícius", id:2, idade:23}, {nome:"Cláudia", id:3, idade:25} ]

Filtrando por chave

resultList("id");

Retorno...

[ 1: {nome:"José", id:1, idade:36}, 2: {nome:"Vinícius", id:2, idade:23}, 3: {nome:"Cláudia", id:3, idade:25} ]

Filtrando por chave e valor

resultList("id", "nome");

Retorno...

[ 1: "José", 2: "Vinícius", 3: "Cláudia" ]

Filtrando por valor

resultList(null, "nome");

Retorno...

[ "José", "Vinícius", "Cláudia" ]

Contagem

count();

Realiza a contagem de dados, desprezando os resultados já existentes (caso já tenha executado um select)

SELECT COUNT(*) FROM ...

size();

Realiza a contagem de dados, considerando os resultados já existentes (se houver sido executado um select)

SELECT COUNT(*) FROM ...

exist();

Retorna true caso a consulta retorne resultados ou false caso não retorne resultados.

Paginação

O Icecream possui uma estrutura ponta de paginação de resultados através da função paginate(). A partir dela é possível resgatar dados de paginação e também filtrar os resultados por página de maneira automatizada.

paginate($page, $perPage, $select = true, $onlyPaginate = false);

$page Número da página atual

$perPage Resultados por página

$select (Opcional) Retorna os dados já selecionados

$onlyPaginate (Opcional) Retorna apenas os dados de paginação, sem filtrar os dados

Dados paginados

O resultado retornado por uma paginação e um array com todos os dados da paginação

{ results : null, size : 150, totalResults : 10, currentPage : 1, totalPages : 15, itemsPerPage : 10, resultsFrom : "1", resultsTo : "10" }

Variáveis retornadas

results Resultados (caso $select seja true).

size Total de itens em toda a consulta (sem paginar)

totalResults Total de itens nesta consulta (paginado)

currentPage Número da página atual

totalPages Quantidade de páginas

itemsPerPage Itens por página

resultsFrom Início dos resultados

resultsTo Final dos resultados

Caso você mantenha como false o parâmetro $onlyPaginate, você poderá paginar os resultados e, em seguida, utilizar outras funções como select() ou resultList() para resgatar os valores, desprezando os resultados recebidos na variável results.

Se preferir paginar primeiro e depois obter os resultados, você pode enviar false para o parâmetro $select, evitando que os resultados sejam consultados logo na paginação.

Tabelas

existTable();

Verifica se a tabela existe

SHOW TABLES LIKE ...

drop();

Exclui a tabela

DROP TABLE ...

create($columns);

Cria a tabela

$columns Recebe um array associativo. Os índices são os nomes das colunas e contêm como valor um array indicando a formação das colunas.

type: string "varchar" Tipo da coluna.\n length: string "255" (Opcional para alguns campos) Tamanho da coluna.\n default: string "NULL" (Opcional) Valor padrão do campo.\n key: string "unique" (Opcional) Indica se há algum tipo de chave nessa coluna ('unique' ou 'primary')
CREATE TABLE ...

CMS
Modules > Classes > CMS

O Framework tem um módulo pronto de CMS que permite a implementa de diversos módulos de terceiros. Conta também com sistema de login e senha automático.

Configurando

Para que o CMS funcione é necessário realizar a sua instalação através do console. A instalação irá criar tabelas próprias no banco de dados e um usuário administrador.

A funcionalidade de CMS depende da configuração do Banco de Dados.

Para executar a instalação, basta abrir o console na pasta do seu projeto e inserir o comando php console CMS/Console:install clean. O parâmetro clean indica que o sistema deve excluir as tabelas de cms se as mesmas já existirem. No caso de uma nova instalação esse parâmetro não é necessário.

Operações de Console

Além de realizar a instalação através do Console, o CMS disponibiliza algumas funcionalidades via console. Para executar, basta abrir o console na pasta do seu projeto e inserir o comando desejado.

Na execução de um comando, caso alguma variável possua espaços, deve-se colocá-la entre aspas duplas.

Criar novo usuário administrador

php console CMS/Console:createUser $login $password $username

$login Login do usuário pelo qual ele realizará o acesso

$password Senha do usuário pelo qual ele realizará o acesso

$username (Opcional) Nome completo do usuário

Funcionamento do CMS

O funcionamento do CMS é similar ao de uma página comum. Ele é renderizado pelo sistema normalmente e seu módulo fornece suas funcionalidades. O módulo principal do CMS está na classe Modules > Classes > CMS > CMS.php que engloba todas as funcionalidades.

O CMS é dividido também em 2 frentes:

CMS

Modules > Classes > CMS > CMS

Funcionalidades de Usuários, Sessões e Módulos.

Interface

Modules > Classes > CMS > InterfaceCMS

Recursos da interface do CMS, tais como botões do menu, eventos, etc.

Início do CMS

A partir do momento em que o CMS é aberto, ele realiza uma busca por módulos na pasta Config. Dentro de cada módulo poderá haver uma indicação de uma inserção no CMS.

O CMS então irá enviar para função indicada uma instância da Interface, na qual o módulo em questão poderá inserir seus elementos.

O CMS registra quais são esses elementos e, em seguida, exibe para o usuário apenas os elementos que estão disponíveis na tabela de permissões. Para saber mais, consulte os Elementos de Interface.

Além de incluir botões e eventos, o módulo também poderá criar uma "view" própria para exibir dentro do CMS, chamada de board. Ela será criada dentro da pasta View > CMS > boards.

Criando um módulo de CMS

Um módulo de CMS possui de 2 a 3 frentes:

1. Arquivo de Configuração

Um arquivo de configuração deverá ser criado para incluir as instruções desse módulo. O arquivo deve ser criado no formato JSON com extensão .config na pasta Config, com a seguinte instrução:

{ "_config" : { "admin" : [ { "module" : "Modulo\\Classe", "method" : "Funcao" } ] } }
module: string "ProdutosCMS" nome do seu módulo/classe de implementação.\n method: string "inserirMenu" função que deverá ser executada para inserir os elementos.

A variável admin pode receber vários arrays associativos com diferentes classes e métodos.

2. Classe de Implementação

Assim que você tiver criado seu arquivo de configuração, você precisa criar o módulo e a função que descreveu. A função deverá receber uma instância do tipo CMS\ InterfaceCMS.

class ProdutosCMS extends \_Core {\n public function inserirMenu (CMS\ InterfaceCMS $interface) {\n $interface->funcao(); \n } }

Assim que o CMS for executado, ele chamará essa função. Através da variável $interface você poderá adicionar elementos como descrito.

Para consultar os elementos, acesse a seção de Elementos de Interface.

3. Board

Uma Board é uma view que poderá ser exibida dentro do CMS. Caso você queria apenas incluir links externos ou eventos dentro do CMS, não é necessário criar uma board!

Para criá-la, consulte a seção Criando uma Board.

Elementos de Interface

Botão do Menu Lateral

$interface->addSideMenu($options, $id);

$id ID único desse elemento

$options deve receber um array com os seguintes valores

icon: string "fas fa-cubes" Classe de ícone do FontAwesome ou FlatIcon.\n title: string "Meu Módulo" Título do botão.\n url: string "http://siteexterno.com.br" (Opcional) URL para a qual o botão irá redirecionar.\n counter: string "10" (Opcional) Valor do ponto de notificação.\n action: string "['Modulo','Board']" (Opcional) Board que o botão deve abrir.\n

Botão da Barra Superior

$interface->addTopBarMenu($options, $id);

$id ID único desse elemento

$options deve receber um array com os seguintes valores

icon: string "fas fa-cubes" Classe de ícone do FontAwesome ou FlatIcon.\n title: string "Meu Módulo" Título do botão.\n url: string "http://siteexterno.com.br" (Opcional) URL para a qual o botão irá redirecionar.\n action: string "['Modulo','Board']" (Opcional) Board que o botão deve abrir.\n

Botão do Menu de Usuário

$interface->addUserMenu($options, $id);

$id ID único desse elemento

$options deve receber um array com os seguintes valores

icon: string "fas fa-cubes" Classe de ícone do FontAwesome ou FlatIcon.\n title: string "Meu Módulo" Título do botão.\n sub-title: string "Clique aqui para ver" Sub-título do botão.\n url: string "http://siteexterno.com.br" (Opcional) URL para a qual o botão irá redirecionar.\n action: string "['Modulo','Board']" (Opcional) Board que o botão deve abrir.\n

Evento

$interface->addEvent($options, $id);

$id ID único desse elemento

$options deve receber um array com os seguintes valores

icon: string "fas fa-cubes" Classe de ícone do FontAwesome ou FlatIcon.\n title: string "Meu Módulo" Título do botão.\n type: string "new" Tipo do evento (new ou old).\n time: string "15/02/2020" (Opcional) Data do envento.\n color: string "success" (Opcional) Cor (de acordo com o Guia de Cores).\n url: string "http://siteexterno.com.br" (Opcional) URL para a qual o botão irá redirecionar.\n action: string "['Modulo','Board']" (Opcional) Board que o botão deve abrir.\n

Guia de cores

brand primary success danger warning

Criando uma Board

Para criar uma Board, crie um novo arquivo .php na pasta View > CMS > boards > SeuModulo.

Dentro dessa board você deverá incluir os códigos HTML que desejar exibir. Também é possível executar métodos normalmente.

Há uma estrutura padrão para Boards no arquivo View > CMS > boards > sample.php. Caso queira, poderá consultar a Documentação do Metronic.

Tela de Carregamento

O Metronic disponibiliza uma ferramenta pronta para exibir telas de carregamento chamada BlockUI em Javascript.

Dentro da sua board, você poderá chamá-la através da função blockLoading(). Assim que chamar, sua tela será bloqueada e receberá um aviso de carregamento. Para desbloquear, utilize a função unblockLoading().

Se preferir, você pode bloquear apenas uma seção, passando seu id como parâmetro da função blockLoading("#idDoBloco").

Acessando funções

As classes do CMS disponibilizam diversas funções úteis tanto para a construção de Boards quanto para as classes de Implementação.

Para acessar as funções dentro da boards, você deve utilizar o seguinte caminho:

Acessando a classe principal

$this->Main

Acessando interface

$this->Main->Interface

Conheça todas as funções na seção Funções do CMS.

Funções do CMS

$this->Main->listModules()

Retorna lista de módulos disponíveis

$this->Main->getLogoImage()

Retorna caminho do logo do CMS

$this->Main->getLoadingImage()

Retorna caminho da imagem de carregamento do CMS

CMS\CMS::validateSession()

Essa é uma função estática, portanto, deve ser acessada diretamente pela classe.

Verifica se o usuário possui uma sessão válida

$this->Main->getUser($var)

$var (Opcional) resgata uma variável específica do usuário.

Resgata dados do usuário.

$this->Main->getUserPermissions($module)

$module (Opcional) informa se o módulo passado é permitido ao usuário atual.

Resgata módulos permitidos ao usuário.

$this->Main->getUserInitial()

Retorna a inicial do nome do usuário.

$this->Main->getUserFirstName()

Retorna o primeiro nome do usuário.

Funções da Interface

$this->Main->Interface->getSideMenu()

Resgatar botões da barra lateral.

$this->Main->Interface->getUserMenu()

Resgatar botões do menu de usuário.

$this->Main->Interface->getTopBarMenu()

Resgatar botões da barra superior.

$this->Main->Interface->getEvent($type)

$type (Opcional) Tipo específico de evento ('new' ou 'old').

Resgatar eventos.

$this->Main->Interface->getEventCount($type)

$type Tipo específico de evento ('new' ou 'old').

Resgatar quantidade de eventos de um determinado tipo.

$this->Main->Interface->addCSS($link)

$link Link CSS a ser inserido.

Adiciona uma dependência de CSS.

$this->Main->Interface->addJS($link)

$link Link JS a ser inserido.

Adiciona uma dependência de JS.

$this->Main->Interface->getAllModulesIds()

Resgata todos os módulos registrados.

Tabelas de Dados
Modules > Classes > Datatable

Uma tabela de dados (Datatable) é um script que permite gerar tabelas automáticas de acordo com dados dinâmicos.

Ela é utilizada principalmente para criar tabelas no CMS que exijam diversos recursos como paginação, busca, ordenação, etc.

O Framework possui um módulo que auxilia na conexão entre a tabela de dados e os métodos. Ela pode ser instanciada através da instrução new Datatable\Datatable().

Você também pode consultar a Documentação do Datatable para conhecer todos os recursos.

Recebendo uma Requisição

Ao utilizar uma datatable, configure-a para que sua conexão seja serverSide, ou seja, todos os dados exibidos serão consultados no backend. Isso permite que sua tabela fique mais rápida caso hajam muitos resultados.

Ao utililzar o serverSide, a tabela irá realizar requisições aos seus métodos todas as vezes que o usuário executar uma ação, como: mudar de página, reordenar colunas, realizar busca, etc.

Ao receber uma requisição desse tipo, você deve instanciar o módulo Datatable\Datatable() para receber os dados enviados.

Exemplo de aplicação

public function listaProdutos ($data, Navigation\JsonTransaction $transaction) { $datatable = new Datatable\Datatable($data);\n\n $produtos = new Icecream('produtos');\n $resultados = $produtos->paginate($datatable->getPage(), $datatable->getPerPage());\n\n $datatable->setResults($resultados);\n return $datatable->getDatatable(); }
  1. No exemplo acima a classe Datatable\Datatable() é instanciada recebendo os dados enviados pela Datatable.
  2. Em seguida, é aberta a tabela "produtos" e é realizada a paginação de acordo com o número da página $datatable->getPage() e a quantidade de itens por página $datatable->getPerPage() solicitados.
  3. Por fim, o resultado da paginação é inserido no datatable e o mesmo é retornado.

Você também pode passar uma instância do Icecream() diretamente para o módulo Datatable\Datatable(), assim, o módulo realiza as consultas necessárias de acordo com o que foi pedido.

Exemplo de aplicação

public function listaProdutos ($data, Navigation\JsonTransaction $transaction) { $datatable = new Datatable\Datatable($data);\n\n $produtos = new Icecream('produtos');\n $datatable->setSource($produtos);\n return $datatable->getDatatable(); }

Exemplo de aplicação mais curta

public function listaProdutos ($data, Navigation\JsonTransaction $transaction) { $datatable = new Datatable\Datatable($data);\n return $datatable->getDatatable(new Icecream('produtos')); }

Funções de Tabela de Dados

Através da instância Datatable\Datatable() é possível executar as seguintes funções:

$datatable->setParams($params)

$params Recebe os dados enviados pela datatable na requisição.

Inclui os dados de requisição.

Você também pode inserir os parâmetros diretamente na construção da instância.

$datatable->getOrder()

Retorna um array com a ordenação de colunas solicitada pelo usuário.

$datatable->getSearch()

Retorna o termo de pesquisa. Caso não haja, retorna uma string vazia.

$datatable->getPage()

Retorna o número da página atual.

$datatable->getPerPage()

Retorna o número de itens por página.

$datatable->setResult($results)

$results Recebe os resultados paginados.

Inclui os resultados paginados.

$datatable->setSource(Icecream $source)

$source Recebe a instância de uma tabela no Icecream.

Realiza a pesquisa através de uma fonte de dados do Icecream

$datatable->getDatatable($results)

$results (Opcional) Recebe os resultados paginados ou a instância de uma tabela no Icecream.

Retorna a tabela de dados.

Datatable::getDataTableLanguage($language)

$language (Opcional) Código da língua.

Resgata as configurações de exibição de acordo com o idioma a ser utilizado na datatable.

Essa é uma função estática, portanto, deve ser acessada diretamente pela classe.

Tratamento de Erros

Em muitos momentos, principalmente durante o desenvolvimento, você poderá se deparar com erros. O Framework possui dois módulos de erros para ocasiões diferentes.

Faults

Faults são erros que indicam que alguma operação não foi bem sucedida. Ele é utilizado na validação de conteúdos, banco de dados Icecream e muitos outros módulos.

Sua principal função é retornar erros silenciosos de modo que você possa analisar esse erro antes de retornar qualquer dado para o usuário. No caso das Faults em Validações de Requisição, os objetos de erro conterão o código e a mensagem do erro, bem como o campo enviado que estava com erro. Isso é útil para que, no frontend, você possa exibir uma mensagem amigável ao usuário.

Validando uma Fault

Caso esteja utilizando funções que possam retornar uma Fault, você poderá verificar o erro através da seguinte função:

$retorno = funcao();\n if($retorno instanceof Fault)\n      return "Houve um erro";

Se você estiver dentro de um método transacional, você poderá retornar o objeto Fault diretamente para o usuário. O sistema de transações irá reconhecer a Fault e retornar uma mensagem de erro bem estruturada.

Lendo uma Fault

Caso você deseje saber mais detalhes sobre uma Fault recebida, pode utilizar as seguintes funções:

$fault->getMessage()

Resgata a mensagem de erro

$fault->getCode()

Resgata o código de erro

$fault->getObject()

Resgata o objeto de erro

$fault->getDetails()

Resgata os detalhes personalizados

$fault->toArray()

Retorna uma lista com todos os dados acima

Criando uma Fault

Caso você deseje retornar um erro, basta criar um novo objeto com as seguintes instruções.

new Fault($message, $code, $object, $details);

$message Mensagem de erro.

$code Código de identificação do erro.

$object (Opcional) Objeto/classe no qual você está trabalhando atualmente.

$details (Opcional) Detalhes extras

Erros

Erros fatais acontecem quando o código não consegue mais prosseguir. Isso pode ocorrer quando há falta de algum valor importante, ou de um arquivo, por exemplo.

Nesse caso, a navegação é interrompida e uma mensagem é exibida ao usuário.

Um arquivo de log com os detalhes do erro é armazenado no caminho Var > error.txt.

Lançando um erro

Para lançar um erro, execute a seguinte função em qualquer classe:

$this->Error($message, $showInFronted = true, $frontendMessage = null);

$message Mensagem simples de erro.

$showInFronted (Opcional) Se true, exibe a mensagem de erro para o usuário.

$frontendMessage (Opcional) Permite a criação de uma mensagem elaborada para o usuário, sem demonstrar o real problema.

Console
Modules > Classes > Console

O Framework possui um módulo nativo para que você possa acessar funções via console. Essas funções são executadas com maior velocidade e não interrompem a conexão do site, melhorando a performance.

Você pode, por exemplo, executar funções de console através de um cron, evitando que uma página do seu site precise ser acessada toda vez para executar uma rotina.

Acessando o console

Para executar funções, basta executar o console na pasta raíz do seu projeto. Caso esteja utilizando um sistema Windows, poderá utilizar o Prompt de Comando ou Powershell. Caso esteja num ambiente linux, basta utilizar o Bash diretamente no servidor ou via uma conexão SSH.

Para executar uma rotina, basta iniciar o comando php console seguido do módulo e função que deseja executar com as demais instruções.

Exemplo de execução

php console Modulo:Funcao parametro1 parametro2

A função ao lado irá chamar a função chamada Funcao do módulo Modulo e irá enviar como parâmetros os valores "parametro1" e "parametro2".

Por padrão, o procedimento de execução exibe mensagens padrão de início e fim, acompanhado do tempo total gasto para executar a função.

Caso seu módulo tenha um namespace utilize a barra normal / para realizar a identificação do caminho.

Criando uma função

Para criar uma função a ser executada no Console basta gerar uma função pública recebendo um parâmetro do tipo Console que irá conter as instruções enviadas.

Exemplo de função

class Rotinas extends _Core\n{ public function executar (Console $console)\n { return "Executado!"; } }

Para executar a função, basta chamar o seguinte comando no console:

php console Rotinas:executar

O código iniciará, exibirá a palavra "Executado!" na tela do console e se encerrará.

Resgatando parâmetros

Os parâmetros opcionais podem ser resgatados de duas maneiras:

Resgatando por índice

$console->getArguments($indice)

Resgata os argumentos na posição definida em $indice ou, caso não seja passado o índice, retorna a listagem de argumentos.

Resgatando por argumento

$console->getArgument($argumento)

Retorna true se o argumento passado em $argumento foi passado pelo usuário.

Exibindo dados

Caso você queira que sua função exiba informações no console ao finalizar, basta retornar os dados com a função return. Contudo, você ainda pode exibir diversos dados durante a execução da sua aplicação através da função $console->output("Mensagem").

Caso sua mensagem estiver informando um erro, você pode passar como true o segundo parâmetro da função $console->output(), assim, o console irá automaticamente exibir uma marca de erro na tela juntamente com a mensagem passada.

Efeitos de texto

Alguns consoles (como o bash do Linux) permitem que você utilize efeitos de texto como: cores, sublinhados e negritos. Para escrever um texto com destaque, utilize a função $console->effect("Texto com efeito", "nome_do_efeito");

Confira os tipos de efeitos disponíveis:

black Texto na cor preta

red Texto na cor vermelha

green Texto na cor verde

yellow Texto na cor amarela

blue Texto na cor azul

magenta Texto na cor magenta

cyan Texto na cor ciano

white Texto na cor branca

bg_black Fundo do texto na cor preta

bg_red Fundo do texto na cor vermelha

bg_green Fundo do texto na cor verde

bg_yellow Fundo do texto na cor amarela

bg_blue Fundo do texto na cor azul

bg_magenta Fundo do texto na cor magenta

bg_cyan Fundo do texto na cor ciano

bg_white Fundo do texto na cor branca

reset Texto comum

bold_bright Destacado/claro

underline Sublinhado

inverse Cores invetidas

_bold_bright Destacado/claro

_underline Sublinhado

_inverse Cores invetidas

Módulos Google

Recaptcha

Analytics

Youtube

Maps