ntf Object
Updated pdexter 2024-03-12
The ntf object passed into rulesets has a number of built in sub-objects and properties useful to the ruleset writer.
ntf.document
This object represents the document in memory, as presented on the current browser page, or that is being operated on. As such, it has no specific utility properties common to all usages.
Eg, ntf.document.documentId is the documentId of the document.
Eg, ntf.document.coverColour is the value of the field "coverColour" on the document.
It has the further advantage that any attributes attached to it will persist through the document browser session that the document is opened in. An attribute attached in its OnLoad ruleset will still be present in later calls to OnFieldChange, PreSave and PreSaveServer rulesets.
This can be handy for setting flags if a particular field is set, eg
/// OnFieldChange
ntf.document.flagAssigneeChanged = true
...
/// PreSave
if (ntf.document.flagAssigneeChanged) {
// do verification
...
delete ntf.document.flagAssigneeChanged;
}
Caution - changes made to ntf.document during client side rulesets will persist right through to saving, if not removed, and you may end up with extraneous data saved with the document. For this reason, you should delete any such flag properties in PreSave or PreSaveServer.
Note - from Formbird v3.3.1-next.63, ntf.documentSession should be used for storing temporary value. See section below.
ntf.context
ntf.context is an object containing context information for use by a ruleset.
This information varies between different ruleset events. Generally there is a wide difference between server side rulesets (PreSaveServer, PostSave) and client-side (PreRender, OnLoad, OnFieldChange, PreSave, PostSaveClient)
Properties of ntf.context
Property | Description | Available In |
---|---|---|
appVersion | String; version of the Formbird application | all |
accountControl | Object; content of the user's account-control document | all |
changeSourceEvent | (number); For OnFieldChange, returns a code number defining the original source of the change. 0 = Component, eg a text change 1 = Ruleset 2 = Document Push, eg document has changed on server, and change is pushed through to the document on screen. This differs from changeSourceType, in that it defines the first change source in a chain of changes, eg, where rulesets make changes to fields in response to an original event. |
OnFieldChange |
changeSourceType | (number); For OnFieldChange, returns a code number defining the current source of the change. 0 = Component, eg a text change 1 = Ruleset 2 = Document Push, eg document has changed on server, and change is pushed through to the document on screen. This differs from changeSourceEvent, in that it defines the latest change source in a chain of changes, eg, where rulesets make changes to fields in response to an original event. |
OnFieldChange |
eventName | String; descriptor of the Event under which this ruleset is occurring Values: PreRender OnLoad OnFieldChange PreSave PostSaveClient PreSaveServer * PostSave |
all |
fieldChanged | String; The name of the field that triggered OnFieldChange event. This is set only in OnFieldChange. |
OnFieldChange |
hostUrlRoot | String; the URL Root of the server. | Server-side |
isChildDoc | Boolean; whether the document is within a child panel of the browser page. | Client-side |
isNew | Boolean; whether the document is new or existing | all |
newValue | (any); The new value of the field that triggered an OnFieldChange event. | OnFieldChange |
oldValue | (any); The previous value of the field that triggered an OnFieldChange event. | OnFieldChange |
template | Object; the full template document of the current document. | Client-side |
templateId | String; The templateId of the current document. Also generally available through ntf.document.systemHeader.templateId |
Client-side |
user | Object; The user account document of the current user. This is the same object as ntf.user. nb: this is readonly |
all |
The following are redundant properties and should be ignored.
Property | Description | Available In |
---|---|---|
formParameters | Object; not used | Client-side |
logger | Object; not used | all |
rsLogger | Object; not used | Server-side |
ruleSetDoc | Object; not used | Server-side |
ruleSetId | String; not used | Server-side |
ruleSetLogTemplateId | String; not used | Server-side |
Methods of ntf.context
isCachingEnabled()
Applies to Formbird v4.2.11 & later
The isCachingEnabled()
method is a part of the OfflineStatusService in Angular, designed to check whether the user has enabled the Formbird offline capability. This method is accessible through client rulesets with ntf.context
. Example:
ntf.context.isCachingEnabled();
This method is particularly useful for applications that need to adapt their behavior based on the availability of offline capabilities, such as dynamically adjusting data fetching strategies and user notifications.
Note: The isCachingEnabled()
method is not available in server-side rulesets. It is exclusively for client-side use in the context of a browser environment.
isModal()
Applies to client-side rulesets only. Applies to Formbird 4.2.21 & later.
Determines if the form is opened in a modal or in the default form viewer.
Syntax
ntf.context.isModal()
Returns
Boolean value indicating if the form is opened in a modal (true
) or in the default form viewer (false
).
Example
// Check if the current template's rule is opened in a modal
var isInModal = ntf.context.isModal();
console.log('Is in Modal:', isInModal);
Note
This function is specifically designed to work within the context of client-side rulesets. It allows for conditional logic based on the display context of the rule (modal or default form viewer). This can be useful for adjusting the behavior or layout of the form depending on how it is being presented to the user.
isOnline()
Applies to Formbird v4.2.11 & later
The isOnline()
method, provides a real-time check of the device's current online status. It can be accessed through client rulesets using ntf.context
. Example:
ntf.context.isOnline();
This function is essential for applications that need to know the current connectivity status to manage operations accordingly. It helps in making real-time decisions based on the immediate network availability.
Note: It is important to understand that isOnline()
only indicates the device's connectivity status at the moment of the check. It should not be assumed that the device will remain online after isOnline()
returns true. Network connectivity can be lost subsequent to the check, potentially during an ongoing operation. In such cases, the data service will automatically fall back to using offline data. Therefore, applications should be designed to handle these scenarios gracefully.
ntf.user
ntf.user is basically a copy of the current user's account document.
The most useful properties here for use in rulesets are:
Property | Description |
---|---|
documentId | String; The current user's account documentId (In JayRule rulesets, ntf.userId is set to this value anyway) |
String; The current user's email address. |
ntf.scope
ntf.scope can be considered the toolbag of rulesets.
In general, we assign the object variable ft3 to this object. So for the most part, we can ignore ntf.scope.
It carries all the ruleset functions we use within rulesets. See Ruleset Functions.
ntf.documentSession
Available with Formbird v3.3.1-next.63
ntf.documentSession is a persistent object "bag" which persists for the entire lifecycle of the document, from OnLoad >> OnFieldChange >> PreSave >> PreSaveServer >> PostSave, and across client/server side ruleset events.
Example
--- ONLOAD ---
ruleSetSessionObjects : {
ruleCondition : true,
ruleAction : function(ntf) {
ntf.logger.info('dsTimeStamp - ' + ntf.documentSession.dsTimeStamp);
ntf.documentSession.dsTimeStamp = ft3.moment().format();
ntf.documentSession.timeStampOB = ft3.moment().toDate();
ntf.logger.info('dsTimeStamp` - ' + ntf.documentSession.dsTimeStamp);
}
}
...
--- ONFIELDCHANGE ---
ruleTestSessionObjects : {
fieldChanged : 'cmdTestDocumentSession',
ruleAction : function(ntf) {
var storedString = ntf.documentSession.dsTimeStamp,
storedDateOB = ntf.documentSession.timeStampOB;
ntf.logger.info(`dsTimeStamp (fieldChanged) - ${storedString}`);
ntf.logger.info(`timeStampOB (date) - ${storedDateOB}`);
}
}
As demonstrated above, one can set objects within documentSession, however the objects are stringified to JSON in the background, therefore one needs to not set "active" objects, eg with function properties, which would get stripped out.
This should be used to replace previous practice of setting a temporary flag or value on the ntf.document (which was the only persistent object available), reacting to it in later rulesets, then remembering to delete the flag/value before or on saving the document.