Customize document output content

preview released

This function and the API used in this function have been released in advance. We do not guarantee the quality at this time, so if you use it, please use it at your own risk. Also, please note that these specifications are subject to change without notice.

Overview

You can customize the document output function that comes standard with Next Design as follows.

Targets that do not output documents can be specified.
You can add arbitrary headings, captions, etc. in the document.
You can arbitrarily change the output order of views.
You can output in a different order than the order of models in the model navigator.

Customize document output

You can customize the behavior by registering the configuration object DocumentGenerationConfigs with IApplication.DocumentGeneratorCustomization.RegisterConfig().

There are two ways to customize the document output.

Option settings
- You can customize the behavior of the built-in document generation by changing option settings in DocumentGenerationConfigs.
Callback processing
- Register callback processing in DocumentGenerationConfigs. Since callback processing can be registered at various timings during document generation, output results can be customized arbitrarily.
  - You can add, delete, and change the content to be output at the timing after content generation.
  - You can control the output contents of Word and Html before and after writing the contents.

option settings

By changing the following option settings of DocumentGenerationConfigs, you can customize the behavior of document generation.

API name	Description	Values that can be set	Corresponding target
TemplateFilePath	You can specify the file path of the template used for output.	any file path	Word only
OrderByViewDefinition	Gets or sets whether views are output in order of view definition.	`true` : Output in order of view definition. `false` : Output diagrams and sequence diagrams first, not in order of view definition.	Word only
AutoFitTables	Gets or sets how the table's column widths are automatically adjusted. If null, do not auto-adjust.	`AutoFitBehavior.AutoFitToContents` : Fit column width to string width. `AutoFitBehavior.AutoFitToWindow` : Fit column width to window size.	Word only

Implementation example

//Example: customize output behavior with option settings
public class DocumentExprotSample : IExtension
{
  //Processing when activating the extension
  public void Activate(IContext context)
  {
    //customize document output
    var app = context.App;
    app.DocumentGeneratorCustomization.RegisterConfig(this, context =>
    {
      //create a configuration object
      var config = new DocumentGenerationConfigs();

      if (context.DocumentFormat == "word")
      {
          //For Word output, get options with `GetWordOptions()`
          var option = config.GetWordOptions();

          //Example: Specify a Word template file to output
          var templateFilePath = Path.Combine("any path", "CustomizeTemplate.dotx");
          option.TemplateFilePath = templateFilePath;

          //Example: change the order of the output views
          option.OrderByViewDefinition = false;

          //Example: change the auto-fit column width of a table
          option.AutoFitTables = AutoFitBehavior.AutoFitToWindow;

      }

      return config;
    });
  }
}

callback processing

You can register the callback process executed at the timing shown below in DocumentGenerationConfigs.

API Name	Description
RegisterGenerationStart	Called when document generation starts.
RegisterGenerationFinish	Called after document generation is complete.
RegisterDocumentWriteStart	Called when the document starts to be written.
RegisterDocumentWriteFinish	Called when the document has finished writing.
RegisterBeforeContentWrite	Called when the content of the document begins to be written.
RegisterAfterContentWrite	Called when the content of the document is finished being written.
RegisterAfterContentsGeneration	Called after all content generation for the document.

Implementation example

IDocumentContent and IPageContent can be received as callback arguments and customized.

Specify targets for not outputting documents

If there are targets that you do not want to output in views, models, or fields, you can remove them from the output targets.

//Example: drop the table itself displaying arbitrary data
private void RemoveTableContent(IPageContent content)
{
    var targetPageContent = content.Pages.FirstOrDefault(_ => _.Title == "Page with Grid");
    var targetViewContent = targetPageContent.Views.FirstOrDefault(_ => _.Title == "Detail");
    var targetTableContent = targetViewContent.Items.FirstOrDefault(_ => _.Control.Title == "List of use cases");
    
    //Example: Delete the "List of Use Cases" table
    targetViewContent.Items.Remove(targetTableContent);
}

//Example: Remove a table column that displays arbitrary field values
private void RemoveTableColumnContent(IPageContent content)
{
    var targetPageContent = content.Pages.FirstOrDefault(_ => _.Title == "Page with Grid");
    var targetViewContent = targetPageContent.Views.FirstOrDefault(_ => _.Title == "Detail");
    var targetTableViewContent = targetViewContent.Items.FirstOrDefault(_ => _.Control.Title == "List of Use Cases");
    var targetTableContent = targetTableViewContent?.GetControl<ITableContent>();
  
    //Remove column headers for any table (example removes first column)
    targetTableContent.Headers.RemoveAt(0);

    //delete any table cell (example deletes the table cell corresponding to the first column)
    foreach (var tableRow in targetTableViewContent.GetAllContents().OfType<ITableRowContent>())
    {
        tableRow.Cells.RemoveAt(0);
    }
}

//Example: Delete the table row corresponding to any element
private void RemoveTableRowContent(IPageContent content)
{
    var targetPageContent = content.Pages.FirstOrDefault(_ => _.Title == "Page with Grid");
    var targetViewContent = targetPageContent.Views.FirstOrDefault(_ => _.Title == "Detail");
    var targetTableContent = targetViewContent.Items.FirstOrDefault(_ => _.Control.Title == "List of use cases");
   
    //delete table rows (example deletes the first row)
    targetTableContent.Items.RemoveAt(0);
}

Add arbitrary headings, captions, etc. in the document

Text can be inserted anywhere on the page, so you can add headings, figure numbers and captions.

//Example: If the output target is a figure, enter the figure number and caption
config. RegisterAfterContentWrite(p =>
{
  if (p.DocumentContent.ContentType == DocumentContentTypes.Image)
  {
      var imageContent = (IImageContent)p.DocumentContent;

      //Processing for Word output
      //get the writing object for Word
      var imageNumber = 1;
      var wordWriter = p.GetWriter<IWordWriter>();
      if (wordWriter != null)
      {
          //center the word text and add figure caption
          wordWriter.SetAlignment(ParagraphAlignment.Center);
          wordWriter.WriteLine($"Figure{imageNumber}: {imageContent.Title}");
          wordWriter.RestoreAlignment();
      }

      //Processing for HTML output
      //get the writing object for HTML only
      var htmlWriter = p.GetWriter<IHtmlWriter>();
      if (htmlWriter != null)
      {
          //Add centered figure caption in HTML
          htmlWriter.WriteLine($"<p style=\"text-align: center;\">Figure{imageNumber}: {imageContent.Title}</p>");
          htmlWriter.WriteLine("</div>");
      }

      imageNumber++;
  }
});

//Example: page header/footer, add string anywhere
config. RegisterBeforeContentWrite(p =>
{
    //Processing for Word output
    //get the writing object for Word
    var writer = p.GetWriter<IWordWriter>();
    if (writer != null && p.DocumentContent.ContentType == DocumentContentTypes.Document)
    {
        //add any string
        writer.WriteText("page description");

        //add a string to the header
        writer. MoveToHeader();
        writer.WriteText("Append to header");
 
        //add page number to header
        writer. InsertField("PAGE");
        writer.WriteText("/");
        writer. InsertField("SECTIONPAGES");

        //add string to footer
        writer. MoveToFooter();
        writer.WriteText("Append to footer");
        
        writer. MoveToDocumentEnd();
    }

    //Processing for HTML output
    //get the writing object for HTML only
    var htmlWriter = p.GetWriter<IHtmlWriter>();
    if (htmlWriter != null && p.DocumentContent.ContentType == DocumentContentTypes.Image)
    {
        htmlWriter.WriteLine("<div style=\"display: inline-block;\">");
    }
});

Arbitrarily change the output order of views

You can change the view to any position and output it.

//e.g. move the view to any position
private void MoveView(IPageContent content)
{
    //get the view to traverse
    var targetContent = content.Pages.FirstOrDefault();
    var moveContent = targetContent.Views.First();
    
    //move the view to any position (moving to the top in the example)
    targetContent.Views.Remove(moveContent);
    targetContent.Views.Insert(0, moveContent);
}

Output in a different order than the models in the model navigator

You can change the output order by moving the page corresponding to the model.

//Example: move the page to any position
private void MovePage(IPageContent content)
{
    //get the object to move
    var targetContent = content.Pages.FirstOrDefault();
    var moveContent = targetContent.Pages.First();

    //move the page to any position
    targetContent.Pages.Remove(moveContent);
    targetContent.Pages.Insert(4, moveContent);
}

sample

public class DocumentExprotSample : IExtension
{
  //Processing when activating the extension
  public void Activate(IContext context)
  {
    var app = context.App;
    app.DocumentGeneratorCustomization.RegisterConfig(this, context =>
    {
      var config = new DocumentGenerationConfigs();

      if (context.DocumentFormat == "word")
      {
          var option = config.GetWordOptions();

          //change the order of the output views
          option.OrderByViewDefinition = false;

          //Change the autofit for table column widths
          option.AutoFitTables = AutoFitBehavior.AutoFitToWindow;
      }

      config.RegisterDocumentWriteFinish(p =>
      {
          //get write object for word
          var writer = p.GetWriter<IWordWriter>();
          if (writer != null)
          {
            //page break
            writer.InsertSectionBreakNewPage();

            //specify page orientation
            writer.SetPageDirection(DocumentPageOrientation.Landscape);

            //add bullets
            writer.ListFormat.ApplyBulletDefault();
            writer.WriteLine("Item 1");
            writer.WriteLine("Item 2");
            writer.ListFormat.RemoveNumbers();

            //wrap paragraph
            writer.InsertParagraphBreak();

            //generate table and rows and columns
            writer.CreateTable();
            writer.WriteCell("Column 1");
            writer.WriteCell("Column 2", Color.AliceBlue, Color.Black, cellWidth: 50d);
            writer.WriteCell("Column 3", Color.LightGreen, Color.Black, cellWidth: 100d);
            writer.EndRow();
            writer.RowFormat.Height = 50;
            writer.WriteCell("<b>Cell Merge Height 50</b>", Color.Transparent, Color.Red, 20d, true);
            writer.Paragraph.LineSpacing = 20d;
            writer.CellFormat.HorizontalMerge = CellMerge.First;
            writer.WriteCell(string.Empty);
            writer.CellFormat.HorizontalMerge = CellMerge.Previous;
            writer.WriteCell(string.Empty);
            writer.CellFormat.HorizontalMerge = CellMerge.Previous;
            writer.EndRow();
            writer.EndTable();

            //insert centered bold text
            writer.Paragraph.Alignment = ParagraphAlignment.Center;
            writer. Font. Bold = true;
            writer.WriteLine("Table");
            writer.Paragraph.RestoreAlignment();
          }
      });

      config. RegisterAfterContentWrite(p =>
      {
          //add caption if content is an image
          if (p.DocumentContent.ContentType == DocumentContentTypes.Image)
          {
              var imageContent = (IImageContent)p.DocumentContent;
              var imageNo = 1;
              var wordWriter = p.GetWriter<IWordWriter>();
              if (wordWriter != null)
              {
                  //insert figure caption in black letters
                  wordWriter.SetColor(Color.Black);
                  wordWriter.SetAlignment(ParagraphAlignment.Center);
                  wordWriter.WriteLine($"Figure{imageNo}: {imageContent.Title}");
                  wordWriter.RestoreAlignment();
                  wordWriter.RestoreColor();
              }<br/>

              imageNo++;
          }
      });<br/>

      return config;
    });
  }

  //Processing when deactivating the extension
  public void Deactivate(IContext context)
  {
    //Unregister custom settings for document output
    var app = context.App;
    app.DocumentGeneratorCustomization.UnregisterConfig(this);
  }
}

Customize document output content

Overview​

Customize document output​

option settings​

callback processing​

Specify targets for not outputting documents​

Add arbitrary headings, captions, etc. in the document​

Arbitrarily change the output order of views​

Output in a different order than the models in the model navigator​

sample​