Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Scout/HowTo/3.9/Creating Word Reports with Docx4j"

< Scout‎ | HowTo‎ | 3.9
(Activate the Docx4j Support for a Scout Application)
 
(22 intermediate revisions by 2 users not shown)
Line 6: Line 6:
 
* How to export the resulting Word document (report)  
 
* How to export the resulting Word document (report)  
  
This how-to makes use of the Docx4j support provided on the Eclipse marketplace.  
+
This how-to makes use of the {{ScoutLink|Concepts|Docx4j}} support provided on the [http://marketplace.eclipse.org/content/docx4j-eclipse-scout Docx4j Eclipse marketplace].  
  
= Activate the Docx4j Support for a Scout Application =
+
== Activate the Docx4j Support for a Scout Application ==
  
The simplest way to integrate the Docx4j support in a Scout application is to tick the checkbox ''Docx4j Support'' in the Scout Object Properties of the Scout application as shown in the screenshot below.
+
The simplest way to integrate the [http://www.docx4java.org Docx4j] support in a Scout application is to tick the checkbox ''Docx4j Support'' in the Scout Object Properties of the Scout application as shown in the screenshot below.
  
 
[[Image:Download docx4j.png|600px]]
 
[[Image:Download docx4j.png|600px]]
Line 16: Line 16:
 
The SDK will then download the docx4j component and update the Scout project setup accordingly. Leave all default settings and accept the suggested proposals.
 
The SDK will then download the docx4j component and update the Scout project setup accordingly. Leave all default settings and accept the suggested proposals.
  
= Create Word Reports =
+
== Create Word Reports ==
  
 +
The simplest way to demonstrate the report generation feature is to add a string field and a button to a test form in your application. In the code below, it is assumed that the string field is called ''TemplateField'' and the button ''RunReportButton''.
  
    @Order(20.0)
+
<source lang="java">
    public class RunReportButton extends AbstractButton {
+
@Order(20.0)
 +
public class RunReportButton extends AbstractButton {
  
      @Override
+
  @Override
      protected String getConfiguredLabel() {
+
  protected String getConfiguredLabel() {
        return TEXTS.get("RunReport");
+
    return TEXTS.get("RunReport");
      }
+
  }
  
      @Override
+
  @Override
      protected void execClickAction() throws ProcessingException {
+
  protected void execClickAction() throws ProcessingException {
        File template = new File(getTemplateField().getValue());
+
    File template = new File(getTemplateField().getValue());
        File report = runReport(template);
+
    File report = runReport(template);
        SERVICES.getService(IShellService.class).shellOpen(report.getAbsolutePath());
+
   
      }
+
    // opens the filled in report using the default application to open this type of fields
     }
+
    SERVICES.getService(IShellService.class).shellOpen(report.getAbsolutePath());
 +
  }
 +
}
 +
</source>
 +
 
 +
In ''execClickAction'' we first get the template field. Where the user needs to provide the absolute path to a Word template file into the template field ''TemplateField''.
 +
 
 +
     C:/templates/invoice_template_sample.docx
 +
 
 +
As an example for this how-to we use a simple invoice Word template file [[Media:Invoice_template_sample.zip|Invoice_template_sample.zip]] (layout copied from [http://www.entrepreneur.com/formnet/form/746 www.entrepreneur.com]). In method ''runReport'' the report is prepared from the template document and shown using the ''shellOpen'' method which is available per default in any Scout application created with the Scout SDK. Now, let's look at the code to create the report.
 +
 
 +
<source lang="java">
 +
private File runReport(File template) throws ProcessingException {
 +
  //  copy original template file into temp file
 +
  File tmpFile = IOUtility.createTempFile(IOUtility.getTempFileName(".docx"),  IOUtility.getContent(template.getPath()));
 +
  DocxAdapter docxFile = new DocxAdapter(tmpFile);
 +
  Map<String, String> variables = new HashMap<String, String>();
 +
 
 +
  // populate doc variables
 +
  variables.put("Name", "John Doe");
 +
  variables.put("Phone", "(123) 456 78 90");
 +
  variables.put("CompanyName", "BSI Business Systems Integration AG");
 +
  variables.put("Email", "john.doe@bsiag.com");
 +
  variables.put("CompanyAddress", "Täfernstrasse 16a, 5405 Baden");
 +
  variables.put("InvoiceNo", "No. 2013-007");
 +
  variables.put("InvoiceDate", DateUtility.formatDate(new Date()));
 +
  variables.put("BillingName", "Jane Smith");
 +
  variables.put("PayableToName", "John Doe, BSI");
 +
  variables.put("SubTotal", "$1,530.00");
 +
  variables.put("SalesTax", "$229.50");
 +
  variables.put("Shipping", "$250.00");
 +
  variables.put("Total", "$2,009.50");
 +
     
 +
  // and content for embedded table
 +
  Object[][] orderItems = new Object[][]{
 +
      new Object[]{"1", "Table", "$800.00", "$800.00"},
 +
      new Object[]{"4", "Chair", "$150.00", "$600.00"},
 +
      new Object[]{"1", "Assembling", "$130.00", "$130.00"},
 +
  };
 +
 +
  // fill in doc variables, table content and create output file
 +
  docxFile.setFields(variables);
 +
  docxFile.fillTable(1, 1, 0, orderItems);
 +
  File reportFile = docxFile.save();
 +
     
 +
  return reportFile;
 +
}
 +
</source>
 +
 
 +
== Mapping Content into Word Templates ==
 +
 
 +
When we look at the corresponding Word template file, it becomes clear how the content is matched with the template.
 +
 
 +
[[image:Word_template_file.png|600px]]
 +
 
 +
Standard doc variables (use [ALT]+[F9] to toggle the visibility of doc variables in Word), such as '''{ DOCVARIABLE CompanyName \* MERGEFORMAT }''' in the screenshot above may simply be filled in with the following line of code.
 +
 
 +
<source lang="java">
 +
variables.put("CompanyName", "BSI Business Systems Integration AG");
 +
docxFile.setFields(variables);
 +
</source>
 +
 
 +
where ''variables'' is of type ''Map<String, String>''.
 +
 
 +
To fill in the content of a table we can look at the example table with the ''orderItems'' featuring attributes such as 'Quantity', 'Description', ...  The data for tables is prepared using 2-dimensional object arrays where the rows correspond to the rows in the template file.
 +
To populate a table in the template Word file we can then use the command in our example.
 +
 
 +
<source lang="java">
 +
Object[][] orderItems = //... your data here
 +
docxFile.fillTable(1, 1, 0, orderItems);
 +
</source>
 +
 
 +
The parameters for method ''fillTable'' are
 +
* ''tableIndex'' ('''1''' references the 2nd table in the example document)
 +
* ''startRow'' ('''1''' references the 2nd row in the order item table)
 +
* ''startColumn'' ('''0''' references the 1st column in the order item table)
 +
* ''data'' (the '''orderItems''' array)
 +
 
 +
Table index 1 is used for the example Word file as the first table in the Word file holds billing information such as ''Bill to:'' and ''Invoice''.
 +
 
 +
== The Result ==
 +
 
 +
Using the code and template above you may get the following output.
 +
 
 +
[[Image:Docx4j report generation.png]]
 +
 
 +
== See also ==
 +
* {{ScoutLink|Concepts|Docx4j}} on the wiki

Latest revision as of 03:28, 4 July 2013

This how-to describes how to:

  • Load a Microsoft Word (docx) template file
  • Load content into it's docvariables
  • How to pouplate tables
  • How to export the resulting Word document (report)

This how-to makes use of the The Scout documentation has been moved to https://eclipsescout.github.io/. support provided on the Docx4j Eclipse marketplace.

Activate the Docx4j Support for a Scout Application

The simplest way to integrate the Docx4j support in a Scout application is to tick the checkbox Docx4j Support in the Scout Object Properties of the Scout application as shown in the screenshot below.

Download docx4j.png

The SDK will then download the docx4j component and update the Scout project setup accordingly. Leave all default settings and accept the suggested proposals.

Create Word Reports

The simplest way to demonstrate the report generation feature is to add a string field and a button to a test form in your application. In the code below, it is assumed that the string field is called TemplateField and the button RunReportButton.

@Order(20.0)
public class RunReportButton extends AbstractButton {
 
  @Override
  protected String getConfiguredLabel() {
    return TEXTS.get("RunReport");
  }
 
  @Override
  protected void execClickAction() throws ProcessingException {
    File template = new File(getTemplateField().getValue());
    File report = runReport(template);
 
    // opens the filled in report using the default application to open this type of fields
    SERVICES.getService(IShellService.class).shellOpen(report.getAbsolutePath());
  }
}

In execClickAction we first get the template field. Where the user needs to provide the absolute path to a Word template file into the template field TemplateField.

   C:/templates/invoice_template_sample.docx

As an example for this how-to we use a simple invoice Word template file Invoice_template_sample.zip (layout copied from www.entrepreneur.com). In method runReport the report is prepared from the template document and shown using the shellOpen method which is available per default in any Scout application created with the Scout SDK. Now, let's look at the code to create the report.

private File runReport(File template) throws ProcessingException {
  //  copy original template file into temp file
  File tmpFile = IOUtility.createTempFile(IOUtility.getTempFileName(".docx"),   IOUtility.getContent(template.getPath()));
  DocxAdapter docxFile = new DocxAdapter(tmpFile);
  Map<String, String> variables = new HashMap<String, String>();
 
  // populate doc variables
  variables.put("Name", "John Doe");
  variables.put("Phone", "(123) 456 78 90");
  variables.put("CompanyName", "BSI Business Systems Integration AG");
  variables.put("Email", "john.doe@bsiag.com");
  variables.put("CompanyAddress", "Täfernstrasse 16a, 5405 Baden");
  variables.put("InvoiceNo", "No. 2013-007");
  variables.put("InvoiceDate", DateUtility.formatDate(new Date()));
  variables.put("BillingName", "Jane Smith");
  variables.put("PayableToName", "John Doe, BSI");
  variables.put("SubTotal", "$1,530.00");
  variables.put("SalesTax", "$229.50");
  variables.put("Shipping", "$250.00");
  variables.put("Total", "$2,009.50");
 
  // and content for embedded table
  Object[][] orderItems = new Object[][]{
      new Object[]{"1", "Table", "$800.00", "$800.00"},
      new Object[]{"4", "Chair", "$150.00", "$600.00"},
      new Object[]{"1", "Assembling", "$130.00", "$130.00"},
  };
 
  // fill in doc variables, table content and create output file
  docxFile.setFields(variables);
  docxFile.fillTable(1, 1, 0, orderItems);
  File reportFile = docxFile.save();
 
  return reportFile;
}

Mapping Content into Word Templates

When we look at the corresponding Word template file, it becomes clear how the content is matched with the template.

Word template file.png

Standard doc variables (use [ALT]+[F9] to toggle the visibility of doc variables in Word), such as { DOCVARIABLE CompanyName \* MERGEFORMAT } in the screenshot above may simply be filled in with the following line of code.

variables.put("CompanyName", "BSI Business Systems Integration AG");
docxFile.setFields(variables);

where variables is of type Map<String, String>.

To fill in the content of a table we can look at the example table with the orderItems featuring attributes such as 'Quantity', 'Description', ... The data for tables is prepared using 2-dimensional object arrays where the rows correspond to the rows in the template file. To populate a table in the template Word file we can then use the command in our example.

Object[][] orderItems = //... your data here
docxFile.fillTable(1, 1, 0, orderItems);

The parameters for method fillTable are

  • tableIndex (1 references the 2nd table in the example document)
  • startRow (1 references the 2nd row in the order item table)
  • startColumn (0 references the 1st column in the order item table)
  • data (the orderItems array)

Table index 1 is used for the example Word file as the first table in the Word file holds billing information such as Bill to: and Invoice.

The Result

Using the code and template above you may get the following output.

Docx4j report generation.png

See also

Copyright © Eclipse Foundation, Inc. All Rights Reserved.