Custom Embedded JavaScript Functions
Intro
3B Docs allows you to write JavaScript code snippets that can be embedded on a document to extend existing functionality and/or create new functionality.
Usage
Most often, a Function Expression will be used to return strings like timestamps, user identifiable information (such as IP address, location, etc) and for locale, timezone and language reasons. Here are some other examples:
- To obtain a photo of the currently viewing user using their integrated camera and then embed it in the document
- To connect via REST API to an external service to fetch additional data for the contextual record (TODO: Add reference to contexts & handling)
- To import an external library and display custom elements/components that are rendered by the external library (say a table, chart, image slider etc)
- To patch-fix a bug in 3B Docs
How To
In order to add custom JavaScript function, you need to create a Function Expression record, which you can access from the 3B Docs Application (or simply search for “Function Expressions” in the app launcher drop down).
When you have navigated to the object list view, you can click on the “New” button which will display the new record form. What is important here is that you give the Function Expression a unique name that has no spaces or special characters. Don’t worry about enforcing this rule yourself, we have built a salesforce validation rule to make sure that the name of the Value Formatter is compliant with 3B Docs.
To use the function expression in your template, navigate to the “Functions” icon within the Template builder.
You will see a drop-down of all the available Function Expressions that you can use within the Tempalte.
When you select a specific Function Expression, it will be copied to your clipboard and you can simply paste it anywhere inside the Tempalte document via CTRL + V / CMD + V (on Mac) command.
When you paste a function expression, it will look something like this: #{Functions.CurrentDate}
Function expressions are treated just like merge fields (TODO: Add reference to merge fields), so you will have access to the value formatters (TODO: Add reference to value formatters) that may be available to modify the value returned by the Function Expression. So, the following Function Expression is completely valid: #{Functions.CurrentDate> EU_Date_Format}
Syntax
Just like Value Formatters (TODO: Reference to Value Formatters), when you create a Function Expression, you are basically creating a JavaScript function. This JavaScript function has access to the global context and thus to the user’s navigator object, the application variables & collections and much more.
The difference between Value Formatters and Function Expressions lies in the fact that Value Formatters can only be applied to a specific merge tag (TODO: add reference to merge tags), whereas Function Expressions form their own independent merge tags.
You must always return a string value – this return value will be your “transformation” of the merge tag.
Examples
Here are some examples to get you started with the basic syntax used by 3B Docs for function expressions:
Return Current Date
This example is useful for getting a dynamically generated timestamp of the current date relative to when the document is opened in dd/mm/yyyy format (don’t worry, you can still apply value formatters and transform the date to a US date!)
() => new Date().toLocaleDateString(‘en-GB’);
Tips & Tricks
Here are some tips and tricks for using Function Expressions:
Block Document Renders in Certain Locales
You can throw a JavaScript error if you deem the currently viewing user’s locale as one that you do not support/allow.
Get Access to the Viewing User’s Hardware
You can request access to hardware such as GPS, Camera, Accelerometer, Barometer etc. and log the return inside the document.
API Callouts
You can use Function Expressions to do callouts, fetch data externally, load additional resources, use JavaScript Libraries such as FullCalendar (TODO: Reference), ChartsJs (TODO: Reference, JS Tables (TODO: Add reference)
User Logging, Tracking and Fingerprinting
You can use such technologies as FingerprintJs (TODO:Add Reference) to user tracking capabilities to your documents