Custom rule: `eachPage` called multiple times for *some* pages about bindery

[freder]

repo: https://github.com/freder/bindery-bug-report

[evnbr]

Hi @freder, sorry this is poorly documented, but it is expected behavior that eachPage is called multiple times during rendering.

(This is what powers features like the table of contents— at the beginning of the book, we aren't sure what page number a certain section will land on. So every time the book changes, we let the other pages know so that they can update. What that means is any changes you make in a custom rule must be resilient to being called multiple times.)

bindery/src/rules/PageReference.ts

Lines 113 to 120 in b946d63

	updatePageReferences(pages: Page[]) {
	// querySelector first, then rerender
	const results = this.references.map(ref => {
	return { ref, matchingPageNumbers: pageNumbersForTest(pages, ref.testFunction) };
	});
	results.forEach(({ ref, matchingPageNumbers }) => this.render(ref, matchingPageNumbers));
	}

[freder]

@evnbr ok, cool. – wasn't sure if this is intended behavior or not.

(This is what powers features like the table of contents— at the beginning of the book, we aren't sure what page number a certain section will land on. So every time the book changes, we let the other pages know so that they can update. What that means is any changes you make in a custom rule must be resilient to being called multiple times.)

does that mean any change a rule makes triggers a 're-layout'? because when I tried resizing / positioning images in a custom rule, it seemed like text flow / layout was already done by the time my rule was executed.

without / with custom rule:

is there a (high-level) description of how layout / rendering works?

[evnbr]

As it currently stands, no rule can 'trigger a relayout'— sizes must be determined up-front. So the table of contents, for example, will first insert a placeholder element with an estimated size, and in the eachPage callback it will update the page number and assume it will still fit.

I suspect what you want to do is hook in earlier in the layout process using beforeAdd/afterAdd, as seen here, but those details are undocumented and probably difficult to use.

is there a (high-level) description of how layout / rendering works?

Great question— not yet, right now it's a bit spaghetti. I have a refactor in-progress that I believe will provide much clearer hooks for what you are trying to do here, presumably something like a "page float" as described in #84 . That work is going to happen in the next version of the pagination library (https://github.com/evnbr/regionize), with the plan that bindery will provide an easy / more declarative api for page floats on top of it. Will write something up when I get a chance!

[freder]

thx 👍