OVERVIEW
The Word Plugin makes it possible to create a Microsoft Word® document without the need to have Microsoft Word® installed and platform independent. Because there is no need to have Microsoft Word® installed it is possible to generate a document from any Smart, Web, Headless and NG client!
The Word Plugin supports features like document creation, content manipulation, mail merge, and full reporting abilities.
Content manipulation is done, amongst others, by moving to bookmarks and inserting text, images, fonts and other formatting.
It is also possible to insert data bookmark per bookmark or by inserting a dataset, foundset or record.
Traditional mail merge for simple content insertion is fully supported. This handles simple things like labels or other printable data exports.
New in 2020 is support for full reporting tools. The plugin uses LINQ templates to allow you to build advanced reports that are simple enough for customers to edit and don’t require any special developer tools. Features like standard data merge, row looping, foundset relations, calculations, content formatting, aggregates, conditional expressions and many more are supported. These can generate beautiful reports with formatted data, charts, and images.
You can export with several document formats among which:
- DOC, DOCM, DOCX etc. MS Word®
- PDF Portable Document Format
- RTF Rich Text Format
- TEXT Text Format
- HTML HyperText Markup Language
The document format can be chosen by adding the correct extension or save format.
The included sample solution shows you the how you can create a new blank document or a document based on an existing template/document (included).
Some of the available methods in the Document object are:
- Document. replaceBookmark – Replace with the entered text (or array of textlines)
- Document. replaceBookmarks – Replace with the columnnames and row values (arrays), dataset, foundset or record
- Document. gotoStart – Go to the beginning of the Microsoft Word® document
- Document. totEnd – Go to the end of the Microsoft Word® document
- Document. gotoBookmark – Go to the bookmark by name
- Document. insertDocument – Insert a (Microsoft Word®) document at the selected position
- Document. insertPagebreak – Insert a pagebreak at the selected position
- Document. insertImage – Insert an image at the selected position
- Document. insertText – Insert the entered text (or array of textlines) at the selected position
Some of the available properties in the Document object are:
- Document. font – Set the font (family, style and size)
- Document. fontColor – Set a new font color
BENEFITS
- Generate a native MS Word® document direct from your solution.
- Use MS Word® templates to generate a new document.
- Generate mail-merge documents.
- Use MS Word® to build report templates and allow your end users to customize them to their individual needs.
Watch the Word Plugin featured on Servoy Tech Series:
COMPATIBILITY
 |
 |
Smart client | Headless client | Web client | Mobile client | NG client | |||
|---|---|---|---|---|---|---|---|---|---|
| 8.0+ | 1.6+ | – | |||||||
| 7.0+ | 1.6+ | – | n/a | ||||||
| 6.1+ | 1.6+ | n/a | n/a |
DOCUMENTATION
We published our API Specifications for the Word Plug-in as a future and current reference.
After downloading the Word Plug-in using our Components Manager a sample solution {servoy_root}/solutions/it2be-examples/it2be-word.servoy is installed.
You can import the sample solution into Servoy Developer and you will have some (basic) code examples of how to use the Word Plug-in.
Use this merge_example.docx with the sample below to see what the template syntax looks like. Make sure bookmarks are visible in your Word setup.
// Path to template should always be complete absolute path var vDocument = plugins.it2be_word.openDocument( "C:\\path\\to\\merge_example.docx"); // Prepare the data. Column names should match merge fields vQuery = "SELECT company_name, company_logo, firstname, lastname, fax_direct FROM yourtable WHERE company_name IS NOT NULL"; vDataSet = databaseManager.getDataSetByQuery( databaseManager.getDataSourceServerName( controller.getDataSource( ) ), vQuery, null, -1 ); // Mailmerge the document with a foundset or dataset vDocument.mailMerge( vDataSet ); // You can also merge generic bookmarks. var vText = utils.dateFormat( new Date( ), i18n.getDefaultDateFormat( ) ); vDocument.replaceBookmark( "body", "This is a mail merge sample.\n\nThere is nothing more to it than creating a template with merge-fields:" ); vDocument.replaceBookmark( "date", vText ); vDocument.replaceBookmark( "user", "security.getUserName()" ); //write to file var outputFileName = "invoice_" + utils.dateFormat(new Date(), "yyyy-MM-dd-HH-mm-ss") + ".doc"; var outputFile = plugins.file.getDefaultUploadLocation() + "\\" + outputFileName; vDocument.save(outputFile, plugins.it2be_word.DOCUMENT_FORMAT.PDF);
Use this invoice_example.docx with the sample below to see what the template syntax looks like.
//Prepare the data
var fs = datasources.db.invoices.getFoundSet();
//Items in the template can be referenced by second parameter
var invoicesDataSource = plugins.it2be_word.createLinqDataSource(fs, "invoices");
//Add related data
invoicesDataSource.addRelatedDataSource("invoices_to_orders", "order");
invoicesDataSource.addRelatedDataSource("orders_to_customers", "customer");
invoicesDataSource.addRelatedDataSource("orders_to_employees", "employee");
invoicesDataSource.addRelatedDataSource("orders_to_order_details", "details");
invoicesDataSource.addRelatedDataSource("order_details_to_products", "product");
//Perform the merge
var templateDocument = plugins.it2be_word.openDocument("C:\\path\\to\\invoice_example.docx");
templateDocument.mergeLinqTemplate(invoicesDataSource);
//write to file
var outputFileName = "invoice_" + utils.dateFormat(new Date(), "yyyy-MM-dd-HH-mm-ss") + ".doc";
var outputFile = plugins.file.getDefaultUploadLocation() + "\\" + outputFileName;
templateDocument.save(outputFile, plugins.it2be_word.DOCUMENT_FORMAT.PDF);
IF/THEN/ELSE:
<<if [conditional_expression1]>> template_option1 <<elseif [conditional_expression2]>> template_option2 <<else>> default_template_option <</if>> //Example You have chosen <<if [!items.Any()]>>no items<<else>><<[items.Count()]>> item(s)<</if>>.
Formatting Data:
<<[expression]:"format" -html>> // HTML <<["<b>Bold</b> and <i>italic</i> text"] -html>> // Date <<[someDate]:"yyyy.MM.dd">> //upper/lower/cap/firstCap <<[something]:upper>> //Combination <<[someDate]:"MMMM":upper>
Looping
<<foreach [variable_type variable_name in sequence_expression]>> data_band_body <</foreach>> //Example: <<foreach [order in orders]>><<[order.total]:"$#,###.00">>, <</foreach>>
Variables
<<var [s = "Hello, "]>><<[s]>><<var [s = "World!"]>><<[s]>>
See our Invoice Example for a real world template with complex examples.
FAQ
There can be many reasons for this behaviour but one of the reasons, reported by Roland Philipp from om computer, was the use of a non-standard quotes.
It might even be caused by other characters that are non-standard.
The problem is that it is not easy to catch them so an exception is not thrown either.
So, when you experience a problem like this, please check for such characters first.
It might save you some time!
In the below example I make use of the Tools Plugin to save the file in a ‘safe’ location on the webserver.
But you can of course use your own method for that.
By using the Servoy File Plugin as shown in the code example you can save (download) the resulting byte[] to the browser default ‘downloads’ folder.
This should do the trick!
vOutputFile = vDocument.save(plugins.it2be_tools.server().userHome + "/document.docx");</p>
<p>application.output(vOutputFile, LOGGINGLEVEL.INFO);</p>
<p>vData = plugins.file.readFile(vOutputFile);</p>
<p>vResult = plugins.file.writeFile("document.docx", vData);</p>
<p>application.output(vResult, LOGGINGLEVEL.INFO);
Chances are that you still have a library installed for Java 5. It should work when you remove ~/plugins/it2be-word/aspose-words-jdk15.jar from your (current) Servoy installation.
RELEASE NOTES
BUY NOW
Developer
One developer & unlimited deployment
- +35% p/y
maintenance fee
Site
Team of developers & unlimited deployment
- +35% p/y
maintenance fee