Running a survey with Editor

Recently, you might have noticed the banner at the top of the DataTables pages, entreating you to fill in a survey about how you use DataTables. If you haven't filled out the survey yet, please do so. I'm reading every reply and building a picture of how DataTables is being used, what its strengths and weaknesses are, and forming a plan for the future.

The survey will run for two weeks, after which I will compile the results and write up a blog post discussing the insights gleaned from it. Before then, I want to detail how I've used Editor to create the survey, which will be done over a series of posts.

Why use Editor to create a survey?

Editor is a row-based editing library for DataTables, so you might not immediately think of it when considering a form such as a survey, but actually, a survey form is simply a "create" action (INSERT in SQL parlance), doing an append-only operation on a database of known fields. That is exactly what happens when we click the Create button in Editor, so we can use that.

There are of course many pieces of survey software out there, and SaaS platforms offering surveys, such as Survey Monkey, but they are external data processors and I prefer data to be "on-prem" (which from the initial survey responses many of you do as well!), plus there is a monthly or annual fee to be payed, with limits that might well require high priced packages.

This being the case, and knowing that Editor could easily act as a survey input, I went about doing that, and will detail the basic setup in this post.

Immediate display

Back in 2017, I posted an article on this blog called Always visible editing panel which presented a display controller for Editor that shows the editing form simply in an element on the page, rather than in a model.

The form uses exactly that display controller (updated to not use jQuery!):

const Editor = DataTable.Editor;

function onPageDisplay(elm) {
    let name = 'onPage' + Math.random();
    let emptyInfo;

    Editor.display[name] = Object.assign({}, Editor.models.display, {
        // Create the HTML mark-up needed the display controller
        init: function (editor) {
            emptyInfo = elm.innerHTML;

            return Editor.display[name];
        },

        // Show the form
        open: function (editor, form, callback) {
            elm.childNodes.forEach(el => el.parentNode.removeChild(el));
            elm.appendChild(form);

            if (callback) {
                callback();
            }
        },

        // Hide the form
        close: function (editor, callback) {
            elm.childNodes.forEach(el => el.parentNode.removeChild(el));
            elm.innerHTML = emptyInfo;

            if (callback) {
                callback();
            }
        },

        node: function () {
            return elm;
        }
    });

    return name;
}

With that in place, we need the element in the HTML where the form will be displayed:

<div id="survey-form"></div>

Then create the Editor instance with the fields we want, and immediately call the create() method with a submit button configured:

let editor = new DataTable.Editor({
    ajax: ajaxUrl,
    fields: fields,
    display: onPageDisplay(document.querySelector('#survey-form'))
});

editor.on('submitSuccess', function () {
    document.querySelector('#survey-form').innerHTML =
        '<h2>Survey submitted!</h2><p>Thank you for taking the time to complete this survey. It is very much appreciated and will help move DataTables and its related software forward!</p>';
});

editor.create({
    buttons: 'Submit'
});

Note the use of the submitSuccess event. This event is triggered by Editor after submission to the server, and the server has reported that it has processed the form. At that point, we can write a message to the user (replacing the form, which is no longer needed), thanking them for completing the form.

Server-side append only

On the server-side, I've used the Editor PHP libraries to receive the data and insert it into the database. No special configuration is required for the survey input, as it will see the submission as a simple create action from the client-side.

That said, we don't want the full read, edit or delete actions that the libraries provide to be available on this route! There are a number of ways to handle this, including using the []pre* events](https://editor.datatables.net/manual/php/events) to cancel an action, a global validator, or simply checking what action was submitted. I opted for the latter:

if (! isset($_POST['action']) || $_POST['action'] !== Editor::ACTION_CREATE) {
    echo json_encode([
        "error" => "Action not allow"
    ]);

    exit;
}

Coming next

That's the basics of how you can create your own survey form with Editor. No need for monthly fees and own your own data! In future posts, I'll cover how to integrate Cloudflare Turnstile to help combat spam, and also the custom field types that I've created for the form input.