What's New in GrapeCity Documents v5.1

GrapeCity Documents (GcDocs) is excited to announce the new v5.1 releases! Included in these releases are enhancements to our existing API's including advanced additions to digital signature support and enhancements to layers (optional content groups) support in GcPdf, enhanced editing experience in GcPdfViewer, enhancements to GcExcel Report Templates support, support for converting PDF and DOCX to SVG, implementation of GcGraphics for output to SVG in GcImaging, and improvements to GcWord API in Report Templates and Font Embedding. 

In addition to the above, there are many new additions catering to our customer requests. Read the full blog below.

GrapeCity Documents for PDF (GcPdf)

Support for PAdES B-LT and B-LTA levels of electronic signatures

Recently, GcPdf introduced the support of PAdES Standard for signing PDF documents which enable electronically signed documents remain valid for long periods. Over time, it may be possible to check if the signature was valid when it was signed – a concept known as Long-Term Validation. 

This is a special requirement for confidential or important documents. The validity of the signature should remain, even if the signing key or certificate has expired or the issuing certificate authority doesn’t exist anymore or the cryptographic algorithms used to create the electronic signature are not valid anymore. 

The ability to programmatically sign PDF documents with electronic signatures that comply with PAdES B-LT (signature with a long-term validation material) and B-LTA (signature providing long-term availability and integrity of validation material) levels has been added in this GcPdf release.

Two new classes have been implemented to support the LTV signatures:

• The Document Security Store: According to PDF specification, all information required to validate LTV signatures should be in Document Security Store (DSS). It is a PDF dictionary in the Document Catalog. The GrapeCity.Documents.Pdf.Security.DocumentSecurityStore class represents the DSS in GcPdf, and an instance of this class is accessible via the GcPdfDocument.SecurityStore property. The DocumentSecurityStore class allows the developer to add verification information for the signature.
• The Document Timestamp Signature is a signature of a special type that establishes the exact contents of the complete PDF file at the time indicated in the timestamp token—the GcPdfDocument.TimeStamp(...) method allows creating Document Timestamp Signature—the GcPdfDocument.TimeStamp()methods should be used in the same way as GcPdfDocument.Sign(...) methods. 

Following snapshot shows PAdES B-LTA level signature generated and added to the PDF document using GcPdf API:

Help | Demo

PDF Layers (Optional Content) enhancements

GcPdf supports adding layers to PDF documents programmatically to help arrange objects in a PDF that are specifically related to one another, such as a building architecture document with several designs for a house – ranging from the base architectural design to piping, electrical, etc. – over the base design, or a multi-language document with multiple languages displayed on separate layers.

Separate layers of content can be added to a single PDF using GcPdfDocument.OptionalContentProperties class that provides an extensive API to work with PDF layers. You can also show/hide layers in GrapeCity Documents PDF Viewer. 

In the v5.1 release, additional functionalities have been added to this support. Suppose you have a PDF document with multiple layers, and you want to find some text in a particular layer or want to extract some information from a certain layer. In that case, you can now perform such operations by passing an instance of the ViewState class to various methods of GcPdf. This class has been introduced to represent transient environment settings so that operations such as text search or saving PDF pages to images can be performed in the context of programmatically specified settings. 

Also new in this release is the ability to remove layer content using Page.RemoveLayersContent or OptionalContentProperties.RemoveLayers methods.

Consider a multi-language product datasheet with content in different languages on separate layers. The following code shows how ViewState is used to export a page showing a non-default layer to an image (PNG).

The default layer is English, but we create an instance of ViewState and set the visibility of all layers but French in it to false, then we pass that ViewState to the Page.SaveAsPng() method so that the French layer is exported rather than the default English one.

using var fs = File.OpenRead("lang-layers.pdf");
var doc = new GcPdfDocument();
doc.Load(fs);
 
// Make a ViewState with all layers except French hidden:
var viewState = new ViewState(doc);
viewState.SetLayersUIStateExcept(false, "French");
viewState.SetLayersUIState(true, "French");
 
// Save page with French text only
// (without specifying the viewState, the page would be saved
// with default English text):
doc.Pages[0].SaveAsPng("lang-French.png", viewState);

The following screenshot illustrates the default view of the PDF and the exported PNG.

Help | Demo

Save Documents to SVG (GcPdf, GcWord, and GcImaging)

Compared to raster image formats such as JPEG and PNG, SVG is a vector format that can be rendered at any size without losing quality. This format gives designers and developers much control over the image appearance. It is also a standardized format for web graphics, designed to work with other web conventions like HTML, CSS, JavaScript, and the Document Object Model. Due to the many advantages of SVG, it is essential to use SVG images in documents, such as PDFs and images.

In the v5.0 release, we introduced a new GcSvgDocument class that can be used to create, load, inspect, modify, and save the internal structure of an SVG image. You can also load an SVG Image from a File, or Stream, or byte array and add it to the GcPdfDocument, GcBitmap, or GcWicBitmap classes using the GcGraphics.DrawSvg method. 

With v5.1, it is now possible to use all common graphics operations to draw on an instance of the new in v5.1 GcSvgGraphics class, which then can be converted to GcSvgDocument and saved as an SVG or an SVGZ image. In addition, saving individual pages of GcPdfDocument or GcWordLayout in SVG and SVGZ formats is also supported. 

The GcSvgDocument class is provided in the GrapeCity.Documents.Svg namespace in the GcImaging library. This class allows you to create, load, inspect, modify and save the internal structure of an SVG image. GcSvgGraphics class is derived from GcGraphics. It makes it possible to render graphics on a GcSvgDocument. 

GcSvgDocument class in GcImaging introduces the ToSvgDocument method that converts a set of drawing commands (from GcSvgGraphics) to the well-defined object model of SVG Document. The resulting SVG Document can be saved to the .SVG file or converted to a byte array with compressed SVGZ data. Pages of GcPdfDocument and GcWordLayout documents can be saved as SVG using methods GrapeCity.Documents.Pdf.Page.SaveAsSvg and GrapeCity.Documents.Word.Layout.Page.SaveAsSvg

The following code exports a PDF page (second page in the document) to SVG/SVGZ formats:

var pdfDoc = new GcPdfDocument();
using (var fs = new FileStream("slide-pages.pdf", FileMode.Open, FileAccess.Read, FileShare.Read))
{
    pdfDoc.Load(fs);
    var page = pdfDoc.Pages[1];
 
    // Render a PDF page to the .svg file
    page.SaveAsSvg("slide-pages.svg");
 
    // Render a PDF page to the byte array with compressed data in SVGZ format
    var svgzData = page.ToSvgz();
    File.WriteAllBytes("slide-pages.svgz", svgzData);
}

Refer to the following Demos to see an implementation of the new methods.

Help GcImaging | Help GcPdf | Help GcWord | Save Graphics to SVG document in GcImaging | Save PDF page to SVG | Save PDF to SVGZ

GrapeCity Documents PDF Viewer (GcPdfViewer)

Rotate Stamp Annotations

You can now rotate Stamp Annotations to any degree using freehand rotation on the UI or through Rotate property in the property panel. The animation below adds a 'Confidential' stamp to the document and rotates freely using the rotate handle:

Help | Demo

Form Fields Orientation

Similar to the above, GcPdfViewer also provides the ability to customize the Orientation property of Form Fields as per the rotated document. When you add a Form Field on a Rotated document, it will add the Form Field with Orientation adjusted as the document is rotated, or it will add the Form Field with Orientation counterclockwise to the current document rotation. In addition, you can set Orientation property from the property panel to any multiples of 90. 

Help | Demo

Support dynamic XFA forms 

Many XFA Forms are being used on the web for data collection. Although these forms are deprecated in PDF 2.0 specification, their wide usage makes it useful to support this format in web-based PDF Viewers. In the last release, GcPdfViewer added support for viewing and printing XFA Forms. Most of the fillable XFA Forms contain useful JavaScript actions. In the v5.1 release, GcPdfViewer now supports the following XFA Forms features:

• Submit, print, reset form actions
• Links
• Some JavaScript actions (common JavaScript calculations, base ECMA functions, etc.)

Help | Demo

Save State of PDF Layers When Saving a Document

If you change the visibility of the layers in GcPdfViewer, and press the 'Save' button, the current layer's visibility state will be preserved in the saved PDF. This PDF, when opened in Adobe Acrobat®, will preserve the visibility of the layers: 

Make Certain Edit Buttons Sticky for Enhanced Editing Experience

GcPdfViewer now optionally makes certain edit buttons (e.g., add 'Text Field') sticky so that the operation can be repeated multiple times without clicking the button again. This will make adding annotations/form fields to PDF documents a faster process. 

New property stickyBehavior has been added to toolbarLayout using which user can define the array of button keys that need to behave as sticky. When Sticky Behavior is defined, the toolbar button will remain selected until the editing is completed. You can stop the Sticky Behavior by de-selecting the annotation editor button.

The new Sticky Behavior applies to Annotation Editor/Form Editor buttons and will particularly help you to create PDF Forms or add the same annotations repeatedly on a page:

The following code will enable sticky behavior on certain Annotation Editor buttons: 

// Make square, circle, line and redact buttons sticky:
 viewer.toolbarLayout.stickyBehavior = ["edit-widget-tx-field", "edit-square", "edit-circle", "edit-line", "edit-redact"];

Help | Demo

SupportAPI Project on NuGet

There is no wait for the latest version to download and upgrade your SupportAPI files for integrating GcPdf on the back-end server with GcPdfViewer on the front-end web page to support Full PDF Editing using the GcPdfViewer Professional version. 

SupportAPI will now be released together with other GrapeCity.Documents packages as https://www.nuget.org/packages/GrapeCity.Documents.Pdf.ViewerSupportApi/. Please note that the default namespace of the SupportAPI classes has changed from SupportAPI to GrapeCity.Documents.Pdf.ViewerSupportApi. If you have overridden the default SupportAPI controller, you may need to update the usings in your C# code.

The complete sources for the SupportAPI project will continue to be available; in particular, they are included in the src/subdirectory of the SupportApi.nupkg file.

Follow these steps to upgrade your project.

GrapeCity Documents for Excel (GcExcel)

We are pleased to announce new feature additions to GcExcel API in v5.1. See key highlights below.

• GcExcel Report Templates Enhancements
• Import Data function to import a Table, Range, or Worksheet from XLSX files
• New CELL Function support
• Convert Table to Range (e.g., remove Table UI but leave formatting)
• Modify the Password of XLSX documents
• CSV Custom Parser
• Specify the 'ShowValuesAs' option for the 'Values' field in Pivot Tables
• Support for Calculated Field in Pivot Tables
• Support for "Show #N/A as an empty cell" in Chart
• Enhanced SpreadJS Integration:
• Support for Pivot Table Views (JSON I/O)
• Support for TableSheet (JSON I/O)
• Support for Numbers Fit Mode

Read the release blog for complete details.

GrapeCity Documents for Word (GcWord)

Enhanced Font Support

In the last release, we added the ability to embed Fonts in DOCX documents to ensure your documents display or print the same in other systems as they appear on your system. In the v5.1 release, we extend this capability further in order to include standard Fonts from a file using the GrapeCity.Documents.Text namespace and saving the Font Info in the DOCX document. This will give an advantage to your documents to look for Fonts within the GrapeCity.Documents.Text namespace and modify/save them after new additions.

Additionally, new Settings are also added to get Theme Fonts for different language cultures if your documents are prepared in multi-language Font scripts.  GcWord looks for Fonts defined in the 'Supplemental map' class from MinorFont and MajorFont of the Theme Font Collection for a particular culture. 

For example, for Settings.LocaleNameFarEast = "ja-JP," GcWord finds "Jpan" font script in Supplemental map from MinorFont and MajorFont of the Theme Font Collection, then defines mapped fonts as "in use" for this document. If the Font is not specified, then GcWord defines Latin.Name font name from MinorFont and MajorFont Theme Fonts as "in use" for this document or uses the default theme fonts.

In this release, DOCX documents using cloud fonts are also supported. 

The following new APIs have been added:

• Extend FontInfoCollection class to add fonts from GrapeCity.Documents.Text namespace.
• Add(Documents.Text.Font font, bool embed = false) method: Adds a new Font into the collection.
• Append(IList<Documents.Text.Font> fonts, bool embed = false): Appends a list of Fonts into the collection.
• Extend Settings class to support SaveOptions class. Define Local Properties to find Fonts related to a language culture:

• LocaleName: Gets or sets the default Locale Name (language) of the formatted characters
• LocaleNameBi: Gets or sets the Locale Name (language) of the complex script characters
• LocaleNameFarEast: Gets or sets the Locale Name (language) of the formatted Asian characters
• SaveOptions: Gets various options that control how to save the document

View Help | Demo

Font Effects

In addition to the above enhancements, GcWord adds additional Fill and Line properties to the Font class. Please note that at this time, the font fill and line are not supported in GcWordLayout (export to PDF or images). This support will be added in a v5.1 hotfix.

The new additions help add Font effects to your documents, such as Line - Solid, Gradient, or No Fill. The following code sets the Font and Line fills to Gradient and Solid fill types in a Resume document: 

//Define a Character type Style, implementing Font Fill and Line effects
var cstyle = doc.Styles.Add("CStyle", StyleType.Character);
cstyle.Font.Size = 48;
var fill = cstyle.Font.Fill;
fill.Type = FillType.Gradient;
var gradient = fill.GradientFill;
gradient.Angle = 45;
gradient.Stops[0].Color.RGB = Color.Purple;
gradient.Stops[1].Color.RGB = Color.Magenta;
var line = cstyle.Font.Line;
line.Width = 1;
fill = line.Fill;
fill.Type = FillType.Solid;
fill.SolidFill.RGB = Color.Black;
 
//Update the styles applied to runs using the above defined new style
foreach (var run in doc.Body.Runs)
{
    if(run.Font.Name == "Lato Black")
    {                                                         
        run.Style = cstyle;
    }               
} 
             
//Save updated document
doc.Save("Resume_FillLine.docx");

View Help | Demo

GcWord Templates Enhancements (Recently Released)

Paragraph Block Behavior 

GcWord now allows defining a list of values (multi-line) within a table cell using a new template formatter named 'pbb' or 'paragraph-block-behavior.' This formatter will help add a range as separate paragraphs inside a single table cell, rather than generating a new table row for each item as is the default range behavior. 

See the following example. If 'pbb' is not defined, the name of seas under the Oceans all appear in separate Table rows. If 'pbb' is defined with the data source binding, all the name of seas name appear together in a single cell. 

The following code shows how to set the 'pbb' formatter for the example above:

table[1, 0].GetRange().Paragraphs.First.GetRange().Runs.Add("{{#ds.seas}:pbb()}{{ds.seas.name}}{{/ds.seas}}");

View the full details here. 

Help | Demo

Run Block Behavior

GcWord also now supports adding the 'rbb' or run-block-behavior formatter to print the data items of a list as runs of the same paragraph rather than as separate paragraphs as is the default range behavior. For more info about runs, please check here. 

See the following example. If the name of seas are added without 'rbb,' the names of seas will be printed on separate lines with the Ocean names repeated. But if you add 'rbb' to #ds.seas, it will separate each sea name with a colon: 

The following code demonstrates how to add the 'rbb' formatter for the example above:

doc.Body.Paragraphs.First.GetRange().Runs.Add("{{#ds.seas}:rbb()}{{ds.seas.name}}; {{/ds.seas}}");

Help | Demo

Ignore Missing Data Members

Sometimes, it may be possible that you use template files containing fields that do not exist in the provided data source. Currently, this throws a KeyNotFound exception. GcWord improves this behavior by silently ignoring such fields and avoiding the exception. The new class DataTemplateOptions defines the property MissingFieldsHandling. When MissingFieldsHandling property is set to Strict, the exception will be thrown when a non-existent field is found; otherwise, if the property is set to Relaxed mode, such fields will be silently ignored. 

var doc = new GcWordDocument();
doc.DataTemplate.Options.MissingFieldsHandling = DataTemplateMissingFieldsHandling.Relaxed;
var ds = new { x = "5" };
doc.DataTemplate.DataSources.Add("ds", ds);
  
doc.Body.Paragraphs.Add("{{ds.x}}{{ds.y}}");        
doc.DataTemplate.Process();
//no errors will be thrown regardless of using non-existent field

Help 

Support for Type Converting Formatter

GcWord adds a Type Converting Formatter that lets you convert the input data into numeric or boolean type data. Two new formatters todouble(<optional_string>) or tobool(<optional_string>) will take in input string and convert to desired format. 

var doc = new GcWordDocument();
  
var ds = new string[] { "-2", "32", "16", "5,45", "12,39" };
doc.DataTemplate.DataSources.Add("ds", ds);
  
doc.Body.Paragraphs.Add("{{ds.value}:todouble():hbi-less(7)}");
doc.DataTemplate.Process(CultureInfo.GetCultureInfo("ru-RU"));
doc.Save(...)

Help | Demo

How to Avoid Common Mistakes in GcWord Templates (Samples)

In case you missed it, we have added a few samples that show you how to solve certain errors that you may observe when working with GcWord Templates and some best practices. Have a look at these samples here. 

What do you think about the new features? Leave a comment below. Thanks!