Today we look at how to print a long text on the last page of a custom Word Report. Some customers have the requirement to print terms and conditions on the last page of their sales quotes. This is exactly what we will do in this tutorial.
I assume that you have a working environment for Business Central in a Visual Studio Code Project. My examples are done using a Docker Container with Business Central 16. Have a look at this tutorial if you do not know how to copy a standard report including Word Layout or if you do not have a working environment yet.
List of Extensions We Will Use:
- AL Object Designer by Márton Sági
- AZ AL Dev Tools/AL Code Outline by Andrzej Zwierzchowski
- ALRunner by Tobias Fenster
What We Will Do
In order to print a long text on our Word Report, we first of all need a way to store this text in a table. Fields of type “Text” are out of the question for us, because according to Microsoft’s Object Specifications and Limitations they can contain a maximum of 2048 characters. But our terms and conditions could contain more than 2048 characters.
For this reason we will use the functionality of the field “Work Description” in the table “Sales Header” and build a similar functionality. The content of the terms and conditions will be stored in the table “Sales & Receivables Setup”.
In the end, all we have to do is add the long text on our Word Report and print it.
Below you will find the high-level steps for the experienced programmers who do not need too detailed instructions. For the ordinary mortals of us I will go into each of the high-level steps in more detail.
High Level Steps To Add Long Text on Word Report For Badasses
Add Long Text on Word Report:
- Copy Standard Report
Copy the standard report 1304 “Standard Sales – Quote” (.al and .docx) and change name and ID. This is the file that we work with.
- Create a table extension
Create a table extension for the table “Sales & Receivables Setup”. Insert a new field “Terms and Conditions” in the table extension according to the field “Work Description” including the functions GetTermsAndConditions and SetTermsAndConditions.
- Create a page extension
Create a page extension “Sales & Rec. Setup Extension”. Create a new group “Documents” for the page extension and place our new field in the group. Make sure that GetTermsAndConditions is called when opening the page and SetTermsAndConditions is called when validating the field.
- Enter Text
Enter a text in the new field.
- Include Field in Report (.al)
Include the field in the report by passing it as a column in the header DataItem. When initializing the report make sure that the content is retrieved from the Sales & Receivables Setup.
- Include Field in Layout (.docx)
Include the new field below the WorkDescription in the layout of the report. Ensure that a PageBreak is executed before the field is printed
- Publish and Run
Publish the report. Run it with “ALRunner: RunSelection” and print a sales offer. You are done, congratulations!
Detailed Steps To Add Long Text on Word Report For the Ordinary People
So much for the high level steps. Now comes the detailed instructions. Let’s go into battle!
1. Copy Standard Report
For this step I assume that you know how to copy a standard report. If not, please read my tutorial about it. To explain this step in detail would go beyond the scope of this article.
We use the AZ AL DevTools to copy the contents of the .al file for the report 1304 “Standard Sales – Quote” and paste it into a new file.
Finally, we export the layout “Sales Quote – Blue – Simple” from the Custom Report Layouts of our Business Central Web Client.
At this point we have two files (1). For a correct naming of the files I recommend to use the CRS Language Extension feature “CRS: Rename – Current File” after you have given your report a name in the .al file. I have dedicated a separate article to the CRS Language Extension if you want to know more about it.
We provide our new AL file with the ID 50100 and the name “Standard Sales – Quote Copy” (2). Afterwards we link the layout with our new .al file (3).
You can remove the RDLC layout property at this point. If you do not remove it, an empty layout is automatically created in your project when you run the Build Task.
2. Table Extension For Table “Sales & Receivables Setup”
We want to recreate the functionality of the field “Work Description” from the Sales Order. In the following screenshot you can see the “Work Description” in the Sales Order.
To view the code for the work description, we use the AL Object Designer. Open the AL Object Designer via the command window (Ctrl + Shift + P).
Advice from me: Assign a shortcut to AL Object Designer, because you will use it very often in your projects. I myself have assigned the NumPad2 shortcut to AL Object Designer:
We look for table 36 and open the definition of the table by clicking on the name “Sales Header”.
Then we search for the “Work Description” (1). We find the blob field with the ID 200 (2). But that is not all.
If we now continue our search, we will come across the functions “SetWorkDescription” and “GetWorkDescription”. These functions are necessary to set or get the contents of the “Work Description” field. Otherwise the field would always be displayed without contents in Pages. Leave this file open, we will need the contents in a moment.
We want exactly the same functionality for our field, which we will create in the “Sales & Receivables Setup” below the group “Dynamics 365 Sales”.
Let’s create a new table extension for the table “Sales & Receivables Setup” using the ttableext snippet.
Showtime. Copy the field definition of the field “Work Description” from the Sales Header into our table extension. Then also copy the functions GetWorkDescription and SetWorkDescription.
In our table extension we change Work Description to Terms and Conditions everywhere. The result looks like this:
3. Page Extension “Sales & Rec. Setup Extension”
Let’s go. For the next step we will have a look at the definition of the page “Sales Order”. Again we use the AL Object Designer.
If we search for “Work Description” here (1), we find a group “Work Description”, in which also an OnValidate trigger is defined (2).
Take a closer look at the code of the field within the group. Here, not the “Work Description” itself is used, but a global text variable WorkDescription.
This global variable is set in the OnValidate trigger with the table function “SetWorkDescription” when you change the value in the page.
To be able to display the content of the field on the page initially, the content of the field must be retrieved from the table with the function “GetWorkDescription”.
Enough with the jibber-jabber. Let’s get chopping. We create a Page Extension “Sales & Rec. Setup Extension” based on the functionality of the Sales Order. For this we add the code of the group “Work Description” after the group “Dynamics 365 Sales”. We change the caption of the group “Work Description” to “Documents”.
Then we change “Work Description” to “Terms and Conditions” everywhere. The result looks like this:
4. Set Terms and Conditions Text
Next we run “Run Without Debugging” (Ctrl + F5). As a result, your Web Client opens. Make sure to open it manually if it does not open automatically.
Open the Page Sales & Receivables Setup in your Web Client. It is time to get creative. Let’s add a text for our Terms and Conditions!
5. Integrate New Field in Report Dataset
Slowly we are approaching the end, we are already very far. We open the .al file of our report and create a new global variable “SalesReceivablesSetup”.
In the OnInitReport function, we make sure that we get the record from the Sales Receivables Setup table.
This is where it gets exciting. Optimally, the TermsAndConditions should be passed in the header Data Item. Navigating through the Data Items of a report can be an annoying task.
That’s why I built a shortcut into my Visual Studio Code Extension AL Navigator that allows you to jump through the Data Items of a report. If you have installed it, you can do the following to get to the right place quickly:
- Jump to the beginning of the file with Ctrl + Home
- Press Ctrl + Alt + D to get to the first Data Item
- Press Ctrl + Alt + D again to get to the beginning of the second Data Item
We insert this code above the Line Data Items:
Afterwards we execute the Build Task (Ctrl + Shift + B). This step is necessary so that we can access the new field in the Word layout.
6. Insert New Field in Layout
We are finished with the programming. Now it’s just a matter of clicking. A chimpanzee could do it just as well, so we can do it too. We right-click on our Word layout and click “Open Externally”.
The layout opens.
Check if you can see the Developer Tab. If not, activate the tab by following the steps in this tutorial.
Then open the XML Mapping Pane in the Developer tab.
Open the Custom XML part of our report in the opening XML Mapping Pane on the right.
So far so good. Next, we click in the free space below the “WorkDescription” field in our layout (1). Then we look for the field TermsAndConditions in the Data Item Header in our XML Mapping Pane. Right click on the field (2), select “Insert Content Control” (3) -> “Plain Text” (4).
Our new field is inserted. The result looks like this:
We mark the field, right click and open the paragraph settings.
In the tab “Line and Page Breaks” we select the option “Page break before”. This will cause our Terms and Conditions to be printed on a new page.
7. Publish and Run Report
We publish the report with Ctrl + F5. Ignore the opening browser. Then we jump to the first line of the report and execute the function “ALRunner: Run Selection”. This automatically opens the report in our Business Central Web Client.
I have previously created a sales quote with the number 1001. If you do not have any sales quote to test, then that is apparently not my problem, haha. This sales quote I now open with Preview.
Our first report of the quote looks just as unattractive as usual:
… and on the second/third page our Terms and Conditions are printed.
That’s it. In this tutorial we learned how to add a long text on our Custom Word Report. Congratulations, we did it.
If you are interested in how to print a long text in RDLC layout, this tutorial by Andrei Lungo might be interesting for you.
Have a nice week!