Documentation Center

Creating a PublishCombineLanguages Plugin in C#

This example shows how to create a C# .NET PublishCombineLanguages plugin using the out-of-the-box implementation as starting point.

Before you begin

The following products need to be already installed on your machine:
  • Microsoft .NET FrameWork
  • Microsoft Visual Studio

Procedure

  1. Create a Visual Studio Project. In this example, the project is called MyCustomCombineLanguagesPluginLibrary, and its type is Class Library.
  2. Add a reference to a plugin SDK (Trisoft.InfoShare.Plugins.SDK.dll). For example, you can copy the file from \Applications\Common\Trisoft.InfoShare.Plugins.SDK.dll.
    1. Browse to the project, then right-click References, and select Add Reference.
    2. To select the reference you want to add, use the Browse button.
    3. Select Trisoft.InfoShare.Plugins.SDK.dll, then Add.
    4. To be able to view the code documentation of the Trisoft.InfoShare.Plugins.SDK.dll, also copy Trisoft.InfoShare.Plugins.SDK.xml.
  3. Add a reference to a plugin common helper (Trisoft.InfoShare.Plugins.Common.dll). For example, you can copy the file from \Applications\Plugins\Trisoft.InfoShare.Plugins.Common.dll.
    1. Browse to the project, then right-click References, and select Add Reference.
    2. To select the reference you want to add, use the Browse button.
    3. Select Trisoft.InfoShare.Plugins.Common.dll, then Add.
    4. To be able to view the code documentation of the Trisoft.InfoShare.Plugins.Common.dll, also copy Trisoft.InfoShare.Plugins.Common.xml.
  4. Add a reference to the System.ComponentModel.Composition assembly.
  5. Add a reference to the System.Xml assembly.
  6. Create a new MyCustomCombineLanguagesPlugin class.
    The name of the plugin corresponds to the value assigned to ExportAttribute, and it needs to be unique.
    using System;
    using System.Collections.Generic;
    using System.ComponentModel.Composition;
    using System.IO;
    using System.Text;
    using System.Xml;
    using Trisoft.InfoShare.Plugins.SDK.Publish;
    
    namespace MyCustomCombineLanguagesPluginLibrary
    {
        /// <summary>
        /// This plugin will create a root map with the configured 'CombineLanguageHeaderIshRef' as header
        /// </summary>
        [Export("MyCustomCombineLanguages", typeof(IPublishCombineLanguagesPlugin))]
        [PartCreationPolicy(CreationPolicy.NonShared)]
        public class MyCustomCombineLanguagesPlugin : IPublishCombineLanguagesPlugin
        {
            #region Private fields
            /// <summary>
            /// The file name of the root map that will be generated
            /// </summary>
            private const string RootMapFileName = "COMBINEDLANGUAGESROOT.ditamap";
            /// <summary>
            /// The configuration of the plugin
            /// </summary>
            private IPublishCombineLanguagesConfiguration _configuration;
            /// <summary>
            /// The logicalId for the topics with the language label
            /// </summary>
            private string _combineLanguageHeaderIshRef = String.Empty;
            #endregion
    
            /// <summary>
            /// Initializes the plugin
            /// </summary>
            /// <param name="configuration">The configuration containing all necessary information to run the plugin</param>
            public void Initialize(IPublishCombineLanguagesConfiguration configuration)
            {
                _configuration = configuration;
    
                string combineLanguageHeaderIshRef;
                if (configuration.CommonParameters.TryGetValue("CombineLanguageHeaderIshRef", out combineLanguageHeaderIshRef))
                {
                    _combineLanguageHeaderIshRef = combineLanguageHeaderIshRef;
                }
            }
    
            /// <summary>
            /// Runs the plugin and returns a file with the resulting root map
            /// </summary>
            /// <param name="reportItems">List with items which are exported to the file system</param>
            /// <returns>FileInfo with the resulting root map</returns>
            public FileInfo Run(List<IPublishSingleLanguageReportItems> reportItems)
            {
                XmlWriterSettings writerSettings = new XmlWriterSettings()
                {
                    CloseOutput = true,
                    Encoding = Encoding.Unicode,
                    OmitXmlDeclaration = false,
                    Indent = true
                };
    
                var rootMapFilePath = Path.Combine(reportItems[0].LanguageDirectory.Parent.FullName, RootMapFileName);
    
                using (XmlWriter writer = XmlWriter.Create(rootMapFilePath, writerSettings))
                {
                    writer.WriteStartDocument();
    
                    // TODO - Get the systemId using a xmlResolver with catalog resolving
                    // REMEMBER - In order for DITA-OT to be able to process this root map, the systemId should contain a valid path for the DTD specified!
                    writer.WriteDocType("map", "-//OASIS//DTD DITA Map//EN", systemId, null);
    
                    writer.WriteStartElement("map");
    
                    foreach (var reportItem in reportItems)
                    {
                        string language = reportItem.Language;
                        string mapFileName = reportItem.RootDocumentObjectReportItem.FileName;
    
                        writer.WriteStartElement("topicref");
                        if (String.IsNullOrEmpty(_combineLanguageHeaderIshRef))
                        {
                            // Make a topicref without href and a navtitle
                            // <topicref>
                            //   <topicmeta><navtitle>nl</navtitle></topicmeta>
                            //   <topicref href = "nl/GUID-C9CA7357-CBA3-43B3-A4B2-B977AD1B7D1E.ditamap" format = "ditamap" />
                            // </topicref>
                            writer.WriteStartElement("topicmeta");
                            writer.WriteElementString("navtitle", language);
                            writer.WriteEndElement();
                        }
                        else
                        {
                            // Use the reportitems to find the topic
                            IPublishReportItem item;
                            if (!reportItem.TryGetItem(reportItem.GenerateKey(_combineLanguageHeaderIshRef), out item))
                            {
                                throw new FileNotFoundException($"The header topic {_combineLanguageHeaderIshRef} could not be found in the export files.");
                            }
    
                            // <topicref href="en/ISHPUBLMODULECOMBINELANGUAGES.xml">
                            writer.WriteAttributeString("href", $"{language}/{item.FileName}");
                        }
    
                        // <topicref href="en/GUID-948607D2-1F33-43B4-B145-0E19594AA808.ditamap" format="ditamap"/>
                        writer.WriteStartElement("topicref");
                        writer.WriteAttributeString("href", $"{language}/{mapFileName}");
                        if (Path.GetExtension(mapFileName) == ".ditamap")
                        {
                            writer.WriteAttributeString("format", "ditamap");
                        }
                        writer.WriteEndElement();
    
                        writer.WriteEndElement();
                    }
    
                    writer.WriteEndElement();
                    writer.Flush();
                }
    
                return new FileInfo(rootMapFilePath);
            }
        }
    }