With v3 release, GcWord adds more features from the Microsoft Word OM features. The special highlight of v3 is the support for merging/splitting documents and document protection.
Copy and Move Document Content
It can be challenging to combine content from multiple Word documents, each with different formatting (and merged content) to fit the destination formatting.
At the same time, there may be a very large Word document from which it may be difficult to find relevant information. The document may need to be split into documents, with relevant content from specific parts of the Word document.
Add Document Protection to Word Documents
If you would like only certain people to open and/or edit a Word document with sensitive information, you can now apply Document protection properties in the Word documents. The properties will help keep the information private or secure. These properties will help control types of modifications applied to the documents. You can also specify if the document draft is the final version for the users.
The GcWord API adds Microsoft Word OM features w.r.t Document Protection and provides several options with the DocumentProtection, EditProtection classes for securing the Word document.
Features Supported in v3:
- Add editing restrictions to the document to prevent edits by mistake
- Add password and password properties to the document to encrypt the Word document, so that no one can access it without the right password
- Mark document as Final to let users infer that the document hasn't changed since last saved
- Apply read-only mode to the document
- Apply document edit mode to limit the content that can be edited, the modes are:
- No Protection
- Specify if document's style can be modified or not while editing the document
- Check whether restrictions were applied and active
More information and how to set document protection properties here.
Add Editable Ranges and Set Editor Permissions to Modify Document Content
In addition to Document protection, you can allow certain portions of text, to be editable by a designated set of people. With GcWord, you can add the range as Editable range, and set the Group editor for that range using the EditableRange and GroupEditor enum.
GcWordDocument doc = new GcWordDocument(); //add new paragraph var para = doc.Body.Paragraphs.Add("Editable paragraph"); //add new EditableRange for this paragraph para.getRange().EditableRanges.Add(new GroupEditor(EditorGroup.Everyone)); //add new paragraph doc.Body.Paragraphs.Add("New paragraph"); //set document region protection mode doc.Settings.DocumentProtection.EditProtection.EditMode = EditProtectionMode.AllowOnlyReading; //enforce document protection doc.Settings.DocumentProtection.EditProtection.isActive = true; //now, first paragraph can be editable by everyone. //rest of the document is ReadOnly doc.Save("EditableRange.docx");
In the document above, the first paragraph is set as an Editable range and editing permissions are provided to everyone. These settings do not apply to the 'New paragraph' so the next paragraph would be read-only and not editable.
Detect Source of Formatting Properties
In a Word document, formatting of a fragment can be determined in different things:
- Default document style
- Parent content formatting (paragraph that also includes font, for a run)
- Direct formatting (user selecting a word and applying font/color)
While programming with Word documents, it is useful to find out where a font comes from a run: from default style, paragraph style, or direct formatting.
GcWord adds the GcWordDocument.GetPropertyValueSource method to get the source of formatting properties. This feature is for advanced users, who want to programmatically determine the formatting of the Word objects uses in the Word document.
This is useful when a user wants to make sure all documents within the organization use pre-defined styles and not direct formatting. In that case, the programmer might want to find out which objects have what formatting properties set in the document and instead set pre-defined styles on the objects to make all documents follow a standard style.
More details here:
GCWord v2 Service Pack 2
Support for Content Controls
Creating templates, forms, or documents are some common scenarios executed in MS Word; for example, arranging a school parent/teacher meeting using dynamic forms. The form should be a template that includes the school logo and school name by default along with the form field labels. The school has thousands of active students and would like to generate a pre-filled field bound to a database in order to send it online.
With the support of Content Controls, forms can now be designed using GcWord. You can add many types of content controls with respective properties to design forms and templates.
New Types of Content Controls
Support Custom XML Parts and XML Mapping
Custom XML parts are used in Word documents to store XML data. Content controls can be bound with these XML parts to generate forms and template documents. A good part of this binding occurs when a user edits the text in the UI of Word document and the corresponding XML element is automatically updated. Similarly, if element values in the custom XML parts are changed, the bound content controls to the XML elements display the new data.
The binding of content control with XML parts can be used in many scenarios. For example, an online store wants to send annual greetings to customers and needs to add a customized note, stating the yearly bonus added to the account.
The data is in the form of an XML document that contains XML data with the customer's name and other details. This data needs to be mapped to the content controls in order to generate multiple greeting letters. In the document above, CustomerName from the XML file is mapped to PlainText content control.
In this release, we added the capability of binding content controls to these XMP parts using CustomXMLPart class in GcWord. You can add, load, and modify custom XML parts and save the document with custom XML parts as .docx files.
Binding in this way is convenient because if a user edits the text in the UI of Word document, the corresponding XML element is automatically updated. Similarly, if element values in the custom XML parts are changed, the content controls that are bound to the XML elements display the new data. To bind content controls with XML parts, GcWord also provides the XMLMapping class. You can map the content control with the XML node, or map any built-in property value with a content control.
GcWordDocument doc = new GcWordDocument(); // create custom xml element to map const string ns = "http://cusomxml/"; XmlDocument xml = new XmlDocument(); xml.AppendChild(xml.CreateXmlDeclaration("1.0", "utf-8", null)); XmlNode root = xml.AppendChild(xml.CreateElement("root", ns)); XmlNode child = root.AppendChild(xml.CreateElement("child", ns)); child.InnerText = "test value"; // add the xml document to a new custom xml part doc.CustomXmlParts.Add(xml); // map a new content control to the xml element ContentControl cc = doc.Body.ContentControls.Add(ContentControlType.Text, false); // gets the content control mapped value string value = cc.XmlMapping.SetMapping(child); // change the mapped value in the xml document and the content control cc.XmlMapping.TrySetValue("new test value"); // set a built-in property value doc.Settings.BuiltinProperties.Author = "me"; doc.Body.Paragraphs.Add(); // add a new content control for the built-in property ContentControl ccp = doc.Body.ContentControls.Add(ContentControlType.Text, false); // map the built-in property value with the content control // now when a user user changes the content control value the built-in property will be changed automatically string author = ccp.XmlMapping.SetMapping(() => doc.Settings.BuiltinProperties.Author); doc.Save("xml-mapping.docx");
Support for Adding Glossary Documents
You may have certain content that you do not want to appear in the Word document, but still want to keep it as part of the document for future insertion as per user action. A Glossary document acts as supplementary document storage that stores the definition and content for those instances.
For example, if you have real estate contract document where you would like to keep certain optional clauses, you would want to add them as an optional clause and to choose from the footer dropdown.
GcWord adds the GlossaryDocument and BuildingBlock classes to be able to add this type of kind of content to Word documents. Since this is in MS Word, there are several pre-defined blocks of text and formatting (known as Building Blocks). The Building Block galleries include pre-formatted Headers, Footers, Page Numbers, Text Boxes, Cover Pages, Watermarks, Quick Tables, Tables of Contents, Bibliographies, and Equations. The BuildingBlock class will help in adding content, (like a GlossaryDocument) to any Building Block Gallery type.
GCWord v2 Service Pack 1
Support for exporting RTL text, vertical text, and East Asian languages to PDF
GcWord API adds support for RightToLeft, vertical text, and East Asian Languages to render documents in multiple languages in DOCX files and export them to PDF. While creating Word documents, you can control:
- First and last character settings
- Line breaking rules
- Character spacing
Set view options on Word files
This feature supports how a document is displayed when it's opened in an application. It controls the view type and zoom type of the document when it opens, along with other properties.
Set compatibility options
Adding CompatibilityOptions to the Word files ensures that the Word documents created in older versions retain their properties when opened in newer versions. The addition of CompatibilityOptions class gives users control over 70+ compatibility features of Word files.
Control hyphenation in text
With the GcWord HyphenationOptions class, you can control hyphenation with various options to either automatically hyphenate the document that you create, or set an option to use the hyphenation tool to manually hyphenate your document.
Improve speed when creating new document
We are continuously monitoring the performance of GcWord with every release and have been working on improving the experience of generating word documents. Now you can generate multiple instances of GcWordDocument in just few seconds as creating a GcWordDocument is 4 times faster than before. Check out the demo sample below.
Support for theme colors
You can now set theme colors and modify existing themes per your company's brand. You can set color schemes that define the colors for background and text in your documents.
Format text as superscript or subscript and export to PDF
You can apply superscript and subscript settings to text in chemical compounds, formulas, mathematical expressions, etc., and GcWord now supports exporting superscript/subscript text to PDF.