Customizing Features
Note: For a quick start on customizing features, see the KTL_Configurator section here.
It is possible to control the KTL’s behavior to match your needs. For example, you may want to disable a feature, modify the default colors, or respond to an event that the KTL has generated for your App.
The process is done using two mechanisms: setups and callbacks.
App -> KTL
A setup is done when your App sends the KTL a set of parameters to initialize itself differently than its defaults. It is usually done at startup, with hard coded or computed values.
But a setup can also occur at any other time later (runtime), using values that are based on your App’s business logic, like the account roles, time of day, geographic location, etc., but also user interactions like preference changes.
To use setups, you must add each one you need manually in your App’s code, as explained below.
KTL -> App
The callbacks play a major role, and can be seen as the “interface” that the KTL uses when it needs to talk to your App.
Some callbacks will provide additional information called “parameters”.
Those without parameters are simple event notifications, like idleWatchDogTimeout for example. A typical use case would be that the idleWatchDogTimeout event would notify your App that no mouse of keyboard activity has occurred in the last hour. Then, you could decide to force a logout, or a logout but only if the account Role does not include Developer. In short, the applicable logic is all yours at that point.
To use callbacks, you must add each one you need manually in your App’s code, as explained below.
To customize the KTL, it is strongly recommended that you create a file named MyApp.js in which your own code will reside. Of course, the name is yours to decide, but throughout this document, we will refer to this name as a reference.
There are two main advantages of keeping your code in a separate file instead of editing directly in the Builder:
- working with your favorite fancy editor is so much better
- it allows using a revision control tool to keep track of what has changed over time. GitHub is a great tool and pretty much a de-facto reference in that field.
These are the 5 lines from this file: KTL_Loader.js
You will copy the contents of the KTL_Customization.js file below the Loader.
This is a startup “template” with a few feature flags and the KTL’s entry point, the ktlReady function.
The number of lines contained will grow over time as you need more customizations.
This is where you can disable features, for example. More on this below.
Copy your existing code from the Javascript pane in the Builder to this section, after the comment: //Your App-specific code goes here...
Each time you want to change the KTL setup, callbacks or your own code, do all the editing in this file. Then when you need to test it, copy its content to the Javascript pane in the Builder, save, refresh your App and see if all works as expected.
Keep an eye on the console output (F12 in most browsers) to see if there are errors.
If you’re tired of this redundant routine, consider using the KTL’s Dev mode. Its purpose is to address this issue. It requires a bit of setup, but it’s well worth it.
Note: For a quick start on customizing features, see the KTL_Configurator section here.
Before you can disable or customize features, it is assumed that you have read and implemented the previous section: Adding Setups and Callbacks.
For those who prefer to have all KTL features disabled by default, and enable them one by one progressively as needed, there’s a template file that does that.
Copy the content of the file KTL_AllDisabled.js under the loader section of your Javascript pane.
Don’t forget top move your own code under the line:
//Your App-specific code goes here...
just before the last curly bracket.
In MyApp.js, locate the ktl.core.setCfg function. This is where you will find the basic feature flags, under enabled.
All KTL basic features are enabled by default. So, you must explicitly disable them individually.
For example, you don’t want to see the version info bar at top-right of the page, set this to false: showAppInfo: false
Note: Some advanced features that require some additional configurations are enabled by default but won’t take effect until the setup is completed.
Ex: Bulk Edit is enabled by default, but not usable until the User Role is created and assigned to an account, the grid has Inline Editing enabled and the keyword added to the view.
Note: For a quick start on customizing features, see the KTL_Configurator section here.
For those who are interested in knowing more about the details, here’s the manual procedure.
- Open the KTL_Defaults.js file in your favorite editor.
- Locate the //KTL Setup section and copy each setCfg function that you want to customize in your MyApp.js file, inside the ktlReady function’s brackets, before the //KTL Setup – END marker.
- Go through each flag and set them to match your needs. You should keep only what is needed and delete the rest to keep the file lean and clean.
You can customize each existing callback that you need in your App by copying its default implementation from KTL_Defaults.js to your file and modifying its code.
NOTE!!! There is no need to copy all the file contents - but only those few functions that you need.
To do so, locate the //KTL callbacks to your App section and go through each function, copying and adapting them to match your needs. All copying must be done inside the ktlReady function's brackets, between the //KTL callbacks to your App markers.
Once completed, for each function copied, you must add its reference in the matching setCfg function.
Ex: For onSceneRender, we need this line in ktl.scenes.setCfg.
ktl.scenes.setCfg({
onSceneRender: onSceneRender,
})
This creates the hook between the KTL and your App.
- Copy/paste the content of your file in the Javascript pane and save.
- If you are in Dev mode, the previous step is not required since the local file server will load the code from your workstation directly.
- Open a browser to your Knack App.
- Check console logs to see if all is looking good.
Since the KTL_Defaults.js file is subject to frequent changes over time, mainly due to added functionalities, is it strongly recommended that you go fetch the latest version regularly to see what has changed.
Omitting to do so will not have any negative impact other than not fully benefiting from the latest updates.
GitHub is great as showing each submitted set of changes over time.
The KTL_Configurator application simplifies the customization of KTL features through its user-friendly interface. It generates all the necessary code to get your customizations up and running in minutes.
The question mark icon automatically direct you to the relevant documentation section, making your configuration journey smoother.
Understanding the workflow is crucial before you start configuring your app. This guide outlines the essential steps and provides tips for a seamless setup process.
As you dive into configuring your app, you'll adjust various fields to tailor the functionality to your needs. Due to unforeseen circumstances such as power outages, lost connections, accidental refreshes, or computer glitches, it's advisable to periodically save your progress.
To safeguard your work, simply enter a unique App name at the top of the page and press the Enter key. By default, this action triggers a Save operation, storing your settings locally in your browser. This means you can pick up right where you left off, continuing to adjust settings and hitting Enter to save as you go.
Once you're satisfied with the configuration, it's time to implement and test your settings. Click on "Generate Configuration" followed by "Copy to Clipboard." Now, you can paste this configuration directly into your Builder just below the Loader, replacing any existing setup.
Note that while we casually refer to it as "the configuration," it technically constitutes a JavaScript code snippet that enacts your settings.
IMPORTANT: For those incorporating custom code, it's advisable to position it just beneath the "//Your App-specific code goes here..." comment, and before the closing curly brace.
This specific placement is crucial, not only for organizational clarity but also to guarantee the correct execution sequence of your custom code, i.e., after KTL has completed its internal initialization.
This step is mandatory; attempting to access KTL functions before the framework is fully initialized will result in errors. By arranging your code in the correct sequence, you gain access to all KTL features and functionalities, facilitating a seamless integration of your custom logic with KTL's robust capabilities.
This process is iterative. Feel free to adjust, re-save, copy/paste and test your settings multiple times until everything aligns perfectly with your vision.
After fine-tuning your configuration, creating a backup is a smart move. Simply click on "Export" and select a filename that reflects your App name. This step ensures you have a saved version of your hard work that's not just stored locally.
The "Import" function serves as the gateway to bring in a previously saved .ktlcfg file into your workspace. If the configuration isn't already saved in your browser's localStorage, it will be loaded into memory for you to work with.
When embarking on a new project, a practical approach is to load an existing configuration as a starting point. This method allows you to utilize a familiar setup, which you can then customize according to the needs of your new App.
It's important to rename your App at the top of the form to prevent accidental overwriting of the original configuration. Once renamed, simply save your work, and you're well-prepared to tackle another unique App development project.
This tool is designed to streamline your workflow and enhance efficiency, ensuring that technical setup and configuration adjustments are straightforward and not a barrier to progress.
These settings control advanced and developer-oriented features.
Developer Names: Add the full names of the users having the Developer role in this App, separated by commas. This is mostly used for remote SW updates. Also adds a few more detailed debug logs.
Developer Email: The email to be notified in case of a critical error being logged. Single entry.
Developer Options PIN: When you click on the Version Info Bar, you will be prompted to enter these characters if you don’t have the Developer role. Once entered, you have access to advanced debug features.
Those features are App-wide, i.e. applied across the board.
The Version Info Bar serves many purposes in the KTL. It displays the App and KTL versions, but also serves as a privileged access to important developer features. It is recommended that it remains active, at least to developers.
To access the developer features, there are two methods:
- Have the Developer role.
- Set a PIN that will be asked to those who click on the Version Info Bar and don’t have the Developer role. See Developer Options PIN in the Core Settings above for more details.
Show App Info: If you want to see your App version number in the Version Info Bar.
Show KTL Info: If you want to see the KTL version number in the Version Info Bar.
Show to These Roles Only: The Version Info Bar will only be visible the users having the roles in the comma-separated list. If left empty, it will be visible to all.
Default Horizontal Pos: The Version Info Bar’s horizontal position on desktop devices.
Default Vertical Position: The Version Info Bar’s vertical position on desktop devices.
Mobile Horizontal Pos: The Version Info Bar’s horizontal position on mobile devices.
Mobile Vertical Position: The Version Info Bar’s vertical position on mobile devices.
Default Opacity: If you want to “tone down” the Version Info Bar, a lower value will make it less visible, being more transparent. Values can be between 0 (fully visible) and 100 (invisible).
Opacity on Hover: This is used to override the default opacity when the mouse hovers over the Version Info Bar. It can be used to hide the bar and make it visible only to the “knowledgeable” users who know where it is located.
These are the “top-level” switches and are used to quickly turn on or off any feature without affecting their more specific settings, as some can be found in the sections further below.
Show Menu in Title: Adds the menu in the browser’s tab.
Select Text on Focus: When an input field gains focus (is clicked on or tabbed to), will select all text within.
Inline Edit Color: Colorizes all grid cells that are inline-editable.
Row Hover Highlight: Colorizes grid rows when hovered.
Auto Focus: Upon scene render, will automatically set the input focus on a specific field, based on an algorithm. Default is “first found text input or search field”, but can also be your own.
Sorted Menus: Will sort all menus in alphabetical order, overriding the Builder’s order.
User Filters: Enables the user filter feature, where you can define a filter, then add a “named button” to it.
Persistent Form: When refreshing a scene containing a form view, it will reload the last entered values of each field, instead of erasing and forcing the user to re-enter everything all over.
Calendar Go To Date: Adds a “Go To Date” date picker above each calendar views. This provides a convenient, quick and direct access to a specific date.
Remember Me: When a login screen is displayed, will turn on the “Remember me” checkbox. This will allow your login to expire after 2 weeks instead of 2 days.
Form Pre-Validation: Will enforce form pre-validation and pre-emptively disable the Submit button in real-time, indicating an issue that must be resolved before submitting. For each field not in compliance, their background color will become pink. This is notably used by the Enforce Numeric feature and other user-defined criteria.
Spinner Watch Dog: When enabled, a timeout will occur if the spinner is detected beyond a certain amount of time specified by “Spinner Watchdog Delay” (see below). After that delay expires, the default behavior is to reload the page. This can be overridden with your own code with the spinnerWatchDogTimeout function.
Idle Watch Dog: When enabled, a timeout will occur if no user activity is detected beyond a certain amount of time specified by “Idle Watchdog Delay” (see below). There is no default behavior, but you can provide your own code with the idleWatchDogTimeout function.
Debug Window: Enables a small draggable window where you can send logs that are stored in the localStorage, in a ring buffer of up to 100 logs. This is useful to trace the code execution on devices where you don’t have a console output, such as Android or iOS. To open that window, you must click in the Version Info Bar and then DebugWnd. To create logs, use the ktl.debugWnd.lsLog() function.
Dev Info Popup: Enables the Developer Info Popup window that can be used to visualize information on the field or view being hovered over. This is triggered by holding down the Ctrl+Shift buttons while moving the mouse around.
Dev Pause Auto Refresh: Shows the Pause Auto-Refresh checkbox at the center-top of the App. This is a convenient feature for users having the Developer role, where it is possible to momentarily pause the auto-refresh mechanism, while inspecting the data or the HTML structure while the App still runs (i.e. not in a breakpoint).
Virtual Keyboard: Enables the custom KTL-friendly Virtual Keyboard for Linux devices using a touch screen.
iFrameWnd: Enables the iFrameWnd utility sub-page, where advanced features can be leveraged.
To perform actions on multiple records at once. See this page for more details: Bulk Operations
Bulk Edit: Enables Bulk Edit operations for all users having the Bulk Edit role.
Bulk Copy: Enables Bulk Copy operations for all users having the Bulk Copy role. Note: this feature is referred to as Duplicate in the user interface.
Bulk Delete: Enables Bulk Delete operations for all users having the Bulk Delete role.
This will set the style for the ktl.core.timedPopup window. The syntax is exactly as can be found in the elements section of the Browser’s DevTools. By default, there are 3 basic styles, but they can be customized and more can be added at will. It is good practice to start the style with a semicolon for easy adding to existing styles.
The 3 basic styles are:
Success: Will show a green popup with bold black text and border.
Warning: Will show a yellow popup with bold black text and border.
Error: Will show a red popup with bold black text and border.
This is used to customize the colors of the Tooltips (_ttip keyword), based on the context. It is possible to choose the colors for text, background and icon.
These are the elements that can be configured and are quite self-explanatory.
Form View Background Color
Form View Text Color
Form View Icon Color
Details/List View Background Color
Details/List View Text Color
Details/List View Icon Color
Table View Background Color
Table View Text Color
Table View Icon Color
To set the scene-related parameters.
Version Display Name: This text will be used in the Version Info Bar as the App’s name. Can be useful when you need a more descriptive or shorter label.
Idle Watchdog Delay (minutes): This value in minutes will define how long the KTL will wait before invoking the idleWatchDogTimeout callback. This is useful to detect and take specific action when there’s no user action such as a mouse move, click, or keypress for a given time.
Spinner Watchdog Delay (seconds): This value in seconds will define how long the KTL will wait when the spinner is showing on the screen or on a button before invoking the spinnerWatchDogTimeout callback. This is typically used to prevent excessive delays after submitting a form. The default behavior is to refresh the page but can be overridden by your own code.
Spinner WatchDog Exclude Scenes (comma-separated IDs): This defines which scenes are not subject to a spinner timeout. Typically used in scenes where a lengthy operation is considered acceptable, as it’s often the case with report views.
To set the view-related parameters.
This feature allows toggling a Yes/No field type quickly without using the inline edit. Just tap all the cells to be toggled in a continuous sequence and all will be applied in background while you can resume working.
Background Color (True): Defines the background color of the cell when the value is Yes, True or On.
Background Color (False): Defines the background color of the cell when the value is No, False or Off.
Background Color (Pending): Defines the background color of the cell while the status is pending to indicate your click has been properly queued and is in progress.
Show Spinner: Defines whether the spinner will show up during the processing.
Show Notification: Defines whether a progress indicator will show up during the processing. Will display the number of operations remaining.
Global Header Alignment: When false, the Header Alignment feature will require the _ha keyword for each view where needed. If true, the alignment is applied across the board, not requiring a keyword per view.
KTL Flash Rate: Defines the flash rate in seconds for the ktlFlashingFadeInOut and ktlFlashingOnOff classes.
KTL Outline Color: Defines the border color to be used for the ktlOutline class.
HSC Collapsed Columns Width (in pixels): Used by the Hide/Show Columns feature and defines the width of the collapsed columns. Values can be from 0 to 500 pixels.
Global Hide/Show Columns: When false, the Hide/Show Columns feature will require the _hsc keyword for each view where needed. If true, the feature is applied across the board, not requiring a keyword per view.
To set the field-related parameters.
Text As Numeric (comma-separated field IDs): Allows specifying which fields must be considered as numeric, even though they are short text as their native type. This will prevent entering alphabetic characters or non-numeric valid values, otherwise the Submit button will be disabled.
Text As Numeric Exclude Scenes (comma-separated scene IDs): Defines which scenes are not subject to numeric values enforcement. Typically used in scenes where exceptions are allowed.
Horizontal Radio Buttons: True will change the default orientation of radio buttons from vertical to horizontal.
Horizontal Checkboxes: True will change the default orientation of checkboxes from vertical to horizontal.
Barcode Timeout (Milliseconds): This setting specifies the duration, in milliseconds, allowed between each character input from a barcode reader. If the time gap exceeds this limit, the input sequence is considered complete, and the barcode is processed. This feature ensures timely data handling by distinguishing between separate scanning events.
Barcode Minimum Length: This parameter sets the required minimum number of characters for a barcode input to be considered valid. It ensures that only complete and potentially valid barcodes are processed, enhancing data integrity, and reducing the likelihood of errors due to partial scans.
Convert Number to Tel: True will change the default field types from text to tel (telephone). This enables switching to a phone-style virtual keyboard for easier numeric entry. Prevents from constantly having to switch from alpha to numeric mode. Mostly useful on mobile devices.
Scenes to Exclude (comma-separated IDs): Defines which scenes are not subject to form persistence. For these, the data will never be reloaded after a page refresh.
Fields to Exclude (comma-separated IDs): Defines which fields are not subject to form persistence. For these, the data will never be reloaded after a page refresh.
Inline Edit Background Color: Defines the background color for cells that are inline editable.
Inline Edit Font Weight: Defines the font weight of text for cells that are inline editable.
Table Row Hover Background Color: Defines the background color for rows while being hovered with the mouse. This overrides the Builder’s settings even when its Row Hover flag is turned off.
To provide a thorough understanding of the sections below, it is strongly recommended to read and fully grasp the information presented on this page: Advanced Features in the Knack Toolkit Library. This resource offers an in-depth exploration of advanced functionalities and settings within the Toolkit, ensuring that users can effectively implement and optimize these features within their applications.
Send Heartbeat: Activating this option (set to true) enables the application to communicate periodic heartbeat signals to Knack through the iFrameWnd. This functionality is crucial for maintaining a record of the account's active status and tracking the most recent heartbeat timestamp. Opting to set this feature to false deactivates the heartbeat communication, thus discontinuing the monitoring of the account's active engagement. This setting provides critical insights into application usage and can be pivotal for system health monitoring and user activity tracking.
The Account Logging feature can be very useful for diagnostics and monitoring of various states and activities. But it can also use a lot of API calls. These flags give you finer control over the logging capabilities and API usage.
All logs are stored and displayed as JSON strings. This may be a bit harder to read but opens the door to further processing using JavaScript.
Critical: True will enable critical logs and an email will be sent to the main developer, as specified by the Developer Email field in the Core Settings.
Error: True will enable error logs.
Server Error: True will enable server error logs. When a server error occurs, the first log will be recorded locally, but then stopped until next log-in. This is to prevent overflowing due to a cascading effect (a log triggers another log, etc.).
Warning: True will enable warning logs.
Info: True will enable info logs. This is where you will see all SW updates occurences.
Debug: True will enable debug logs. Typically, these are used temporarily during development, and removed when done. Can also be used permanently to monitor any suspicious issues.
Login: True will enable login logs. Used to see who logged-in your App, and displays various information like operating system, browser, IP address, etc.
Activity: True will enable user activity logs. Used to gather counters of keypresses and mouse clicks per hour. Only the counters are sent and not the details of which keys are pressed nor what is clicked.
Navigation: True will enable navigation logs. This provides valuable information regarding the user’s page access, view searches and filtering applied.
The Kiosk mode forces the App to be displayed in full screen, without an address bar, no menus, no possibility to log out and larger buttons. Typically used as passive dashboard displays, data entry terminals or point of sales.
It’s often required to have additional buttons to ease navigation and interactions. These are the default buttons available in the KTL, but you can also add your own.
Refresh, Back and Done Buttons
All buttons have the same 4 settings.
HTML: Defines the HTML content of the button, typically used to set an icon or style.
ID: Defines the unique ID of the button.
href: Defines the link to be followed when clicking on the button. Can also be an inline function that executes custom code.
Scenes to Exclude (comma-separated IDs): Defines the scenes where the button should not exist.