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. To be able to view the code documentation of the Trisoft.InfoShare.Plugins.SDK.dll, also copy Trisoft.InfoShare.Plugins.SDK.xml.
  3. Browse to the project, then right-click References, and select Add Reference.
  4. To select the reference you want to add, click the Browse button.
  5. Select Trisoft.InfoShare.Plugins.SDK.dll, and select Add.
  6. Add a reference to the System.ComponentModel.Composition assembly.
  7. Add a reference to the System.Xml assembly.
  8. 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);
            }
        }
    }