-
-
Notifications
You must be signed in to change notification settings - Fork 7
Customizing Features
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.
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 configuration are enabled by default but won’t take effect until the setup is completed.
Ex: Bulk Edit is enabled by default, but not useable until the User Role is created and assigned to an account, the grid has Inline Editing enabled and the keyword added to the view.
The KTL_Configurator application allows you to customize the KTL features easily with its intuitive user interface, and it will generate all the code you need to get started in a few minutes.
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.
These settings control some advanced and developer 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.
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.
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 defined 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.
Exclude Scenes (comma-separated scene IDs) : Defines
Horizontal Radio Buttons: Defines
Horizontal Checkboxes: Defines
Barcode Timeout (seconds) : Defines
Barcode Minimum Length: Defines
Convert Number to Tel: Defines