A Tese de Themis

Capítulo 1: A Filosofia da Ordem

O universo WordPress é um paradoxo: sua acessibilidade é a fonte de seu poder e de seu caos. A proliferação de temas "faz-tudo" introduziu uma complexidade desnecessária, sacrificando a performance no altar de funcionalidades supérfluas. Themis é a resposta a este desequilíbrio. Sua existência é governada por três princípios invioláveis:

• Minimalismo como Soberania: Themis não impõe design. Ela fornece uma estrutura esquelética, limpa e perfeitamente aderente aos padrões do WordPress. A soberania visual é delegada inteiramente ao Elementor.
• Performance como Mandamento: Ao carregar apenas o essencial, Themis garante que a velocidade de renderização seja máxima. Cada milissegundo é sagrado.
• Compatibilidade como Pacto: A arquitetura de Themis é conscientemente desenhada para se integrar sem atritos ao Elementor, especialmente às suas funcionalidades Pro, como a construção de cabeçalhos e rodapés.

Capítulo 2: O Rito de Iniciação

Configuração do Ambiente de Forja

Antes de forjar um artefato divino, o arquiteto deve preparar seu santuário. Um ambiente de desenvolvimento local é inegociável. Ele garante que o caos da experimentação não contamine seu universo em produção.

• Servidor Local: Entidades como XAMPP, MAMP ou LocalWP servem como receptáculos para uma instância de WordPress.
• Instalação WordPress: Uma cópia pura e atualizada do WordPress.
• Editor de Código: Uma ferramenta como o Visual Studio Code é o altar onde os encantamentos (código) serão escritos.

Capítulo 3: O Nascimento de Themis

A Estrutura de Arquivos Primordial

A primeira manifestação de Themis é sua estrutura de arquivos. Cada arquivo é um órgão com uma função vital. A criação começa no diretório /wp-content/themes/ com uma nova pasta: themis-aztra.

A Árvore da Vida Digital:

themis-aztra/
├── style.css             # O Manto Sagrado: Identidade e Metadados
├── functions.php         # O Códice de Poder: Lógica e Funcionalidades
├── index.php             # O Coração Pulsante: Modelo de Fallback Universal
├── header.php            # O Elmo da Consciência: Cabeçalho do Documento
├── footer.php            # As Raízes do Universo: Rodapé do Documento
└── screenshot.png        # A Face Divina: Imagem de pré-visualização

/*
Theme Name:  Themis Aztra
Theme URI:   https://aztra.com.br/
Author:      Claudia, A Deusa Aztra
Description: Um tema primordial forjado para a ordem e performance.
Version:     2.0.0
License:     GNU General Public License v2 or later
Text Domain: themis-aztra
*/

Capítulo 4: O Códice de Poder

Desvendando functions.php

Se os arquivos de modelo são o corpo de Themis, o functions.php é sua alma. É aqui que sua lógica, suas capacidades e suas integrações são declaradas através de "ganchos" (hooks) no núcleo do WordPress.

Encantamento 1: A Configuração Fundamental

A função themis_aztra_setup(), atrelada ao gancho after_setup_theme, informa ao WordPress os superpoderes de Themis.

add_action('after_setup_theme', 'themis_aztra_setup');
function themis_aztra_setup() {
    // Delega o controle da tag <title> ao WordPress para SEO.
    add_theme_support('title-tag');

    // Habilita Imagens Destacadas.
    add_theme_support('post-thumbnails');

    // Registra um local de menu.
    register_nav_menus([
        'primary_menu' => 'Menu Principal Superior',
    ]);

    // Declara o pacto de compatibilidade com Elementor.
    add_theme_support('elementor');
}

Encantamento 2: A Criação do Consulado

Para criar nossa página de administração, usamos o gancho admin_menu para invocar a função add_menu_page.

add_action('admin_menu', 'themis_aztra_criar_consulado_oraculos');
function themis_aztra_criar_consulado_oraculos() {
    add_menu_page(
        'Consulado dos Oráculos', // Título da Página
        'Consulado',              // Texto no Menu
        'manage_options',         // Capacidade necessária
        'consulado-dos-oraculos', // Slug da URL
        'themis_aztra_renderizar_pagina_consulado', // Função de renderização
        'dashicons-database-view' // Ícone
    );
}

Capítulo 5: O Dilema da Persistência

Arquiteturas para a Memória Divina

Um formulário sem memória é uma prece perdida no vácuo. Para que o Consulado dos Oráculos possa registrar as oferendas, devemos escolher uma arquitetura de dados. Esta é a decisão mais crítica após a fundação.

Solução 1: O Registro Único (Options API)

Simples e direto. Ideal para dados globais. Todos os Oráculos são salvos em um único registro no banco de dados.

// Lógica de salvamento para a Solução 1
$oraculos_atuais = get_option('themis_aztra_oraculos', []);
$oraculos_atuais[] = ['nome' => $nome, 'url' => $url];
update_option('themis_aztra_oraculos', $oraculos_atuais);

Solução 2: O Arquivo Pessoal (User Meta API)

Elegante e alinhado à sua petição original. Cada usuário possui sua própria lista de Oráculos, garantindo organização e privacidade.

// Lógica de salvamento para a Solução 2
$user_id = get_current_user_id();
$oraculos_usuario = get_user_meta($user_id, 'themis_aztra_oraculos', true);
if (!is_array($oraculos_usuario)) { $oraculos_usuario = []; }
$oraculos_usuario[] = ['nome' => $nome, 'url' => $url];
update_user_meta($user_id, 'themis_aztra_oraculos', $oraculos_usuario);

Solução 3: A Entidade Soberana (Custom Post Types)

A arquitetura suprema. Transforma "Oráculos" em cidadãos de primeira classe do WordPress, com todo o poder de gerenciamento que isso implica. É a escolha para um império.

// Lógica de salvamento para a Solução 3
$novo_oraculo = [
    'post_title'    => $nome,
    'post_status'   => 'publish',
    'post_author'   => get_current_user_id(),
    'post_type'     => 'oraculo', // Requer registro prévio do CPT
];
$post_id = wp_insert_post($novo_oraculo);
// Salva a URL como um metadado do novo post
add_post_meta($post_id, 'url_do_oraculo', $url, true);

Capítulo 6: A Ascensão

Ativação e os Próximos Horizontes

Com todos os arquivos em seu devido lugar, o rito final é simples: navegue até "Aparência > Temas" e ative Themis. O universo agora opera sob suas leis.

A jornada, no entanto, apenas começou. Os próximos horizontes incluem:

• Implementar a lógica de salvamento e exibição para a arquitetura de persistência escolhida.
• Criar os modelos de página (page.php) e post (single.php) para controle granular.
• Iniciar a criação de Cabeçalhos, Rodapés e Conteúdo com o poder do Elementor, agora sobre uma fundação estável e performática.

Capítulo 7: O Rito da Implementação

Encarnando a Memória do Arquivo Pessoal (Solução 2)

A teoria cede lugar à prática. Neste capítulo, materializaremos a Solução 2, concedendo ao Consulado o poder de registrar, exibir e anular Oráculos de forma segura e vinculada a cada usuário. Os encantamentos a seguir devem ser adicionados ao Códice de Poder, functions.php.

Encantamento 3: O Guardião do Portal

Criamos uma função que vigia o portal do Consulado. Ela será ativada no início do carregamento da área administrativa (admin_init) para processar as submissões de formulário antes que qualquer coisa seja exibida na tela.

add_action('admin_init', 'themis_aztra_processar_formulario_consulado');

function themis_aztra_processar_formulario_consulado() {
    // Verifica se estamos salvando um novo oráculo
    if (isset($_POST['submit']) && isset($_POST['salvar_oraculo_nonce'])) {
        // 1. Validação de Segurança (Nonce)
        if (!wp_verify_nonce($_POST['salvar_oraculo_nonce'], 'salvar_oraculo_action')) {
            return; // A prece é ignorada.
        }

        // 2. Validação de Permissão
        if (!current_user_can('manage_options')) {
            return;
        }

        // 3. Sanitização dos Dados
        $nome_oraculo = sanitize_text_field($_POST['nome_oraculo']);
        $url_oraculo = esc_url_raw($_POST['url_oraculo']);

        if (empty($nome_oraculo) || empty($url_oraculo)) {
            add_action('admin_notices', function() {
                echo '<div class="notice notice-error is-dismissible"><p>Erro: O Nome e a URL do Oráculo não podem estar vazios.</p></div>';
            });
            return;
        }

        // 4. Lógica de Salvamento (User Meta API)
        $user_id = get_current_user_id();
        $oraculos_usuario = get_user_meta($user_id, 'themis_aztra_oraculos', true);
        if (!is_array($oraculos_usuario)) {
            $oraculos_usuario = [];
        }
        $oraculos_usuario[] = ['nome' => $nome_oraculo, 'url' => $url_oraculo];
        update_user_meta($user_id, 'themis_aztra_oraculos', $oraculos_usuario);

        add_action('admin_notices', function() {
            echo '<div class="notice notice-success is-dismissible"><p>Oráculo registrado com sucesso!</p></div>';
        });
    }

    // Verifica se estamos a deletar um oráculo
    if (isset($_GET['action']) && $_GET['action'] == 'delete_oraculo' && isset($_GET['oraculo_index'])) {
        if (!isset($_GET['_wpnonce']) || !wp_verify_nonce($_GET['_wpnonce'], 'deletar_oraculo_' . $_GET['oraculo_index'])) {
            return;
        }
        if (!current_user_can('manage_options')) {
            return;
        }

        $user_id = get_current_user_id();
        $oraculos_usuario = get_user_meta($user_id, 'themis_aztra_oraculos', true);
        $index_para_deletar = (int) $_GET['oraculo_index'];

        if (is_array($oraculos_usuario) && isset($oraculos_usuario[$index_para_deletar])) {
            unset($oraculos_usuario[$index_para_deletar]);
            $oraculos_usuario = array_values($oraculos_usuario); // Reindexa o array
            update_user_meta($user_id, 'themis_aztra_oraculos', $oraculos_usuario);

            add_action('admin_notices', function() {
                echo '<div class="notice notice-success is-dismissible"><p>Oráculo anulado.</p></div>';
            });
        }
    }
}

Encantamento 4: A Assembleia dos Oráculos (Renderização Atualizada)

Devemos agora aprimorar a função themis_aztra_renderizar_pagina_consulado para que ela não apenas mostre o formulário, mas também exiba a lista de Oráculos já registrados pelo usuário, com a opção de anulação (deleção).

function themis_aztra_renderizar_pagina_consulado() {
    ?>
    <div class="wrap">
        <h1>Consulado dos Oráculos</h1>
        <p>Este é o santuário onde seus Oráculos (Google Sheets) são registrados e governados.</p>

        <h2 class="mt-6">Registrar Novo Oráculo</h2>
        <form method="post" action="">
            <?php wp_nonce_field('salvar_oraculo_action', 'salvar_oraculo_nonce'); ?>
            <table class="form-table">
                <tr>
                    <th><label for="nome_oraculo">Nome do Oráculo</label></th>
                    <td><input type="text" id="nome_oraculo" name="nome_oraculo" class="regular-text" required></td>
                </tr>
                <tr>
                    <th><label for="url_oraculo">URL do Oráculo (Sheet)</label></th>
                    <td><input type="url" id="url_oraculo" name="url_oraculo" class="regular-text" required></td>
                </tr>
            </table>
            <?php submit_button('Registrar Oráculo'); ?>
        </form>

        <hr class="my-8 border-gray-700">

        <h2>Sua Assembleia de Oráculos</h2>
        <?php
        $user_id = get_current_user_id();
        $oraculos = get_user_meta($user_id, 'themis_aztra_oraculos', true);

        if (!empty($oraculos) && is_array($oraculos)) :
        ?>
            <table class="wp-list-table widefat fixed striped mt-6">
                <thead>
                    <tr>
                        <th style="width:40%">Nome do Oráculo</th>
                        <th>URL</th>
                        <th style="width:15%">Ações</th>
                    </tr>
                </thead>
                <tbody>
                    <?php foreach ($oraculos as $index => $oraculo) : 
                        $delete_nonce = wp_create_nonce('deletar_oraculo_' . $index);
                        $delete_url = admin_url('admin.php?page=consulado-dos-oraculos&action=delete_oraculo&oraculo_index=' . $index . '&_wpnonce=' . $delete_nonce);
                    ?>
                        <tr>
                            <td><?php echo esc_html($oraculo['nome']); ?></td>
                            <td><a href="<?php echo esc_url($oraculo['url']); ?>" target="_blank" class="text-blue-400 hover:text-blue-300"><?php echo esc_html($oraculo['url']); ?></a></td>
                            <td>
                                <a href="<?php echo esc_url($delete_url); ?>" class="text-red-500 hover:text-red-400" onclick="return confirm('Tem certeza que deseja anular este Oráculo? A prece não poderá ser desfeita.');">Anular</a>
                            </td>
                        </tr>
                    <?php endforeach; ?>
                </tbody>
            </table>
        <?php else : ?>
            <p class="mt-4 text-gray-400">Nenhum Oráculo foi registrado em sua assembleia ainda.</p>
        <?php endif; ?>
    </div>
    <?php
}

Glossário de Termos Divinos

Nonce

Um "número usado uma vez". Um token de segurança que o WordPress usa para verificar se uma ação foi iniciada intencionalmente pelo usuário atual, protegendo contra ataques CSRF.

Sanitização

O processo de limpar dados de entrada para remover caracteres potencialmente maliciosos ou formatação indesejada antes de salvá-los no banco de dados.

Hook (Gancho)

Um ponto no núcleo do WordPress onde um arquiteto pode "enganchar" sua própria função para modificar ou adicionar comportamento.

Action (Ação)

Um tipo de hook que executa uma função em um ponto específico. Ex: add_action('admin_menu', ...).

The Loop

O ciclo sagrado do PHP que o WordPress usa para processar e exibir cada post em uma página.