KTL Setup - how to add and customize callbacks

[cortexrd]

A callback is a function that you provide to the KTL so that it can "talk" to your code.

This is used when an event happens, like user interactions (mouse clicks and keyboard keypresses), when the KTL has completed some processing like a scene render, has found one of your custom keywords, has encountered some kind of error, and a lot more.

The KTL_Defaults.js file contains all the callbacks that exist. Those are defined by the KTL, and more are being added as the feature set grows over time.

You can find them between the //KTL callbacks to your App begin/end markers.

Tip: You should browse through that file once in a while to see what's in there and what's new. But much better, you should subscribe to the KTL Changelog discussion to be notified each time a novelty is added. This will save you a lot of reading time.

If you would like to have a specific callback to be added to the KTL, please submit an issue describing what you would need and what's your typical use case.

Adding a Callback

Let's say you don't like the way the auto-focus behaves. The priority is not right for your type of pages.

1. Open the KTL_Default.js file and locate the auto-focus function by searching for function autoFocus()
2. Copy its code to your app code, typically in a file referred to as the MyApp.js file
3. That code should be placed between the //KTL callbacks to your App begin/end markers.
4. You now have an "overridden" default implementation as follows:

//Your app's version.
window.APP_VERSION = '1.0.0';

var ktl;
window.ktlReady = function (appInfo = {}) {
    ktl = window.ktl;

    //KTL Setup - BEGIN

    ktl.core.setCfg({
        enabled: {
            //Don't forget to turn on the feature!  This line could be deleted also, would have the same effect.
            autoFocus: true,
        },
    })

    ktl.scenes.setCfg({
        //This line below is the "callback hook", linking the KTL to your customized version of the function.
        autoFocus: autoFocus,
    })

    //KTL Setup - END




    //KTL callbacks to your App - BEGIN

    //This is your app-specific callback of the autoFocus function.
    function autoFocus() {
        if (!ktl.core.getCfg().enabled.autoFocus || window.self.frameElement) //Never in iFrames.  Prevents parent from working properly.
            return;

        //I use Kiosks a lot, and never want to set the focus since there's no user input anyways.
        if (ktl.core.isKiosk())
            return;

        //If these fields are in the page, always prioritize them.
        const autoFocusFields = ['field_123', 'field_456'];

        var field = autoFocusFields.find(function (element) {
            if ($('#' + element).length > 0)
                return element;
        });

        if (field !== undefined) {
            $('#' + field).focus(); //Focus of the fields above if present.
        } else {
            //Otherwise use this custom code with my own focus priorities.

            //Text input first
            //Radio buttons
            //Calendars
            //Etc..
        }
    }

    //KTL callbacks to your App - END

    /////////////////////////////////////////////////
    //Your App-specific code goes here...

}

Hope this helps.

P.S. If someone has some good auto-focus code snippet to share, it would be appreciated.

Normand