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 Template.

When you select a specific Function Expression, it will be copied to your clipboard and you can simply paste it anywhere inside the Template 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, so you will have access to the custom 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 custom 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 custom value formatters and Function Expressions lies in the fact that custom value formatters can only be applied to a specific merge tag, 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 custom 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, Chart.js, Datatables and many more..

Here is a sample of how to initialize FullCalendar (you may need extra code in order to import JS and CSS):

document.addEventListener('DOMContentLoaded', function() {
    var calendarEl = document.getElementById('calendar');
    var calendar = new FullCalendar.Calendar(calendarEl, {
      initialView: 'dayGridMonth'
    });
    calendar.render();
});

User Logging, Tracking and Fingerprinting

You can use such technologies as Fingerprint to user tracking capabilities to your documents