Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor string formatting across HTML and language, add "blockwrap" metatag #348

Merged
merged 12 commits into from Dec 30, 2023

Conversation

towerofnix
Copy link
Member

@towerofnix towerofnix commented Dec 29, 2023

Development:

This pull request brings a few related changes together:

  • Preserve lives values through language formatting functions.
    • Previously, html.Tag values (which we call "live values") which got passed into functions like language.$ or language.formatConjunctionList would get stringified at the time of that formatting function call, so that they could be inserted into string surroundings, either from a template specified in a strings file, or dynamically placed by an Intl.ListFormat formatting function.
    • Now, we always preserve the live values passed in as template options or list items. in order to surround those values with string-based text, we wrap results in a multiple-child html.tags element. (We already did a similar wrapping for marking the output of a formatting function as no longer needing sanitization; we're accomplishing the same thing now, too, but also using html.tags to be able to bundle multiple live values together.)
    • The meat of the new formatter is in a relatively generic #iterateOverTemplate function, which takes a "template", a regular expression that identifies parts of the template that should be replaced, and an insertion function, which processes the match and returns the content to insert at that point. The insertion function can return undefined to mark output forming as canceled, in which case the rest of the matches are stlil iterated over, but no final output is returned.
      • Usage 1: Iterate over {OPTION_NAMES} in a language file string; insert option values as provided, or, if missing, cancel string forming and mark the option as missing. Strike used options from a list; mark unused options as misplaced.
      • Usage 2: Iterate over <::insertion_0>, <::insertion_1>, <::insertion_2> etc in a string that was composed by an Intl.ListFormat formatting function. Replace with the corresponding items in a provided array.
      • #iterateOverTemplate sanitizes raw string values (using #sanitizeValueForInsertion, née #sanitizeStringArg) and conjoins adjacent strings. It also flattens nested tag values that are "content only", i.e. no tag name/attributes nor special (metatag) behavior - i.e, html.tags(), which are most often embedded as the result of another formatting function call.
      • In general, #iterateOverTemplate not only is an abstraction of the basic iteration/insertion behavior, but also consolidates supplemental stuff common across formatString and list formatters.
    • Lists formatters (like formatConjunctionList) now use a #formatListHelper function to take care of creating and operating on insertion markers - it's just a convenient wrapper around #iterateOverTemplate.
    • We also detect and report misplaced language string options now (in addition to missing ones). In general, formatString has been touched up with fresher reading, mostly thanks to #iterateOverTemplate.
  • Add new html.metatag system, including html.metatag('blockwrap').
    • "Metatags" are tags that should be treated differently from normal tags when being processed by a parent.
    • blockwrap is a metatag which, during content stringification, "absorbs" all same-parent siblings following it and puts them together with its own children, under a <span class="blockwrap"> tag.
    • Blockwrap exists as a somewhat crude, begrudgingly markup-based solution to the goal of "keep my words together on the same line, and let whatever inline content follows me come right after my last word". See details in this write-up.

Since blockwrap fundamentally functions outside the normal stringification hierarchy behavior, the language changes are required to ensure the blockwrap itself gets stringified (at which point it can't be detected for special handling by the parent's stringification).

We don't actually use blockwrap anywhere in this PR - changes to content are kept for a follow-up pull request.

@towerofnix towerofnix added scope: page generation - content type: groundworks Changes are foundational to further issues & code work labels Dec 29, 2023
@towerofnix towerofnix force-pushed the blockwrap branch 4 times, most recently from 12ac8f5 to 8d0762e Compare December 30, 2023 17:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
scope: page generation - content type: groundworks Changes are foundational to further issues & code work
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant