Button event

In the “ButtonEvent” table of the demo database, the record’s fields (“caption”, “the color”, “Tooltip”, “badge.caption”, “badge.color”) set the label, the color, the tooltip and the badge of the “Bonjour” button, through the onUpdate function described below.

Customizing Buttons with Ninext

With Ninext, you can modify the appearance of Ninox buttons by defining a function called onUpdate in the button's "Display field only, if" formula. This function must return an object describing the visual elements to be modified, and the script must end with a Boolean indicating whether the button should be displayed.

Using this approach, you can:

• Change the button's caption.
• Update the tooltip (or title) of the button.
• Change the button's color, among Ninox's three button styles: "blue" (blue background), "red" (pink background, red text) and "grey" (white background, blue outline, like the “Bonjour” button above).
• Display a badge to highlight important information.

This feature can be turned off in the Ninext Settings, "UI Enhancements" section: Button Events (onUpdate) (on by default).

Quick Overview of JSON Properties

General Workflow

1. Define the onUpdate Function
   In the button's "Display field only, if" formula, declare a function called onUpdate. This function returns an object (in JSON format) describing the elements to modify. It receives as a parameter the button's label and color as defined in Ninox: { caption, buttonColor }.
2. Return a Boolean for Visibility
   The formula must end by returning a Boolean (true or false) to indicate whether the button should be displayed.
3. Ninext Applies the Modifications
   When the record is opened or refreshed, Ninext executes the onUpdate function, reads the returned object, and dynamically applies the appearance changes to the button.

Implementation

Single Code Block in the "Display field only, if" Formula

"Declaration of the onUpdate function that customizes the button";
function onUpdate(buttonValues : any) do
 let count := this.Count;
 {
      caption: if count > 0 then
          "Send (" + count + ")"
      else
          "Send"
      end,
      tooltip: "Click to send your request",
      buttonColor: if count > 0 then "red" else "blue" end,
      badge: {
           caption: if count > 0 then text(count) else "" end,
           color: "red"
      }
 }
end;

"Determination of the button's visibility";
this.Count >= 0

Comments:

• The onUpdate function builds an object that allows modifying the button caption (with a numerical indicator if Count is positive), the tooltip, the button color, and displaying a badge.
• The final block of code returns a Boolean to determine whether the button should be displayed.

Minimal Example (Badge Only)

"Declaration of the onUpdate function to display only a badge";
function onUpdate(buttonValues : any) do
 let newItems := this.newItems;
 {
      badge: {
           caption: if newItems > 0 then text(newItems) else "" end,
           color: "red"
      }
     }
end;
"The button is always displayed";
true

Comments:

• Only the badge property is returned to display a value if newItems is greater than 0.
• The button is displayed unconditionally.

Important Points

• Final Boolean Return
  Without returning true or false at the end, the button will not be visible.
• A badge caption always in text
  Ninext only displays the badge if badge.caption is a non-empty text. A number (3 instead of "3") leaves the badge hidden: use text().
• A function evaluated separately
  Ninext extracts the onUpdate function alone from the formula, then evaluates it separately, in the context of the record. It therefore sees neither the variables nor the other functions declared elsewhere in "Display field only, if": declare inside onUpdate everything it needs. It can read the record's fields (this.Count) and call the database's global functions.