¶ Playground
Did you think that you had to generate a new document every time to check if the expression you built was correct?
Forget about it! Let us present you with Playground! It is designed to check the validity of the built and evaluated expressions.
The evaluated result you have at the end is the same result that will appear in the document after the template is generated. So Playground helps you simulate what will happen when the document is merged. Moreover, you can edit the GraphQL Query and Variables in the same tab to see how it affects the expression results. Or you can execute the query you have to see the context that will your Document Template use when you start generating your documents.
You can find Playground in the Maven Documents Application next to the Query Builder. Click on the corresponding tab and you’ll see what we are talking about.
Playground consists of five separate sections:
Each section is a separate piece of functionality, which we will describe in the corresponding articles below. By the way, the headers of sections are clickable and lead to the similarly-named sections on this document.
Query, Variables, and Context sections have Text folding feature. It means you can click the black down arrow on the right pane of each section and hide the text under the header category.
¶ Query
In this section, you will find the same query as you have in Query Builder. There is no need to switch between the tabs to check objects and fields included in the query. But if you made changes in Query Builder, they would be displayed in Playground. Just click the Refresh button in the top right corner of the Query section and the query will be updated.
Note: the Refresh button plays an important role in updating data in the Playground tab. If you make changes in the Query Builder tab, you need to use this button to have everything up-to-date in the Playground tab. It is also possible to click on the Query section and press the Ctrl+Enter combination on the keyboard
So here and further in the text, by the Refresh button we mean the button from the Playground's Query Section.
Besides, you can manually edit the query right in the Query section as well. Place the cursor in the query and delete, add, or edit fields. These changes are only valid in the Playground tab and don't affect the query in Query Builder. You can discard everything by clicking the Refresh button.
¶ Variables (Query, Global)
- Query Variables from the Query Builder tab are displayed in this section. The connection between this section and Query Builder is similar to the one that the previous section has: if you add, delete, or edit variables in the Query Builder tab, these changes will be shown in Playground after you click the Refresh button.
You can also edit, add, or delete variables directly in this section, by placing the cursor in the Variables section and making the needed changes. It is important to remember, because placing a specific value in the variable affects data in the Context section and, hence, the result of an expression. Don't forget that everything you do with variables in Playground doesn't influence the Salesforce data.
Be aware that the currentuserId variable is automatically populated with the ID of the user who is editing Maven Documents Playground.
- Global Variables from the Query Builder tab are displayed in this section. This type of variable operates the same: it takes and then represents some value. The difference between the two is that you will use Global Variables in the document template. More detailed information description is in the Global Variables section. If Global Variables are not defined, curly brackets that wrap them, stay empty.
As we mentioned earlier, values in Variables influence the context, and Context influences the result of the expression. You can get the right context by putting some values in the corresponding variables. As mentioned above, the currentuserId variable is already populated. So one more thing to do is to copy and paste the ID of the record from Salesforce to the recordId variable instead of the {!recordId} value.
¶ Context
This section holds the result data of the query execution.
Only a few steps are needed to make it happen:
- Paste the record's ID in the corresponding variable's field in the Variables (Query, Global) section.
- Click the Refresh Context button in the Context section, or click on the Context section and press the Ctrl+Enter combination on the keyboard.
It is possible to get context without changing the recordId variable. It just won't display information about the query filtered with the recordId variable.
It is important to remember, that every time anything was edited in the query or variables, the context should be refreshed
In the blink of an eye, all the information about the chosen record will be shown in the respective section. We mean it: the data appears fast. To prove our words we added the Context retrieval execution time mark in the bottom right corner of the Context section.
And you can notice that Code Wrap is disabled in the Context section wich helps you to have a more clean view of the data
¶ Context With Global Variables
Notice, that if Global Variables are defined, they will appear in the Context section after you refresh it.
¶ Context With Custom Queries
The Context section will also show you the data on custom queries if you have them in the document solution.
One more thing. You can easily edit displayed information right in the Context section. It means that you can correct or modify data in the context to influence the result of the expression you built. But be aware, that these changes only live until you refresh the context. These modifications in Context won't change data in Salesforce. Do you remember? What happens in Playground stays in Playground.
Note: If you make changes in Salesforce and want them reflected in Playground, for example, you changed locale or time zone settings, it is necessary to reload the page with Playground. Refreshing the context or query won't be enough.
But if you made changes in the query or variables in the Playground tab and want these changes to modify the context, you need to click the Refresh Context button.
¶ Expression
This is why we are all here: this section is all about creating expressions. Here you can write expressions manually or use the help of the built-in Expressions Builder. It helps you to construct expressions by pointing and clicking. You can find more information on Expression Builder in the corresponding article in the documentation.
How to write expressions manually doesn't need explanation: you are typing symbols using the right syntax in the Expression section. Using Expression Builder is something different. Let's build the following expression {!$groupBy(Opportunity[0].OpportunityLineItems,'Quantity','OpportunityLineItem')} to group products from Opportunity by quantity. Here is the quick instruction:
-
Click on the icon in the top right corner of the Expressions section. This will open Expression Builder.
First of all, you can see all the available functions in the Select function menu. The first dropdown menu filters functions by categories (date, number, string, etc.), and the second dropdown menu contains filtered functions you can use.
You can also insert your Salesforce fields into expressions by using the Select Object or Field menu. Select the needed field (an arrow (>) next to a field suggests that it's a relationship field - e.g. Account > Contact > ...) and click the Insert Object or Field button.
Before inserting the function or a field, verify that you've selected the text you want to replace in the text field below. -
From the Select function menu, choose the function and then choose the function type. Click Insert.
-
If needed, replace some parts of the function with Salesforce fields, other function types, or data.
-
Click Insert Expression. This inserts the expression back into the Expression Builder view. Click Insert Expression to insert it into the Expression window. That is how you create an expression.
After you have the body of the expression and the context it can use, you can start the process of evaluating that expression with just one click on the Evaluate button next to the Expression Builder button. You can evaluate the expression by pressing the Ctrl+Enter combination on the keyboard as well.
An important things to remember: multiple expressions can be evaluated at a time.
¶ Expression With Global Variable
If Global Variables are defined, you can simply write them down in the Expression section and click Evaluate Expression or press Ctrl+Enter. The value from the variable will appear in the Result section.
¶ Result
The last section to describe is called Result. It represents the result of the expression you've built and evaluated.
For example, the result of the expression that we've built in the previous section is going to look like this:
If the Result section stays empty after you clicked the Evaluate button, please contact support.
Notice, that this section has the time mark as well, so you will know how long the expression was evaluated.
Note: If the expression contains an error or wasn’t built properly, you’ll get an error message with a description of the problem.
