Custom Embedded JavaScript Functions: Difference between revisions
No edit summary |
No edit summary |
||
Line 13: | Line 13: | ||
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). | 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. | 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 [[Custom Value Formatting|Value Formatter]] is compliant with 3B Docs. | ||
To use the function expression in your template, navigate to the “Functions” icon within the Template builder. | To use the function expression in your template, navigate to the “Functions” icon within the Template builder. | ||
Line 26: | Line 26: | ||
== Syntax == | == 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. | Just like [[Custom Value Formatting|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 Fields and Tags|merge tag]], whereas [[Custom Embedded JavaScript Functions|Function Expressions]] form their own independent merge tags. | The difference between [[Custom Value Formatting|custom value formatters]] and Function Expressions lies in the fact that [[Custom Value Formatting|custom value formatters]] can only be applied to a specific [[Merge Fields and Tags|merge tag]], whereas [[Custom Embedded JavaScript Functions|Function Expressions]] form their own independent [[Merge Fields and Tags|merge tags]]. | ||
You must always return a string value – this return value will be your “transformation” of the merge tag. | You must always return a string value – this return value will be your “transformation” of the [[Merge Fields and Tags|merge tag]]. | ||
== Examples == | == Examples == | ||
Line 36: | Line 36: | ||
=== Return Current Date === | === 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!)<syntaxhighlight lang="javascript" line="1"> | 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 Formatting|custom value formatters]] and transform the date to a US date!)<syntaxhighlight lang="javascript" line="1"> | ||
() => new Date().toLocaleDateString(‘en-GB’); | () => new Date().toLocaleDateString(‘en-GB’); | ||
</syntaxhighlight> | </syntaxhighlight> |
Revision as of 06:05, 3 September 2022
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