-
-
Notifications
You must be signed in to change notification settings - Fork 8
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
Next major version #17
base: master
Are you sure you want to change the base?
Conversation
@line-o please rebase |
@duncdrum done! Thanks for merging the other PRs |
@line-o p.s. As long as this involves breaking changes, I'm not sure if you want to resurrect a previously reverted breaking change from @wolfgangmm involving the |
You are right @joewiz ! |
Also food for discussion is where to put which functions. As it is now possible to use only functions in the templates namespace, which functionality does it have to provide to be useful on its own?
|
@joewiz There is no need to reincorporate the reverted changes from #8 as the delimiters can no longer be set in templates but are now set once in the configuration. templating/test/xqs/test-suite.xql Lines 305 to 306 in a544af7
If, however, this is not acceptable then we would have to look into this once more. |
Hello, sorry to be a bit late to the party! I had some suggestions which I've previously raised with @joewiz for improving some aspects of the templating system; I've added them here as feature request #20 : is there any mileage in considering a similar solution as part of this next version? Looking at the code, the implementation still looks fairly straightforward, with the suggested changes to |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good to me. We should check the documentation article for templating for necessary adjustments.
Needs another rebase
I wonder if it would make sense to have |
I appreciate your feedback, honestly. Good stuff here @duncdrum @wolfgangmm
|
@line-o i can help with the docs |
@wolfgangmm your proposal is now part of this PR |
I have an additional question regarding the handling of the now obsolete declaration of
Is it worth it keeping this extra check in the library or even harmful as those declarations stay in there? |
+1 for throwing an error, explicit design >> black box design |
- refactor initial functions - templates:apply#3 and eXist-db#4 - templates:render#3 - add function templates:configure called in all initial functions - attribute filtering function is now selected by configuration instead main benefit is the if condition does not need to be called each time
- lib:include moved to templates:include - lib:parse-params is now moved to templates:parse-params - remove lib - last remaining lib function lib:resolve-apps is now apps:by-abbrev links are now added to the model under key 'app' declare default value for links of apps that were not found - delimiters are now part of the configuration and cannot be changed inside of templates - add example (and test) for reading template-path from model - refactor for speed and readability
- the default handling of duplicates when merging maps will change to use-first. Therefore set duplicate handling explicitly to use-last where it is crucial
This is the first version that implements map:merge#2
BREAKING CHANGES: - $templates:START_DELIMITER => $templates:CONFIG_START_DELIMITER - $templates:END_DELIMITER => $templates:CONFIG_END_DELIMITER - All errors are prefixed with E_ - All settings are prefixed with CONFIG_
In an effort to declare all dependencies explicitly.
- add comment if surround template was not found - avoid *-selector in XPath expression
Simplify check for problematic options.
The $selected variable either contains the attribute setting an option as selected or an empty sequence.
This is in order to drop them from being the default in the next step.
- apps is now tmpl-apps to make it obvious it is not an application module - tmpl-util contains utility functions that clobber up the core library (unused for the moment)
- build regular expressions for parse-params at configuration and re-use those throughout the code base - remove functions from template that are now in tmpl-util - use tmpl-util:* replacements in templates functions
This deprecates templates:parse-params as placeholders in text and attribute nodes will always be replaced. Before: `<span data-template="templates:parse-params">[[item]]</span>` Now : `<span>[[item]]</span>` Any data-template attribute with the value "templates:parse-params" is ignored.
Always throw an error if a declared template function cannot be found. The attempt to ignore certain function names creates more problems than it solves as it does not incentivise to clean up templates when switching to the newer templating library. The test for templates with a legcacy declaration was apapted.
eXist-db will now return status code 500 server error when an exeption is thrown during query execution (see eXist-db/exist#4639). Since the templating library is not concerned with routing we simply add this other accepted status code to the list. Tests expecting errors will pass with both satus code 400 and 500.
The feedback from the community
data-template="templates:parse-params"
obsoleteNOTE: #22 is out of scope as it can be implement later as a configuration option
Embrace the top-down approach by allowing dynamic includes
with main page template, which is passed to
templates:render
and a model, (the second parameter to
templates:render
)It is feasible to create quite flexible template structures that are easier to reason about. You do not need many, maybe no custom template function at all.
Don't worry
templates:surround
is still... around.BREAKING CHANGES
templates:parse-params
(could be renamed totemplates:substitute
) must be set as configuration options now. This also means there is no way to change them somewhere in between.In order to include the in the output you will have to set
$templates:CONFIG_FILTER_ATTRIBUTES : false()
in the options.lib:resolve-apps
is now part of a new module calledtmpl-apps
and the function was renamed totmpl-apps:by-abbrev
. It will put all resolved application paths into a map in the model under theapps
key. Retrieval is done by<p id="test1">${apps?templating-test}</p>
.FEATURES
Function resolution
You can pass in
xs:QName(?)
as CONFIG_QNAME_RESOLVER instead of passing in a function that callsfn:function-lookup
CONFIG_FN_RESOLVER. Due to a an issue in eXist-db's XQuery implementation (see eXist-db/exist#4614 ) this can only resolve functions from imported modules at the time of writing. The old approach can be used as before.If you pass in none of the above the default resolver will still allow you to use all basic template functions in
templates
namespace.Parameter resolution
The configuration option for parameter resolution can now contain a sequence of functions
(function(xs:string) as item()*)*
where it had to be a single function before. This allows for greater control over where parameter values are read from.Defaults to
Error reporting
when a template function cannot be resolved then the node is serialised in the error message to make it easier to find where the issue has occurred
New entry point
templates:render
is a shorthand totemplates:apply
where the lookup is passed as part of the configMax arity
With
$templates:CONFIG_MAX_ARITY
you can now specify the maximum arity of template functions. Defaults to 8 was 20.Placeholder replacement
Before you had to declare
data-template="templates:parse-params"
(that wasdata-template="lib:parse-params"
respectively in 1.1.0) to have placeholders in attributes and text nodes replaced.This is no longer necessary and placeholders will always be replaced using the provided resolvers or the model.
Changes
templates:resolve-key($model, $key)
will call the configured parameter resolvers internallyAs the tests show this version does raise the minimum required processor version to eXist-db v5.4.1 because of NPEs in v5.2.0.