Header/Footer behaviour with continuous section break (LinkToPrevious)

[Niccober]

What I want to achieve:
I have some static title content which takes up roughly one half of the first page. After that first half, user-specified content should be added to the document. This content can vary in length so it is not clear when the next page will be needed. I want to have a header/footer for the first page and then different headers/footers for the rest of the document and at the same time I do not want to skip the available space on the first page. So the user-specified content should start already on the second half of page one and whenever the content reaches page two, the headers/footers of the second section should apply.

To achieve this, I inserted a continuous section break after the static title page content, specified the different header/footer styles in the sections array and expected the different header/footer styles to be applied at page two and subsequent pages.

The problem:
When using a continuous section break, the specified headers and footers of the new section are not reflected in the document. Instead, the headers and footers of the previous section (title page) are applied. This is only the case when using a continuous section break, with e.g. next page section break the headers and footers of the new section are applied as expected. But then the available space on the first space would be lost.

This is IMO not a bug of this library, but is rather caused by the default Word behaviour which automatically sets the Link to previous option in the header/footer menue (see also MS docs: https://support.microsoft.com/en-us/office/link-to-previous-7b3bb5d6-d7e5-44fe-b2f1-ec71f8d9f193):

When looking at the underlying XML, one can see that a new section after a continuous section break does not contain a headerReference. I assume that based on the missing reference, Word automatically activates the Link to the previous option.

When creating a word document manually, this problem can be overcome if one adds the continuous section break, then adds multiple paragraphs until page two is showing up and then double clicks in the header/footer section (as shown above) and deactivates the Link to previous option. After that, one can style the header/footer of the second section without changing the ones on the first page.

Possible solutions:
Of course, if only the first page should look different, one can use the titlePage option but IMO it would be a way cleaner approach if the different stylings could be assigned to separate sections in general even when using the continuous section break.

I wonder if it would be possible to somehow adjust the library to prevent that behaviour either by

1. implementing the correct headerReference in the first place at the section xml when using a continuous section break or
2. giving the possibility to deactivate the Link to the previous setting before the headers are created (not sure if possible)

I would love to hear your opinion on that topic.

Cheers!

[dolanmiu]

Interesting observations, I am liking option 1, but I got to re-familiarize myself with the code to fully understand the scope

Can you send some sample code I can work with?

[Niccober]

Hi @dolanmiu , thanks for your answer. In the following you find a sample code for further investigation as requested:

  var doc = {
    file: {
      extension: 'docx',
      path: './files/',
      name: 'Test',
    },
    creator: 'Creator',
    title: 'Title',
    sections: [
      {
        headers: {
          default: new docx.Header({
            children: [
              new docx.Paragraph({
                children: [
                  new docx.TextRun({
                    text: 'HEADER PAGE ONE',
                  }),
                ],
              }),
            ]
          }),
        },
        footers: {
          default: new docx.Footer({
            children: [
              new docx.Paragraph({
                children: [
                  new docx.TextRun({
                    text: 'FOOTER PAGE ONE',
                  }),
                ],
              }),
            ]
          }),
        },
        children: [
          new docx.Paragraph({
            children: [
              new docx.TextRun({
                text: 'STATIC TITLE PAGE CONTENT',
              }),
            ],
          }),
          new docx.Paragraph({
            spacing: {
              after: 500
            },
            children: [
              new docx.TextRun({
                text: 'The first section ends after this paragraph.' 
              }),
            ],
          }),
        ]
      }, {
        properties: {
          type: docx.SectionType.CONTINUOUS
        },
        headers: {
          default: new docx.Header({
            children: [
              new docx.Paragraph({
                children: [
                  new docx.TextRun({
                    text: 'HEADER PAGE TWO AND FOLLOWING PAGES',
                  }),
                ],
              }),
            ]
          }),
        },
        footers: {
          default: new docx.Footer({
            children: [
              new docx.Paragraph({
                children: [
                  new docx.TextRun({
                    text: 'FOOTER PAGE TWO AND FOLLOWING PAGES',
                  }),
                ],
              }),
            ]
          }),
        },
        children: [
          new docx.Paragraph({
            children: [
              new docx.TextRun({
                text: 'DYNAMIC USER DEFINED CONTENT STARTING ON TITLE PAGE',
              }),
            ],
          }),
          new docx.Paragraph({
            children: [
              new docx.TextRun({
                text: 'The second section starts with the headline above. Move cursor to the end of this text and press enter until next page is generated in continuous section break mode.' 
              }),
            ],
          }),
        ]
      }
    ],
  }

To switch between the different break options just omit the type: docx.SectionType.CONTINUOUS in the properties object of the second section. When omitted, the default next page break will be applied. I am looking forward to hearing from you!

[dolanmiu]

I did a lot of research and now understand.

This is not a problem with docx. docx has the correct behaviour

This is IMO not a bug of this library, but is rather caused by the default Word behaviour which automatically sets the Link to previous

The Link to previous is nothing to worry about. Yes this is the case when there is no header in the section. So it is more of a visual indicator. I tried to de-select this option in Word, and it actually duplicates my header and adds it to the section. I believe

When looking at the underlying XML, one can see that a new section after a continuous section break does not contain a headerReference

Yes, because how Word works is that you have a 3 types of headers, first, default and odd.

Of course, if only the first page should look different, one can use the titlePage option

Correct. To achieve the effect you want, you need to specify that your first section is a titlePage, then set the first and default headers in the FIRST section.

but IMO it would be a way cleaner approach if the different stylings could be assigned to separate sections

It may be cleaner for the user, but not clean for the code haha. It would mean docx needs to do an internal translation of adding the titlePage property, shifting the headers to the right places blah blah, a lot of work for something which may not even catch all use cases. Sounds dangerous.

I have made an example: https://github.com/dolanmiu/docx/blob/master/demo/81-continuous-header.ts

I am guessing SectionType.CONTINUOUS is special in some way so it does not behave like a real section.

Potential solution

Perhaps a cleaner thing to do is to disable the header/footer property in the type definition whenever SectionType.CONTINUOUS is activated.

[Niccober]

Thanks for your research effort! Yes, it seems like the continuous section break is indeed somewhat special. I will go with the title page approach then which does work out for the given use case. In case of the need of an additional (third) set of headers/footers in the document later on I will just stick to the default next page section break.

Besides that, whenever you find the time I would highly appreciate if you could give me a short hint regarding the ExternalHyperLink element in combination with an image (#1699). It seems like a bug but I am not sure about it - could you verify?

[dolanmiu]

Will take a look and respond to the issue, thanks!