Keywords - cortexrd/Knack-Toolkit-Library GitHub Wiki
Contents
About Keywords
For an introduction on what are KTL keywords, see this section on the main page of this GitHub project.
Multiple Instances
Some keywords support multiple instances of that same keyword in a given view or field. Each keyword section will mention whether or not this is supported.
Keyword Parameters
Some keywords require one or more parameters, and some are optional. When using parameters, the equal sign “=”operator is added after the keyword, followed by the parameter(s). If multiple parameters are used, the comma is the separator and spaces are allowed.
Example:
_rvs=vTitle1, vTitle2
The keywords are not case-sensitive, but the parameters are and must always be an exact match to take effect. There are a few exceptions, and they will be clearly documented.
Parameter Groups
Some keywords can accept many groups of parameters in a chain. In those cases, the groups are enclosed in square brackets. All groups must be separated by a comma.
Example of a keywords using two groups:
_cfv=[Column1,neq,,,red,,iu], [Column2,gte,100, yellow,#00F9]
Keyword Options
Some keywords can also be used with options that will affect their behavior. The options can be used alone or combined with parameters. When used with parameters, they must be enclosed in square brackets. The placement of the option group is not important. Each keyword can use many options, but only one of each kind.
Here are the available options:
ktlRoles
Defines to which roles the keyword will be applied. If you wish to exclude a role, add an exclamation mark before. This option has the highest precedence. It is being evaluated before anything else, and if this condition is not satisfied, the keyword will not be executed. It is possible to add several roles, separated by a comma. The roles are compared from left to right against the roles of the logged-in account. As soon as a false condition is met, the keyword execution is aborted.
Example:
_hv=[Monthly Sales], [ktlRoles, !Executive]
Will hide the view with title Monthly Sales if the user roles doesn’t include Executive.
ktlTarget
A Universal Selector (see below) that defines to which element the keyword will be applied. See Universal Selectors below for accepted values.
Example:
_cls=[ktlFlashingOnOff], [ktlTarget, field_101, view_104]
Will add a KTL class that flashes the field_101 in view_104.
ktlRefVal
A Universal Selector (see below) from which the text or numeric value will be extracted. This value will then become the reference of a comparison that takes place in the processing of the keyword. Ex: with _cfv, can be used to compare if a numeric value is higher than the reference, and apply a specified color in such case. The selector can be anywhere on the page, not necessarily in the same view. Can be a text value, a numeric value, a calculated summary like Total, Average, Maximum or Minimum. If the ktlRefVal contains only a field without a view, then the keyword’s view is used, and this field’s value becomes the reference in the comparison process for each record. See Universal Selectors below for accepted values.
Example:
_cfv=[Price,gt,ktlRefVal,orange,#6575bb], [ktlRefVal, Average Sales, Store Details]
Will colorize the grid’s Price cells if its value is greater than the reference value found in the Average Sales field of the Store Details view.
ktlSummary
This is actually a “sub-option” of the ktlRefVal option. It is used to specify that the reference value shall be taken from a summary section, at the intersection of a row and column, using their label. If a view is specified, it must be the last parameter. If omitted, the current view is assumed by default.
Example:
_cfv=[Price, lt, ktlRefVal, blue, lightblue, bold], [ktlRefVal, ktlSummary, Avg, Total Sales, view_219]
Will colorize the grid’s Price cells if its value is greater than the reference value found in the summary’s average of Total Sales in view_219.
ktlCond
Will trigger the keyword based on a condition – the result of a comparison between two values.
The following parameters must be supplied:
- Operator: see the list below for all supported operators
- Value to compare, that is the “fixed reference”. See note below about “Special Values”.
- Against value, that is a “dynamic value” (to be compared against): Can be…
- Field and View: both must be supplied. Can be by label/title or by ID. Supported in Details and Form views only.
- jQuery selector (see Universal Selectors)
The supported Operators are these:
- is (exact match - text or numeric)
- not (not equals - text or numeric)
- has (contains text)
- hasnt (does not contain text)
- sw (starts with)
- ew (ends with)
- equ (equals - numeric only)
- lt (less than)
- lte (less than or equal)
- gt (greater than)
- gte (greater than or equal)
- in (within range of time, ex: 17:00-08:00)
- out (outside range of time, ex: 17:00-08:00)
Special Values
These values can be used to trigger special behavior:
- ktlMobile: can be used with is and not operators. It will enable the keyword based on the device type – being mobile or not. The other parameters are ignored.
- ktlMatch: can be used with is and not operators. This value is used when two grids are on the same page, and you need to apply the keyword action for each row of this view (with the keyword) only if the specified field value exists in the other grid, for that same field.
- ktlLoggedInAccount:
ktlMsg
Can be used to define a text message that will be displayed in a popup during lengthy operations.
The first parameter is the type of message, is required and defined the behavior.
The supported types:
- static: just a simple fixed text message. Ex: Please wait…
- count: (future improvement) will display am item count and total to be processed. Ex: Copying record 5 of 20
Examples
_hv=ktlCond, is, No, Franchise, Store Details
Will hide the current view if the Franchise field value is No in the Store Details view.
_hc=[Category, Price],[ktlCond, has, test, Item Desc, Add Item]
Will hide a grid’s Category and Price columns if the Add Item form contains test in its Item Desc field. This will update in real-time as you type!
_hv=ktlCond, is, ktlMobile
Will hide the view if the device is mobile.
_cls=[ktlLinkDisabled], [ktlCond, is, ktlMatch, Survey, Completed Surveys], [ktlTarget, Survey]
Will add the ktlLinkDisabled class to disable the Survey link, if the Survey (name) has a match in the Completed Surveys grid (a utility grid hidden with _hv). This is to prevent clicking in the link that would enter an already completed survey.
_cls=[success-bkgd], [ktlCond, has, Craig, field_6960, ktlLoggedInAccount], [ktlTarget, $('#${viewId} th.field_3304, #${viewId} td.field_3304')]
The success-bkgd class will be added to the grid column (header and cells) with field_3304 in the current view, but only if the logged-in account's name contains Craig.
Keyword Options Examples
For more examples, see in next section below. There’s also a discussion on this topic here, where you can also post questions if you need assistance: Examples on using the KTL - keywords and code
Universal Selectors
The Universal Selectors is a concept that provides a simplified and flexible method of specifying elements for processing. If the user prefers using the field_id and view_id syntax, it will work. Using the View Title and Field Label will also work, as well as a mixed combination.
Note: View Titles and View Names are not the same thing and are not interchangeable. View Names are not used in the KTL. Be careful when referencing a view by its title to choose the right label.
The syntax can be one of the following:
- view_id, field_ids: When providing both, in the ID form, the order is not strict. Multiple fields are supported, but only one view.
- field_ids or fields label only: When providing only the field ID or label, then the view is assumed to be the same as the keyword’s container. Multiple fields are supported.
- Fields label, view title: When providing both but using their textual format, then the order is important. The field(s) must be first, followed by the view. Multiple fields are supported, but only one view.
- jQuery selectors that points to an element containing text or value. This allows selecting more complex or custom text elements, including multiple elements. The KTL automatically detects a jQuery selector string. The syntax must include the dollar sign, parentheses and quotes (or double quotes), as follows:
$('selectorString'). As a special token, you can use${viewId}to blindly reference the current view’s ID without having to explicitly specify it.
Universal Selectors examples
_cfv=[Price, lt, ktlRefVal, red, yellow, ,i], [ktlRefVal, Reg Price], [ktlTarget, Price, Item Desc], [ktlRoles, !Manager, !Supervisor]
This keyword command is added to the description of a list view. It will compare each record’s Price field against a reference value: the field named Reg Price of the same view, same record. If Price is less than Reg Price, the Price and Item Desc fields will be colorized with red italics text on a yellow background. But this will not take effect if the logged-in account has either the role Manager or Supervisor.
_cfv=[Price, gte, ktlRefVal, blue, palegreen, bold], [ktlRefVal, Average Sales, Store Details], [ktlTarget, Item Desc], [ktlRoles, Manager]
This keyword command is added to the description of a grid view. It will compare each row's Price field against a reference value found another view: a details view entitled Store Details, and its field Average Sales. If the value is greater than or equal, then the Item Desc field's value of this grid's row will be colorized blue, and the cell will have a pale green background. But this will only take effect if the logged-in account has the Manager role.
_cls=[ktlDisplayNone], [ktlTarget, $('#${viewId} .kn-export-button')], [ktlCond, is, No, Can Export, Account Permissions]
Will hide the Export button in the current view (regardless of its ID) if the Can Export field is set to No in the Account Permissions details view.
Keyword examples
_ni= [Amount, Phone], [ktlRoles, !Developer]
Will disable Inline Editing of two columns of a grid having headers Amount and Phone, for all roles except Developer.
_hc= [Address, Name], [ktlRoles, Sales, Supervisor]
Will hide columns Address and Name in a grid, for roles Sales and Supervisor.
_zoom=[120], [ktlTarget, $('#view_123 .kn-table')], [ktlRoles, Senior, Visually Impaired]
Will zoom view_123’s table by 20% for seniors and users with low vision.
_cfv=[Sales, gt,ktlRefVal,yellow,darkgreen], [ktlRefVal, $('#view_219 .kn-table-totals:last-of-type td:nth-child(2)')]
Will colorize the column having the title “Sales” with yellow text on dark green background, if the value of the cells are greater than the last summary found in the grid in view_219.
Keywords List
Here's the complete list of all keywords, in alphabetical order.
You will see what is specific to each such as where to use them (ex: view, field), what are the supported options and if possible, to use multiple instances.
_ac
Auto Complete
Used in: Fields
Supported options: none
This feature addresses the broken auto-complete (also known as autofill) functionality commonly found in most web browsers. It offers a solution to enhance data input efficiency by recalling prior text entries from a list, reducing the need for repetitive and time-consuming typing.
All entries are stored in the local storage of your workstation and cannot be automatically migrated, although manual migration is possible. Please be aware that clearing your browser's cache will result in the removal of all stored entries.
You can enable this feature for both Short Text and Paragraph Text field types, and it will be applied universally across the application within all Add and Edit forms. However, please note that it is not supported during inline edits.
Usage:
When typing in a field with this feature enabled and where previous text entries exist, a dropdown menu will appear, displaying those past entries. As you continue typing, the filtering becomes more precise. You can select an entry either by clicking on it or by using the keyboard, utilizing the up and down arrows, followed by the Tab key to make your selection.
You may also click the X to delete an unwanted entry.
Video tutorial: none
_afs/g
Auto-Fill and Submit / Generate QR
Used in: Views
Supported options: keyword-dependent, see Advanced Setup for details.
The "Auto-Fill and Submit" (_afs) and "AFS - Generate QR" (_afsg) feature introduces an innovative approach to form submission and data entry processes. By enabling the automatic filling of forms through the scanning of a QR code, this feature streamlines the submission process, reducing manual input errors and saving time. It is especially designed to enhance efficiency in data collection and processing. The QR code contains all necessary instructions for the form, including the landing URL, which fields to auto-populate, which to disable, and whether the form should be submitted automatically or close itself, making it an ideal solution for fast-paced environments where accuracy and speed are paramount.
Setup Instructions:
See the Advanced Keywords Setup page: _afs/g - Auto-Fill and Submit / Generate QR
Video tutorial: none
Demo: https://ctrnd.knack.com/ktl-tutorials#auto-fill-and-submit-qr-generator/
_al
Auto-Login
Used in: Views
Supported options: None
Used to automate boot-up of Kiosks, Dashboards or any unattended devices. A first-time setup procedure must be done manually, by entering the email and password information. This is done for each new device and can be bypassed if desired. The auto-login process uses AES encryption, and the KTL automatically generates the 32-byte private key. Then, the login credentials are stored in localStorage as cyphertext for retrieval on each reboot.
This keyword must be used in the view title of the login page.
When asked “Do you want to logout?”, click Ok.
Resetting the Auto-Login
To reset the auto-login, you must click on the Version Info Bar, then on the Reset Auto-Login button.
Bypassing Auto-Login
If you wish to use that page but don’t want to use the auto-login process, you need to click Cancel when asked “Do you need Auto-Login on this page?” This will set a flag in localStorage and you won’t be asked again.
_ar=n
Auto Refresh view
Used in: Views
Supported options: None
The view will be refreshed periodically every “n” seconds. If omitted or invalid parameter is given, the default is 60 seconds. It is possible to programmatically start/stop the process using the autoRefresh function.
The accepted range is 5 to 86400 (24h).
_arh=[context, string], [include, fields], [exclude, fields], [expiry, delay]
Add Record History
Used in: Views
Supported options: ktlRoles
Note: this feature uses API calls. Keep an eye on your daily usage. One per call.
This feature is used to keep track of specific record creations, edits and deletions.
This keyword can be used in a add and edit forms, as well as with grid and search views with inline editing enabled. For deletions, a delete action must be added to the view as usual.
When a form or inline edit is submitted, it will compare the “before and after” values of each field and will create a record containing all the changes. Those records are stored in a table called Record History, where they can be searched, filtered and exported at will.
Only the changes will be logged, with both the before and after values being shown on top of each other for an easy visual comparison.
Parameters:
The parameters must be separated into up to 4 groups. All are optional and their order is not strict.
Group 1:
context: This field is a freeform text field that sets the context of the record being created or updated. Its main goal is to facilitate the eventual search and filtering process when it’s time to browse through the records history. It can be seen as a placeholder for commonly used “tags”. It’s up to you to decide what it should contain and how you want to use it.
Group 2:
include: When this list is used, only those fields will trigger the process if changed. Others will always be ignored.
exclude: When this list is used, those fields will be ignored and not trigger the process, even if changed.
expiry: A delay that will be added to the current date/time used to set the Expiry field. This can be used to pre-emptively clean-up the history records and avoid overflowing your subscription plan. Currently, the cleanup must be done manually. The format is a numeric value immediately followed by the letter d, h or m (days, hours or minutes). A Task can be set to run daily and check if the Expiry date is today, then set the Status to Expired. Then, an administration-level page can be created with a grid that filters on those expired records only and allows deleting them with the Bulk Delete feature.
Notes:
- Each submit uses one API call, regardless of how many fields have changed.
- By default, all fields in the form will trigger the record history recording, if changed.
- Using both the include and exclude parameter groups is not recommended as they can lead to conflicting and unpredictable results.
Examples:
_arh
Will create a record history entry without context and expiry, when any field is changed.
_arh=[context, Specs Change Approval Signature], [include, Signature, Reason, SKU], [expiry, 90d]
Will create a record history entry with the stated context, when the Signature, Reason and/or SKU is changed. The expiry date/time will be set to 90 days from now.
Setup Instructions:
See the Advanced Keywords Setup page: _arh - Add Record History.
Video tutorial: none
_asf=delaySeconds
Auto Submit Form
Used in: Views
Supported options: None
When used in a form view, will automatically be submitted. An optional parameter can be supplied that is a delay in seconds to wait before submitting.
No parameter is zero or instant submit.
Example:
_asf=5
Will wait 5 seconds before submitting the form.
Video tutorial: none
_ask=actionLinkText, questionText, yesOption, noOption
Ask for Confirmation
Used in: Views
Supported options: ktlRoles, Parameter Groups
When used in table or search views, creates confirmation popups before action links execute, preventing accidental clicks.
Supports multiple action links per view with individual customization. For example, a table with "Disable" and "Delete" action links can have unique confirmation messages and buttons for each.
Using the keyword without parameters applies a default "Are you sure?" with Yes/No buttons confirmation to all action links in the view.
Parameters:
actionLinkText (optional): The action link text to be processed. It must be the cell text, not the header.
questionText (optional): Default value is “Are you sure?”.
yesOption and noOption (optional): The text to be shown on the confirmation buttons. By default, it will be Yes and No. The yesOption is always at left and the noOption at right in the popup.
Example:
_ask
Will apply the default confirmation popup, for all action links in the view.
_ask=[Disable, Disable this item?, Confirm, Cancel], [Delete Record, Delete this record?, Sure, Geez... NO!]
Will apply two different implementation, one for each action link.
Testing Tip: It is recommended that a dummy action link be created for testing this keyword’s setup. One of the simplest ways to do this is to create an action that sets a field to its own value, so it has no real effect.
Video tutorial: none
_bcg=[size, field, h], [format, width, height], [style, styleString], [text, staticText]
Barcode Generator
Used in: Views
Supported options: Parameter Groups, ktlRoles
Used to generate QR Codes or 1D Barcodes containing the text of a specified field or static text.
It can be used with Details, List, Rich Text and Form views. When used in a Form view, the QR code will be generated in real-time, as the user types characters in the input field. Note that the image itself is not stored, only its text.
The first group of parameters must exist, and the following are optional.
Group 1
size (optional): The first parameter is optional and is the QR Code size. It’s a single numeric value that defines both the width and eight dimensions in pixels. If omitted, 200 is used by default. Minimum is 30 pixels.
field: The field parameter defines which field to use, by its ID or label. If omitted and in a Details or List view, the first one is used.
h: adding the "h" letter (hide) will remove the text. If the text is visible, the QR/barcode will be placed above if in a Details or List view, and below if in a Form view.
Group 2 (optional)
format (optional): The first parameter is optional and is the barcode format. If empty, QR Code will be used by default. The following are supported: QR, CODE128, EAN/UPC, CODE39, ITF-14, MSI, Pharmacode and Codabar.
If omitted, the width and height values will be 100 by default.
width, height: This defined the width and height in pixels of the 1D barcode. Ignored for QRs.
Group 3 (optional)
style (optional): This is a style string that allows aligning, centering, positioning the codes. The parameter’s style syntax is exactly as typically viewed in style tab of the console’s view, when looking at the HTML element.
Group 4 (optional)
text: This allows using static text instead of text extracted from a field in the view.
Examples:
_bcg=75, field_123, h
Will create a QR code of 75x75 pixels for field_123, and no text below it.
_bcg=,,h
Will create a QR code of 200x200 pixels for the first field found in a Details view, without the text.
_bcg=[, Web], [format, CODE128, 100, 70]
Will create a 1D barcode using format CODE128, 100 pixels wide by 70 pixels high, using the text found in field labeled Web.
_bcg=[, My Barcode], [format, CODE128, 90, 45], [style, text-align: center]
Will create a 1D barcode using format CODE128, 90 pixels wide by 45 pixels high, using the text found in field labeled My Barcode, and with centered text style.
Video tutorial: none
Demo: https://ctrnd.knack.com/ktl-tutorials#ktl-demo-page/barcodes/
_bcr= [field, numChars, numDecimals], [prefix, prefixChars], [auto, command, delay], [match, matchMode]
Barcode Reader
Used in: Views
Supported options: Parameter Groups, ktlRoles
Used for reading QR Codes or 1D Barcodes containing text data. For short, we’ll simply refer to both as “barcodes”.
It can automate the extraction and populate some fields in a form. Additionally, auto-submit can be enabled with a pre-delay.
Applicable to both Add and Edit Form views.
The parameters Group 1 is mandatory, while the others are optional. Note that in this keyword, the group order is not strict. The first parameter of a group defines its functionality.
Group 1
field: Specifies the field to extract from the barcode and populate in the form. It can be identified by field label or field ID. Supported field types are all text fields and connected fields.
numChars: The number of characters to extract and paste into the specified field.
numDecimals (optional): The number of decimal places to insert a period among digits. This can only be used with numeric values. The sum of numChars and numDecimals must equal the actual length of that barcode segment, excluding the period.
Group 2 (optional)
prefix (optional): The initial characters expected at the start of all barcodes. This indicates the use of a barcode device and serves as a format validation. Typically, a non-alphanumeric symbol or an unlikely character combination is used.
prefixChars: The actual prefix characters.
Group 3 (optional)
auto (optional): Defines if automation is processed once the form is populated.
command: currently, the only command supported is submit and must be supplied.
delay: defines how long to wait before executing the command, in milliseconds. Default: zero for an instantaneous execution.
Group 4 (optional)
match (optional): Used only for dropdown field types. Defines the behavior of the search match mode when searching the list. Note that all dropdown searches are not case sensitive.
matchMode: options are
- exact: the text must be an exact match. When not specified, this is the default.
- partial: when there is more than one entry found, the first one will be automatically selected by default, and close the dropdown.
- select: when there is more than one entry found, the dropdown will be left opened and the user will have the opportunity to inspect the results and choose the desired one.
Examples:
_bcr=Lot
Will read the whole barcode and populate the Lot field with its value. Lot can be a text or a dropdown field. Barcode length can be variable.
_bcr=[prefix, ::], [Lot, 6], [Item, 8], [Price, 4, 2], [auto, submit, 2]
Will read a QR/Barcode when the prefix :: is encountered, like this one:
::123456ToolBelt003199
The next 6 characters will populate the Lot field that is a dropdown single select connection, in this case, Lot is 123456.
The next 8 characters will populate the Item field that is a short text, in this case, Item is ToolBelt.
The next 6 characters will populate the Price field with the insertion of a period between the 4th and 5th characters. In this case the Price is 0031.99. The Currency or Number field will remove the leading zeros.
Once the dropdown search has completed successfully, the submit button will be clicked after 2 seconds.
Video tutorial: none
Demo: https://ctrnd.knack.com/ktl-tutorials#ktl-demo-page/barcodes/barcode-reading-automation/
_bm
Add Bookmarks
Used in: Views
Supported options: ktlRoles
Enables page bookmarking functionality throughout your application. Users can bookmark their frequently visited pages by clicking the bookmark icon at the top-right corner of any page.
When this keyword is added to any view of a page, a collection of bookmark buttons will appear at the bottom of that page, providing quick navigation to previously bookmarked pages.
This keyword is disabled when the device is used in kiosk mode.
Parameters:
all (optional): if included, the bookmark buttons will be consistently displayed across all pages of the application.
top (optional): if included, the bookmark buttons will be added at the top of the page, instead of the bottom as per default.
Examples:
_bm
_bm=all
_bm=top
_bm=[all, top], [ktlRoles, !Customer] *(to be shown on all pages, at top, but not for customers)*
Video tutorial: none
_cfv=colHeader, operator, refValue, textColor, backgroundColor, fontWeight, options
Colorize Field by Value
Used in: Views and Fields
Supported options: Multiple Instances, Parameter Groups, ktlRoles, ktlTarget, ktlRefVal, ktlSummary
Can be used with grids, lists and details views. Used to compare the content of a cell to a reference value, and apply the following:
- Change the text and background colors
- Set the following styles: font weight (bold, extrabold , 700), underline and italic
- Affect the whole cell or only the text within
- Propagate the style across the whole row
- Flash the cell with On/Off or Fade In/Out modes, and an adjustable rate
- Hide or remove the cell's text
- Suppress (delete) a grid or search view’s row
The color formats supported are:
- named values (ex: red, purple)
- hex values with optional transparency (ex: #ff08, or #ffff0080 for 50% transparent yellow)
Parameters:
colHeader (required): The colorization will be applied to the cells of the column having this header. The field ID can also be used instead of the header text. Note: if used in a field, the colHeader must match the field name.
operator (required):
- is (exact match - text or numeric)
- not (not equals - text or numeric)
- has (contains text)
- sw (starts with)
- ew (ends with)
- equ (equals - numeric only)
- lt (less than)
- lte (less than or equal)
- gt (greater than)
- gte (greater than or equal)
referenceValue (required): Any literal text or numeric value against which the field value will be compared. For “empty” string, leave two consecutive commas. When a fixed value or text is not desirable, a special option can be used instead: ktlRefVal. This links to a reference value that can change dynamically. When used, this option must be added as the first token of an additional group, followed by a comma and a Universal Selector that fetches the reference value in real-time. At a minimum, a field must be specified. In this case the view is assumed to be the current one and the value is extracted from each record during processing. If a view is specified, it must be a Details view.
textColor (required): any standard “named colors” or hex values starting with # and has 3, 4, 6, or 8 digits is supported.
backgroundColor (optional): Same as above. Will colorize the cell or only the text if the “t” option is included.
fontWeight (optional): Any named value like “bold”, or “lighter”, or a numeric values like 700. Omit or leave empty for default.
options (optional): Possible values are
u - underline
i - italic
t - text only
b - ignore blank cells
p - propagate style to whole row
r - remove text
h - hide text
f - flash with On/Off mode
ff - flash with fade In/Out mode
l – line-through text (aka strike-through)
s - suppress (delete) the grid or search view’s row
Example:
_cfv=[Discount,not,,,red,bold,iu], [Reg Price,gte,50, yellow,#00F9,,ff]
The first group between square brackets will set the background in red and text in bold when the Discount value is not blank and set the text style to bold, italics and underlined. The second group will "smooth flash" the text color to yellow and the background in blue at 56.3 % transparency, when the Reg Price value is greater than or equal to 50.
Additional notes:
- The square brackets are optional if you have only one group of parameters.
- Be careful to avoid conflicting conditions since they will yield unpredictable results.
- The group of parameters are applied from left to right, so that if you have overlapping conditions, the last one will have precedence.
- Transparency can’t be used to combine various colors. Only the last setting will have precedence.
- This keyword can be used in a view’s title or description.
- This keyword can be used in a field’s description (table view). In such cases, it will take effect in all grids and lists across the app.
- Using _cfv in both the view and the field simultaneously is supported but the views will supersede the fields colorization if both are competing. Care should be taken to avoid conflicting conditions and confusion. Using transparency helps combining colors while maintaining the desired visual cue.
_click=actionLinkText, auto, buttonLabel
Automated Clicks on Action Links
Used in: Views
Supported options: Multiple Instances, ktlRoles
Will sequentially click on all Action Links with the specified text. Can be used with Grid and Search views.
Parameters:
- actionLinkText: the text that is shown in the action link (not the header). Must be exclusive in that view.
- auto (optional): When added, it will trigger the clicking operation without user intervention. If you want a confirmation prompt first, add confirm or leave blank
- buttonLabel (optional): When added, will create a button with this label, that needs to be clicked to trigger the clicking operation. Once clicked, the auto parameter above will also be applied if present.
Important:
- It is crucial to properly filter your view to exclude any records that should not be clicked.
- In the source table of your grid, you must add a flag that will have a default value: false. Name it something like actionIsClicked.
- Configure your action to do whatever it needs to do, but to also set the actionIsClicked flag to true.
- Configure the display rule for that action so that it hides the action link text when the flag is false.
- The two steps above will prevent entering in an endless clicking loop, or getting stuck after the first action.
Example:
_click=Reset, auto, Reset Assigned
Will add a Reset Assigned button to the view and once clicked, will start clicking on all Reset action links, without confirmation.
Video tutorial: none
_cls=class1, class2
Add/Remove Classes
Used in: Views
Supported options: Multiple Instances, Parameter Groups, ktlRoles, ktlTarget, ktlCond
To remove a class, add an exclamation mark in front of it.
The KTL has several built-in classes that you can use with this keyword and in your apps. See this section for a detailed list: KTL Built-in Classes
Examples:
_cls=[ktlFlashingOnOff], [ktlTarget, $('.kn-view thead')]
Will flash the headers of all tables on the page.
_cls=[!is-small], [ktlTarget, $('#view_206 .is-small')], [ktlRoles, Sales]
Will remove the .is-small class in view_206, if logged-in user has the Sales role.
Video tutorial: none
_cmr=viewsToRefresh
Close Modal and Refresh Parent Views
Used in: Views
Supported options: none
Add this keyword to a modal add/edit form, to close the form without scrolling back all the way to the top. Also refreshes the desired parent views to see the latest changes.
Set up the Submit rule to Show a confirmation message – not Redirect to parent page.
Depending on where you add the keyword, it will have different behaviors:
- Added to the Form, it will take effect upon clicking on Submit.
- Added any other view (than the Form), it will take effect upon closing the modal page.
Parameters:
Can be the following:
- A list of views to refresh in the parent page. Can be view IDs or title. This will update the views’ data but will NOT apply the Builder’s Page rules.
- No parameter: to refresh all views in parent page. This will update the views’ data but will NOT apply the Builder’s Page rules.
- ktlPageRefresh: to refresh the whole page but also apply any page’s display rules that exist.
Example:
_cmr=view_123, My View Title
Video tutorial: none
_copy
Copy to Clipboard
Used in: Views
Supported options: ktlRoles
Adds a copy button to Grids, Search and Details views. When clicked, will copy the HTML contents of the view to the clipboard, ready to be pasted in Excel, Word, or any other app.
Video tutorial: none
_cpyfrom=[srcView, auto, buttonLabel, mode], [fieldsToCopy], [optional parameters]
Copy Records from View
Used in: Views
Supported options: Parameter Groups , ktlRoles, ktlMsg
Note: this feature uses API calls. Keep an eye on your daily usage.
Allows copying all visible records from a source grid to this grid - called the destination grid, where the keyword is used. Will work even when both views have different data sources, but compatible field types with matching header text.
There are two modes of operation: Add and Edit.
Add is used to insert all records from the source grid in the destination grid. The destination grid must be empty and the operation will not occur if it has any record.
Edit is used to update any records in the destination grid with information found in the source grid. This also works with duplicate records, which means that if the source grid has one record and the destination has 5 instances of that same record, all 5 instances will be updated. The Edit mode can be used to copy connected records where such connections would not be possible otherwise.
The destination grid must have Inline Edit enabled as well as for each field you intend to be copied. All non-editable fields will be ignored.
Note that for this keyword, all parameters must be used in groups, which means they must be enclosed in square brackets. The order is important.
API is used to fetch data from a remote view that is not necessarily on the same page as the keyword’s view. Once the data is fetched, it can be used to update any other record/field on the page.
This has been used to fill-in the gaps between unrelated tables, where connections or text data had to be copied.
This feature is still under development, but we’re interested in hearing about any potential use cases on your behalf.
Parameters:
Group 1**:**
srcView: Mandatory, specifies the view ID or title of the source grid.
auto (optional): When added, will trigger the copy operation without user intervention. If you want a confirmation prompt first, add confirm or leave blank
buttonLabel (optional): When added, will create a button with this label, that needs to be clicked to trigger the copy operation. Once clicked, the auto parameter above will also be applied if present.
mode (optional): Can be Add, Edit or API. When added, will define how the copy operation will be performed, by creating new records or updating existing ones. See details above. If omitted, Add will be used by default.
Group 2**:**
This group is optional and is an enumeration of the fields to be copied for each record. They must be in text format, never the field ID since this label is used to find the matching headers in both grids. This also means that, to do the mapping properly, the headers must not only match, but also have the same field type.
To copy all fields, leave empty like this: [] or omit group. Note that if you omit this second group, you can’t use any additional groups.
Group 3+**:**
The following groups are optional and can be used to perform special mapping. Again, the destGridViewHeader parameter must be the textual header of the destination grid, not the field ID.
They can be used to…
- map a header to a fixed value from an external Details field/view in same page. Format is:
[destGridViewHeader, srcDetailsViewField, srcDetailsView]. The two last parameters can be by IDs or label/title. - map a header to special value. Currently, we support the ktlLoggedInAccount option to use the currently logged-in account’s record ID. Format is:
[destGridViewHeader, ktlLoggedInAccount]. Of course the field must be a connection field to the Accounts table.
Example:
_cpyfrom=[Survey Questions, auto], [], [Account, ktlLoggedInAccount], [Survey, Survey, Survey Details]
Will copy all survey fields from the Survey Questions grid to this grid and create a connection to the logged-in user in the Account field. Will also assign the value from the Survey field in Survey Details view to the Survey field in this view.
The ktlMsg option can be used in another group to define the text to be displayed during the copy operation. See the Keywords Options section for more details on ktlMsg.
Example:
_cpyfrom=[Survey Questions, auto], [ktlMsg, static, Copying records, please wait…]
Video tutorial: none
_cpytxt=[srcColumn, dstColumn]
Copy Text
Used in: Views
Supported options: Parameter Groups, ktlRoles
Can be used in grid and search views to copy the cells’ text from a source column to a destination column, for all rows, while preserving the destination links, if any.
This is typically used when it’s not possible to view a field’s data when you need a link at same time. Usually a two-column solution is needed, one for each. With this keyword, you can hide the source column containing the data of interest, but copy its text to the destination column, which has the link to another page.
Example:
_cpytxt=[Lot, Edit Lot], [Customer, Edit Customer]
Will copy the text from all cell in the column Lot and Customer to their respective destination columns Edit Lot and Edit Customer.
Video tutorial: none
_da=alignment, field1, field2…
Data Alignment
Used in: Views
Supported options: ktlRoles
When used in a details view, the data for the desired fields will be aligned as specified.
Parameters:
- First parameter is the alignment type. Can be one of the following options:
- left
- center
- right
- Second and following parameters are optional.
- If no parameters, then all fields will be aligned
- If a list of field is supplied, only those will be aligned. Can be field ID or field label
Video tutorial: none
_dl
Disable Links
Used in: Views
Supported options: ktlRoles, ktlTarget
When added to a Grid, Search or Details view, will disable clicking on any link.
If ktlTarget is used with “page” as parameter, then all links in the page will be disabled. Other ktlTarget parameters (ex: field/view or jQuery) are not supported.
Notes:
- Action Links are still enabled
- Only URLs, Phone Numbers and Emails links are affected
- The disabled links appearance will become grayish, semi-transparent and without the underline
- Mouse clicks are disabled
- Uses the built-in ktlLinkDisabled class
Video tutorial: none
_dr=rowsNumber
Displayed Records
Used in: Views
Supported options: ktlRoles
Sets the initial number of rows in a Grid or Search view, allowing to go beyond the maximum value of 100 in the Builder.
Can also be used to specify any arbitrary (non-standard) number or records, like 30 or 200 for example.
The accepted range is 1 to 2000.
Notes: When displaying more than 1000 records, Knack will only consider the first 1000 records to calculate the summary.
_dtp
Add Date/Time Picker to a table
Used in: Views
Supported options: ktlRoles
This feature works with grids and pivot tables.
The view must have a Date/Time field, and the first one found from the left will be used. Six new fields will appear at the top of your table view: From, To and periods as Monthly, Weekly, and Daily. Depending on the active period, when you change From, the To field will automatically update itself accordingly, and the view will be filtered in real-time. On the other hand, if you change the To date, the From will not be affected, leaving you more flexibility. The focus is conveniently placed on the last field used so you can use the up/down arrows to scroll quickly through months and visualize data. This is also compatible with additional filter fields, provided that the AND operator is used. Once you have a filter that you like, it is also possible to save it as a User Filter.
Demo: https://ctrnd.knack.com/ktl-tutorials#ktl-demo-page/date-time-picker-dtp/
_dnd=dndType, [other type-specific parameters]
Drag'n Drop
Used in: Views
Supported options: ktlRoles
Note: this feature uses API calls. Keep an eye on your daily usage.
Parameters:
The first parameter is the Drag’n Drop operation type:
sort
Currently, sort is the only supported method.
It enables the manual reordering of grid rows by moving them up and down. Upon a drop event all records will be automatically re-numbered from 1 to n.
When the grid has groupings, the records can only be moved within their current group.
It is possible to set an upper limit for the re-numbering process. This can be useful to assign a special meaning to upper values that should remain. Note that these rows can still be dragged upwards in the grid to be reassigned to a lower Order value if needed. See Optional Parameters below for more details.
Setup Instructions:
- Add a numeric field to the grid's table. Let’s call it “Order” (not strict).
- Ensure that both the grid and the Order field are set to Inline Editable.
- Configure the grid's data source to sort based on the Order numeric field, arranging the values from lowest to highest.
- To maintain the intended sorting functionality, it is important to add the _nsg (No Sort on Grid) keyword and disable Search and Filtering. This is crucial to prevent unpredictable outcomes since the API is applied to all visible records in the grid.
- Optionally, you may want to add _ni to the Order field to prevent manual inline editing.
Optional parameters:
If you need to limit the upper numbering, use the lte, numericValue option in a separate group (lte stands for less than or equal).
Examples:
_dnd=[sort, Order], [lte, 99]
Will sort on the Order column and stop the renumbering process at 98 inclusively.
src
Future improvements.
dst
Future improvements.
These are not yet implemented but will allow moving elements from one view to another.
Callbacks:
It is possible to handle Drag’n Drop’s Start, Move and End events in your App for specific processing. It requires a bit of additional setup. If interested, please contact us for details.
Video tutorial: none
Demo: https://ctrnd.knack.com/ktl-tutorials#dragn-drop/
_dpf=publicFilterName, h
Default Public Filter
Used in: Views
Supported options: Multiple Instances, ktlRoles
This feature is typically used to provide a default view layout that can be based on the account role.
When your app is set-up to use Public Filters, you can use this keyword to select which one will be automatically applied to the view when the page is loaded. By design, it will only be triggered on a scene render and not a view render.
The view type must be a grid and the keyword will only take effect if the view doesn’t already have an active filter.
Parameters:
- The first parameter is the name of the Public Filter button and must be an exact match.
- If the second parameter is ‘h’, the button will be hidden.
Video tutorial: none
_dv
Disable View
Used in: Views
Supported options: ktlRoles
Used to disable all clickable items from a view, including links, action links and inline edits.
The following types are supported: Grid, Search, List, Menu and Forms.
Also, when used in a Form, will disable all input fields.
Video tutorial: none
_footer
Add Footer to all Pages
Used in: Views
Supported options: none
Will dynamically append a footer to each page in the application.
Setup instructions:
- Create a new page with only a Rich Text view in it. Add any desired elements that you want to appear as your app-wide footer.
- At the very end, or on a separate line ideally, add the _footer keyword, without parameter.
Video tutorial: none
_ebo=[edit, copy, delete, action]
Enable Bulk Operations
Used in: Views
Supported options: ktlRoles
Will enable any Bulk Operations, without requiring the specific user role. This is a per-view solution, vs per-role.
Refer to this section about Bulk Operations:
https://github.com/cortexrd/Knack-Toolkit-Library/wiki/Features-Overview#bulk-operations
You must ensure that all settings are applied properly for each operation.
Parameters:
Can be any combination of these:
- edit
- copy
- delete
- action
No parameter means all.
Examples:
_ebo=edit, copy, delete
Would enable all of them. No parameters would do the same, or any combination, as desired.
In such case, the bulk ops would be enabled, regardless of whether the user has the Bulk Op role(s).
If you combine this with a new User Role, you can then enable per user and per view.
_ebo=[edit, delete], [ktlRoles, Bulk Ops Per View]
Assign the role "Bulk Ops Per View" to those users only. The role name can be any User Role found in the Builder, not being dictated by the KTL.
Video tutorial: none
_ha
Header Alignment
Used in: Views
Supported options: ktlRoles
When used with grids, search or pivot tables, the headers will match the alignment of each column’s data.
_hc=colHeader1, colHeader2
Hide Columns
Used in: Views
Supported options: Multiple instances, Parameter Groups, ktlRoles, ktlCond
To hide a grid’s columns, based on the header’s exact text. The columns are only hidden but still exist in DOM. The visibility can be reversed on the fly with a bit of extra code. Hiding a column is useful to save real-estate or hide its data, while maintaining API calls capability or allow filtering on all fields.
_hf=field1, field2…
Hide Fields
Used in: Views and Fields
Supported options: Multiple instances, Parameter Groups, ktlRoles, ktlCond
To hide fields in forms, details or list views, based on their exact labels in the view. The field IDs are also supported. These are typically used as "utility" fields that are required but not needed to be visible.
When used in a field, parameters are ignored.
Video tutorial: none
_hsc
Hide/Show Columns
Used in: Views
Supported options: ktlRoles
When added to a Grid or Search view, it will add a small arrow to each column’s header.
- When clicked, it will compress the column to a narrow, hatched vertical zone to save space.
- Clicking anywhere in the that zone will expand the column back to its normal size.
- Hovering over the arrow of a collapsed column will display its header title in a small popup.
The User Filters and Public Filters are the placeholders to save your collapsed columns settings and make them persistent.
If saved in a Public Filter, you can also use the _dpf keyword in conjunction to set the default button to activate when none is active.
Additionally, you can customize the behavior of the _hsc keyword using the ktl.views.setCfg function:
- Set the collapsed columns width in pixels. See hscCollapsedColumnsWidth variable.
- Enable globally in all grids and search views, so you won’t have to do it for each views. See the hscGlobal variable.
- Add a callback in your code to a function called hscAllowed that determines if that view can have collapsible columns, based on your own conditions. Ex: do not apply _hsc if the device is in kiosk mode. Or only if the code runs on a mobile device.
Video tutorial: none
_hsr=[dr, duration, rate], [clr, outlineColor], [cls, class1, class2, …], [style, styleString]
Highlight Submitted Record
Used in: Views
Supported options: Parameter Groups
Used in an Add or Edit Form view to highlight the record just submitted. The behavior and highlight modes are highly customizable.
This can used when the form and other views to be highlighted are in the same scene.
Notes:
- This keyword will work with modal scenes, as long as the views to be refreshed are also present in the same scene and the submit rule doesn’t close the modal page. It will not work when the views to be refreshed are separated, i.e. in the background of the modal page.
- Do not use the _rvs keyword along with _hsr, as this would cause double-refreshes since _hsr already triggers a render of all views in scene.
Parameters:
The parameters must be separated into up to 4 groups. All are optional.
Group 1:
dr: Duration and Rate. The duration is in milliseconds and defines how long the highlight will remain visible. Range is 100 to 3600000 (1 hour). Rate is a number in milliseconds that defines how fast the flashing will occur, when a flashing class is specified in the cls parameters (ignored otherwise). See cls below. Lower values will flash faster. Range is zero to 50000. Zero disables flashing, giving a steady color.
Group 2:
clr: The color of the Outline, if the ktlOutline class is used. See cls below. Can be any named value like red or a hex value like #FF0 (for yellow).
Group 3:
cls: Will add the specified classes that are the following parameters, separated by commas. Can be KTL’s built-in classes or any other that you create.
If flashing is desired, these classes are available, built-in the KTL: ktlFlashingOnOff and ktlFlashingFadeInOut. In such cases, the rate parameter will also be applied.
Group 4:
style: Will apply the desired style, like colors, font size, weight, etc.
By default, if no parameter is supplied, the records will flash with a pale yellow background color for one second and a flash rate of 500ms.
Example:
_hsr=[dr, 2000, 500], [clr, purple], [cls, ktlFlashingOnOff, ktlOutline], [style, background-color: indianred; font-weight: bold; color: yellow;]
Will flash the record for 2 seconds at 500ms rate, with a purple outline, an indianared background color, and bold/yellow text.
Video tutorial: none
_hsv=openCloseDelay, defaultOpened
Hide/Show View
Used in: Views
Supported options: none.
When added to any view, will make the view vertically collapsible.
The view’s header will be converted to a tab with an arrow. The tab can be clicked to hide or show that view using a smooth up/down scroll.
Parameters:
openCloseDelay: Defines the time in milliseconds taken by the view to open and close itself. Smaller values will give a higher scroll speed. Default is 500 ms.
defaultOpened: Defines the initial opened or closed view state. Opened: true, closed: false.
Examples:
_hsv
Will open the page with the view expanded by default and a scroll delay of half a second.
_hsv=1500, true
Will open the page with the view expanded by default and a scroll delay of 1.5 seconds.
_hsv=, false
Will open the page with the view collapsed by default and a scroll delay of half a second.
Video tutorial: none
_ht
Hide View Title
Used in: Views
Supported options: ktlRoles
Used to save real-estate while keeping the title in the Builder and allow the functionalities of other dependent keywords.
_hv
Hide View
Used in: Views
Supported options: Multiple Instances, ktlRoles, ktlCond
Moves the view away from screen but kept in DOM. Used to save real-estate, while maintaining API calls and automated search capabilities.
_int
Integer Characters Only
Used in: Fields
Supported options: None
Will only allow entering numeric characters 0 to 9, even if the field type is short text. Validation is done in real time with enforceNumeric.
_ip
Enforce IP Format
With automatic colons and hex char real-time validation (not yet implemented).
Video tutorial: none
_kb
Kiosk add Back Button
Used in: Views
Supported options: None
_kbs=style
Kiosk Buttons Style
Used in: Views
Supported options: None
Only effective in kiosk mode. Provides control over the default buttons style.
The parameter’s style syntax is exactly as typically viewed in style tab of the console’s view, when looking at the HTML element.
Example:
_kbs=height:50px;font-weight:700;min-width:150px;background-color:green!important;
Video tutorial: none
_kd
Kiosk add Done Button
Used in: Views
Supported options: None
Video tutorial: none
_km
Kiosk Mode
Used in: Views
Supported options: None
Triggers the Kiosk mode for that page. This only applies for any role other than Developer. For the accounts having the Developer role, it is possible to switch back and forth between the Normal and Kiosk modes by clicking on the Version Info Bar, provided that it is accessible.
Video tutorial: none
_kn
Kiosk No Buttons
Used in: Views
Supported options: None
When Kiosk mode is enabled programmatically and we don’t want to see any buttons.
Video tutorial: none
_kr
Kiosk add Refresh Button
Used in: Views
Supported options: None
For Kiosk mode only, when there’s no keyboard/mouse. When this keyword is used, any menu on the page will be moved next to it to save space.
_lbl=[labelText], [viewTypes]
Label Text
Used in: Fields
Supported options: Multiple Instances
Allows changing the displayed label or header of a field at runtime. This is typically useful to keep the Builder's labels short and have a more elaborate and descriptive text showing up on the user's pages.
The keyword is used in the field and will be applied across the board.
Parameters:
This keyword’s parameters must always come in pairs of groups.
Group 1:
Label: The text to be used for the field’s label of header.
Group 2:
View Types: Contains any combination of the following parameters that will define in which view types it will take effect:
- t = grid/table
- d = details
- f = form
- l = list
Example:
_lbl=[Tell us more about you], [f]
_lbl=[About you], [tdl]
Will display “Tell us more about you” in form views only, and display “About you” in grids, lists and details views.
Video Tutorial: none
_lf=view1, view2…
Linked Filters
Used in: Views
Supported options: None
Add this to the main “controlling” view, and all other linked views will apply the same filtering pattern. The number of records per page, sort column/order and searched text will also apply, if the view allows it.
Note that the linked views don’t require their Filter feature to be enabled for this to work. This is useful if you want to save real-estate or prevent filtering on these views.
Demo: https://ctrnd.knack.com/ktl-tutorials#ktl-demo-page/linked-filters3/
_ls=view1, view2…
Linked Searches
Used in: Views
Supported options: None
Add this to the main “controlling” view, and all other linked views will apply the same searched text.
Note that the linked views don’t require their Search feature to be enabled for this to work. This is useful if you want to save real-estate or prevent searching on these views.
Supported view type: Grid.
Video Tutorial: none
_lub and _lud
Last Updated By and Last Updated Date
Used in: Fields
Supported options: None
Note: this feature uses API calls. Keep an eye on your daily usage. One call per submits.
Both must be used together. _lud is a date/time field and _lub is a connection to an account. When this pair of fields are included in a table that has Inline Editing enabled, each time the user modifies any cell, an API call will automatically update these two values with the current date/time and the logged-in account.
_loh
Log Out Here
Used in: Views
Supported options: none.
When used in any view of a given page, the user will be redirected to that page upon clicking the Log Out link.
Note: This is an app-wide keyword, meaning that it is not related to the view in which it is placed, but to the whole app. Also, only one instance can be used per application. Any view will do. A typical example would be your Home page, or a “Thank you, see you soon” page.
Video tutorial: none.
_nbo=edit, copy, delete, action
No Bulk Operations
Used in: Views
Supported options: ktlRoles
Disables the bulk operations for this view. Applies to Grid and Search views.
Refer to this section about Bulk Operations:
https://github.com/cortexrd/Knack-Toolkit-Library/wiki/Features-Overview#bulk-operations
Parameters:
Can be any combination of these:
- edit
- copy
- delete
- action
No parameter means all.
Video tutorial: none
_mc=colHeader
Match Color
Used in: Views
Supported options: ktlRoles
Will colorize the whole row’ background color of a grid or search view by matching the cell’s color at the specified column. The parameter can be the header’s title or the field ID. Also works with action links columns.
Can be used in conjunction with the _qt feature to use its colors.
_nf=field_x, field_y, field_z
No Filtering
Used in: Views and Fields
Supported options: ktlRoles
Will prevent filtering on these fields, even if they are visible in the view.
If used in fields, the filtering will be disabled for that field in all views.
Supported view types are grids and lists.
_ni=colHeader1, colHeader2
No Inline editing
Used in: Views
Supported options: ktlRoles
Disables inline editing on columns with specified headers. If no parameter is supplied, it will apply to the whole table. Disables inline editing for the user, even if enabled in the Builder. Enabling inline editing in grids or search views is not always desirable at the user interface. This provides a solution.
Notes:
- It is possible to allow inline editing for a specific field by adding an exclamation mark as the first character. Ex:
_ni=!Phone Number, !Addresswill disable inline editing for the whole grid, except for the columns with headers Phone Number and Address. - About _ni security: use this keyword with caution as it only disables the user interface. Someone with coding skills and bad intentions could still modify the data using commands in the console.
_notes
Invisible Development Notes
Used in: Views
Supported options: None
Allows entering development notes or instructions in a view's title or description. Similar to the Description text box in a field.
Video tutorial: none
_nsg
No Sorting on Grid
Used in: Views
Supported options: ktlRoles
Add this to a grid view to disable sorting. Done by disabling mouse click on the grid’s header by adding the class ktlSortDisabled.
Video Tutorial: none
_nswd
No Spinner WatchDog
Used in: Views
Supported options: None
Disables the spinner watchdog that causes a page reload after a timeout of 60 seconds waiting. Only one instance of this keyword in any view is required per page. Applies to all views.
Video tutorial: none
_num
Numeric only
Used in: Fields
Supported options: None
Enforces numeric characters only, including dot and minus sign. This will prevent entering any other characters even if the field type is short text. Validation is done in real time with enforceNumeric.
Video tutorial: same as _int
_obf=field1, field2
Obfuscate text
Used in: Views and Fields
Supported options: Multiple Instances, ktlRoles
Supported by Grids and Details view types.
Will turn any data in fields to asterisks '*************' to mask sensitive information. Useful when sharing screen captures. Also work with live sessions by hiding the real data until all is obfuscated.
Parameters:
- When used in a view, if none is provided, will obfuscate all fields
- When used in a view, if some are provided, will obfuscate these specified fields
- When used in a field, all views with this field will see it obfuscated
- Parameters are not supported when used in a field
Video tutorial: none
_oln=url
Open Links in a New page
Used in: Views
Supported options: ktlRoles, ktlTarget
To redirect your browser to another URL, in a new tab.
Can be used in a Grid, Search, Details and Rich Text views.
When used in a Grid, Search, Details
The parameter is optional.
If no parameter is supplied, the keyword will be applied to the current view only, for all fields that are links, excluding action links.
If using the ktlTarget option, then the only supported parameter is page, the keyword will be applied to all views in the page.
Example:
_oln=ktlTarget, page
When used in a Rich Text view
After any text you intend to keep visible, add the keyword _oln= as plain text, followed by a link to the website and a descriptive text (or same URL).
Example:
_oln=Support
When clicked on the Support top menu, a new tab will be opened to the Cortex R&D Inc. website.
Video tutorial: none
Demo: https://ctrnd.knack.com/ktl-tutorials (click on the Support menu)
_ols=url
Open Links in the Same page
Used in: Views (Rich Text only)
Supported options: None
To redirect your browser to another URL, on the same page. In the rich text, add the keyword _ols= as plain text, followed by a link to the website and a descriptive text (or same URL).
Video tutorial: none
_parent=nLevelsUp, buttonLabel
Go to nth Parent after submit
Used in: Views
Supported options: ktlRoles
Can be used in Form and Menu views. Provides a quick method of navigating up the ancestor pages.
Note!! This is not the same as going back in navigation history.
The code parses the URL and trims out the portions containing record IDs to go upwards. This is mostly when you want to hide the crumb trails or save a few clicks to the users.
The first parameter is optional and is the number of parent levels to go up and valid values are from 1 to 10. If none are supplied, then 1 is the default value.
Used in a Form
Useful when a series of cascaded Add Record forms will bring the user deep into nested child pages. This is also known as the “Wizard” interface, asking simple questions in a sequence of minimalistic forms.
In such cases, the existing Submit Rules do not allow jumping straight to the top ancestor page once in the last child page. The Go to the parent page option is limited to the immediate parent and Redirect to an existing page won't let you choose that upper nth parent because the Builder doesn’t know the record ID at build time.
After a successful Submit, it will navigate up the current URL through parent pages. The number of levels is determined by the nLevelsUp parameter. The second parameter buttonLabel is ignored in a Form view.
Used in a Menu
In a menu, adding this keyword will create a button that will jump up directly as specified by nLevelsUp. The button text will be buttonLabel, and will be appended as the last button if other exist in the menu. If no buttonLabel is provided, then the default is Go Back.
Using a menu with _parent can be useful when you need to hide the crumb trails, and you’re navigating deeper and deeper in a succession of Grid+Details+Details+Form+(…) then you want to jump right back at the top page, for example.
Video tutorial: none
_qt=bgColorTrue,bgColorFalse
Quick Toggle
Used in: Views and Fields
Supported options: ktlRoles
Quick Toggle of boolean fields in a grid or search view. Will queue all clicks on cells with a Yes/No type of fields and will invert their state in a background processing loop.
The view must have Inline Editing enabled to handle the clicks. If not enabled, the _qt specified colors will still be applied, but the clicks will be ignored.
Parameters:
Optional true/false/pending colors can be specified, compatible with all web formats like #rrggbbaa, #rgba and named colors (ex: darkolivegreen).
The colors are applied in order of precedence, per field, per view or app-wide, respectively and as desired.
It is possible to make the operation more silent with these app-wide flags in the quickToggleParams object:
showSpinner: can set to false to hide the spinner.
showNotification: can set to false to hide the popup progress message.
To override the app-wide default colors and behavior, see quickToggleParams for details in the KTL_Defaults.js file.
_rc=colHeader1, colHeader2
Remove Columns
Used in: Views
Supported options: Multiple instances, Parameter Groups, ktlRoles, ktlCond
To delete de columns based on the header’s exact text. This will delete them from the table and the DOM. Like _hc, removing a column will maintain API calls capability and allow filtering on its field.
This option is “somewhat” a bit more secure than _hc since it’s not as easy to peek at data from the browser’s console. Though someone could intercept the data before it’s been removed, i.e. while it’s being sent by the server, so keep this in mind.
_rcm=delayToRemove
Remove Confirmation Message
Used in: Views
Supported options: None
Used in Add or Edit Form views to automatically suppress the confirmation message that is shown after a submit has successfully completed. Optionally, a delay can be provided to leave enough time to read the message before the suppression occurs.
Note: Any error or neutral message types won’t be suppressed.
Parameters:
The only parameter is the delay in milliseconds to wait before suppressing the message. Range is zero to 3600000 (1 hour).
This parameter is optional and if not provided, will be zero.
Zero means instant suppression of the message, i.e. never visible.
Video tutorial: none
_rdclk=srcColumn, dstColumn
Redirect Click
Used in: Views
Supported options: Parameter Groups, ktlRoles
This can be used in grid and search views to redirect a cell click from one column to another. This is particularly useful when Knack doesn’t provide the option to display both the field data and the associated link. Often, you can display either the field data or the link, but not both simultaneously. This feature resolves that issue.
Typically, you will want to hide the destination column using _hc, as only the source column is necessary for displaying its cell data. The destination cell contains a link to a page where you can edit the data, or perform any other desired action.
About the source column:
Typically, the source column will contain simple passive text data. In this case, the keyword automatically adds an anchor, making it behave as a clickable simulated link when hovered. If the column already contains a link to a page or other destination (which would defeat the purpose), it will be ignored but will still jump to the destination link as expected.
Parameters:
The parameters must be provided in groups of pairs: source and destination column labels. Multiple groups are supported, but only a single keyword instance.
Video tutorial: none
_recid=recIdField
Auto-Populate Record IDs
Used in: Views
Supported options: ktlRoles
Note: this feature uses API calls. Keep an eye on your daily usage.
When used in a grid view, it will fetch each row’s record ID and use an API call to set its value in a background task. This is useful for external connectivity via WebHooks for example.
Add a Short Text field to any table and label it Record ID. If you prefer another label, you can use the parameter to specify its value. The default label doesn’t require any parameter.
As soon as an empty Record ID field is detected in the grid, it will be populated automatically.
Note: the grid must have Inline editing enabled as well as the Record ID field in that grid.
Existing Records
You can use this to “retro-populate” existing records in large numbers by creating a filter that only displays records having an empty Record ID field. After the grid’s page is fully populated, the code will automatically trigger a refresh of that grid. This enables a continuous processing chain of empty IDs until all records are updated.
New Records
For new records, add a grid with the _recid keyword in the same page as the Add Form. Each time a new record is added, its record ID will be updated automatically. Ensure that new records will be visible in the grid, otherwise they will be missed. This is usually done by setting the sort order appropriately, using Auto Increment from high to low or a Date/Time with most recent at top.
Remember that this grid can be hidden using the _hv keyword if it only serves as a background utility.
The Record ID field may also be hidden using the _hf keyword. And may be combined with ktlRoles to be visible only to the Developer role.
The grid only needs to contain a single field: the Record ID field.
Video tutorial: none
_req=field1, field2…
Required Fields
Used in: Views and Fields
Supported options: Multiple Instances, ktlRoles, ktlCond
This is used in form views to set the fields to be required dynamically, based on specific conditions.
The global flag Form Pre Validation (formPreValidation) must be enabled for this feature to work.
Applicable field types include:
- All text-based inputs
- Single and Multiple Selection dropdowns
- Date/Time
- Signature
On the specified fields, the required value will be enforced by applying a pink background color to each field where the value is empty, and also by disabling the form’s Submit button when at least one field is empty.
The ktlCond option supports Details views.
Example:
_req=[Regular Price, Sale Price, Item Desc], [ktlRoles, Sales Clerk], [ktlCond, gt, 0, Quantity, Inventory]
Will prevent submitting when one of the 3 fields is empty, but only if the user roles include Sales Clerk and the value in the field Quantity of details view Inventory is greater than zero.
Video tutorial: none
_rlv=field1, field2…
Reload Last Values
Used in: Views
Supported options: None
Used in Add or Edit Form views to minimize redundant data entry, thus saving time and reducing errors. This is achieved by reloading the last form data submitted for each specified field.
Parameters:
Will reload the last values for each field specified in the list.
When used without parameters, all fields will be reloaded.
Note that this keyword leverages the existing feature persistentForm, so it must also be enabled using the ktl.core.setCfg function.
Video tutorial: none
_ro=field, option1, option2…
Remove Options
Used in: Views
Supported options: Multiple Instances, ktlRoles, ktlCond
This is used in form views to limit the choices available to a user by excluding specified options for a given field.
Applicable field types include:
- Multiple Choices
- Booleans (such as Checkboxes, Radio Buttons, and Yes/No selections)
- Single and Multiple Selection dropdowns with fewer than 500 entries.
To the specified field, it will remove the listed options.
Example:
_ro=Sale, 50%, 75%
Will modify the Sales field by removing the 50% and 75% options, leaving others like 15% and 25% still available.
Video tutorial: none
_rv
Remove View
Used in: Views
Supported options: Multiple Instances, ktlRoles, ktlCond
Removes the view from the screen but also from the DOM. Used to save real estate. Note that it won’t be possible to access the HTML elements of this view when using this keyword. This may affect other keywords so it’s important to take this into account.
Video tutorial: see _hv
_rvd=confirmationView, view1, view2…
Refresh Views after a calendar's event Drag’n Drop
Used in: Views
Supported options: ktlRoles
Note: this feature uses API calls. Keep an eye on your daily usage.
Used in a Calendar view to confirm that a drag’n drop operation has completed successfully after an event has been moved or resized. Once confirmed, the specified views in parameters will be refreshed to reflect the change.
Parameters:
- The first parameter is a List view’s ID or title of same object as the calendar, with the events’ date/time field, that must be added in the same page as the Calendar view. It should have the _hv keyword since it’s a utility view that displays no useful information to the user. It only serves to perform a GET API call on it.
- The following parameters are a list of views by ID or Title that should be refreshed after the event change has been validated.
Setup Instructions:
- Add the calendar view and select the desired Data Source and Date Field
- Add a List view with the same Data Source as the calendar and include only one field, the same as the Date Field of the calendar. Set Use a limited number records to 1 record only. Note that this record will never show anything meaningful, just the first record that happens to be there, and it will never change. The sole purpose of this view is to allow an API call in the background.
- Set all parameters for the List view to defaults, display 10 records, disable Search and Filtering. Set title to something like DnD Confirmation - or other, as desired. Add the _hv keyword to hide it since it’s only a utility view.
- Add any additional views that are to be refreshed when the DnD operation has succeeded. Be sure that those views have the same Date Field included to see the changes.
- Add the keyword: _rvd=DnD Confirmation, view1, view2, … Where the view1 and following are those to be refreshed when the DnD operation has succeeded.
- You can see a green confirmation log in the console for each event change.
_rvr=view1, view2…
Refresh Views after a Refresh
Used in: Views
Supported options: ktlRoles
Same syntax as _rvs. Used to trigger a refresh to other views. Care must be taken to avoid infinite circular loops: A>B>C>A>B>C…
_rvs=view1, view2…
Refresh Views after a Submit
Used in: Views
Supported options: ktlRoles
Add this to a form’s title and when it is submitted successfully, will refresh any other views specified. Use the exact full title text, separated by commas, spaces are allowed.
Example:
_rvs=Client Sales, Store Sales
Here, the form’s visible title will be “Customer Sales”, and when submitted successfully, the two views with the title “Client Sales” and “Store Sales” will be refreshed.
_sa
Add "Select All" Option in Dropdowns
Used in: Fields
The keyword adds a "Select All" option to form dropdown fields. This feature lets users quickly select or clear all options in a dropdown field.
_scs=style
Sorted Column Style
Used in: Views
Supported options: Multiple Instances, ktlRoles
When added to a Grid or Search view, will apply the desired style to the sorted column. The style parameter syntax is exactly as in a CSS attribute.
Example:
_scs=background-color: burlywood; color: #8f1c1c; font-weight: 700;
Video tutorial: none
_scv=[duration, color, style, mode, flashRate]
Show Changed Values
Used in: Views
Supported options: ktlRoles
The _scv keyword provides a visual indication of changed values in grid or search views, making it easier for users to identify and track changes over time.
When added to a grid or search view, it will highlight the changed values for a given amount of time. Typically, this is used in conjunction with the auto refresh keyword (_ar).
Parameters:
duration: A numeric value in seconds that will define the duration of the highlight. A value of zero will reset the highlight at the next view render. Values higher than zero can maintain the highlight across subsequent renders. Default: 5 seconds. Max is one hour: 3600.
color: The color of the highlight. Can be any web-compatible color naming.
style: The accepted styles are border and fill.
mode: The accepted modes are flash or fade. Omitting this value will give a steady highlight.
flashRate: If the mode is flash, this value will determine the flash rate, in cycles per second. Lower values will flash faster. Default: 1.
Examples:
_scv=[60, green, fill]
Will highlight the cell with a solid green color for one minute. If the view has an auto-refresh every 10 seconds, the highlight will persist and not be interrupted.
_scv=[0, #ff0000, border, fade, 0.5]
Will highlight the cell with a red border color with a smooth fade-in fade-out twice per second, and last until the next view refresh.
Video tutorial: none
_sddt=minNumChars, delay
Searchable DropDown Thresholds
Used in: Fields
Supported options: None
When added to a connected field, this keyword will fix the issue where some characters disappear while typing in the search input of the dropdown, rendering the usage of this object quite frustrating.
Note that this issue will manifest itself only when…
- the number of entries are greater than 500.
- you’re typing at a medium-slow speed.
- you’re typing more than 2 characters.
To address this issue, you need to provide two parameters.
Parameters:
minNumChars: the minimum number of characters that need to be typed-in before the search is triggered.
delay: a delay in milliseconds, that must elapse after the last character typed, before the search is triggered.
Both must be supplied and there are no default values. These are set internally by the dropdown object.
The fix will be applied to the field across all views.
Video tutorial: none
_stc=numOfColumns, bgColor
Sticky Table Columns
Used in: Views
Supported Options: None
When used in a grid it will stick the first n columns. It can take up to 2 parameters _stc=numOfColumns, background-color or you can just add _stc and the default parameters of numOfColumns = 1 or 2 if bulk edit is applied and background-color = 'rgb(243 246 249)'. The background-color is needed for grids as cells are transparent, it stops the text from showing under the stuck columns.
Examples:
_stc=, aliceblue // will stick the first column and apply the background color of aliceblue
_stc=3, // will stick the first 3 columns and apply the default background-color
Video tutorial: none
_sth=numOfRecords, viewHeight
Sticky Table Header
Used in: Views
Supported Options: None
When used in a grid it will add a height to the grid and stick the header while the records scroll. It can take up to 2 parameters _sth=numOfRecords, viewHeight or you can just add _sth and the default parameters of numOfRecords = 10 and viewHeight = 800px. The number of records is the minimum number of records the table needs to have before the sticky header is applied. This stops the rows stretching to fill the height of the view i.e. If the grid has nine records the header will not stick.
Examples:
_sth=, 1000 // will stick the header if grid has more than 10 records and add a height of 1000px
_sth=3, 300 // will stick the header if grid has more than 3 records and add a height of 300px
Video tutorial: none
_style
Apply Style to an element
Used in: Views
Supported options: Multiple instances, Parameter Groups, ktlRoles, ktlTarget
To add a style to a view, page or a jQuery selector. This will merge your new style to any existing style. Can be used with the ktlTarget option.
The parameter’s style syntax is exactly as typically viewed in style tab of the console’s view, when looking at the HTML element.
Example:
_style=[min-width:250px],[ktlTarget, $('.kn-button')]
Will set all Knack buttons in the page (those having class kn-button) to have a minimum width of 250px.
Video tutorial: none
_trk
Truncate Cell Text
Used in: Views
Supported options: ktlRoles
When used with a grid, any “long” cell text will be truncated and ended with an ellipse, to indicate more can be seen upon inline editing. The width of text will match that of the column’s custom settings in the Builder. The units must be in pixels, percentage is not supported.
Video tutorial: none
_ts=[prefix, prefixString], [format, formatString]
Timestamp
Adds a timestamp to the view header that indicates its last render.
Used in: Views
Supported options: Parameter Groups, ktlRoles
Parameters:
The parameters for this keyword are optional, and there is no specific order required.
Group 1:
Prefix: Add a group containing the “prefix” parameter. The text that follows this parameter will be prepended to the timestamp. This serves as passive text to describe the purpose of the timestamp to the user.
Group 2:
Format: Add a group that contains “format” parameter. The text that follows specifies the desired format of the date and time.
It supports the following case sensitive placeholders:
YYYY: Four-digit year (e.g., 2024)
MM: Two-digit month (e.g., 01, 02, ..., 12)
MMM: Short month name (e.g., Jan, Feb, ..., Dec)
DD: Two-digit day of the month (e.g., 01, 02, ..., 31)
HH: Two-digit hour in 24-hour format (e.g., 00, 01, ..., 23)
hh: Two-digit hour in 12-hour format (e.g., 01, 02, ..., 12)
mm: Two-digit minutes (e.g., 00, 01, ..., 59)
ss: Two-digit seconds (e.g., 00, 01, ..., 59)
SSS: Three-digit milliseconds (e.g., 000, 001, ..., 999)
A: AM/PM indicator (e.g., AM, PM)
The default is HH:mm:ss
Examples:
_ts
Will show: 16:20:45
_ts=[format, MMM DD, YYYY hh:mm:ss A]
Will show: Jun 30, 2024 4:20:45 PM
_ts=[format, YYYY-MM-DD HH:mm:ss.SSS]
Will show: 2024-06-30 16:20:45.123
_ts=[format, YYYY-MM-DD HH:mm:ss]
Will show: 2024-06-30 20:20:45
_ts=[format, MM/DD/YYYY HH:mm]
Will show: 06/30/2024 16:20
_ttip=parameters depend on context
Tooltip
Used in: Views and Fields
Supported options: Multiple instances, Parameter Groups, ktlRoles
Used to provide additional information on the field being hovered over by the mouse.
Tooltips can be added to…
- Fields: In such case, it will be applied across the board, in all views.
- Views: for more localized instances, overriding the field’s text. The supported view types are the grids, details, lists and forms.
- Action Links: to explain the intention and outcome of a click.
For each tooltip added, a question mark icon will show up on the associated label or header, and when the mouse hovers over the icon, the tooltip’s text will appear.
Parameters:
This keyword’s parameters must always come in pairs of groups and will depend on whether it is used in a field or in a view.
Used in a Field:
Group 1:
Tooltip Text: The helpful hint that will show upon hover.
Group 2:
View Types: Contains any combination of the following letters that define in which view types it will take effect:
- t = grid/table
- d = details
- f = form
- l = list
Examples:
_ttip=[This will add a Details & Form Tooltip], [df]
Will show the tooltip only when the field is used in a details or a form view.
_ttip=[This is a Form Tooltip], [f], [This is a Details and a Grid Tooltip], [dt]
Will show the first tooltip in a form, and the second one in a grid.
_ttip=[This Tooltip will be added to all 4 view types], [tdfl]
Will show the tooltip in grid, details, forms, and list views.
Used in a View:
Group 1:
Tooltip Text: The helpful hint that will show upon hover.
Group 2:
Label/Header: Defines which label or header it will apply to.
Example:
_ttip=[Click here to send an email to the store owner], [Email]
Will show the tooltip when used in a grid, list or details view with an action link that has the Email header or label.
To change the default tooltip icon:
The default icon is 'fa-question-circle'. But it can be any other icon you want from the Font Awesome library (must be from same version as Knack’s). The easiest way to select a new icon is to go to the Builder in a page where you can add an icon and find one that you like from the list. Hover over it and note its name. Ex: shopping-cart. Add the prefix fa- and it becomes fa-shopping-cart.
This will be the second parameter of the second group.
Examples:
_ttip=[View all purchases], [t, fa-shopping-cart]
Used in a field, will show the tooltip in a grid.
_ttip=[Phone number in View], [Phone, fa-phone-square]
Used in a view, will show the tooltip in a grid, list or details view with the Phone header or label.
Tooltip styling:
The icon color and the tooltip background-color and color can be edited by adding the tooltipStyles config from the defaults file into the core cfg area.
_uc
UpperCase
Used in: Fields
Supported options: None
To convert text to uppercase in real-time
_uvc=fldName1, fldName2
Unique Value Check
Used in: Views and Fields (in tandem)
Supported options: None
Used when it is not possible to use the Builder’s Must be unique option due to the nature of the field. This is the case for Connected and Text Formula fields. This feature requires additional setup in the field’s description and a dedicated hidden Search view.
Setup Instructions:
See the Advanced Keywords Setup page: _uvc - Unique Value Check.
_uvx=str1, str2
Unique Values Exceptions
Used in: Views and Fields (in tandem)
Supported options: None
Used when we need unique values, but with a few specific exceptions.
Setup Instructions:
See the Advanced Keywords Setup page: _uvx - Unique Values Exceptions.
_vk
Enable Virtual Keyboard
Used in: Views
Supported options: None
When used in a view (any type), will force the virtual keyboard to show up when an input field gains focus.
Normally, the virtual keyboard is only enabled when running under Linux and is typically used in embedded platforms like the Raspberry PI along with a touch screen, where there’s no keyboard in kiosk mode.
Video tutorial: none
_vrd=referenceField, searchView
View Record Details
Used in: Views
Supported options: ktlRoles
Used to quickly see a Grid or Search view’s record details, upon clicking on its row. This will instantly show the record’s details without having to navigate back and forth between two pages.
Setup Instructions:
See the Advanced Keywords Setup page: _vrd - View Record Details.
Video tutorial: none
Demo: https://ctrnd.knack.com/ktl-tutorials#ktl-demo-page/view-records-details-vrd/
_vrh=[headerLabel, fa-icon], [filters, roles], [align, mode]
View Record History
Used in: Views
Supported options: ktlRoles
The _vrh keyword can be used with grid or search views and provides an easy way to track and view the history of changes made to individual records within the view, in a modal popup. It allows users to quickly access the record history and see the “before and after” values of modified fields.
It will automatically add a new column at the far-right of the view, with a header labeled "History" and a clickable icon on each row. Both the header text and the icon can be customized.
Clicking on the icon will open a modal popup with a pre-filtered grid showing all the record histories related to the clicked record.
For each changed field, the "Before: …" value will be shown, followed by the "After: …" value on the next line.
Notes:
Only changes made manually in forms and inline editing will be tracked by the record history feature. All changes done by record rules will not be captured.
Parameters:
All groups are optional, and their order is not strict.
Group 1:
Header Label (optional): Specifies the header label that is added by the KTL as the last column. Default: History.
fa-icon (optional): Specifies the font-awesome icon to use. Format must be fa-iconname. Default is fa-history.
Group 2:
filters (optional): Specifies which account roles can see the filtering controls (Add filters button). Default: all.
Group 3:
align (optional): To modify the alignment of both the header and the icon in the added column. Accepted values are left, center and right. Default: left.
Example:
_vrh=[Hist, fa-clock-o], [filters, Developer, Administrator], [align, center]
Will enable viewing record histories in this view, and add an extra column at right with header Hist and a clock icon, both centered. Only developers and administrators will have the filter visible and enabled.
Setup Instructions:
See the Advanced Keywords Setup page: _vrh - View Record History.
Video tutorial: none
_yourOwnKeywords
Used in: Your implementation
Supported options: Your implementation
You can also add your own app-specific keywords and process them in the callback function processViewKeywords.
Video tutorial: none
_zoom=zoomValue, options
Apply Zoom to an element
Used in: Views
Supported options: ktlRoles, ktlTarget
Applies a zoom value in percentage to a specified element.
The options are:
- None (leave empty): for the view where the keyword is placed
- page: to apply to whole page
- sel,selectorString: to apply to a specific valid jQuery selector
Example:
_zoom=120,sel,.myClass
Will zoom in at 120% all elements having the class myClass.
Video tutorial: none
Advanced Keywords Setup
Some keywords require additional setup, and this section provides the step-by-step procedure that applies to each.
_arh - Add Record History
To use the Add Record History Feature, follow this procedure:
Create the table to store all records history
Note: you can follow the step-by-step instructions below, but you can also import the following template file to create the table and all its fields: Record History.csv
This will save some time and reduce the chances of typographic errors. Then you can go through the steps to address the few remaining modifications to do.
- Create a table named Record History
- Rename the first short text field to Context
- Add an Auto Increment field, leave default name
- Add a Text Formula field named Log ID: HIST_{Auto Increment}. Make this field the table’s Display Field. Note that you can choose your own prefix as this is not strict.
- Add a Date/Time field, default name, chose your preferred formats, set to current date and time.
- Add a Multiple Choices field named Status, custom sort, radio buttons, with these entries:
- Added
- Updated
- Expired
- Archived
- Deleted
- Add a Short Text named Object Name
- Add a Short Text named Identifier
- Add a Paragraph Text named Changes
- Create a connection to Accounts named Logged By
- Add a Short Text named View ID
- Add a Short Text named Record ID
- Add a Link named App URL with format: Use the same text for all links and Link Text: Open App URL. Open in new window = yes
- Add a Link named Builder URL. Open in new window = yes
- Add a Link named History URL with format: Use the same text for all links and Link Text: Open History URL. Open in new window = yes
- Add a Date/Time named Expiry, with preferred format and default date and time to None.
Creating the Add Record History Form
Note: this feature uses API calls. Keep an eye on your daily usage. One call per submits.
- Create a new login page
- Give permission to all users
- Name it Add Record History
- Add a form view that adds a new record history, connected to the logged-in account
- Remove all fields and add these: Status, Object Name, Identifier, Changes, Context, View ID, Record ID, App URL, Builder URL, History URL and Expiry.
- No need to arrange the layout nicely since no one will ever see it, being solely used in the background by API calls.
- Create an Invisible Menu, where you can assign various utility views like this one. Follow the procedure as described in the Advanced Features page, in the “Creating an Invisible Menu” section (only): https://github.com/cortexrd/Knack-Toolkit-Library/wiki/Advanced-Features#creating-an-invisible-menu
- Select the Invisible Menu and assign it the Add Record History page.
The rest will be automated by the KTL.
Activating the feature per view
In all views where you want to save record change activity, add the _arh keyword in the title or description.
Add/edit forms are supported, as well as grid and search views with inline editing enabled.
Note: this feature uses API calls. Keep an eye on your daily usage. One call per submits.
To view the records’ history, you need to set-up the _vrh keyword.
_afs/g - Auto-Fill and Submit / Generate QR
This feature is actually two-fold:
- Creating the QR codes, from an admin page
- Scanning QR codes, from a public page without login
Each QR code contains:
- The landing URL
- View and Field data
- Automation instructions
Creating the QR Codes: _afsg
You will add this keyword to an Add Record Form view.
Note: Even though Edit forms will also work, they wouldn’t have much value in real life applications since they would overwrite the same QR code each time, making them ephemeral. Unless that’s what your use case, of course.
Add the fields you need to be processed at the destination page.
Supported field types:
- Short text
- Numbers
- Connected fields, single selection
In the table that is the data source of the Add form, you must create a field named “QR Code URL” of type Link. This field will contain the endpoint URL with all the parameters, that will be used to generate the QR Code. By design, this field will appear as disabled in the form, so it’s normal and expected.
Parameters:
This keyword requires multiple parameter groups, like this:
_afsg=[landingPageUrl, addFormView, qrCodeSize], [qr, field1, field2,...], [auto, submit, close, closeDelay], [disable, field1, field2,...]
Description of each group:
Group 1:
- URL: The landing page, where the Add Record Form is located. Must end with a forward slash “/”.
- Add Form: Add Record Form view in the landing page, by title or ID.
- QR Code Size: in pixels. Default is 200.
Group 2: (optional)
- qr: means “Use the QR Code’s embedded data to auto-populate the following fields: …”
- field 1, field2, … : A list of all fields to be populated, by label or ID. See Supported field types above.
Group 3: (optional)
- auto: to enable process automation.
- submit: optional, will submit without user intervention.
- close: optional, will close the page without user intervention.
- close delay (in seconds): optional, defines how many seconds to wait before auto-closing. If no delay is provided, will close instantly. If Submit is included it will close after the operation has succeeded.
Group 4: (optional)
- disable: will disable all fields specified. This is useful to display information to the user but as read-only.
- field 1, field 2, … : the list of fields to be disabled and grayed-out.
Note: for the optional groups 2, 3 and 4, their order is not strict.
Real-time QR Code update:
When you refresh the page with the Add form view, you will see a QR Code that has already been generated. If you have input fields, you will notice that the QR Code is updated in real-time, as you type text or when you select an entry from a dropdown selector.
Scan and Process the QR Codes: _afs
Add this keyword to an Add Record Form to automate the filling of specified fields, submit and close the page.
Note: this feature will not work with Edit Forms.
Parameters: None
The behavior is defined by its companion, the _afsg keyword above.
Upon scanning the QR code:
- Will open the Landing Page, with the Add Record Form.
- Auto-populate fields, based on the information “baked” inside the QR Code.
- Disable specified fields to prevent overwriting by user.
- Apply automated actions: Submits and/or Close (close with optional delay).
This streamlined approach optimizes form submission efficiency by automating entry and processing through QR code technology.
Note about the URL and the Tables:
The source and destination tables don’t need to be the same. As long as the fields’ labels and types are matching for short text and number fields, it will work. For connected fields, it is a bit more complicated since you need to know the foreign record ID somehow, typically using manual lookup, then copy/pasting the value to a short text field and adding the square brackets like this: [“65c8e0d31d464e00288e2cd7”]
About the URL, it can be just about anything, not limited to the same app. This means that you can even point a completely different app in another account.
_uvc - Unique Value Check
- In the field of interest, add the _uvc keyword in its description.
- Create an Add form containing the _uvc field, and add in the title or description: _uvc=fieldName1, fieldName2, fieldName3
- In this example, the field is a Formula Text that concatenates three fields together. The number of fields is not important, but all must match, i.e. both what is displayed and the real field name in the schema.
- Those fields must all be in that same form.
- Add a Search view that has the same source and the _uvc field as the search input.
- The search input must have “Users can choose from different filter options” unchecked and Exact Match selected.
- Result in a grid, one column with _uvc field.
- Add _uvc and _hv to the view title or description.
- Adding duplicate values should prevent submitting and show an error message.
_uvx - Unique Values Exceptions
- In the field of interest, add the _uvx keyword in its description with this format:
_uvx=excText1, excText2
In this example, there will be two expressions that will be accepted as duplicates for that field.
- Add a Search view that has the same source and the _uvx field as the search input.
- The search input must have “Users can choose from different filter options” unchecked and Exact Match selected.
- Result in a grid, one column with _uvx field.
- Add _uvx and _hv to the view title or description.
- Adding duplicate values should prevent submitting and show an error message, unless they are among the exceptions allowed.
Additional notes about _uvc and _uvx:
The _uvx feature can combine more than one field in the same Add form, as long as all fields are also included in the Search view.
Furthermore, the _uvc and _uvx are inter-compatible, i.e. they can be used together in the same Search view. In that case both the _uvc and _uvx keywords must be included in its title or description.
_vrd - View Record Details
- This keyword is driven by a Grid or a Search view. For short, we will refer to that view as the “Grid”.
- Add a Grid view to your page that displays the records you want.
- Add a few fields and chose one of them that will be designated as the Reference Field. It’s a field that would be the best candidate to be searched in a Search view and give only the intended result. Ideally, it would be the Display Field of this table’s source, but any other field should work. As long as it would find only one result, or less than 10. Best results are achieved when choosing a field having unique values.
- Add a Search view near your grid that has the same data source as the Grid.
- The search field must be the Reference Field chosen above. Advanced Filters: on, Default operator: is (leave value blank).
- Settings: Display results in a list. Add the fields you want to see. Set the layout to your liking.
- In the Grid view add the keyword:
_vrd=referenceField, searchView. This tells the Grid view which Search view to use. Both parameters may be used by label/title or by field/view ID. - The Search field and operators are automatically hidden, mimicking the appearance of a Details view.
- Typically, you may want to position the Search view at the right for the Grid view, to conveniently display details of the row clicked in the grid. And keep the Grid’s record low otherwise, the details (Search view) may become out of scope, forcing the user to scroll up and down repeatedly.
- Note that if the results contain multiple records, the record ID will be used to filter out unwanted records by removing them from the DOM, leaving only the one of interest. This can happen if the reference field value is not unique, like a person’s name.
_vrh - View Record History
In this section, we will create a generic page that will be re-used automatically every places you set-up the _vrh keyword in a grid or search view. This page will be the modal popup that displays the histories.
This page can also be used as a standalone page by administrators to browse through all records. In this case, it will not be modal.
To create the Record History viewer, follow this procedure:
- Create a login page, give permission to all users.
- Set name and title to: View Record History.
- Add a grid view: select all Record Histories as data source, sort order by Auto Increment, high to low.
- Add all fields in the same order as the table.
- Settings: Search=on, Filtering=on, 25 records (user can change)
- You can set the page to be visible in menus if you want, but it’s not required.
- Do not set the page as modal. The KTL handles this automatically.
Note:
Feel free to create your own additional version of the Record History browser page. It may have different columns and roles access, depending on your needs. Just ensure that the original version above, dedicated primarily to record-specific browsing, remains unchanged.
Need more keywords?
If you would like to propose new keywords or options, please use the Discussion page here: https://github.com/cortexrd/Knack-Toolkit-Library/discussions
Click on “New discussion“ (green button) and select “Ideas”.
Explain how you would see the ideal implementation and tell us a bit about your use cases.
KTL Built-in Classes
The KTL offers several classes that can be used both with the keywords and any way you like in your apps.
Here’s the list:
ktlBlurry
Will create a simulated blurry effect, using a combination of transparency and shadow effects. Can be used to obliterate text.
ktlBottomExtraSpaces
Will a margin of 500px at the bottom of an element. Typically used to allow scrolling down further more on touch devices, while using a virtual keyboard that would otherwise block access to the fields of interest.
ktlCollapse
Will hide an element by setting its visibility property to collapse.
The visibility: collapse property is specifically designed for table rows and columns. It hides the row or column, but unlike display: none, it preserves the space that the row or column would have taken up. If used on non-table elements, it behaves like visibility: hidden.
ktlDenseGrid
When used in a grid view, will force text padding to 1px for top-bottom and 2px for left-right. Used when high-density grids are needed.
ktlDisplayNone
Will hide an element by setting its display property to none.
This approach completely removes the element from the document flow. The element is not rendered at all, meaning it takes up no space, is not visible, and cannot be interacted with by Javascript (in terms of events). This is a common method for hiding elements that you might want to show later via Javascript.
ktlFlashingFadeInOut
Same as ktlFlashingOnOff above, but with a smooth transition between the two opacities for a softer, more subtle effect.
ktlFlashingOnOff
Will cause an element to flash at a rate specified by value ktlFlashRate. Default rate is 1 second. The flash feature is designed to attract attention, while keeping the data visible at all time. This is done by alternating its opacity between 100% to 30%.
ktlHidden
Will move an element far away from the screen to hide it, by setting position:absolute and left:-9000px.
This method physically moves the element far off-screen. It is still rendered by the browser, meaning it takes up space in the DOM and can be interacted with by screen readers or Javascript.
This method is often used when you want the element to remain accessible to your code or to make API calls on a view, while being visually hidden.
ktlInvisibleScrollBars
Will remove all scroll bars from page but leave scrollable in both directions. Useful to maximize real-estate usage in high-density pages.
ktlLinkDisabled
Will disable mouse clicks on the link and change its color to semi-transparent gray.
ktlNarrowMarginsPage
When applied to the .kn-content class, will reduce page margins and padding to a minimum of 2px to maximize real-estate usage.
To have narrow margins, use this in one view in your page:
_cls=[ktlNarrowMarginsPage], [ktlTarget,page]
ktlNoBgColor
Forces the background color of the element to transparent.
ktlNoInlineEdit
Disables inline editing in a grid, in terms of user interaction. The API calls remain functional.
ktlNotValid
Sets the background color of the element to the typical Knack’s pink for error messages.
ktlOutline
Will create a surrounding box of 2px solid width border, having a color specified by ktlOutlineColor. Default color is green.
ktlOutlineDevPopup
Same as ktlOutline box above, but having hard-coded blue, dashed lines.
ktlRemove
Will delete this element from the page (DOM). Note that this class is not in the KTL.css file. It is directly processed by the _cls keyword.
ktlSingleLineTable
Will force all text to be continuous, disabling wraparounds. Typically used in grid views to maximize vertical density.
ktlSortDisabled
When used in grid views, will disable sorting when clicking on the headers.
ktlVisibilityHidden
Will hide an element by setting its visibility property to hidden.
This method makes the element invisible, but unlike display: none, the element still occupies its space in the layout. The element is not visible, but it can still be interacted with by Javascript. This method is useful when you want to hide something visually but maintain its space in the layout.
Others
There are several other undocumented classes that are mostly used internally by the KTL. But feel free to use them as desired for your app.
The complete list can be found in this file: KTL.css
Console Utilities
These are commands that can be invoked in the browser’s console.
ktlkw(stringToFind)
Used to search and display the ktlKeywords object content.
Parameters:
If no parameter is specified, will show all keywords and their parameters.
If a parameter is specified, it must be a string in quotes. It can be a keyword, a keyword option, a view ID or any other text you need to find.
Examples:
ktlkw() will show everything.
ktlkw(‘_ar’) will show all instances of the auto refresh keyword.
ktlkw(‘ktlCond’) will show all instances of the ktlCond keyword option.
ktlkw(‘view_123’) will show all keywords and parameters in the view_123.
kw2str(depth)
Will display the content and the count of elements found in the ktlKeyword object, based on the depth level is parameter.
Depth can be a value from 1 to 10. 10 being the default when no parameter is supplied.
A value of 1 will only show the views and fields with keywords, but not the keywords themselves.
A value of 2 will show the views, fields and all keywords therein, but not the keywords parameters.
Typically a value of 6 will show everything (same as 10) since the ktlKeywords object is only 6 levels deep.
Note that this function uses the ktl.core.objectToString (obj, depth) function, which can be used to inspect any other object for debugging.
kwcount()
Will display a count by keyword type, in decreasing order, and a grand total at the bottom.
ktlpause()
Will pause all auto-refresh in the page, for all views. The pause checkbox, if displayed, will become checked and its text in red color.
Glossary
Version Info Bar
This is the colored rectangle that is shown at the top-right of your app. It contains the App Name, App version and KTL version. By default, the Version Info Bar is visible when using the KTL, unless you explicitly modify the configuration to remove or hide it. This bar is also a button that can be clicked to open the KTL Develop Tools popup, where several powerful utilities are accessible when you have the Developer role, or have the proper PIN characters. See this page for additional details: https://github.com/cortexrd/Knack-Toolkit-Library/discussions/186