Custom Forms

Using the Kanboard\Helper\ModalHelper class, you can open contextual menus (modals) to perform additional actions and then redirect to a specific page. For example, to trigger a myform action in your plugin’s controller, add this to your template:

<?= $this->modal->small('font-awesome-icon', 'My Form text', 'MyController', 'myform', array('plugin' => 'myplugin')) ?>

If you’d like your modal to redirect to the current page after submission, don’t forget to give it additional params to build the redirect URL. For example, adding the task’s ID to redirect to the task view:

<?= $this->modal->small('font-awesome-icon', 'My Form text', 'MyController', 'myform', array('plugin' => 'myplugin', 'task_id' => $task['id'])) ?>

Displaying the form

Using the Kanboard\Helper\FormHelper class, you can generate your form, automatically handling submitted values and validation errors:

<form method="post" action="<?= $this->url->href('MyController', 'myform', array('plugin' => 'myplugin', 'task_id' => $task_id)) ?>" autocomplete="off">
    <?= $this->form->csrf() ?>
    <?= $this->form->label('Single line field', 'first_field') ?>
    <?= $this->form->text('first_field', $values, $errors) ?>
    <br>
    <?= $this->form->label('Text area field', 'second_field') ?>
    <?= $this->form->textarea('second_field', $values, $errors) ?>
    <?= $this->modal->submitButtons() ?>
</form>

Do not add a second form in the same modal. Only one form per modal is supported. If you need to handle several forms from your modal, simply open a new modal from the current modal, like so:

<h2>Select a project:</h2>
<form method="post" action="<?= $this->url->href('MyController', 'myform', array('plugin' => 'myplugin', 'task_id' => $task_id)) ?>" autocomplete="off">
    <?= $this->form->csrf() ?>
    <?= $this->form->select('project_id', $projects, $values, $errors) ?>
    <?= $this->modal->submitButtons() ?>
</form>
Alternatively, create a new one:
<?= $this->modal->small('plus', 'Create project', 'MyController', 'createproject', array('plugin' => 'myplugin', 'task_id' => $task_id)) ?>

Clicking the Create project link will close the current modal and open a new one with the createproject action, avoiding confusion between forms.

Validating the form

To check if the request is a fresh form, or contains submitted values, you can use $this->request->isPost(). After validating the submitted values returned by $this->request->getValues(), you should indicate success and redirect somewhere:

$this->flash->success('My form was successful');
$this->response->redirect($this->helper->url->to('TaskViewController', 'show', array('task_id' => $this->request->getStringParam('task_id'))), true);

Or upon error, redisplay the current form with the $errors and $values arrays in the template context:

$this->flash->failure('My form failed');
$this->response->html($this->template->render('myplugin:myform', array(
    'task_id' => $task_id,
    'errors' => $errors,
    'values' => $values,
)));

Whether you’re performing manual form validation, or using custom validators, the form helpers will display the errors alongside the fields that failed validation. For this purpose, make sure $errors has one entry for each errored field, containing an array of error messages. For example:

$errors = [ "age" => [ "Age cannot be a negative number" ] ];

Adding modal forms in your plugin

Opening a modal form from a template

Displaying the form

Validating the form