Adding TOC to RadFlowDocument Not Working

[Brian]

I am trying to add a Table of Contents to a RadFlowDocument.  I then export it to PDF.  However, there is never anything in the TOC.  If I replace the second parameter in the InsertField statement with "results", I see the word results on top of the document.  The below snippet has what I think are the important parts of the code.

I am hoping that this is something obvious that I am missing, but either way, any help would be appreciated.

public static IFormatProvider < RadFlowDocument > GetFormatProvider ( string extension )
{
    if ( !extension.StartsWith ( "." ) ) extension = "." + extension;
    switch ( extension.ToLower() )
    {
        case ".docx": return new DocxFormatProvider();
        case ".html": return new HtmlFormatProvider();
        case ".pdf":  return new PdfFormatProvider();
        case ".rtf":  return new RtfFormatProvider();
        case ".txt":  return new TxtFormatProvider();
        default:      return null;
    }
}
...
var editor = new RadFlowDocumentEditor(doc);
var tocField = editor.InsertField("TOC \\o \"1-3\" \\h \\z \\u", "");
tocField.IsDirty = true;
tocField.UpdateField();
using(var ms = new MemoryStream())
[
    requestedDocType.Provider?.Export ( doc, ms );
    return ms.ToArray();
}
...

[Brian]

The references in the TOC need to be linked so that a person reading the PDF can click it and go to the appropriate page.  If there is not an automated way of doing this, can someone suggest an algorithm for building it?

[Tanya]

Hi Brian,

Тhe reason for the observed results is the fact that RadWordsProcessing doesn't genuinely support Table of Contents. The CustomCodeField concept that you've applied in the example allows to use unsupported fields when exporting to flow formats like DOCX but entirely depends on the consumer (most commonly MS Word) to update the field and properly visualize the document. When exporting to PDF, however, the content should be laid out in advance as the PDF viewers read only instructions for rendering and cannot update the content. Since RadWordsProcessing is independent of UI, it currently cannot construct a Table of Contents as it requires a notion about the positioning of the elements on the pages. 

Implementing TOC fields and their export to all available formats is in our backlog though I cannot say when it might be implemented. You can cast your vote for this functionality on our feedback portal and follow the item in order to be updated for any status changes: Table Of Contents Field.

After converting the content to the PDF model, all the text is mapped to glyphs and only information related to the rendering of these glyphs is preserved. With that said, I am afraid that I cannot suggest you an approach for adding a TOC to a PDF file.

Hope this information is useful.

Regards,

Tanya
Progress Telerik

[Brian]

Hi Tanya,

Thank you for the response! 

I found that feedback page a couple of days ago and voted for it then.  Thank you for pointing it out though, in case someone else would like to vote as well.  However, it has been out there for two years in approved status, and nothing has been done with it, which gives me little hope that anything will be done.

Also, I am still confused.  I know that active links still are placed in the document by testing it, and I know via your documentation anchors/bookmarks can be placed in documents.  PDFs are not (to the best of my knowledge) viewer dependent.  Margin, page size, orientation, etc. are already set when the PDF is made.  Everything on a page should be on that page, no matter what viewer is being used.  Is this not the case?  Even if it is not the case, and even if it were without page numbers, having a table with links that would take the user to the appropriate page via a bookmark link would be better than nothing.  A lot of companies have some very large documents.  A way to navigate them is a necessity, which is why I am stunned by this omission.

I really like your product.  It has made things much better in most areas.  But... There are a lot of other products that do this, so I know that it can be done (even Word can do it when you use Save As).  When researching your tool, I saw that it worked with PDFs using the RadFlowDocument, and that TOCs could be added to RadFlowDocuments as above (among all of the other features I looked at).  I don't have time when doing this kind of thing to spend months looking at all of the functionality when making these decisions, and I took what I saw as an indicator that it worked as we needed.  While we did not buy it specifically for this functionality, we already spent thousands on this tool set (at my urging no less), and I am going to have a hard time getting them to purchase something else.

This is a bit of a disappointment, and I hope that there is movement on that Feedback soon.

My biggest frustrations are twofold.  The first lies in the fact that after two years on the backlog and with no apparent movement, I have a hard time believing that this will ever be addressed.  The second is that I can no longer recommend this product as wholeheartedly as I have been.  I now have to caveat my recommendations with what I have found.

Finally, while I am very frustrated, I hope I did not come across too harsh.  I want this to be constructive.  

Thanks!

[Boby]

Hello Brian,

I am very sad to hear about your frustration, but I totally understand it. I will try to justify our position a bit, and then I will try to propose a workaround for the case.

As we are working with limited resource, we are trying to prioritize the most important items and work on them first. One of the most important factors, of course, is the customer demand, and while the demand for the support of TOC field is relatively high, we consider it currently not sufficient to justify the complexity of the implementation. What you say is indeed absolutely true - all of the needed PDF elements (like texts and hyperlink annotations) are already supported, and one of the hardest points of the implementation is that page numbers for the different elements included should be computed. While this is partially implemented in the PDF export (which can do basic layout and determine the position of the elements on the pages), the concept could not be easily extracted and applied in the general case. 

We can consider partial implementation of the feature by skipping the page numbers, as you suggested, but we believe that this is one of the main features of a table of content, and could cause more frustration then benefits - as sometimes customers are investing significant time to implement a solution, believing that a feature is supported, only to find out at the end that it's not.

One possible workaround that comes to my mind is to use the classes associated with RadRichTextBox for WPF. The same set of format providers is supported, as well as TOC field update. You can use the similar RadDocumentEditor class to insert and update the field. The downsides of the approach would be:
- Some more references to Telerik assemblies should be added, as well as to some WPF-related .NET Framework assemblies (e.g. PresentationCore and PresentationFramework).
- The code handling the document models and import/export should be executed in an STA thread (such could be started from your web app's threads, which are most probably MTA).
- I just checked the implementation with the team (the documentation article update is currently in progress, so the information should be present online soon), and the only switch not supported among the ones used in the sample code is "\z".

Let us know in case you need further assistance with any of the approaches.

Regards,
Boby
Progress Telerik