Formulários

Um dos conceitos-chave do framework é o conceito de formulário.

Quando o usuário clica em um item do menu principal, o método view do item correspondente é executado, criando o formulário de visualização.

Esse formulário de visualização pode conter os botões Novo e Editar. Ao clicar neles, os métodos insert_record e edit_record serão executados. Esses métodos criam um formulário de edição de item.

Os formulários são baseados em templates de formulário HTML, que determinam seu layout. Os templates de formulário são definidos no arquivo Index.html, localizado na pasta raiz do projeto.

A aplicação já possui templates padrão para visualização e edição de dados, para especificar filtros e parâmetros de relatórios.

Por exemplo, todos os formulários de edição do projeto Demo utilizam o seguinte template HTML:

<div class="default-edit">
    <div class="form-body">
        <div class="edit-body"></div>
        <div class="edit-detail"></div>
    </div>
    <div class="form-footer">
        <button type="button" id="ok-btn" class="btn btn-primary">
            <i class="bi bi-check-square"></i> OK<small class="muted">&nbsp;[Ctrl+Enter]</small>
        </button>
        <button type="button" id="cancel-btn" class="btn btn-secondary">
            <i class="bi bi-x-square"></i> Cancel
        </button>
    </div>
</div>

Você pode definir seus próprios templates de formulário para criar formulários personalizados. Veja Templates de formulário

Quando algum método cria um formulário, a aplicação localiza o template HTML correspondente.

Se o parâmetro container (um objeto Jquery) for especificado, o método esvazia esse container e anexa o template HTML a ele. Caso contrário, cria um formulário modal vazio e anexa o template ao formulário.

Após isso, o atributo prefix_form do item é atribuído ao template, os eventos on_prefix_form_created são disparados, o formulário é exibido e os eventos on_prefix_form_shown são acionados, onde prefix é o tipo do formulário (view, edit, filter, param). Veja Eventos de formulário para mais detalhes.

Abaixo está um exemplo do manipulador de evento on_edit_form_created da tarefa:

function on_edit_form_created(item) {
    item.edit_form.find("#ok-btn").on('click.task', function() { item.apply_record() });
    item.edit_form.find("#cancel-btn").on('click.task', function(e) { item.cancel_edit(e) });

    if (!item.master && item.owner.on_edit_form_created) {
        item.owner.on_edit_form_created(item);
    }
    if (item.on_edit_form_created) {
        item.on_edit_form_created(item);
    }

    item.create_inputs(item.edit_form.find(".edit-body"));
    item.create_detail_views(item.edit_form.find(".edit-detail"));

    return true;
}

Neste exemplo, o método find do JQuery é utilizado para localizar elementos no formulário.

Primeiramente, atribuímos um evento click do JQuery aos botões OK e Cancelar, de forma que os métodos cancel_edit e apply_record serão executados quando o usuário clicar nos botões. Esses métodos cancelam ou aplicam as alterações feitas no registro, respectivamente, e chamam o método close_edit_form para fechar o formulário.

Em seguida, se o item não for um detalhe e tiver um manipulador de evento on_edit_form_created definido no módulo cliente do proprietário, esse manipulador de evento será executado.

Depois disso, se o item tiver um manipulador de evento on_edit_form_created, definido no módulo cliente do próprio item, esse manipulador também será executado.

Nesses manipuladores de evento, ações adicionais podem ser executadas. Por exemplo, é possível atribuir eventos de clique a botões ou outros elementos contidos no template do formulário de edição, alterar as edit_options, criar tabelas utilizando o método create_table e assim por diante.

Depois disso, o método create_inputs é chamado para criar os campos de entrada no elemento com a classe “edit-body”.

Por fim, o método create_detail_views é chamado para criar os detalhes no elemento com a classe “edit-detail”.

Nota

Se alguns elementos estiverem ausentes no template do formulário, nenhuma exceção será lançada.

O método close_prefix_form, onde prefix é o tipo do formulário, fecha o formulário desse tipo. Mas antes que o formulário seja fechado, os eventos on_prefix_form_close_query e on_prefix_form_closed são disparados. Após o formulário ser fechado, ele é removido do DOM.