Skip to content

Advanced Features

Jump to bottom
Cortex R&D Inc edited this page Dec 17, 2023 · 17 revisions

Advanced Features

These features are considered "advanced" in the sense that they require some additional setup before they can be used.

They provide or use communication mechanisms between various parts of your app, thus leveraging quite powerful administration features.

iFrameWnd

This hidden utility sub-page has several views that provide background automated tasks: Heartbeat Monitoring, User Preferences, Account Logging, User and Public Filters and Remote SW Updates.

Heartbeat Monitoring

Heartbeat Monitoring allows your app to assess an account's presence and generate alerts or perform remote SW updates.

User Preferences

User Preferences provides an object to store any information about the account. It is in the form of a string representing a JSON object. There are a few already built-in, and you can also add your own.

Account Logging

This will provide comprehensive logging capabilities to your application. All logs are connected to an account, and can collect vast amounts of information related to the following:

  • Login date/time
  • IP address
  • OS type/version
  • Browser type/version
  • APP+KTL versions
  • Navigation history, including URL, searches and filters
  • Typical log types as Critical, App Errors, Server Errors, Warnings, Debug and Information
  • Your own app-specific logs types as well
  • User activity: count of mouse clicks and keypresses

WARNING!!! This feature can use a lot of API calls in some cases. It is your responsibility to perform regular/frequent checks on your API usage. You may decide to disable some logging event to keep them within safe limits.

This is done in the ktl.log.setCfg function for general flags. You can also achieve a finer level of control using the logCategoryAllowed callback to your app, where more specific conditions can be applied.

Remote SW Updates

User Filters

In addition to being able to create named buttons for the User Filters that are saved in localStorage, it is possible with a bit of setup to upload your settings to Knack and download them back wherever and whenever needed. This two-way process is automatically done in the background, and can be seen as a backup method, but also to migrate them to other devices (or browsers, see note below). Note that if you migrate filters from one app to another, typically a temporary development copy, some filters may stop working due to the record IDs that have changed for connected fields. This is a normal behavior, and the only way to fix this is to redo their settings and save back to the same button name.

Public Filters

For those having the Public Filters role, they will be able to create a User Filter, but also to right-click on it and set it as Public. Doing this will upload the filter to the cloud and make it available to all users when they access that page and view. Only those with the Public Filters is role can drag’n drop the filter for re-ordering, rename or delete it.

Pre-requisites

Customization Principles

Before proceeding with the Setup section that follows, it is assumed that the reader is familiar with the principles of KTL Customization found in this page: https://github.com/cortexrd/Knack-Toolkit-Library/wiki/Customizing-Features#customizing-features

Also, it is assumed that your Accounts table still has its default name. If you renamed it, you would need to use the function ktl.iFrameWnd.setCfg to set the variable accountsObjName accordingly.

Naming Conventions

Important!!! Throughout the following sections, whenever we mention the name of a table, a field or a view title, it must be written exactly as shown, case sensitive, spaces, punctuation, everything. It is recommended to copy/paste such text to avoid any typos.

Defaults

If a setup information is omitted, it means that you shall use the default. This applies to both fields and views.

Creating an Invisible Menu

Having an invisible menu may be counterintuitive, but actually it will soon prove to be very useful. It allows hosting any utility pages that the users don't need to see, but still accessible by the developers via its direct URL, and also by the KTL to perform several background tasks.

We will now create a hidden menu that will be your default place for any future utility hidden pages.

  1. Add a new Dropdown Menu named Invisible Menu.
  2. Do not add any page yet, click Continue at bottom.
  3. In settings, uncheck Include this page in the Page Menu.

The iFrameWnd will soon be its first resident.

Creating the iFrameWnd

For a description of what is the iFrameWnd, see this page: https://github.com/cortexrd/Knack-Toolkit-Library/wiki/Features-Overview#iframe-window

  1. Create a new Login Page accessible to all users
  2. Page Name: iFrameWnd
  3. Its URL is automatically set to iframewnd
  4. Assign it to the Invisible Menu above

This page will be the placeholder for the next features. For now, leave it blank and we’ll get back to it later.

To activate this feature, you must set the iFrameWnd flag to true in the ktl.core.setCfg function.

If not done already, take a moment to read that page: https://github.com/cortexrd/Knack-Toolkit-Library/wiki/Customizing-Features#customizing-features

This section contains what you’ll need to do the set-up: https://github.com/cortexrd/Knack-Toolkit-Library/wiki/Customizing-Features#the-ktl-setupscallbacks

Adding the Roles

Create these roles:

  • Developer
  • Bulk Edit
  • Bulk Delete
  • Bulk Copy
  • Sysop
  • SW Update (to implement)
  • Local Dev (to implement)

Assign them all to yourself.

Adding the Fields

Accounts Table

See Pre-requisites above if you changed the name of the Accounts table.

  1. User Prefs: Paragraph Text
  2. SW Version: Short text.
  3. UTC HB:
    1. Date/Time
    2. Date Format: mm/dd/yyyy
    3. Default Date: none
    4. Time Format: military
    5. Default Time: none
  4. TZ:
    1. Number
    2. No decimals.
  5. LOC HB:
    1. Type: Equation
    2. Equation Type: Date
    3. Date Type: hours
    4. Result Type: Date
    5. Equation Editor: {UTC HB}+{TZ}
    6. Date Format: mm/dd/yyyy
    7. Time Format: military.
  6. Online:
    1. Type: Yes/No
    2. Default No
    3. Input: Checkbox
  7. UTC ACT: Type: Date/Time, Date Format: mm/dd/yyyy, Time Format: military.
  8. LOC ACT:
    1. Type: Equation
    2. Equation Type: Date
    3. Date Type: hours
    4. Result Type: Date
    5. Equation Editor: {UTC ACT}+{TZ}
    6. Date Format: mm/dd/yyyy
    7. Time Format: military.

App Settings Table

Create a table named App Settings with these fields:

  1. Item:
    1. Rename the default first field from App Settings Name to Item
    2. Set it as the table’s Display Field
    3. Sort: Item, a to z
  2. Value: Paragraph Text
  3. Date/Time:
    1. Type: Date/Time
    2. Date Format: mm/dd/yyyy
    3. Time Format: military

User Filters Table

Create a table named User Filters with these fields:

  1. Account: Connection to Accounts, all settings at default
    1. Date/Time:
      1. Type: Date/Time
      2. Date Format: mm/dd/yyyy
      3. Default Date: Current Date
      4. Time Format: military
      5. Default Time: Current Time
    2. Filters Code: Paragraph Text
    3. Table’s settings:
      1. Display Field: Account
      2. Sort: Account, a to z

Delete the first default field created: User Filters Name.

Adding the Views

iFrameWnd Page

  1. Add a Form view:
    1. Updates the currently logged-in account
    2. Title: Heartbeat
    3. Submit rules: auto-reload
    4. Confirmation message: Heartbeat sent successfully
    5. Fields on first line:
      1. SW Version
      2. UTC HB
      3. LOC HB, as read-only
    6. Fields on second line:
      1. Online
      2. UTC ACT
      3. TZ
  2. On a second row, add a Details view:
    1. For Logged-in Account
    2. Fields: User Prefs
    3. Title: Current User Prefs _ar=10
  3. Still on second row, at right, add a Form view:
    1. Updates the currently logged-in account
    2. Fields: User Prefs
    3. Title: Update User Prefs
    4. Submit rule: auto-reload
  4. On a third row, add a Grid view:
    1. Displays App Settings
    2. Title: App Settings _ar=20
    3. No Search
    4. Inline editing: On
    5. 10 records at a time
    6. No filtering
    7. Add all fields
    8. Set Value’s Shorten Text to 75 characters
    9. Source filter: Item starts with APP
  5. On fourth row, add a Grid view:
    1. Displays User Filters connected to the logged-in account
    2. Title: User Filters _ar=30
    3. Remove the Account column and leave only Date/Time and Filters Code
    4. Set Filters Code’s Truncate Text to 75 characters
    5. Limit number of records to 1
    6. No search
    7. Inline Editing: On
    8. 10 records at a time
    9. No filtering

User Preferences Page

  1. Go to User Pages (at the bottom of the Pages view) and edit the Account Settings page
  2. Add a menu:
    1. Title: My Settings
    2. Move it to the top of the page
  3. Add a link to a new page:
    1. Title My Preferences
    2. Enter it to edit that page
  4. Add a Form view:
    1. That updates the currently logged-in account
    2. Title: My Preferences
    3. Field: User Prefs
    4. Submit rule: auto-reload

Sysop Dashboards

This section will guide you through the creation of a Sysop Dashboards menu with pages that will allow viewing and managing various system-wide information.

These will be created:

  1. A page to view all account status like heartbeats, online, latest user activity, SW Version and User Preferences
  2. A page to broadcast synchronous software updates
  3. A page to browse through all Account Logs

Sysop Dashboards menu

  1. Add a new Dropdown Menu
  2. Leave empty for now, just click the Continue button at the bottom
  3. Menu name: Sysop Dashboards

Status Monitoring

  1. Create a new Login page accessible to Sysop role
  2. Title: Status Monitoring _ar=60 _ts
  3. Icon: eye
  4. Add a Grid view that displays all Accounts
  5. Add the narrow margins and high-density classes in the description: _cls=[ktlNarrowMarginsPage], [ktlTarget,scene] _cls=[ktlDenseGrid],[ktlTarget, $('.kn-table')]
  6. Source filter: User Status is active
  7. Fields:
    1. Name
    2. Online
    3. LOC HB
    4. UTC HB
    5. UTC ACT
    6. LOC ACT
    7. SW Version
    8. User Prefs
  8. Assign the page to the Sysop Dashboards menu

This view will refresh itself every minute, so you can assess the presence, latest activity and SW Version for each account.

Note about the Online status flag:
This flag is set to Yes programmatically by the KTL, but obviously, the only way to reset it to No would be to use some kind of supervision mechanism that declares the account being offline after a specific amount of time since the last heartbeat has been received.

This being said, you have 3 options:

  1. Ignore the Online status if it’s not important to your organization
  2. You can create some (1, 2 or 3+) daily task(s) to reset it
  3. Leave the Status Monitoring page running 24/7 on a dedicated device, so the KTL code will take care of this in real-time using API calls. This is the best option and Cortex R&D can provide such solutions using low-cost Linux devices in Kiosk mode to do it. Please enquire for more information.

SW Update

Here are the reasons why you might want to broadcast a manual software update:

  • You have some new code to release
  • You want to update the KTL to a newer version
  • You want the users to fetch the latest Builder’s changes
  • Any combination of the above
  1. Create a new Login page accessible to SW Update role only. Ideally, only one person should have that role to prevent clashing updates. Otherwise, it will be crucial to establish a very clear procedure and communication protocol between the involved parties.
  2. Title: SW Update
  3. Icon: bullhorn
  4. Add a Grid view that displays the App Settings table
  5. Title: SW Update
  6. Settings:
    1. No search
    2. Inline Edit: On
    3. 10 records
    4. No filtering
    5. Source filter: Item is APP_KTL_VERSIONS
  7. Fields:
    1. Item
    2. Value
    3. Date/Time
    4. Add an Action column
      1. Header: Broadcast SW Update
      2. Link Text: BROADCAST NOW
      3. Action: Update this record, Item to a field value: Item (just a dummy action)
      4. Confirmation msg: SW Update in progress...
      5. Text style: bold red with the display rule: when Item is not blank
  8. Assign the page to the Sysop Dashboards menu

Account Logging

Creating the Accounts Logs Page

  1. Create a new Login page accessible to Sysop role
  2. Add a Grid view that displays the Account Logs table
    1. Title: Account Logs
    2. Settings:
      1. Display Field: Account
      2. Sort Order: Log Nb, low to high
    3. Fields:
      1. Log Nb: Type: Auto-Increment
      2. Account: Type: Connection to Accounts
      3. Date/Time:
        1. Type: Date/Time
        2. Date Format: mm/dd/yyyy
        3. Default Date: Current Date
        4. Time Format: military
        5. Default Time: Current Time
      4. Log Type: Type: Short Text
      5. Details: Type: Paragraph Text
      6. Log Id: Type: Short Text (see note below for details)
      7. Email To: Type: Email
  3. Assign the page to the Sysop Dashboards menu

In the iFrameWnd

  1. Add a Grid view that displays the Account Logs connected to the logged-in Account
  2. Title: Account Logs _ar=30
  3. Settings:
    1. No search
    2. Inline editing: On
    3. 10 records at a time
    4. No filtering
    5. Sort by Log Nb: high to low
    6. Limit to 5 records
  4. Fields:
    1. Date/Time
    2. Log Type
    3. Details
    4. Log ID
    5. Email To
    6. A Custom Email action with these settings: KTL Account Logs Email Settings.jpg.
    7. The blank value to Email To in Action #2 is intended. This field also acts as a flag and resetting it to blank prevents sending the email more than once.
    8. The Outcome phrase “Account Logs - Email sent successfully” is used in the code to confirm completion, so it must be exactly the same.

Note about the Log Id field

This is a unique ID that is a UTC millisecond timestamp. It is generated by the code at the moment the log is created and stored in localStorage. Its purpose is to validate that the log has been sent and received properly. With that confirmation, the log can safely be deleted from localStorage.

Testing the Features

Refresh your app to see all changes take effect.

User Preferences

  1. Click on Account Settings link at the top right of your page.
  2. Click My Preferences menu button.
  3. You will see 4 new checkboxes (dynamically generated by code):
    1. Show View ID
    2. Show iFrameWnd
    3. Show DebugWnd
    4. Show Extra Debug
  4. Check all 4 and Submit:
    1. View IDs will be shown in red next to each view
    2. The iFrameWnd will appear at the bottom of the app
    3. The DebugWnd will show up
    4. In the console output, some new logs about WndMsg processing (REQ, ACK, etc.) will be shown.
  5. Uncheck all checkboxes and Submit to hide all views and stop extra logs.

Heartbeat Monitoring

  1. Check the Show iFrameWnd checkbox from the above procedure and Submit to see the iFrameWnd again.
  2. In the iFrameWnd you will see the heartbeat being submitted every minute. All fields will be populated properly with SW versions, timestamps, time zone and the Online flag being set to Yes.

User Filters

  1. Open your app on two different devices (or browsers - ex: Chrome and Edge)
  2. Log-in with your own account in both
  3. On both browsers go to the same page, where there’s a Grid with filtering enabled
  4. In a given view, create a couple of filters in the first browser
  5. Wait about 30 seconds and in the second browser, you will see those filters appear for that same view.

Broadcasting the SW Update

Whenever you need to do a SW Update, do the following procedure:

  1. Be sure to close all browsers that you have opened on this app
  2. Open the SW Update page created previously
  3. Go back in the Builder’s Javascript pane and increment your App's version number in the global variable:
    window.APP_VERSION = '1.0.0';
  4. Copy/paste your code in the Javascript pane – but don’t save yet!
  5. Update the KTL version in the Loader if needed.
    NOTE: Sometimes you may want to intentionally hold back a KTL update until you also have an App update to push, so you can do both at the same time
  6. Save the Javascript code. Important: wait until the spinner is gone
  7. Refresh your app to get the latest version
  8. Do a quick visual check to validate the numbers in the Version Info Bar at top right
  9. Click the BROADCAST NOW action link
  10. Validate that the version in the Grid matches that of the Version Info Bar
  11. Open the Status Monitoring page to see all users’ version slowly being updated and the process completes abroad for those who are online.

IMPORTANT!!! The steps 6 to 9 must be done without interruption, otherwise all users will see their app page(s) reloading over and over again.

If this happens, click BROADCAST NOW once again and check if the value in the Grid matches the one in the Version Info Bar – as it should.

If the looping persists

If, despite the retry mentioned above, the app keeps reloading in a loop, disable the iFrameWnd flag (false) in the ktl.core.setCfg function and save your Javascript code. Once the dust has settled, you can start investigating the root cause. Usually it’s due to a typo in a field name or a view title somewhere. Check the console logs also.

Behind the scenes, this is what happens: The KTL uses an API call to update the App Settings' APP_KTL_VERSIONS record. All users with opened browsers will have their iFrameWnd detect the version change and force a page reload to get the latest code.

Those who are not online will simply get the latest code when they launch the app next time.

Public Filters

  1. Open two browsers of different types, ex: Chrome and Edge.
  2. Log-in with your account having Public Filters role, in the first browser
  3. Log-in with another account not having Public Filters role, in the second browser
  4. Go to the same page on both browsers
  5. Create two User Filters with your account
  6. Set them to Public
  7. You can drag’n drop them left and right and can rename them
  8. On the second browser, those two filters will appear about 30 seconds later
  9. The other user can’t move them, rename them nor delete them
  10. In your page, click on the padlock icon to unlock Public Filters. See notes below about the padlock icon
  11. Make changes to the filter and re-order them
  12. All changes will be reflected in the other browser a few seconds later

About the padlock icon

The padlock only applies to Public Filters and is only visible to users having that role.

  • Locked: Makes the Public Filters “read-only”. When you make changes to Public Filters, they won’t be saved locally or uploaded. This is useful for normal day to day usage. Otherwise, when you just want to change the sorting, searching, etc., an upload would occur each time, disturbing the others working with that view.
  • Unlocked: Makes the Public Filters “writable”. When you make changes to Public Filters, they will both be saved locally and uploaded. This is useful during (or after) an editing session, when you’re ready to broadcast the updated filters to all users. Typically, you unlock, edit all filters and lock back.

Using multiple browsers

It’s important to understand that the localStorage (where the filters information is stored) is not shared across different browser families – ex: Chrome and Edge. Furthermore, this is also true within the same browser family, when opening their private/incognito counterpart.

This means that without the automatic upload/download of filters, all users would have to re-create them when switching devices or browsers. But now, this takes care of the transfer in all cases.

This particularity can be leveraged by allowing you to log-in to 4 different accounts and/or roles at the same time. This can be very useful during testing phases for example.

Conclusion

Hope you’ll enjoy the KTL’s Advanced Features. Give us some feedback, we always love to hear from you.

Normand Defayette

Cortex R&D Inc.

Clone this wiki locally