Wordize 25.5 Released

Wordize
1

We are happy to announce the new monthly 25.5 version of Wordize is published.

Issue Description
WRDZNET‑54 Incorrect metadata in documents generated by Wordize library
WRDZNET-31 Add possibility to use text shaping in Wordize.
WRDZNET-51 Implement Hyphenation wrapper in Wordize.

What’s new

Using Text Shaping

Enabling text shaping globally:

Wordize.Settings.EnableTextShaping = true;

Enabling text shaping for concrete operation:

ConverterContext context = new ConverterContext();
context.LayoutOptions.EnableTextShaping = true;

Converter.Create(context)
    .From(inPath)
    .To(outPath)
    .Execute();

Using Hyphenation

To use the hyphenation feature, first register a hyphenation dictionary.The following code example shows how to load hyphenation dictionaries for the specified languages from a file:

Wordize.Settings.Hyphenation.RegisterDictionary("en-US", @"C:\Temp\hyph_en_US.dic");
Wordize.Settings.Hyphenation.RegisterDictionary("de-CH", @"C:\Temp\hyph_de_CH.dic");

The following code example shows how to load hyphenation dictionaries for the specified language from a stream:

using(Stream stream = File.OpenRead(@"C:\Temp\hyph_de_CH.dic"))
    Wordize.Settings.Hyphenation.RegisterDictionary("de-CH", stream);

IHyphenationCallback can be used to get requested languages:

Wordize.Settings.Hyphenation.Callback = new HyphenationRequestsCollector();

Converter.Create()
    .From(@"C:\Temp\in.docx")
    .To(@"C:\Temp\out.pdf")
    .Execute();

private class HyphenationRequestsCollector : IHyphenationCallback
{
    public void RequestDictionary(string language)
    {
        Console.WriteLine(language);
    }
}

Saving Result of Action to Array of Image Streams

Comparer

New method introduced:

/// <summary>
/// Compares two documents and saves the differences as images.
/// Each item in the returned array represents a single page of the output rendered as an image.
/// </summary>
/// <param name="v1">The original document.</param>
/// <param name="v2">The modified document.</param>
/// <param name="saveOptions">The output's image save options.</param>
/// <param name="author">Initials of the author to use for revisions.</param>
/// <param name="dateTime">The date and time to use for revisions.</param>
/// <param name="compareOptions">Document comparison options.</param>
public static Stream[] CompareToImages(string v1, string v2, ImageSaveOptions saveOptions, string author, DateTime dateTime, CompareOptions compareOptions = null)

/// <summary>
/// Compares two documents and saves the differences as images.
/// Each item in the returned array represents a single page of the output rendered as an image.
/// </summary>
/// <param name="v1">The original document.</param>
/// <param name="v2">The modified document.</param>
/// <param name="saveOptions">The output's image save options.</param>
/// <param name="author">Initials of the author to use for revisions.</param>
/// <param name="dateTime">The date and time to use for revisions.</param>
/// <param name="compareOptions">Document comparison options.</param>
public static Stream[] CompareToImages(Stream v1, Stream v2, ImageSaveOptions saveOptions, string author, DateTime dateTime, CompareOptions compareOptions = null)

Use cases:

Stream[] pages = Comparer.CompareToImages("v1.docx", "v2.docx", new ImageSaveOptions(SaveFormat.Png), "Wordize", Datetime.Now);

using (Stream v1Stream = File.OpenRead("v1.docx"))
using (Stream v2Stream = File.OpenRead("v2.docx"))
{
    Stream[] pages = Comparer.CompareToImages(v1Stream, v2Stream, new ImageSaveOptions(SaveFormat.Png), "Wordize", Datetime.Now);
    // .................
}

Conerter

API changes (Applies only to Wordize)

Old:

public static Stream[] ConvertToImages(string inputFile, SaveFormat saveFormat)
public static Stream[] ConvertToImages(Stream inputStream, SaveFormat saveFormat)

New:

public static Stream[] ConvertToImages(string inputFile, ImageSaveOptions saveOptions)
public static Stream[] ConvertToImages(Stream inputStream, ImageSaveOptions saveOptions)

MailMerger

New API

/// <summary>
/// Performs a mail merge operation for a single record and renders the result to images.
/// </summary>
/// <param name="inputFileName">The input file name.</param>
/// <param name="saveOptions">The output's save options.</param>
/// <param name="fieldNames">Array of merge field names. Field names are not case sensitive. If a field name that is not found in the document is encountered, it is ignored.</param>
/// <param name="fieldValues">Array of values to be inserted into the merge fields. Number of elements in this array must be the same as the number of elements in fieldNames.</param>
/// <param name="mailMergeOptions">Mail merge options.</param>
public static Stream[] ExecuteToImages(string inputFileName, ImageSaveOptions saveOptions, string[] fieldNames, object[] fieldValues, MailMergeOptions mailMergeOptions = null)

/// <summary>
/// Performs a mail merge operation for a single record and renders the result to images.
/// </summary>
/// <param name="inputStream">The input file stream.</param>
/// <param name="saveOptions">The output's save options.</param>
/// <param name="fieldNames">Array of merge field names. Field names are not case sensitive. If a field name that is not found in the document is encountered, it is ignored.</param>
/// <param name="fieldValues">Array of values to be inserted into the merge fields. Number of elements in this array must be the same as the number of elements in fieldNames.</param>
/// <param name="mailMergeOptions">Mail merge options.</param>
public static Stream[] ExecuteToImages(Stream inputStream, ImageSaveOptions saveOptions, string[] fieldNames, object[] fieldValues, MailMergeOptions mailMergeOptions = null)

/// <summary>
/// Performs mail merge from a DataRow into the document  and renders the result to images.
/// </summary>
/// <param name="inputFileName">The input file name.</param>
/// <param name="saveOptions">The output's save options.</param>
/// <param name="dataRow">Row that contains data to be inserted into mail merge fields. Field names are not case sensitive. If a field name that is not found in the document is encountered, it is ignored.</param>
/// <param name="mailMergeOptions">Mail merge options.</param>
public static Stream[] ExecuteToImages(string inputFileName, ImageSaveOptions saveOptions, DataRow dataRow, MailMergeOptions mailMergeOptions = null)

/// <summary>
/// Performs mail merge from a DataRow into the document and renders the result to images.
/// </summary>
/// <param name="inputStream">The input file stream.</param>
/// <param name="saveOptions">The output's save options.</param>
/// <param name="dataRow">Row that contains data to be inserted into mail merge fields. Field names are not case sensitive. If a field name that is not found in the document is encountered, it is ignored.</param>
/// <param name="mailMergeOptions">Mail merge options.</param>
public static Stream[] ExecuteToImages(Stream inputStream, ImageSaveOptions saveOptions, DataRow dataRow, MailMergeOptions mailMergeOptions = null)

/// <summary>
/// Performs mail merge from a DataRow into the document and renders the result to images.
/// </summary>
/// <param name="inputFileName">The input file name.</param>
/// <param name="saveOptions">The output's save options.</param>
/// <param name="dataTable">Table that contains data to be inserted into mail merge fields. Field names are not case sensitive. If a field name that is not found in the document is encountered, it is ignored.</param>
/// <param name="mailMergeOptions">Mail merge options.</param>
public static Stream[] ExecuteToImages(string inputFileName, ImageSaveOptions saveOptions, DataTable dataTable, MailMergeOptions mailMergeOptions = null)

/// <summary>
/// Performs mail merge from a DataRow into the document and renders the result to images.
/// </summary>
/// <param name="inputStream">The input file stream.</param>
/// <param name="saveOptions">The output's save options.</param>
/// <param name="dataTable">Table that contains data to be inserted into mail merge fields. Field names are not case sensitive. If a field name that is not found in the document is encountered, it is ignored.</param>
/// <param name="mailMergeOptions">Mail merge options.</param>
public static Stream[] ExecuteToImages(Stream inputStream, ImageSaveOptions saveOptions, DataTable dataTable, MailMergeOptions mailMergeOptions = null)

/// <summary>
/// Performs mail merge from a DataTable into the document with mail merge regions and renders the result to images.
/// </summary>
/// <param name="inputFileName">The input file name.</param>
/// <param name="saveOptions">The output's save options.</param>
/// <param name="dataTable">Table that contains data to be inserted into mail merge fields. Field names are not case sensitive. If a field name that is not found in the document is encountered, it is ignored.</param>
/// <param name="mailMergeOptions">Mail merge options.</param>
public static Stream[] ExecuteWithRegionsToImages(string inputFileName, ImageSaveOptions saveOptions, DataTable dataTable, MailMergeOptions mailMergeOptions = null)

/// <summary>
/// Performs mail merge from a DataTable into the document with mail merge regions and renders the result to images.
/// </summary>
/// <param name="inputStream">The input file stream.</param>
/// <param name="saveOptions">The output's save options.</param>
/// <param name="dataTable">Table that contains data to be inserted into mail merge fields. Field names are not case sensitive. If a field name that is not found in the document is encountered, it is ignored.</param>
/// <param name="mailMergeOptions">Mail merge options.</param>
public static Stream[] ExecuteWithRegionsToImages(Stream inputStream, ImageSaveOptions saveOptions, DataTable dataTable, MailMergeOptions mailMergeOptions = null)

/// <summary>
/// Performs mail merge from a DataSet into the document with mail merge regions and renders the result to images.
/// </summary>
/// <param name="inputFileName">The input file name.</param>
/// <param name="saveOptions">The output's save options.</param>
/// <param name="dataSet">DataSet that contains data to be inserted into mail merge fields.</param>
/// <param name="mailMergeOptions">Mail merge options.</param>
public static Stream[] ExecuteWithRegionsToImages(string inputFileName, ImageSaveOptions saveOptions, DataSet dataSet, MailMergeOptions mailMergeOptions = null)

/// <summary>
/// Performs mail merge from a DataSet into the document with mail merge regions and renders the result to images.
/// </summary>
/// <param name="inputStream">The input file stream.</param>
/// <param name="saveOptions">The output's save options.</param>
/// <param name="dataSet">DataSet that contains data to be inserted into mail merge fields.</param>
/// <param name="mailMergeOptions">Mail merge options.</param>
public static Stream[] ExecuteWithRegionsToImages(Stream inputStream, ImageSaveOptions saveOptions, DataSet dataSet, MailMergeOptions mailMergeOptions = null)

Use cases:

DataTable dt = new DataTable();
dt.Columns.Add("FirstName");
dt.Columns.Add("SecondName");

dt.Rows.Add("James", "Bond");
dt.Rows.Add("John", "Doe");

Stream[] pages = MailMerger.ExecuteToImages("in.docx", new ImageSaveOptions(SaveFormat.Png), dt);

Merger

New methods introduced:

/// <summary>
/// Merges the given input documents into a single output document using specified input output file names and save options.
/// Renders the output to images.
/// </summary>
/// <param name="inputFiles">The input file names.</param>
/// <param name="saveOptions">The save options.</param>
/// <param name="mergeFormatMode">Specifies how to merge formatting that clashes.</param>
public static Stream[] MergeToImages(string[] inputFiles, ImageSaveOptions saveOptions, MergeFormatMode mergeFormatMode)

/// <summary>
/// Merges the given input document streams into a single output document using specified image save options.
/// Renders the output to images.
/// </summary>
/// <param name="inputStreams">The input file streams.</param>
/// <param name="saveOptions">The save options.</param>
/// <param name="mergeFormatMode">Specifies how to merge formatting that clashes.</param>
public static Stream[] MergeToImages(Stream[] inputStreams, ImageSaveOptions saveOptions, MergeFormatMode mergeFormatMode)

Use cases:

Stream[] pages = Merger.MergeToImages(new string[] { "in1.pdf", "in2.docx" }, new ImageSaveOptions(SaveFormat.Png), MergeFormatMode.KeepSourceFormatting);

using (Stream pdfStream = File.OpenRead("in1.pdf"))
using (Stream docxStream = File.OpenRead("in2.docx"))
{
    Stream[] pages = Merger.MergeToImages(new Stream[] { pdfStream, docxStream }, new ImageSaveOptions(SaveFormat.Png), MergeFormatMode.KeepSourceFormatting);
    // ..............
}

Replacer

New method introduced:

/// <summary>
/// Replaces all occurrences of a specified character string pattern with a replacement string in the input file.
/// Renders output to images.
/// </summary>
/// <param name="inputFileName">The input file name.</param>
/// <param name="saveOptions">The save options.</param>
/// <param name="pattern">A string to be replaced.</param>
/// <param name="replacement">A string to replace all occurrences of pattern.</param>
/// <param name="options"><see cref="FindReplaceOptions"/> object to specify additional options.</param>
public static Stream[] ReplaceToImages(string inputFileName, ImageSaveOptions saveOptions, string pattern, string replacement, FindReplaceOptions options = null)

/// <summary>
/// Replaces all occurrences of a specified character string pattern with a replacement string in the input file.
/// Renders output to images.
/// </summary>
/// <param name="inputStream">The input file stream.</param>
/// <param name="saveOptions">The save options.</param>
/// <param name="pattern">A string to be replaced.</param>
/// <param name="replacement">A string to replace all occurrences of pattern.</param>
/// <param name="options"><see cref="FindReplaceOptions"/> object to specify additional options.</param>
public static Stream[] ReplaceToImages(Stream inputStream, ImageSaveOptions saveOptions, string pattern, string replacement, FindReplaceOptions options = null)

/// <summary>
/// Replaces all occurrences of a specified regular expression pattern with a replacement string in the input file.
/// Renders output to images.
/// </summary>
/// <param name="inputFileName">The input file name.</param>
/// <param name="saveOptions">The save options.</param>
/// <param name="pattern">A regular expression pattern used to find matches.</param>
/// <param name="replacement">A string to replace all occurrences of pattern.</param>
/// <param name="options"><see cref="FindReplaceOptions"/> object to specify additional options.</param>
public static Stream[] ReplaceToImages(string inputFileName, ImageSaveOptions saveOptions, Regex pattern, string replacement, FindReplaceOptions options = null)

/// <summary>
/// Replaces all occurrences of a specified regular expression pattern with a replacement string in the input file.
/// Renders output to images.
/// </summary>
/// <param name="inputStream">The input file stream.</param>
/// <param name="saveOptions">The save options.</param>
/// <param name="pattern">A regular expression pattern used to find matches.</param>
/// <param name="replacement">A string to replace all occurrences of pattern.</param>
/// <param name="options"><see cref="FindReplaceOptions"/> object to specify additional options.</param>
public static Stream[] ReplaceToImages(Stream inputStream, ImageSaveOptions saveOptions, Regex pattern, string replacement, FindReplaceOptions options = null)

Use cases:

Stream[] pages = Replacer.ReplaceToImages("in.docx", new ImageSaveOptions(SaveFormat.Png), "document", "(DOCUMENT)");

using (Stream inStream = File.OpenRead("in.docx"))
{
    Stream[] pages = Replacer.ReplaceToImages(inStream, new ImageSaveOptions(SaveFormat.Png), "document", "(DOCUMENT)");
    // ...................
}

ReportBuilder

New methods introduced:

/// <summary>
/// Populates the template document with data from multiple sources.
/// Renders the output to images.
/// </summary>
/// <param name="inputFileName">The input file name.</param>
/// <param name="saveOptions">The output's save options.</param>
/// <param name="data">An array of data source objects.</param>
/// <param name="dataSourceNames">An array of names to reference the data source objects within the template.</param>
/// <param name="reportBuilderOptions">Additional report build options.</param>
public static Stream[] BuildReportToImages(string inputFileName, ImageSaveOptions saveOptions, object[] data, string[] dataSourceNames, ReportBuilderOptions reportBuilderOptions = null)

/// <summary>
/// Populates the template document with data from multiple sources.
/// Renders the output to images.
/// </summary>
/// <param name="inputStream">The input file stream.</param>
/// <param name="saveOptions">The output's save options.</param>
/// <param name="data">An array of data source objects.</param>
/// <param name="dataSourceNames">An array of names to reference the data source objects within the template.</param>
/// <param name="reportBuilderOptions">Additional report build options.</param>
public static Stream[] BuildReportToImages(Stream inputStream, ImageSaveOptions saveOptions, object[] data, string[] dataSourceNames, ReportBuilderOptions reportBuilderOptions = null)

Use cases:

public class DummyData
{
    public string Name { get; set; }
    public string Position { get; set; }
}

DummyData data = new DummyData() { Name = "James Bond", Position = "Spy" };
Stream[] pages = ReportBuilder.BuildReportToImages("in.docx", new ImageSaveOptions(SaveFormat.Png), new object[] { data }, new string[] { "data" });

DummyData data = new DummyData() { Name = "James Bond", Position = "Spy" };
using (Stream inStream = File.OpenRead("in.docx"))
{
    Stream[] pages = ReportBuilder.BuildReportToImages(inStream, new ImageSaveOptions(SaveFormat.Png), new object[] { data }, new string[] { "data" });
    // ........................
}

Watermarker

New method introduced:

/// <summary>
/// Adds a text watermark into the document with options. Renders the output to images.
/// </summary>
/// <param name="inputFileName">The input file name.</param>
/// <param name="saveOptions">The save options.</param>
/// <param name="watermarkText">Text that is displayed as a watermark.</param>
/// <param name="options">Defines additional options for the text watermark.</param>
public static Stream[] SetWatermarkToImages(string inputFileName, ImageSaveOptions saveOptions, string watermarkText, TextWatermarkOptions options = null)

/// <summary>
/// Adds a text watermark into the document with options. Renders the output to images.
/// </summary>
/// <param name="inputStream">The input file stream.</param>
/// <param name="saveOptions">The save options.</param>
/// <param name="watermarkText">Text that is displayed as a watermark.</param>
/// <param name="options">Defines additional options for the text watermark.</param>
public static Stream[] SetWatermarkToImages(Stream inputStream, ImageSaveOptions saveOptions, string watermarkText, TextWatermarkOptions options = null)

/// <summary>
/// Adds an image watermark into the document with options. Renders the output to images.
/// </summary>
/// <param name="inputFileName">The input file name.</param>
/// <param name="saveOptions">The save options.</param>
/// <param name="watermarkImageBytes">Image bytes that is displayed as a watermark.</param>
/// <param name="options">Defines additional options for the image watermark.</param>
public static Stream[] SetWatermarkToImages(string inputFileName, ImageSaveOptions saveOptions, byte[] watermarkImageBytes, ImageWatermarkOptions options = null)

/// <summary>
/// Adds an image watermark into the document with options. Renders the output to images.
/// </summary>
/// <param name="inputStream">The input stream.</param>
/// <param name="saveOptions">The save options.</param>
/// <param name="watermarkImageStream">Image stream that is displayed as a watermark.</param>
/// <param name="options">Defines additional options for the image watermark.</param>
public static Stream[] SetWatermarkToImages(Stream inputStream, ImageSaveOptions saveOptions, Stream watermarkImageStream, ImageWatermarkOptions options = null)

Use cases:

Stream[] pages = Watermarker.SetWatermarkToImages("in.docx", new Saving.ImageSaveOptions(SaveFormat.Png), "My Cool Watermark");

using (Stream inStream = File.OpenRead("in.docx"))
{
    Stream[] pages = Watermarker.SetWatermarkToImages(inStream, new Saving.ImageSaveOptions(SaveFormat.Png), "My Cool Watermark");
    // .....................................................
}

Stream[] pages = Watermarker.SetWatermarkToImages("in.docx", new Saving.ImageSaveOptions(SaveFormat.Png), File.ReadAllBytes("watermark.png"));

using (Stream inStream = File.OpenRead("in.docx"))
using (Stream imgStream = File.OpenRead("watermark.png"))
{
    Stream[] pages = Watermarker.SetWatermarkToImages(inStream, new Saving.ImageSaveOptions(SaveFormat.Png), imgStream);
    // ...................................
}
2