Prerequisites
This assumes you’ve read the Data Events Introduction.
Some legacy plans do not support data events. See plans
Scenario
This example will carry you through the scenario of using data events to expose a hidden field only to members with specific roles within your organization. By default, there are four system-level member roles types included within a Fulcrum organization.
Setting Up Data Events
For this example, our app will only have two fields. The Record Label field is seen by all users, but we want to keep the Sensitive Field hidden from users in the Standard User role while allowing it to be seen by the Manager and Owner roles.
Data Events button
As you are building your app, you will see a “Data Events” button in the app builder sidebar. This is where you define your data events within the app. Let’s go ahead and click this to enter our expression to define our data event.
Interface
With our expression builder modal window open, let’s take a quick tour of the interface.
Editor Components
Form fields: Reveals a window showing all of your fields within your app.
Function list: Reveals a window showing all of the built-in custom functions. Clicking the function will add it to the workspace; clicking the description text for a function will take you to the reference page for that function.
Editor settings: Reveals a window that allows you to set the settings. You can set the theme (light/dark), font size (12px - 18px), code options (default/strict), and text wrapping (on/off).
Workspace: This is the area where you will write your data event code.
Save and Cancel buttons: Click these buttons to either save your code or cancel out of saving your code.
Navigator: This shows all your data event codes; additionally, any errors will be highlighted in the scroll bar to the right of the navigator.
Right-Click Options
Right-clicking within the editor will reveal some additional options that can be helpful when writing your code.
Go To Definition: Will go directly to the defined function within the code.
Peek Definition: Will open a window showing the defined function while keeping your position in the editor.
Peek References: Will open a window showing all the references throughout the code.
Go To Symbol: Brings up a pick list of all functions and variables within the code. Clicking on a function or variable will take you to the location of that variable/function.
Change All Occurrences - Right click on text and have all occurrences of that text throughout the code highlighted so that it can be changed to something else.
Format Document/Selection: Will properly format the entire code or the highlighted code with proper indentations.
Adding expression
Now let’s enter our expression to expose the hidden field only to certain roles. The 12 lines of JavaScript below define a function named checkRole which evaluates if the user’s role is either ‘Owner’ or ‘Manager’ with the ROLE function, from the Calculation Expressions. If the role matches those values, the ‘sensitive_fields’ hidden settings will be set, exposing the field to those users; for roles such as ‘Standard User,’ the field will stay hidden.
If your data events expression is valid, upon saving you will notice the ‘Data Events’ button text now shows ‘Enabled.’
If the expression is invalid, your browser will alert you and you’ll need to debug before being able to save. If you want, you can also comment out your code so that you can save what you have so that you can come back and work on the code later.
Additionally, you can see where the possible errors are in your code by looking for the red line under the text and the red lines in the scrollbar on the right side of the editor.
