528
edits
Custom Value Formatting: Difference between revisions
Custom Value Formatting (view source)
Revision as of 06:13, 3 September 2022
, 06:13, 3 September 2022no edit summary
No edit summary |
No edit summary |
||
| Line 1: | Line 1: | ||
== Intro == | == Intro == | ||
3B Docs allows you to build a library of | 3B Docs allows you to build a library of “Value Formatters” – these are special functions built with JavaScript that let you apply a specific formatting to a [[Merge Fields and Tags|merge tag]] that are stored in the Value Formatter object table. | ||
== Usage == | == Usage == | ||
- Depending on the currently viewing user’s browser locale settings, change a <code>#{Contact.Id:CreatedDate}</code> merge tag to return a date in dd/mm/yyyy or mm/dd/yyyy | You can use Value Formatters in order to adjust, change, mutate and transform values returned by [[Merge Fields and Tags|merge tags]]. Here are some examples of how you can employ the power of Value Formatters: | ||
- Depending on the currently viewing user’s browser locale settings, change a <code>#{Contact.Id:CreatedDate}</code> [[Merge Fields and Tags|merge tag]] to return a date in dd/mm/yyyy or mm/dd/yyyy | |||
- Change a decimal with higher resolution to a lower resolution (round a decimal) | - Change a decimal with higher resolution to a lower resolution (round a decimal) | ||
- Conditionally display a value, for example if the currently viewing user’s browser declares their location to be outside of your country, you may want to not show the return value of the merge field. | - Conditionally display a value, for example if the currently viewing user’s browser declares their location to be outside of your country, you may want to not show the return value of the [[Merge Fields and Tags|merge field]]. | ||
- Translations and internationalisation – you could build maps of translations for specific strings, say if a field from salesforce returns “Hello”, you may want to transform this to “Hola”, “Здрасти“, “Pronto”, etc. again, depending on the currently viewing user’s browser locale. | - Translations and internationalisation – you could build maps of translations for specific strings, say if a field from salesforce returns “Hello”, you may want to transform this to “Hola”, “Здрасти“, “Pronto”, etc. again, depending on the currently viewing user’s browser locale. | ||
| Line 22: | Line 23: | ||
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 Value Formatter 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 Value Formatter 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 newly created Value Formatter with your template, you need to navigate to a Template record, load the editor, add a merge tag | To use the newly created Value Formatter with your template, you need to navigate to a Template record, load the editor, add a [[Merge Fields and Tags|merge tag]] and click on the merge tag. | ||
[[File:Adding Value Formatter.png|thumb|Adding Value Formatter]] | [[File:Adding Value Formatter.png|thumb|Adding Value Formatter]] | ||
From the options list, select the value formatter that you want to apply to the merge tag. The merge tag will be transformed from say <code>{Contact.Id:CreatedDate}</code>to <code>#{Contact.Id:CreatedDate>EU_Date_Format}</code> . This arrow right chevron indicates that the merge tag is to be formatted by the Value Formatter with the same name immediately after the chevron. | From the options list, select the value formatter that you want to apply to the [[Merge Fields and Tags|merge tag]]. The merge tag will be transformed from say <code>{Contact.Id:CreatedDate}</code>to <code>#{Contact.Id:CreatedDate>EU_Date_Format}</code> . This arrow right chevron indicates that the merge tag is to be formatted by the Value Formatter with the same name immediately after the chevron. | ||
== Syntax == | == Syntax == | ||
When you create a value formatter, you are basically creating a JavaScript function that accepts a single parameter “value”. This JavaScript function has access to the global context and thus to the user’s navigator object, the application variables & collections and much more. This parameter “value” is the value returned by the merge tag embedded on the template. | When you create a value formatter, you are basically creating a JavaScript function that accepts a single parameter “value”. This JavaScript function has access to the global context and thus to the user’s navigator object, the application variables & collections and much more. This parameter “value” is the value returned by the [[Merge Fields and Tags|merge tag]] embedded on the template. | ||
Note: You must always return a string value – this return value will be your “transformation” of the merge tag. | Note: You must always return a string value – this return value will be your “transformation” of the [[Merge Fields and Tags|merge tag]]. | ||
== Examples == | == Examples == | ||
Here are some examples to get you started with the basic syntax used by 3B Docs for | Here are some examples to get you started with the basic syntax used by 3B Docs for Value Formatters: | ||
=== Format Date Time to EU Format Date === | === Format Date Time to EU Format Date === | ||
| Line 63: | Line 64: | ||
=== API Callouts === | === API Callouts === | ||
You can use | You can use Value Formatters just like [[Custom Embedded JavaScript Functions|Function Expressions]] to connect to external systems<syntaxhighlight line="1"> | ||
var getJSON = function(url, callback) { | var getJSON = function(url, callback) { | ||
var xhr = new XMLHttpRequest(); | var xhr = new XMLHttpRequest(); | ||