claude-plugins/perfex-dev/skills/perfex-forms/SKILL.md

name, description

name	description
perfex-forms	Gestao de formularios em modulos Perfex CRM -- form_open(), tokens CSRF, validacao e AJAX. Baseado apenas na documentacao oficial.

/perfex-forms - Formularios Perfex CRM

Gestao de formularios em modulos. Zero assumptions, zero hallucinations - apenas documentacao oficial.

---

Documentacao Base

• Working With Forms
• CodeIgniter Form Helper

---

Regra Fundamental: form_open()

SEMPRE usar form_open() para gerar token CSRF automaticamente.

<?php echo form_open(admin_url('meu_modulo/save')); ?>
    <!-- Inputs aqui -->
<?php echo form_close(); ?>

NUNCA usar <form> HTML directo - sem CSRF protection.

---

Sintaxe form_open()

// Basico
echo form_open(admin_url('meu_modulo/save'));

// Com atributos
echo form_open(admin_url('meu_modulo/save'), [
    'id'    => 'form-meu-modulo',
    'class' => 'form-horizontal',
]);

// Com upload de ficheiros
echo form_open_multipart(admin_url('meu_modulo/upload'), [
    'id' => 'form-upload',
]);

// Fechar formulario
echo form_close();

---

Elementos de Formulario

Todos os elementos com exemplos completos em: references/elementos-formulario.md

Elementos disponiveis: Input Text, Textarea, Select, Select AJAX, Checkbox, Radio, Date Picker, DateTime Picker, File Upload, Hidden.

Padrao geral:

<div class="form-group">
    <label for="CAMPO" class="control-label">
        <?php echo _l('CAMPO'); ?>
        <span class="text-danger">*</span>  <!-- se obrigatorio -->
    </label>
    <input type="text" id="CAMPO" name="CAMPO" class="form-control"
           value="<?php echo isset($item) ? html_escape($item->CAMPO) : ''; ?>">
</div>

---

Validacao Client-Side

O Perfex usa jQuery Validation. Usar appValidateForm():

<?php init_tail(); ?>
<script>
$(function(){
    appValidateForm($('#form-meu-modulo'), {
        name: {
            required: true,
            minlength: 3
        },
        email: {
            required: true,
            email: true
        },
        amount: {
            required: true,
            number: true,
            min: 0
        }
    });
});
</script>
</body>
</html>

Regras de Validacao

Regra	Descricao
required: true	Campo obrigatorio
email: true	Email valido
number: true	Numero
digits: true	Apenas digitos
minlength: N	Minimo N caracteres
maxlength: N	Maximo N caracteres
min: N	Valor minimo
max: N	Valor maximo
equalTo: '#field'	Igual a outro campo

---

Validacao Server-Side

public function save()
{
    if (!$this->input->post()) {
        redirect(admin_url('meu_modulo'));
    }

    $this->load->library('form_validation');

    $this->form_validation->set_rules('name', _l('name'), 'required|min_length[3]');
    $this->form_validation->set_rules('email', _l('email'), 'required|valid_email');
    $this->form_validation->set_rules('amount', _l('amount'), 'required|numeric');

    if ($this->form_validation->run() === false) {
        set_alert('danger', validation_errors());
        redirect(admin_url('meu_modulo/create'));
    }

    $data = [
        'name'   => $this->input->post('name'),
        'email'  => $this->input->post('email'),
        'amount' => $this->input->post('amount'),
    ];

    // ... guardar
}

---

AJAX com jQuery

POST Simples

$.post(admin_url + 'meu_modulo/ajax_save', {
    name: $('#name').val(),
    description: $('#description').val()
}).done(function(response) {
    response = JSON.parse(response);
    if (response.success) {
        alert_float('success', response.message);
    } else {
        alert_float('danger', response.message);
    }
});

Controller AJAX

public function ajax_save()
{
    if (!$this->input->is_ajax_request()) {
        show_404();
    }

    if (!staff_can('create', 'meu_modulo')) {
        echo json_encode(['success' => false, 'message' => _l('access_denied')]);
        return;
    }

    $data = [
        'name'        => $this->input->post('name'),
        'description' => $this->input->post('description'),
    ];

    $id = $this->meu_modulo_model->add($data);

    echo json_encode([
        'success' => (bool) $id,
        'id'      => $id,
        'message' => $id ? _l('added_successfully') : _l('error_occurred'),
    ]);
}

---

Excluir CSRF para Webhooks

Para endpoints que recebem callbacks externos:

// modules/meu_modulo/config/csrf_exclude_uris.php
<?php
defined('BASEPATH') or exit('No direct script access allowed');

return [
    'meu_modulo/webhook',
    'meu_modulo/callback',
    'meu_modulo/api/.*',  // Regex
];

---

Anti-Patterns (NUNCA FAZER)

Anti-Pattern	Risco	Alternativa
<form> HTML directo	CSRF bypass	form_open()
Valores sem html_escape()	XSS	Escape sempre
Validacao so client-side	Bypass	Validar server tambem
AJAX sem verificar is_ajax_request()	Acesso directo	Verificar sempre

---

Checklist Formularios

1. [ ] form_open() para todos os formularios
2. [ ] html_escape() em todos os values
3. [ ] Validacao client-side (appValidateForm)
4. [ ] Validacao server-side (form_validation)
5. [ ] Permissoes verificadas no controller
6. [ ] CSRF excluido apenas para webhooks
7. [ ] form_open_multipart() para uploads
8. [ ] is_ajax_request() em endpoints AJAX

---

References

• references/elementos-formulario.md - Todos os elementos HTML/PHP com exemplos
• references/formulario-completo-exemplo.md - View completa com todos os elementos

---

Fonte: help.perfexcrm.com/working-with-forms