Skip to main content

How to add a ribbon button in Adapter for Microsoft Word?

How to add a ribbon button in Adapter for Microsoft Word?

Ribbon Extensibility

This sample demonstrates the capability of adding a new ribbon button, along with handling conditional validation and execution of associated action. The sample also additionally demonstrates the capability of moving the out-of-the-box ribbon buttons of ‘Done Editing’ and ‘Discard changes’ to the ribbon in Home Tab.

In general, using ribbon extensibility following use cases can be achieved

  • Add new ribbon elements with custom validations and actions.
  • Override existing ribbon control actions and validations.
  • Override existing ribbon control icons or strings.

Add-In Extensibility

This sample also demonstrates the capability of tweaking the save routine using the BeforeSave event.

To demonstrate the same, it sets the asset name in the following format: _Test.docx

Enhanced add-in extensibility opens immense possibilities for developers by allowing access to the Application object, also see https://msdn.microsoft.com/en-us/library/office/ff194565.aspx

Developers can register for various native Microsoft Word events and also programmatically override the Ribbon class.

Configuration

To configure the sample, follow the steps mentioned below:

Update publish version

If published version of the Add-in is already installed then create copy of /Application Files/Quark.CMSAdapters.Office.Word_ folder and change the published version (preferably by changing last digit which denotes build revision) e.g. if folder name is Quark.CMSAdapters.Office.Word_11_2_25000_0 then create copy of this folder with name Quark.CMSAdapters.Office.Word_11_2_25000_1.

Note: If you have changed the published version then in the configuration steps below, wherever specified, denotes .

Override the out-of-the-box configuration

  • Copy the following file to the /Application Files/Quark.CMSAdapters.Office.Word_ folder
    • Quark.CMSAdapters.Samples.Office.Word.Extension.dll
  • Modify the Quark.CMSAdapters.config.deploy file as follows
    • Add the highlighted content below to the section:
      
      <appSettings>
      
      <add key="IAddInHostExtension" value="Quark.CMSAdapters.Samples.Office.Word.Extension" />
      
      </appSettings>
      
      
  • Modify the Ribbon.config.deploy file as follows
    • Add the highlighted content above <backstage onShow=”OnBackstageShow”> section:
      
      <ribbon>
        <tabs>
          <tab idMso="TabHome">
            <group id="CMSTabGroupShow" getLabel="GetLabel">
              
              	  <button id="CMSCheckIn4" tag="Id=CMSCheckIn;SaveSilently=false;SaveAsMinorVersion=;KeepMoreOptionsExpanded=" getImage="GetImage" getLabel="GetLabel" getEnabled="IsActionEnabled" onAction="Save" size="large"/>
      		  <button id="CMSCancelCheckout2" tag="Id=CMSCancelCheckout" getImage="GetImage" getLabel="GetLabel" getEnabled="IsActionEnabled" onAction="CancelCheckout" size="large"/>
            <button id="SampleActionId" getImage="GetControlImage" getLabel="GetControlLabel" getEnabled="IsSampleActionEnabled" onAction="SampleAction" size="large" />
            </group>
          </tab>
        </tabs>
      </ribbon>
      
      

Update the ClickOnce VSTO installer

  • Delete <Publish Location>/Application Files/Quark.CMSAdapters.Office.Word_<Publish Version>/ Quark.CMSAdapters.Office.Word.vsto file.
  • Open Visual studio command prompt and run command “Mage” which will open Mage tool
  • Go to File->Open and select <Publish Location>/Application Files/Quark.CMSAdapters.Office.Word_<Publish Version>/Quark.CMSAdapters.Office.Word.dll.manifest file.
  • Go to “Name” and set version number as specified in the name of Quark.CMSAdapters.Office.Word.dll.manifest file’s folder.

  • Go to “Files” and select check box “When populating add the .deploy extension to any file that does not have it” and click on Populate button as shown below

  • Go to File -> Save and select “Yes” in the Validation dialog as shown below.

  • Select option “Sign with certificate file” and provide the certificate file and password and click “OK”.

  • Close Mage tool.
  • Open Visual studio command prompt and run following command

    mage -Update “<Publish Location>/Quark.CMSAdapters.Office.Word.vsto” -AppManifest “<Publish Location>/Application Files/Quark.CMSAdapters.Office.Word_<Publish Version>\Quark.CMSAdapters.Office.Word.dll.manifest” -CertFile “<Certificate Location>\<Certificate>.pfx” -Password “<Password>”

  • Copy the <Publish Location>/Quark.CMSAdapters.Office.Word.vsto to <Publish Location>/Application Files/Quark.CMSAdapters.Office.Word_<Publish Version> folder

Download Sample

How to configure Quark XML Author to use external methods?

How to configure Quark XML Author to use external methods?

Programming for Quark XML Author

Quark XML Author can be configured to call any external application that exposes public methods. The person configuring Quark XML Author simply needs to know the assembly, class, and method name and what parameters the method expects. For example, the following method requires that an XML node and an array of Delegates be passed to it:

public bool IsEditableElement(XmlNode node, Delegate[] delegates)
{
  try
  {
   //read all the delegates here.
   //The namespaces for all delegates are Quark.XA.ExtensibilityDelegates.
   IsEditableElement isEditableElementDelegate = delegates[0] as IsEditableElement;           
   if(isEditableElementDelegate != null && node != null && node is XmlElement)
   {
     // This delegate indicates whether a node is editable or not.
     // This is based on values associated to a proprietary
     // Invision attribute called inv:access where
     // xmlns:inv="urn:xpressauthor:xpressdocument".This attribute is usually
     // applied in another EI method. A typical example would be a document coming
     // from a CMS system with certain nodes
     // tagged as non-editable, On an open, this EI method would read the non-editable
     // tag from this document and add a Quark XML Author
     //tag (inv:access="read-only") identifying it as a readOnly chunk.
     return isEditableElementDelegate(node);
   }
  }
  catch(Exception e)
  {
   System.Diagnostics.Debug.WriteLine("IsEditableElement Exception :" + e.Message + "\nStackTrace:" + e.StackTrace);
  }
  return false;
}

As long as the assembly and class to which this method belongs are known, Quark XML Author can be configured to supply the XML node and any delegates that the method requires. The method would do its work and return a Boolean value to Quark XML Author to be acted upon.

Calling Quark XML Author from an External Method with Delegates

In addition to being able to call external methods, Quark XML Author exposes its own methods that can be called by external methods via delegates. Delegates are function pointers to Quark XML Author methods that can be passed on to external DLLs. The External DLLs may then call the methods to perform operations within the application. Custom methods can accept delegates by implementing the Delegate[] argument type.

For more information, see the System Administrator Guide.

How to implement the support for a new language?

How to implement the support for a new language?

The Microsoft .Net Framework organizes language support in the following way. Each language has a main language resource assembly. For example, English (en). Within each language, there may be culture / locale specific versions of a language resource assembly.  For example, United States English (en-us) or British English (en-gb). Quark XML Author provides the same support for main language and locale specific language resources.

Figure 1: Locale specific versions of English supported by .Net

In addition, we need to differentiate between the Display Language and Editing Language within the context of Microsoft Office applications. The Display Language is the language displayed in the user interface (UI) of the Microsoft Office application. This includes menu items, toolbar buttons, ribbons, ribbon buttons, backstage views and Help. The Display Language only supports main language resources such as English (en), but not locale specific language resources such as United States English (en-us). The Editing Language is the language of the content that you are authoring on the Word canvas. This includes language-specific features such as dictionaries and grammar checking. The Editing Language supports locale specific language resources, “Figure”.

Figure 2: The user can specify both an editing language and a display language

Microsoft and Quark XML Author support using one language for the Display Language and a different language for the Editing Language. However, Quark XML Author does not support the authoring of multiple languages within a single Quark XML Author document.

Presently, Quark XML Author is distributed with the following Display language resources:

  • English main language

  • Spanish main language

  • Japanese main language

  • French main language

Quark XML Author supports the following languages:

Non-IME:

  • English

  • Spanish

  • French

  • Japanese

  • Chinese (Traditional)

  • Chinese (Simplified)

  • Korean

  • Vietnamese

  • Arabic

  • Hebrew

Support for these languages must be enabled in Microsoft Word. East Asian languages will also require IME to input characters.

Figure 3: Choosing an editing language

Bidirectional language support

Bidirectional languages (right-to-left languages) refers to any writing system that is written from right to left and includes languages that require contextual shaping, such as Arabic, and languages that do not. Right-to-Left languages are written and read mainly from right to left, but some portions of the text, such as numbers and embedded Latin languages (e.g. English) are written and read left to right.

Bidirectional language support in Microsoft Office

Microsoft Office supports right-to-left functionality and features for languages that work in a right-to-left (or a combined right-to-left, left-to-right) environment for entering, editing, and displaying text.

Bidirectional language support in Quark XML Author

XML Author supports authoring in LTR and RTL layouts depending on the default editing language set in MS Word.

To support Bidirectional Text in XML Author, the following option must be disabled in Microsoft Word:

Figure 4: The option to automatically switch keyboard to match language of surrounding text must be disabled.

Configuring the XAS to allow support of direction attributes for elements

The Quark XML Author structure must be configured to allow support for direction attributes of elements. Use the directionAttribute datatype to enable Quark XML Author to support bidirectional text.

An example is shown below:

<Attributes><AttributeDef name="dir" datatype="directionAttribute" visible="false"/>
<AttributeDef name="tablestyle" datatype="tableStyle" friendly="" visible="false"/></Attributes>
The following corresponding changes are required in the XpressSchema.xsd file:
<xs:attributeGroup name="fieldAttributes">
…
   <xs:enumeration value="directionAttribute"/></xs:attributeGroup>
<xs:attributeGroup name="tableStyle">
…
   <xs:attribute name="tableDirection" type="xs:string" use="optional" /></xs:attributeGroup>

Configuring the user interface for bidirectional language support

The dir attribute sets the text direction for elements regardless of the text direction of the document. Once this attribute is set, UI controls can be used to set text direction.

For example, the Text Direction buttons can be configured in config.xml to facilitate the insertion of elements with a right-to-left or left-to-right text direction, as in Microsoft Word.

<buttonGroup id="TextDirection">
       <toggleButton id ="TextDirectionLeftToRight"imageMso="TextDirectionLeftToRight">
           <InternalClass name="ToggleReadingDirectionControl" directionAttribute="ltr" />
       </toggleButton>
       <toggleButton id="TextDirectionRightToLeft" imageMso="TextDirectionRightToLeft">
           <InternalClass name="ToggleReadingDirectionControl" directionAttribute="rtl" />
        </toggleButton>
</buttonGroup>

Figure 5: Text direction buttons.

Configuring bidirectional language support at the content level

Use the TextDirection formatting type to format attributes that will allow different text runs within a single paragraph.

Example:

<Formatting>
...
<TextDirection name="ph" friendly="direction" TextDirectionAttributeName="dir"/>
...
  </Formatting>

 

The following changes must be made to the XpressSchema.xsd file:

 

  <xs:element name="XpressSchema">
    <xs:complexType>
      <xs:sequence>
       ...
       ...
       <xs:element name="TextDirection" minOccurs="0">
       <xs:complexType>
       <xs:attribute name="name" type="xs:string" use="required"/>
       <xs:attribute name="friendly" type="xs:string" use="optional"/>
       <xs:attribute name="TextDirectionAttributeName" type="xs:string" use="required"/>
       ...
       ...
        </xs:sequence>
      </xs:complexType>
</xs:element>

Configuring bidirectional language support at the element level

Text runs will be created for blocks of text whose text direction is different as compared to the element.

Root snippet:

<topic id ="" xmlns:inv="urn:xpressauthor:xpressdocument" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xlink="http://www.w3.org/1999/xlink" xsi:noNamespaceSchemaLocation="BUSDOCS.xsd" xml:lang="ar" dir="rtl">
<title/><body/></topic>

 

The XML snippet generated for left-to-right  text in a paragraph:

<body>
       <p widow-orphan="true" xml:id="IDd3ab0288-d634-4e82-90b1-c1ecd1b3ee5f">سشةحمث <ph dir="ltr">  sample text </ph>
 </p>
</body

 

Add the following to the element definition to support multi-directonal text runs:

<Formatting>
      --------
    <FormattingType name="ph"/>
</Formatting>

Configuring bidirectional language support at the document level

To configure bidirectional language support at the document level, see  dir.

How to access out of the box functions through third-party Excel Add-in?

How to access out of the box functions through third-party Excel Add-in?

This sample demonstrates the capability of hiding all out of the box UI options and accessing same functionality from third-party Excel Add-in. This sample exposes automation service object to allow third-party Add-Ins to communicate with Quark Add-in.

Configuration

To configure the sample, follow the steps mentioned below:

  • Copy the following files to the Platform Adapter installation folder, e.g. “C:\Program Files (x86)\Quark\Platform Adapter for Microsoft Office\Excel
    • Quark.CMSAdapters.Samples.Office.Excel.Extension.Automation.dll
    • Quark.CMSAdapters.Samples.Office.Excel.Extension.Automation.pdb
    • Ribbon.config
  • Modify the Quark.CMSAdapters.config file as follows
    • Add the highlighted content below to the section:
      
      <appSettings>
      <!-- Other -->
      <add key="IAddInHostExtension" value="Quark.CMSAdapters.Samples.Office.Excel.Extension.Automation" />
      <!-- Other -->
      </appSettings >
      
      

Once the configuration is complete you can test automation capability using TestExcelAddIn which is included with this sample.


Download Sample

How to add a ribbon button in Adapter for Microsoft Excel?

How to add a ribbon button in Adapter for Microsoft Excel?

This sample demonstrates the capability of adding a new ribbon button, along with handling conditional validation and execution of associated action.

s3 location

In general, using ribbon extensibility following use cases can be achieved

  • Add new ribbon elements with custom validations and actions.
  • Override existing ribbon control actions and validations.
  • Override existing ribbon control icons or strings.

Add-In Extensibility

This sample also demonstrates the capability of tweaking the save routine using the BeforeSave event.

To demonstrate the same, it sets the asset name in the following format: _

Enhanced add-in extensibility opens immense possibilities for developers by allowing access to the Application object, also see https://msdn.microsoft.com/en-us/library/office/ff194565.aspx

Developers can register for various native Microsoft Excel events and also programmatically override the Ribbon class.

Configuration

To configure the sample, follow the steps mentioned below:

Update publish version

If published version of the Add-in is already installed then create copy of /Application Files/Quark.CMSAdapters.Office.Excel_ folder and change the published version (preferably by changing last digit which denotes build revision) e.g. if folder name is Quark.CMSAdapters.Office.Excel_11_2_25000_0 then create copy of this folder with name Quark.CMSAdapters.Office.Excel_11_2_25000_1.

Note: If you have changed the published version then in the configuration steps below, wherever specified, denotes .

Override the out-of-the-box configuration

  • Copy the following file to the <Publish Location>/Application Files/Quark.CMSAdapters.Office.Excel_<Publish Version> folder

    Quark.CMSAdapters.Samples.Office.Excel.Extension.dll

  • Modify the Quark.CMSAdapters.config.deploy file as follows

    Add the highlighted content below to the section:

    
    <appSettings>
    <!-- Other -->
    <add key="IAddInHostExtension" value="Quark.CMSAdapters.Samples.Office.Excel.Extension" />
    <!-- Other -->
    </appSettings>
    
  • Modify the Ribbon.config.deploy file as follows

    Add the highlighted content below to the <ribbon> section:

    
    <ribbon>
    <tabs>
    <tab idMso="TabHome">
    <group id="CMSTabGroupShow" getLabel="GetLabel">
    <!-- Other -->
    <button id="SampleActionId" getImage="GetControlImage" getLabel="GetControlLabel" 
    getEnabled="IsSampleActionEnabled" onAction="SampleAction" size="large" /> </group> </tab> </tabs> </ribbon>

Update the ClickOnce VSTO installer

  • Delete <Publish Location>/Application Files/Quark.CMSAdapters.Office.Excel_<Publish Version>/ Quark.CMSAdapters.Office.Excel.vsto file.

  • Open Visual studio command prompt and run command “Mage” which will open Mage tool

  • Go to File->Open and select <Publish Location>/Application Files/Quark.CMSAdapters.Office.Excel_<Publish Version>/Quark.CMSAdapters.Office.Excel.dll.manifest file.

  • Go to “Name” and set version number as specified in the name of Quark.CMSAdapters.Office.Excel.dll.manifest file’s folder.

    s3 location

  • Go to “Files” and select check box “When populating add the .deploy extension to any file that does not have it” and click on Populate button as shown below

    s3 location

  • Go to File -> Save and select “Yes” in the Validation dialog as shown below.

    s3 location

  • Select option “Sign with certificate file” and provide the certificate file and password and click “OK”.

    s3 location

  • Close Mage tool.

  • Open Visual studio command prompt and run following command

    mage -Update “<Publish Location>/Quark.CMSAdapters.Office.Excel.vsto” -AppManifest “<Publish Location>/Application Files/Quark.CMSAdapters.Office.Excel_<Publish Version>\Quark.CMSAdapters.Office.Excel.dll.manifest” -CertFile “<Certificate Location>\<Certificate>.pfx” -Password “<Password>”

  • Copy the <Publish Location>/Quark.CMSAdapters.Office.Excel.vsto to <Publish Location>/Application Files/Quark.CMSAdapters.Office.Excel_<Publish Version> folder.


Download Sample