GroupDocs.Assembly for .NET 20.3 Release Notes

Major Features

Supported dynamic insertion of documents and images from Base64-encoded bytes and dynamic checkbox value setting.

Full List of Features Covering all Changes in this Release

KeySummaryCategory
ASSEMBLYNET-145 Support dynamic checkbox value setting for Word Processing documents Feature 
ASSEMBLYNET-147 Support dynamic image and document insertion from Base64-encoded bytes Feature 
ASSEMBLYNET-148 ArgumentException is thrown if image or document expression returns an empty string Bug 

Public API and Backward Incompatible Changes 

Supported dynamic insertion of documents and images from Base64-encoded bytes and dynamic checkbox value setting

Inserting Documents Dynamically

You can insert contents of outer documents to your reports dynamically using doc tags. A doc tag denotes a placeholder within a template for a document to be inserted during runtime.

Syntax of a doc tag is defined as follows.

<<doc [document_expression]>>

An expression declared within a doc tag is used by the assembler to load a document to be inserted during runtime. The expression must return a value of one of the following types:

  • A byte array containing document data
  • Stream instance able to read document data
  • An instance of the Document class
  • A string containing a document URI, path, or Base64-encoded document data

While building a report, an expression declared within a doc tag is evaluated and its result is used to load a document which content replaces the doc tag then.

By default, a document being inserted is not checked against template syntax and is not populated with data. However, you can enable this by using a build switch as follows.

<<doc [document_expression] -build>>

When a build switch is used, the assembler treats a document being inserted as a template that can access the following data available at the scope of a corresponding doc tag:

  • Data sources
  • Variables
  • A contextual object 
  • Known external types 

Inserting Images Dynamically

You can insert images to your reports dynamically using image tags. To declare a dynamically inserted image within your template, do the following steps:

  1. Add a textbox to your template at the place where you want an image to be inserted.
  2. Set common image attributes such as frame, size, and others for the textbox, making the textbox look like a blank inserted image.
  3. Specify an image tag within the textbox using the following syntax.
<<image [image_expression]>>

The expression declared within an image tag is used by the assembler to build an image to be inserted. The expression must return a value of one of the following types:

  • A byte array containing an image data
  • Stream instance able to read an image data
  • An Image object
  • A string containing an image URI, path, or Base64-encoded image data

While building a report, the following procedure is applied to an image tag:

  1. The expression declared within the tag is evaluated and its result is used to form an image.
  2. The corresponding textbox is filled with this image.
  3. The tag is removed from the textbox.

By default, the assembler stretches an image filling a textbox to the size of the textbox. However, you can change this behavior in the following ways:

  • To keep the width of the textbox and change its height preserving the ratio of the image, use the fitHeight switch as follows.
<<image [image_expression] -fitHeight>>
  • To keep the height of the textbox and change its width preserving the ratio of the image, use the fitWidth switch as follows.
<<image [image_expression] -fitWidth>>
  • To change the size of the textbox according to the size of the image, use the fitSize switch as follows.
<<image [image_expression] -fitSize>>
  • To change the size of the textbox according to the size of the image without increasing the size of the textbox, use the fitSizeLim switch as follows.
<<image [image_expression] -fitSizeLim>>

Setting Checkbox Values Dynamically

You can set checkbox values to either checked or unchecked in your reports dynamically by taking the following steps:

  1. Add a checkbox content control to your template at a place where you want it to appear in a result document.
  2. By editing content control properties, add a check tag to the title of the checkbox content control using the following syntax.
<<check [conditional_expression]>>

Here, conditional_expression defines a condition upon which the value of the checkbox content control is to be set to checked (or unchecked, if the condition is not met). The conditional expression must return a Boolean value.

While building a report, a conditional expression declared within a check tag is evaluated and the value of its containing checkbox content control is set accordingly. The check tag itself is removed then.