What's New in GrapeCity Documents in v4.2
GrapeCity Documents (GcDocs) is excited to announce the new v4.2 release! This release introduces a whole set of new features to support full document workflows end-to-end.
With the new v4.2 feature set, you can solve complex business problems, including programmatically adding layers in PDFs, generating secure PDFs with complex encryption algorithms, adding stamps to PDFs in our JS PDF Viewer, adding dynamic array formulas to Excel workbook, supporting new calculation engine functions, and generating Word reports with data from multiple data sources.
Read on to learn about our exciting new features and enhancements!
GrapeCity Documents for PDF (GcPdf)
Add Layers to PDF Documents
Arrange objects in a PDF that are specifically related to one another, such as a building with several designs for a house – ranging from the base architectural design to piping, electrical, etc. – over the base design. It's now possible to add separate layers of content to a single PDF with PDF documents, which you can show/hide in Adobe Acrobat.
The snapshot below shows a housing plan that uses various house designs for electrical wiring, lighting, security, etc., and how users can view them all in a single PDF. To see all designs simultaneously, adjust the visibility setting of all layers to "On". Accomplish this programmatically using this new API feature in GcPdf.
The new GcPdfDocument.OptionalContentProperties class provides an extensive API to work with PDF layers. With the new API, you can:
- Add layers
- Enumerate and find existing layers
- Associate PDF content that you draw on GcPdfGraphics, FormXObject, and annotation objects with specific layers
- Examine and set layer properties, such as visibility, print state, etc.
- Remove layers *Note: Currently, removing a layer does not remove the existing associated content
GcPdfViewer does not yet provide a UI to access layer properties. This support will soon be available in an upcoming release. Check out these resources for more details.
Set Output Intent and Embed ICC Profile
PDF specification provides a way to define the list of output intent objects. These objects specify the color characteristics of the output devices that can render a document. In v4.2, GcPdf adds support for PDF output intents. Output intents are represented by instances of the OutputIntent class and can be accessed via the GcPdfDocument.OutputIntents collection.
The ICCProfile class represents the ICC profiles used by output intents. Access the ICC profile of an output intent via the OutputIntent.DestOutputProfile property. A static utility method OutputIntent.Create() provides a convenient way to create output intents.
The following code shows how to add output intents to a PDF using the new GcPdf API:
var profiles = new (string, string)[] {
("Probev2_ICCv4.icc", @"https://www.color.org/probeprofile.xalter"),
("Probev1_ICCv4.icc", @"https://www.color.org/probeprofile.xalter"),
("Probev1_ICCv2.icc", @"https://www.color.org/probeprofile.xalter"),
};
foreach (var profile in profiles)
{
sb.AppendLine($"{bullet}{profile.Item1}, source: {profile.Item2}");
using (FileStream fs = File.OpenRead(Path.Combine("Resources", "Misc", profile.Item1)))
{
var oi = OutputIntent.Create($"Output intent testing {i++}", "", "http://www.color.org", profile.Item1, fs);
doc.OutputIntents.Add(oi);
}
}
In these samples, a "probe" ICC profile is used, which deliberately distorts colors for debugging and testing purposes.
Check out these resources for more details.
Support for AES 256 Revision 6 Encryption
GcPdf also adds Standard Security Handler Revision 6, originally added in PDF 2.0, which uses AES 256 encryption to encrypt PDF documents. This encryption uses a more complex algorithm to generate the encryption key.
It offers a more secure solution to prevent unauthorized access to PDF documents. Define the StandardSecurityHandlerRev6 handler properties and set them to GcPdfDocument.Security.EncryptHandler class.
var ssh6 = new StandardSecurityHandlerRev6()
{
OwnerPassword = ownerPassword,
UserPassword = userPassword,
CopyContent = false,
PrintingPermissions = PrintingPermissions.Disabled,
EncryptStrings = true,
};
// Assign the handler we created to the document so that it is used when saving the PDF:
doc0.Security.EncryptHandler = ssh6;
Improved PDF to Images Export: Introducing Blend Mode
GcPdfGraphics now implements the BlendMode property. This property specifies the blend mode that affects all drawing on the current graphics, including graphic primitives, text, and images. The 12 blend modes described in the PDF spec are supported. Blend modes are also supported when GcPdf renders a PDF to an image.
*Note: While PDF supports only 12 blend modes, the BlendMode enum used by GcPdf includes some additional blend modes not supported in PDF. To programmatically test whether a particular blend mode is supported, use the GcPdfGraphics.IsBlendModeSupported() method.
The following snapshot is a PDF file with various Blend Modes applied. You can obtain similar results when a PDF is converted to an image.
GrapeCity Documents PDF Viewer (GcPdfViewer)
Add Predefined Stamps to PDF Documents
A document stamp can authenticate the document with your personal or business signature, emblem, or logo. It can help track the document or make notes of the document's status. In this release, GcPdfViewer now supports adding predefined or custom stamps to a PDF document.
The viewer supports all Standard and Sign stamps used on the PDF documents, as supported in Adobe Acrobat Pro. Open the Stamp Annotation drop-down, choose a stamp from the predefined stamps list, and add it to your PDF document.
The viewer will save the last added stamp in the drop-down. Predefined stamps are shown by default in the Stamp Annotation drop-down or if the stampCategories option is "true". To enable predefined stamps in the Stamp Annotation drop-down, set the following code:
var viewer = new GcPdfViewer("#root", {
stamp: {
stampCategories: true
}
});
With this new feature added to the Stamp Annotation drop-down, users can now:
- Specify their own set of predefined stamps on the client-side
- Disable the predefined stamps drop-down
- Specify your own set of predefined stamps on the server-side
Check out more details below on how to do so!
Help | Predefined Stamps Demo | Custom Client-Side Demo | Custom Server-Side
Set Font Family for Text Fields and Free Text Annotations
GcPdfViewer has long supported adding text to existing or new PDF documents through text annotations or text fields. Due to application business standards, some users may need to add text in a particular Font.
We've added the fontName property to all text fields, plus the FreeText annotation. This property will now reflect in the property panel, where you can choose your font from a set of font arrays–defined using the fontNames property and added to the editorDefaults option.
This is how you add your own array of fonts to the fontNames property:
<script>
var viewer = new GcPdfViewer("#root",
{
editorDefaults: {
fontNames: [{ value: 'Arial', name: 'Arial' },
{ value: 'OpenSans', name: 'Open Sans' }]
}
});
</script>
You can also add custom font to the text fields and FreeText annotation. Check out these resources for more details.
Set Opacity on Annotations
GcPdfViewer now allows users to control annotation opacity. Annotation opacity can highlight underlying content or add content over your PDF document but with opacity, for example, a company logo or watermark. All annotations added using GcPdfViewer now have the Opacity property.
The following code sets default opacity for a Square Annotation:
<script>
var viewer = new GcPdfViewer("#root",
{
editorDefaults: { squareAnnotation: { opacity: 0.3, interiorColor: '#0000FF' } }
});
</script>
Support Tab Order in PDF Form Fields
The most common way of navigating through a long-form document is through the "tab" key. GcPdfViewer now supports tab order of PDF form fields within the Viewer. You can set various types of tab orders, such as AnnotationsTabsOrder.ColumnOrder or AnnotationsTabs.Order.RowOrder.
The following GIF shows AnnotationsTabOrder set to "Row":
Check out these resources for more information on these enums below.
Add a New Page with Custom Page Height and Width
You can now programmatically set Page Height and Width for a page in GcPdfViewer for a new page or existing page through the new API method setPageSize. The following code sets the page size for Page 1:
viewer.setPageSize(0, { width: 300, height: 500 } );
Annotation Editor Help | Form Editor Help
New Sample Browser
You will now be able to view GcPdfViewer specific samples in the new sample browser, which includes Javascript Sources that offer the user input capabilities to edit Javascript code and view changes.
New browser link: /documents-api-pdfviewer/demos/
GrapeCity Documents for Excel (GcExcel)
We are pleased to announce new feature additions to GcExcel API:
- Add dynamic array formulas to workbooks
- Support for new calculation engine functions
- Support for external workbook links from the web
- Supports Excel to PDF chart exporting in GcExcel Java
- New document properties for workbooks
- Row and column grouping information
- Copy hidden rows to a new range
- Control the size of an exported JSON file
- Support margin settings for text within a shape
- Expand/collapse grouped rows in Pivot Table
- More features for GrapeCity SpreadJS integration
Read the release blog for full details.
GrapeCity Documents for Word (GcWord)
New Features Supported in Word Report Templates
Support Multiple Data Sources in a Single Template
In complex business applications, data is stored or retrieved from multiple data sources. GcWord Report Templates now supports binding Word Report Templates with data from multiple data sources. The example below adds two different JSON data sources to the template.
The 'makes' data source lists some popular car makers, while another data source, 'bodystyles' lists the different styles of the car.
var makes = "[" +
"{ \"make\": \"Toyota\" }," +
"{ \"make\": \"General Motors\" }," +
"{ \"make\": \"Volkswagen\" }," +
"{ \"make\": \"Ford\" }," +
"{ \"make\": \"BMW\" }," +
"{ \"make\": \"Nissan\" }," +
"{ \"make\": \"Hyundai\" }," +
"{ \"make\": \"Honda\" }," +
"{ \"make\": \"Mazda\" }," +
"{ \"make\": \"Jaguar\" }," +
"]";
var bodyStyles = "[" +
"{ \"style\": \"Sedan\" }," +
"{ \"style\": \"Coupe\" }," +
"{ \"style\": \"Hatchback\" }," +
"{ \"style\": \"SUV\" }," +
"{ \"style\": \"Crossover\" }," +
"{ \"style\": \"Minivan\" }," +
"{ \"style\": \"Pickup\" }," +
"{ \"style\": \"Wagon\" }," +
"]";
var doc = new GcWordDocument();
// Add the data sources:
doc.DataTemplate.DataSources.Add("makes", makes);
doc.DataTemplate.DataSources.Add("styles", bodyStyles);
New Range Template Formatters
Restart Numbered Lists
GcWord adds a new range template formatter restart to restart a numbered list in different blocks of data. For example, if you need a result like this...
...you can use the following code to restart the number with every new company name.
\{{#products}:restart()}\{{products.category}}
1. \{{products.category.productname}}
\{{/products}}
Attach the new restart formatter to the template range tag with '#'. You can also use the 'all' formatter to restart all numbered lists, parent groups, or inner groups.
Sequence and Follower Formatter
Two new range template formatters, sequence (or seq ) and follow, were added to GcWord Report Templates. When 'seq' is used with 'follow', the range will iterate with the same data index as the parent range. When used in conjunction, you can co-iterate the objects of two collections simultaneously and produce an output like this:
var p = doc.Body.Paragraphs.Add("\{{#nums}:seq(seq1)}\{{nums.num}} -- \{{#ds}:follow(seq1)}\{{ds.name}}\{{/ds}}\{{/nums}}", doc.Styles[BuiltInStyleId.ListParagraph]);
Support JSON as a Data Source
JSON is the most widely used data format for data interchange on the web. You can now directly bind Word Report Templates to single or multiple JSON data sources. The following new object types are supported:
- JSON file
- JSON string
- JSON stream
- JSON stream reader
- JSON token
The following example shows the binding of a Word Report Template with a JSON string as the data source:
var doc = new GcWordDocument();
doc.DataTemplate.DataSources.Add("ds", oceans);
var myListTemplate = doc.ListTemplates.Add(BuiltInListTemplateId.BulletDefault, "myListTemplate");
var p = doc.Body.Paragraphs.Add("\{{#ds}}\{ds.seas.name}:toupper()}\{{/ds}}", doc.Styles[BuiltInStyleId.ListParagraph]);
p.ListFormat.Template = myListTemplate;
doc.DataTemplate.Process();
doc.Save("Oceans.docx");
Check out these resources for even more examples for binding Word Report Templates with JSON object types.
New Copy/Paste Options
GcWord now features a new enum option: KeepSource to type FormattingCopyStrategy. Ensure that the copied and pasted range in a Word document has similar formatting; unchanged by another document's default properties.
In the snapshot below, the content of the first document is copied to the second document. The template is then processed using the FormattingCopyStrategy.KeepSource enum. The resulting document maintains the formatting of the source document while pasting the new content.
View further examples below.
Shapes and Textboxes Support in Word to PDF and Images Export
Last year, we introduced the new GcWordLayout class that provided stronger support for exporting Word to PDF and image formats. Exporting Word to PDF now supports shapes in Word documents. Microsoft Word has several predefined shapes, including rectangles, arrows, frames, and more.
GcWord now supports all standard shapes upon PDF export. Many shapes also have special adjustments, such as the radius of the internal circle within the donut shape. These adjustments are now fully supported in GcWordLayout.
GrapeCity Documents for Imaging (GcImaging)
Background Bitmap and Transparency Mask
PDF supports transparency masks, background isolated, and knockout group features (see pages 515, 539, 540) while rendering images in PDF (see Blend Mode). GcImaging also includes the above features through a new API added to BitmapRenderer class to draw graphics, text, and images to GcBitmapGraphics objects.
1. Blend Mode
While earlier versions of GcImaging supported blend modes when combining images (i.e. the GcBitmap.CompositeAndBlend() method), users can now set a blend mode on GcBitmapGraphics or BitmapRenderer. That blend mode will affect all bitmap, including drawing graphic primitives, images, and text.
In total, there are 16 types of Blend Modes supported in GcImaging. The following image, generated with GcImaging, shows how text is drawn over a spectrum image using various supported blending modes.
Help | Blend Orchid, Blend Spectrum, and Blend Text Demos
2. Background Bitmap
When drawing semi-transparent graphic objects, the resulting color of a pixel is a combination of the target bitmap pixel's color and the color of the graphic object's pixel. If the new BackgroundBitmap property is set on the BitmapRenderer, the pixels of that bitmap will be used instead of the target bitmap's pixels to determine the color.
Use background bitmaps to support isolated and knockout transparency groups (as defined in the PDF specification) when rendering PDFs to images.
3. Transparency Mask
Another object added to BitmapRenderer class is the TransparencyMaskBitmap object, which provides a transparency mask for all drawing and filling operations. This helps you apply transparency together with other effects, such as blend mode or opacity.
If you have any comments on the new features or want to share how these are helpful, drop a comment below!
Shilpa Sharma