Search
Create a Saved search
Start by creating your saved search. In the below example we are creating a saved search based on the Task record but you can use any searchable record, both standard and custom.
Set a search title and id that can easily be linked to your layout. It is adviced to use prefixes or the name of the printout as part of the name.
Remember to mark the search as public.
Add your criteria (optional). - You can also add filtering directly in the dataset record.
Add the columns you want to include (joined fields and formulas work too).
Set the sorting of the data.
Save.
Add a new Dataset record
When your search has been saved, go to your layout and navigate to the Dataset subtab and click on the New Dataset button.
In the field Type select the dataset type Search. The form will automatically display the fields relevant for this dataset type.
Name: The name of your dataset. This name works as the reference to this search when adding the data in your code. Remember to be consistent in how you name you datasets. Omit spaces and special characters.
Saved Search: Add your saved search. The search is only available for selection if it has been set to public in the previous step.
If you want to filter your dataset:
Use Filter Expression: If you want to use a filter expression (which will allow "AND" and "OR" and more complex filtering) tick this check box. When ticked, a new text area field called Filter Expression will be displayed in which you can add your filter expression. The below three filtering fields will be hidden.
Filter Field: Add the id of the field you want to use for your filter in this field.
Filter Operator: Add the filter operator (e.g. anyof).
Filter Value: Add the filter value (e.g. {id}).
Group By: Only applicable for the other search dataset type Custom Label Search.
Max Search Result: gIf you only want to include a fixed number of results, e.g. only the first 5 results of the search, you can add that number here.
Once your dataset record has been saved you can access the dataset from the context menu. The name of your dataset will be displayed in the library and when expanded you can choose to do one of the following:
Insert a specific fields
This option adds the FreeMarker tag for that specific field and for the first result only. If you have a search with multiple results and you want to print all of them, the next option should probably be used.
Insert a complete table
This option will add the necessary code to print the entire search result including headers. It will loop through the seach result using the <#list> FreeMarker method.
To insert the code, simply double-click on the option from the tab library.
On the right is an image of how it looks like when the complete table has been inserted for the search used in the example.
In the <thead> section (row 25 - 34) the labels are added as table headers using the @label extension of the FreeMarker tag. Since we only want to print the labels once we only print from the first result of the search (using 0 index [0] ).
The <#list> method will leep through the search result and refer to each result as "item". For each result it will add a row (<tr>) and the columns (<td>) from the search.
Since this is done using HTML and FreeMarker you can change how the data is printed in your own layout. If you want to print it as a bullet point list instead for example you can remove the table-related tags and use the tags for HTML formatted lists instead.
Formula fields in Searches
Of course you can add a dataset using a saved search containing one or multiple formula fields (text, numeric, percent, date, date/time and currency). However, you need to think of the following.
When using the dataset type Search it is not mandatory to assign your search column a custom label. A custom label will however make it easier for you to read and follow your code in the editor when it comes to the formula fields. It it however advised to not add any custom label for the regular fields added your search.
The reference key to your formula column field will be built in the following way:
The first part will always be the internal id of the field followed by an underscore.
formulatext_
formulanumeric_
formulacurrency_
formulapercent_
formuladate_
formuladatetime_
The column label will then be automatically added to the string. If you use a custom label, that label will be added after the underscore. If no label is used, the field id will be added as the label.
For example: formulatext_formulatext if no label and formulatext_mylabel with custom label
Lastly, a sequential numbering will be added starting with 1 to make sure that no columns get the same reference keys. If you would have two formula text columns for example without a custom label they would be both called formulatext_formulatext. To handle this, a number is added at the very end of the string based on the ordering in the saved search. As a result the example with the two formula text fields will instead be defined as formulatext_formulatext1 and formulatext_formulatext2.
Please note that the numbers are always added for the Search dataset type.
Add Base Record from Search
Most often your layout will be based on a specific record type, a so-called base record. The base record is often defined using the dataset type Record, read chapter Record for more information.
You can however also choose to use a saved search to define the base record type. Please note however that the type Record will always take precedence over this type when it comes to defining the base record.
Instructions:
Create a saved search based on your record and add the required columns. Make sure to set the search as Public.
Navigate to Dataset - New Dataset and choose "Search" in Type.
Select your search in the Saved Search field. Before saving, also make sure to fill in Filter Field, Filter Operator and Filter Value. Read more about filtering options here.
When you are done with the above, click on Save.
In order for your added search to be defining the base record of your layout, it must meet the following criteria:
The Filter Value must be dynamic and using { }. Most often it will say {id}.
If you add a search but the Filter Value is empty or, as in the example below on the first line, is hard-coded it will not be considered a base record.
It must be the first search added to your datasets fulfilling the above criterion.
If you add two searches that both have { } filter values, the one you added first will be considered to be the base record search.
