Template

Como desenvolvendo um template para o sistema

O sistema One permite que você utilize templates personalizados para definir o visual e o layout do seu site. Os templates podem funcionar diretamente no diretório templates/ da instalação, para isso basta ir em Configurações → Templates → Limpar template ativo.

Um template é um conjunto de arquivos PHP com HTML, usados como base para exibir páginas, posts e demais conteúdos do sistema.

Estrutura mínima obrigatória

Para que um template funcione corretamente, ele precisa conter os seguintes arquivos principais:

• index.php – Arquivo padrão carregado caso nenhuma outra regra se aplique.
• page.php – Usado para exibir páginas estáticas.
• post.php – Usado para exibir posts únicos.
• header.php – Cabeçalho do site, geralmente contém a abertura do HTML e o início da estrutura da página.
• footer.php – Rodapé do site, geralmente fecha as tags abertas no header.

Esses arquivos são obrigatórios para que o sistema consiga renderizar corretamente os conteúdos do site.

Localização do template

Os templates devem ser colocados dentro do diretório templates/ localizada na raiz do sistema. O nome do diretório do template será usado como identificador interno. Exemplo: templates/meu-template/

Carregamento dos arquivos

O sistema carrega os arquivos do template automaticamente, de acordo com o tipo de conteúdo acessado. Se o visitante acessar uma página, o arquivo page.php será utilizado. No caso de um post, será usado o post.php, e assim por diante.

O index.php é o arquivo padrão para listagem de posts e utilizado como fallback para search.php, home-page.php e category.php caso esses arquivos não estejam disponíveis.

Notas

• O sistema não exige CSS, JavaScript ou qualquer framework no template. Isso fica a critério do desenvolvedor.
• É possível criar templates totalmente personalizados, desde que os arquivos básicos estejam presentes.
• Se um arquivo obrigatório estiver ausente, uma exceção será exibida durante o carregamento da página.

Arquivo info.json

Todo template deve conter um arquivo chamado info.json localizado na raiz do diretório do template, ou seja: templates/nome-do-template/info.json, exceto quando o template estiver sendo usado diretamente no diretório templates/, fora de um subdiretório.

Não é recomendável manter templates diretamente no diretório templates/ com o template ativo na raiz pois isso pode causar conflitos.

Esse arquivo usado normalmente em subdiretórios é obrigatório para que o template apareça na tela de seleção em Configurações → Templates no painel de administração.

O conteúdo do arquivo deve estar em formato JSON, com pelo menos a chave template_slug definida. Se essa chave estiver ausente, o template não será exibido na lista, e todos os templates seguintes na ordem alfabética também serão ignorados.

Exemplo de info.json completo:

{
  "template_name": "Esqueleto",
  "template_slug": "esqueleto",
  "template_url": "https://esqueleto.com",

  "author": "Wellington Pragidi",
  "author_url": "https://pragidi.com",

  "description": "Explicabo aptent, rhoncus nisl cubilia ullamcorper.",

  "version": "1.0.0"
}

Chaves disponíveis:

• template_slug (obrigatória) – Identificador interno do template. Deve coincidir com o nome do diretório e ser único.
• template_name – Nome exibido no painel. Se ausente, nada é exibido no lugar, o que pode deixar a interface pouco amigável.
• template_url – Link para a documentação, site do template, seu site, em fim a URL que você desejar, não temos nada com isso, o trabalho é seu, você é quem decide!.
• author – Nome do autor ou desenvolvedor do template.
• author_url – Link para o site ou portfólio do autor.
• description – Descrição do template curta ou longa, não tem limites.
• version – Versão atual do template, exemplo: "1.0.0".

Notas importantes:

• Se o arquivo info.json estiver ausente, o template será completamente ignorado pelo sistema.
• Se o arquivo existir mas não tiver template_slug, o template e os próximos serão ignorados na listagem.
• É recomendado incluir template_name para uma melhor apresentação no painel.
• As demais chaves são opcionais, mas ajudam na identificação, organização dos templates, enfim, nós não obrigamos a nada que não for realmente necessário para o funcionamento, mais o trabalho é seu, eu sempre aconselho, faça você mesmo!, mais faça bem feito!.
  
  

Conteúdo base dos arquivos:

A seguir estão exemplos mínimos do conteúdo necessário para cada um dos arquivos do template. Esses arquivos são usados para estruturar a exibição das páginas do site.

Os exemplos estão só com HTML básico, sem nenhum atributo, apenas para demonstração para que a seguir você faça como quiser.
Existe documentação para todas as funções usadas no template, portanto se ficar na dúvida copie o nome da função e cole na barra de pesquisa..

header.php

<code><!DOCTYPE html>
<html lang="pt-BR">
<head>
<?php head() ?>
</head>
<body>
  <header>
    <?php 
    echo ( is_home() || is_posts() ) ? '<h1>' : '<h2>';
      echo '<a href="'. site_url() .'">' . site_title() . '</a>';
    echo ( is_home() || is_posts() ) ? '</h1>' : '</h2>'; 
    ?>
    <nav>
      <ul>
        <li><a href="<?= site_url() ?>">Home</a></li>
        <?php if( User::logged() ) : ?>
        <li><a href="<?= User::url() ?>"><?= User::name() ?></a></li>
        <?php else : ?>
        <li><a href="<?= site_url('access/?action=login') ?>">Login</a></li>
          <?php endif; ?>
          <li><a href="<?= site_url('contato') ?>">Contato</a></li>
      </ul>
    </nav>
  </header></code>

footer.php

<code><footer>
    <p><?php echo site_title() . '&copy;' . date('Y') ?></p>
</footer>
<?php foot() ?>
</body>
</html></code>

Os arquivos header.php e footer.php são pré-carregados, não necessita include, require ou nenhuma função que faça esse trabalho.

index.php

<code><?php category_title('<h1>Categoria: ', '</h1>') ?>
<?php category_description('<div>', '</div>') ?>

<?php search_title('<h1>', '</h1>') ?>

<div><?php post_count() ?></div>

<main>

    <?php while( rows_exists() ) : show_rows(); ?>

    <article>
        <a href="<?php permalink(); ?>" title="<?php title_attr() ?>">

            <?php featured_image() ?>

          <h2><?php title() ?></h2>

        </a>

        <div><?php content_summary() ?></div>
        
        <div>
          <p><small>Publicado por: <?php author() ?></small></p>
          <p><time>Publicado em: <?php indate() ?></time></p>
        </div>
    </article>

    <?php endwhile; ?>

    <?php posts_paginator() ?>

</main>

<aside>
    <?php search_form() ?>
    <?php list_categories(['thumbnail' => true]) ?>
    <?php posts_recents() ?>
</aside></code>

Este arquivo é o modelo padrão utilizado para exibir a listagem de posts. Ele também funciona como fallback caso outros arquivos específicos não existam, como:

• home-page.php – para a página inicial do site
• category.php – para listagem de posts de uma categoria
• search.php – para exibição de resultados de busca

Ou seja, se o visitante acessar a homepage, realizar uma busca ou visitar uma categoria, e não houver arquivos específicos para esses casos, o sistema carregará automaticamente o index.php.

As funções abaixo são usadas para exibir dinamicamente informações da URL atual:

• category_title( $before, $after ) – Exibe o nome da categoria atual, apenas quando o visitante estiver navegando em uma página de categoria.
• category_description( $before, $after ) – Exibe a descrição da categoria, quando disponível.
• search_title( $before, $after, $result_text ) – Exibe o título da busca com base no valor de ?q= na URL.
• post_count() – Exibe a quantidade de posts listados na página atual:
  • Em index.php, mostra o total geral de posts.
  • Em buscas (?q=), mostra o total de resultados encontrados.
  • Em categorias, mostra o total de posts daquela categoria.

Essas funções aceitam parâmetros de marcação (como h1, div, etc.) para evitar a exibição de elementos vazios em páginas onde elas não se aplicam. Assim, o código permanece limpo mesmo em contextos onde o conteúdo não está presente.

post.php

<code><main>
    <?php while( rows_exists() ) : show_rows(); ?>

    <h1><?php title() ?></h1>

    <?php featured_image('large') ?>

    <article>
        <div><?php content() ?></div>

        <div>
            <p>Publicado por: <?php author() ?></p>
            <p><time>Publicado em: <?php indate() ?></time></p>
            <p><time>Atualizado em: <?php updatein() ?></time></p>
        </div>

        <?php admin_edit() ?>
    </article>
    
    <?php endwhile; ?>

    <p>Categorias: <?php post_categories(', ') ?></p>

    <?php shares() ?>

    <?php comment_area() ?>
    
</main>

<aside>
    <?php search_form() ?>
    <?php list_categories(['thumbnail' => true]) ?>
    <?php posts_recents() ?>
</aside></code>

page.php

<code><main>
    <?php while( rows_exists() ) : show_rows(); ?>

  <h1><?php title() ?></h1>

    <?php featured_image('large') ?>

    <article>
        <div><?php content() ?></div>

        <div>
          <p>Publicado por: <?php author() ?></p>
          <p><time>Publicado em:<br> <?php indate() ?></time></p>
        </div>

        <?php admin_edit() ?>
    </article>
    
    <?php endwhile; ?>
</main>

<aside>
    <?php search_form() ?>
    <?php list_categories(['thumbnail' => true]) ?>
    <?php posts_recents() ?>
</aside></code>

Como o sistema escolhe qual arquivo do template será usado com base no tipo de conteúdo acessado.

Na pagina Inicial ou Home Page:
Primeiro o sistema procura pelo arquivo home-page.php, se não encontrar ele usa index.php.

Na pagina de pesquisa:
Primeiro o sistema procura pelo arquivo search.php, se não encontrar ele usa index.php.

Na listagem de posts por categoria:
Primeiro o sistema procura pelo arquivo category.php, se não encontrar ele usa index.php.

Outros arquivos do template

Além dos arquivos "principais", o sistema também reconhece alguns arquivos "opcionais" que controlam situações específicas. Embora não sejam obrigatórios na estrutura inicial, sua ausência pode gerar exceções dependendo da rota acessada.

404.php

Arquivo usado quando o sistema não encontra nenhuma rota correspondente.

Esse arquivo é opcional, mas altamente recomendado. Se não existir, o sistema lançará uma exceção quando uma URL inválida for acessada.

Esse pode ser um arquivo com conteúdo simples. Exemplo:

<code><article>
    <h1>404</h1>
    <p>Oops! A página que você procura não foi encontrada.</p>
    <a href="<?= site_url() ?>">Voltar para a página inicial</a>
</article></code>

Se quiser adicionar funções de widgets, formulário de pesquisa..

pages/{page-template}.php

O sistema permite a criação de templates personalizados para páginas. Esses arquivos devem ser salvos dentro do diretório templates/{template-slug}/pages/ e conter um comentário no topo com o nome do template que será exibido no painel.

O sistema reconhece o template pelo comentário e usa o nome do arquivo como valor salvo no banco de dados.

Exemplo:

/** Template Page: Galeria */

Este arquivo pode ter qualquer nome, como page-galeria.php, galeria.php, arquivo.php ou outro. O nome exibido no painel será Galeria, e o valor salvo será exatamente o nome do arquivo, por exemplo: galeria.php.

O sistema aceita múltiplos formatos de comentário de bloco. Os reconhecidos atualmente são:

/** Template Page: Galeria */

/** Template Page : Galeria */

/* Template Page: Galeria */

/* Template Page : Galeria */

/** 
 * Template Page: Galeria
 */

/** 
 * Template Page : Galeria
 */

Se você fizer isso abaixo, vai funcionar

/** 
 * 
 * Template Page: Galeria
 * 
 */

Porém na seleção de edição de paginas será exibido assim: * Galeria *

Importante: ao alterar o nome do arquivo, é necessário atualizar a página no painel para refletir essa mudança. O sistema continuará funcionando normalmente, pois ele sempre busca pelo nome do arquivo salvo no campo page_template.
Observação: Se o arquivo salvo no campo page_template não for encontrado, irá para a pagina 404.

user.php

Usado para exibir páginas de perfil de usuários, dados ou ações internas da conta. Se esse arquivo não existir e uma rota de usuário for acessada, o sistema lançará uma exceção.

Atualmente, não há um controle de ativação/desativação dessas rotas. A única forma de impedir o uso do sistema de usuários é não criar o arquivo user.php e não utilizar a função comment_area() nos posts. Ainda assim, usuários podem acessar rotas como /access/?action=login, /access/?action=register, etc., se souberem que elas existem. Mais em breve teremos ganchos para contornar isso e além.

Exemplo do código para a pagina user.php:

<code><main>

    <?php user_title('<h1>', '</h1>') ?>

    <div>
        <?php User::image_profile() ?>
    </div>

    <p><?php User::since() ?></p>

    <div>
        <h5><?php User::comment_count() ?></h5>
        <?php User::commented_on() ?>
    </div>
    
    <?php User::lastupdate() ?>

    <?php if( User::authorized() ) : ?>
        <div>
            <?php User::settings_form() ?>
        </div>
    <?php endif; ?>

</main></code>

Para estilizar elementos HTML gerados por funções e métodos relacionados a usuários, comentários e outras áreas internas do sistema, a forma mais prática é inspecionar o DOM diretamente. Assim, você consegue visualizar os seletores exatos aplicados e criar o CSS necessário sem depender da leitura dos arquivos PHP.