V4: Page Templates ( AKA Parent Pages, Master pages ) Proposal

[dbolack-ab]

Core concepts:

• A Page Template is a set of markup that is applied to all pages invoking the template.
• A Page Template may have will have a default markup along or right and left markups for use in aternating pages.
• A Page Template has two default, absolutely placed containers for elements. Additional containers are optional.
  • The first default represent the paper of the page. This should be sized for bleed where printing is expected. Background elements, watermarks, page numbers, paper-textures, etc. should go here. This is roughly analogous to the current page div element. This container is classed Template-page page. page is the document/theme default, ensuring baseline styling.
  • The second default represents the default text-pour area of the document. This is is roughly analogous to the columwrapper div element. This container is classed Template-default default. default is the document/theme default, ensuring baseline styling.
  • CSS classes for containers follow a simple, but fixed naming scheme. If a left and right layout is desired then the :odd pseudo selectors should be used with the assumption that the default is also :even.
• A Page Template is invoked in the \page declaration. eg: `\page Chapter1 {page-settings}.
• A Page Template may have it's own {{ }} declarations which will be prepended to any added for the page.
  • Example: If Template Weapons has {--chapterColor:orange} and page is invoked as \page Orange {--chapterColor2: red} the combined mustache would be {--chapterColor:orange,--chapterColor2: red}. This will allow for pages to override Template Page defaults.
• Pages Templates ARE inherited from Themes.
• A Page Template page definition is a normal Markdown+ page.
  • Containers are declared in the page definition as {{}} blocks with the first elementbeing the container type name ( paper, text, other custom name. )
• Default is an expected name for when no Template is declared for use on invocation.
• Template names should have spaces transformed to _

Changes required:

• Adjust class names in existing themes to new structure
• Push paper level elements from existing themes into template-page or page classes as appropriate.
  • Example: the page numbering footnote, parchment background
• Alternate versions of snippets targeting the paper when appropriate.
• Rendering restructure
• Additional Page Template editing pane

Rendering Restructure

This will slightly complicate our current rendering flow for a single page.

1. Determine Page template.
   a. If no template is declared, walk backward in document to last used template
   b. If no template is found in a, walk inheritance tree to last defined Default ( page, theme, theme-parent1... ) which should ultimately end at the Blank theme's Default.
2. Scan page for containers that exist the in Page Template.
   a. If none are found, wrap the page in the text container.
   b. Merge containers in the page definition and the filter. Classes and content from the template insert ahead of the page definition.
   c. Expand and substitute container name into class names in {{}} definition.
   i. paper becomes template-paper paper
   ii. text becomes template-text text
   iii. etc.
3. Parse resulting merged text.

What does this look like for users

• For light users who "simply" build documents, this should be a transparent change.The behavior of the default Template for the provided themes should match V3 behavior.
• Theme creators will be able to provide additional prefab material for end users with minimal work for those users.
• Distinct repeated page content can be pushed into a page and out of the edit window. Particularly useful for books with distinct chapter or section layouts.

A note about names

I chose Page Templates as the concept term here as it fits more in the names used with the Word processors frame of reference more of our users would be familiair with than the Master Page or Parent Page names that are more common with DTP. I'm not hugely married to that, if someone has a better idea.

Similarly, the container names for the .page and .columnWrapper analogues.