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

Support "transparent" HTML templates #437

Open
towerofnix opened this issue Mar 20, 2024 · 0 comments
Open

Support "transparent" HTML templates #437

towerofnix opened this issue Mar 20, 2024 · 0 comments

Comments

@towerofnix
Copy link
Member

These are templates with certain internal "constraints":

  1. These templates always accept any slot key paired with any slot values.
  2. These templates' content functions may return one top-level template (not wrapped in any HTML content).

And in external behavior, they:

  1. Run content just like normal.
  2. If content returned a template, slot their own slots into this template before returning it.

The content function, like usual, is always called with slots. The generate function (of a content function) is provided slots (which may carry any values) if the content function is explicitly transparent, i.e. it self-describes slots: 'transparent'.

Typically, transparent templates will only be used as part of infrastructure, for example to acquire context (#434) where internal behavior requires it (#435). Explicit transparency should only be used when the content function is specifically wrapping some template (or multiple templates) with actual content, and so needs to provide those slots directly, e.g:

export default {
  // doesn't need slots: 'transparent'

  generate: (data, relations) =>
    relations.linkTemplate.slots({
      someSlot: data.someValue,
    }),

  // does need slots: 'transparent'

  slots: 'transparent',

  generate: (relations, slots, {language}) =>
    language.$('misc.spookyLink', {
      what: relations.linkTemplate.slots(slots),
    }),
};

Transparent templates never validate any slot values since they're expressly meant not to make assumptions about the contents of the slots. They can introspect on the provided slots, if this is relevant, but acknowledge values are always provided as-is and not filtered or made "nice" (e.g. by providing html.blank() instead of null or undefined on a slot that the internal template specifies is type: 'html').

Actually making the same expectations about a slot as another template does is a completely separate issue, and generally a much higher-level of abstraction than what transparent templates are working with.

There's some concern about transparent templates that only exist implicitly, i.e. by internal requirement ('to' in extra dependencies), because these will look like ordinary templates externally, but will take any slots and then may not provide those slots to another template to be validated. Because we don't statically compute content functions' generate functions (i.e. the actual layout of the template), there's not really any getting around this right now, but in an ideal world we would...

  1. Require content functions that are explicitly transparent to always provide those slots somewhere to be validated
  2. Statically assess if content functions that are implicitly transparent directly return a template
    • If they do, treat them as normal transparent templates, taking all slots and validating them via child template as usual
    • If they don't, treat them as transparent templates for the sake of evaluation (internally they still require access to template context), but prevent them from accepting any slot values, since the slots will never be validated

But reaching that ideal is pending on static template layout evaluation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant