Widget Steps v7

• status: complete
• version: 7.x
• follows from: Widgets Methods

Widgets-steps are a particular type of steps where a widget is loaded in the frame waiting for some input from the user.

When node.done() is called, the widget checks if any action from the user is required; if so, the game won't step forward.

To create a widget-step, just extend an existing step with a widget property containing the name of the desired widget, e.g. MoodGauge:

stager.extendStep("mood", { widget: "MoodGauge" });

Below is an example with all the available options.

stager.extendStep("mood", {

    widget: {
        // Name of the widget to load.
        name: 'MoodGauge',

        // Optional custom id.
        id: 'my_widget_id', // Default: 'ng_step_widget_' + name

        // Optional id of the root element for the widget.
        root: 'append-to-this-root', // Default: an element with id
                                     // 'widget-container', or the
                                     // document.body element of the IFRAME, or
                                     // the document.body element of the page.

        // Do not append the widget,
        // just make it available in node.widgets.instances
        append: false, // Default: TRUE.

        // Do not check if values are correct (as returned by `getValues()`).
        checkValues: false, // Default: TRUE.

        // Widget-specific options.
        choices: [ 1, 2, 3 ],
        emotions: [ 'Upset', 'Active' ]

        // Before v7.1.0, widget-specific options needed to specified inside
        // an options object. This is no longer necessary, but still allowed.
        // options: {
        //     choices: [ 1, 2, 3 ],
        //     emotions: [ 'Upset', 'Active' ]
        // }
    },

    // Optional step properties.

    // Frame.
    frame: 'my/custom/frame.html', // Default: a blank page.

    // Callback.
    cb: function() { ... },        // Executed after the widget
                                   // is appended.

    // Done.
    done: function(values) { ... } // Executed if there are no errors,
                                   // it receives the return value of
                                   // the getValues() method as input parameter.
});

Next

• Learn how to create a new widget