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

Add a Handlebars LibraryTemplateLoader and rework file loading to support partial templates #4921

Merged
merged 5 commits into from
Sep 14, 2024

Conversation

fishface60
Copy link
Contributor

@fishface60 fishface60 commented Sep 13, 2024

Identify the Bug or Feature request

closes #4920

Description of the Change

This has two major changes:

  1. Moves the code for injecting the base tag to after templates have been applied instead of when they are read.

    This is necessary because the syntax for including partial templates is {{> path}}
    but the Jsoup code that adds the <base> tag normalises this strictly invalid HTML to {{&gt; path}}
    which makes it an invalid Handlebars template.

  2. Adds a Handlebars TemplateLoader that loads from lib:// URLs.

    Because the templates are already publicly exported from add-ons,
    and they can load css from other files with relative URLs
    it is natural to support loading partial templates the same way.

    It is implemented as a URL loader which is aware of the path of the template being loaded
    and interprets relative paths as relative to the directory.
    As-implemented, absolute paths can load content from other add-ons, but this could be prevented by adjusting the prefix and current paths.

See https://gitlab.com/richardmaw/maptool-bar-test/-/tree/main/mtlib/library/public/sheets/basic for an example stat sheet that uses partial templates.

Possible Drawbacks

lib:// URIs were used to implement it as a URLTemplateLoader because handlebars.java already had a URL-based loader
and it was less intrusive to pass the URL around.

It would instead be possible to define a loader that uses a reference to the library which would have the benefit of allowing non-public templates, and bypasses the URL fetch machinery, but it may be useful to permit add-ons to depend on each other.

Documentation Notes

In https://wiki.rptools.info/index.php/Stat_Sheet_Tutorial there is a comment:

The & CSS selector didn't work when I created the examples, but may be available by the time you read this. It doesn't hurt to try it and see.

Which was probably due to the base tag being added before templates are parsed.

Release Notes

  • Fixed handlebars templates being mis-parsed if they were not strictly HTML.
  • Added support for loading partial handlebars templates with the {{> path}} syntax, which includes the contents of the named partial template file in the current template. If the path is an absolute path the first component is the library namespace. If the path is a relative path it is in the same directory as the template.
  • Adds the include helper, e.g. {{include "foo" bar=baz}} will include the partial template "foo" with the context altered to set bar to the value of baz in the current context.

This change is Reviewable

This needs to be fixed both in macros that show HTML frames
and in the stat sheets, so there should be a common util for it.
The Jsoup HTML fixup is destructive.
{{> foo}} gets turned into {{&gt; foo}}
which is not a valid template.

The Library.readAsHTMLContent method was removed because this was the
only place it was used for and it can't be safely used there,
and I couldn't think of another time it could be used.
This can now be supported after fixing the premature base url
handling and adding a lib:// based template loader.
@cwisniew cwisniew added this pull request to the merge queue Sep 14, 2024
Merged via the queue into RPTools:develop with commit 531498d Sep 14, 2024
4 of 5 checks passed
@cwisniew cwisniew added the feature Adding functionality that adds value label Sep 14, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature Adding functionality that adds value
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[Feature]: Handlebars partial template support would be helpful
2 participants