NotePlan Plugin Templating

[mikeerickson]

NotePlan Templating

Overview

There are a slew of templating libraries available in the JavaScript world as it relates to templating and we could discuss the pros and cons ad nauseum. Our aim is to implement a templating system that can be used across all current and future NotePlan Plugins, paying close attention to the common tasks such as conditionals, looping, method execution and data pipe filter.

Shared Templating

Since most of the NotePlan users won’t have a programming background, I think choosing a tool that is as user friendly as possible is important and should be one of the primary factors that goes into our final decision. On the other hand, we as plugin developers will be using the templating tool the most, thus we need to make sure it supports all of our current (and future) requirements.

Core Features

While we all have our own unique requirements, there are core features which should be available in the library we settle on

• easy to read
• ability to execute javascript functions {{ myFunction() }} or <% myFunction %>
• conditional branching ( if / else)
• looping
• pipe filter
• how well does it fit into NotePlan notes (make sure nothing breaks as a markdown note)

JavaScript Templating Libraries

I have personally used handlebars a lot over the years, but I could just as easily pick a tool such as nunjucks or eta as they have their own unique set of features.

The following are some of the more popular templating libraries for JavaScript and provide the most features to align with our current and future templating needs.

There are obviously pros and cons to any templating library (this topic could be discussed forever as I am sure everybody is going to have their opinion).

📖 Refer to References at end of document for links to each library

• ejs (see comparisons with eta)
• eta (this is the one used by Obsidian Templater Plugin, perhaps a good selection for attracting Obsidian user)
• handlebars (successor to mustache)
• swig (JavaScript port of Twig, a popular PHP templating tool used by Symphony)
• squirrelly

💬 Jinja (popular in the Python world) has been mentioned on a github issues and there are two similar libraries for JavaScrip, see nunjucks or eta for more context.

Templating Libraries to Avoid

One thing I would like to stress, there is a popular templating library called pug (formerly jade) which should be avoided as the templates simply will not work in NotePlan notes. They are dependent on indentation style formatting (much like Python programming) and NotePlan notes fail in this regard.

Templating Tags

If we ultimately decide to use nunjucks or eta, I feel we need to make that decision sooner, rather than later, as it will require a shift from current templating tags

Current Tags:

• {{ }}

Alternate Tags:

• <% %> used by eta
• {% %} used by nunchucks

References

eta

handlebars

mustache

nunjucks

pug

swig

squirrelly

eta vs Ejs

templater

[dwertheimer]

I would echo what @jgclark said before I got here…why not just mirror Templater (and use eta)? Then if people migrate over that have templates, they will just work. My only concern with using a library is speed and size. Every plugin that uses templates is going to get the whole ETA code, less any tree-shaking. My guess is this is why @nmn chose to write a small version of it. Whichever version you choose I hope it will provide for template function extension without requiring someone to edit core template files (which they do now)

…

On Thu, Sep 16 2021 at 2:50 PM, Mike Erickson < ***@***.*** > wrote: ******************* NotePlan Templating ******************* -------- Overview -------- There are a slew of templating libraries available in the JavaScript world as it relates to templating and we could discuss the pros and cons ad nauseum. Our aim is to implement a templating system that can be used across all current and future NotePlan Plugins, paying close attention to the common tasks such as conditionals, looping, method execution and data pipe filter. ----------------- Shared Templating ----------------- Since most of the NotePlan users won’t have a programming background, I think choosing a tool that is as user friendly as possible is important and should be one of the primary factors that goes into our final decision. On the other hand, we as plugin developers will be using the templating tool the most, thus we need to make sure it supports all of our current (and future) requirements. ------------- Core Features ------------- While we all have our own unique requirements, there are core features which should be available in the library we settle on * easy to read * ability to execute javascript functions {{ myFunction() }} or <% myFunction %> * conditional branching ( if / else) * looping * pipe filter * how well does it fit into NotePlan notes (make sure nothing breaks as a markdown note) ------------------------------- JavaScript Templating Libraries ------------------------------- I have personally used handlebars a lot over the years, but I could just as easily pick a tool such as nunjucks or eta as they have their own unique set of features. The following are some of the more popular templating libraries for JavaScript and provide the most features to align with our current and future templating needs. There are obviously pros and cons to any templating library (this topic could be discussed forever as I am sure everybody is going to have their opinion). > > > 📖 Refer to References at end of document for links to each library > > * ejs (see comparisons with eta) * eta (this is the one used by Obsidian Templater Plugin, perhaps a good selection for attracting Obsidian user) * handlebars (successor to mustache) * swig (JavaScript port of Twig, a popular PHP templating tool used by Symphony) * squirrelly > > > 💬 Jinja (popular in the Python world) has been mentioned on a github issues > and there are two similar libraries for JavaScrip, see nunjucks or eta for > more context. > > Templating Libraries to Avoid ----------------------------- One thing I would like to stress, there is a popular templating library called pug (formerly jade) which should be avoided as the templates simply will not work in NotePlan notes. They are dependent on indentation style formatting (much like Python programming) and NotePlan notes fail in this regard. --------------- Templating Tags --------------- If we ultimately decide to use nunjucks or eta , I feel we need to make that decision sooner, rather than later, as it will require a shift from current templating tags Current Tags: * {{ }} Alternate Tags: * <% %> used by eta * {% %} used by nunchucks ---------- References ---------- eta ( https://eta.js.org/ ) handlebars ( https://handlebarsjs.com/ ) mustache ( https://mustache.github.io/ ) nunjucks ( https://mozilla.github.io/nunjucks/ ) pug ( https://pugjs.org/api/getting-started.html ) swig ( https://node-swig.github.io/swig-templates/ ) squirrelly ( https://squirrelly.js.org/ ) eta vs Ejs ( https://eta.js.org/docs/about/eta-vs-ejs ) templater ( https://github.com/SilentVoid13/Templater ) — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub ( #89 ) , or unsubscribe ( https://github.com/notifications/unsubscribe-auth/ACEI6VAWIWFXKFBK7RP5VT3UCJRB7ANCNFSM5EFVWNNQ ).

[mikeerickson]

@jgclark@dwertheimer i am 100% on board with mirroring Templater and using Eta. Seeing as we are basically shaping the future of NotePlan Templating, we already have a consensus on the direction.

If any of us want to tackle creating our own version of Temlater for NotePlan, that is fine by me, the sooner the better.

I do think it would be a better plan to create a new project (maybe np.Templating so it has np moniker from the get go) and start with a clean canvas, as opposed to reworking nmn.Templates.

As far as speed is concerned, I really don’t think it will be that big an issue, but for argument sake, we could create a POC and throw some big jobs at it and see how it performs.

I am eager to get something in as soon as possible as I have been stalling on a few plugins/commands that will use this library from the jump.

So, if either one of you want to run np-cli plugin:create np.Templating please do so, or if you want me to get it started, I am game as well.

[jgclark]

Thanks, @mikeerickson. I agree with all your requirements, and would add ...

My original reason for raising the related issue (#11) was concern at the too-tight coupling between extension functions (my name for {{doSomething()}}) that we were writing through a number of plugins, and the Templates plugin itself. This still does all the dispatch for extension functions, which means there's a need for one dispatcher, which alone knows all things. At the moment this is ok, but it doesn't naturally scale, or allow for private (or other non-'blessed') plugins to provide functions.

So I think there's a new requirement: the ability for a dev to write an extension function and be able to run it locally without having to submit it to 'the NotePlan team' for inclusion.

I also wouldn't be surprised if a Template mechanism doesn't appear in the NotePlan app itself at some point. We're also actively discussing the plugin configuration mechanism getting direct support in the app. Therefore I think we should separate out these different concerns that the Template plugin currently handles in one place.

So let's not forget that part of this is sorting out a more future-proof plugin framework, not just picking a templating language/library.

I also wonder whether we have a requirement to be able to run (arbitrary?) JavaScript given as a parameter to future extension functions?

On potential templating solutions, I have no experience to offer. And now I've just had a week off, I'm not going to be in a place for a while to go and do lots of research into the options. And, as you know, I'm still a JavaScript newbie, so I can't really evaluate that side of them anyway.

[mikeerickson]

@jgclark you are too modest my friend, you are doing a fabulous job, even if it is a hobby.

@dwertheimer seeing as @jgclark will be tight on time, let me know if you want to tackle the initial tooling, or if you would like me to start. I have plans this weekend to do some of my template required work, and I was going to do a crude implementation, and will do so around eta regardless, so just let me know.

[dwertheimer]

Sadly I am slammed with work and can’t spend enough time on this for a bit. Also, I’m more of a hacker… :)

…

On Thu, Sep 16 2021 at 6:18 PM, Mike Erickson ***@***.***> wrote: @jgclark <https://github.com/jgclark> you are too modest my friend, you are doing a fabulous job, even if it is a hobby. @dwertheimer <https://github.com/dwertheimer> seeing as @jgclark <https://github.com/jgclark> will be tight on time, let me know if you want to tackle the initial tooling, or if you would like me to start. I have plans this weekend to do some of my template required work, and I was going to do a crude implementation, and will do so around eta regardless, so just let me know. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#89 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACEI6VBG7GZ3MERMFDGI5U3UCKJPJANCNFSM5EFVWNNQ> .

[tastapod]

As a consumer rather than producer of templates, I would advocate for something that respects Postel's Law, and is generous with what it consumes.

I have noticed already that constructs like this are very brittle with respect to white space:

{{events({template:"- [ ] ***|START|***: *|TITLE|*",allday_template:"- **|TITLE|**"})}}

Putting any space after the {{ or anywhere inside the parameter object, say around the commas, colons or braces, breaks the template silently.

This hurts my brain because some of the syntax is for the template, and some of it is just Markdown within the template, and I can't tell which is which without staring at each character! I would hope for a solution that is more forgiving than this.

Choosing a parameter syntax that doesn't look like Markdown will help. **|EXPAND_ME|** seems particularly pathological! I'm a fan of $EXPAND_ME with generalised case of ${EXPAND_ME some other stuff}, but happy to take anything that passes the "Oh that looks obvious!" test.

Another principle I tend to follow with templating is "less is more". As soon as your templating becomes an actual language, people will do crazy things with it. If it has anything more than rendering and formatting of values; branching; looping; inclusion/partials, then we are likely overthinking it IME.

Finally, if there is a well-understood and well-respected templating/macro solution in the JS world that plays nice with Markdown (I don't know the state of the art enough to know) then I would advocate for that rather than reinventing any wheels.

Thanks for listening!

[mikeerickson]

@dwertheimer I completely understand what you are saying. in my opinion, the template should be as human readable as possible, let extensive enough to accomplish the task. And, with regards to “white space” I believe the only thing that should be truncated is the the leading and trailing space inside the tag

Your example it tough to read and predict outcome, something that we will hopefully eliminate (on both items) with the new templating library. I feel like if it were recreated as the following, the output should be the same.

<%events({timed: "- [ ] ***|START|***: *|TITLE|*",allday: "- **|TITLE|**"})%>

This readable code block is less intimidating for the end user to read, and would require very little refactor in the underlying plugin code. Basically, the events method will receive a config object and destructure it to get the parameters.

const{timed: template,allday: allday_template}=configFromNoteParam

but the user doesn’t need to know what happens within the plugin, they just need the result

[jgclark]

Well said, @tastapod and thanks for the link to Postel's Law, which was new to me.
I hope eta will have a better templating scheme to use than *|...|*, which hurt me to implement, and particularly to document! @mikeerickson is right to say it gets easier to read when laid out with added whitespace, but even so, please let's change it!

[mikeerickson]

@tastapod

I have noticed already that constructs like this are very brittle with respect to white space:

{{events({template:"- [ ] ***|START|***: *|TITLE|*",allday_template:"- **|TITLE|**"})}}

Putting any space after the {{ or anywhere inside the parameter object, say around the commas, colons or braces, breaks the template silently.

So, if the construct were like I have suggested, would that be "offending", for example:

<%
events({
template: "- [ ] ***|START|***: *|TITLE|*",
allday_template: "- **|TITLE|**"
})
%>

Or, even as a one liner:

<% events({template: "- [ ] ***|START|***: *|TITLE|*", allday_template: "- **|TITLE|**"}) %>

[mikeerickson]

Well said, @tastapod and thanks for the link to Postel's Law, which was new to me.
I hope eta will have a better templating scheme to use than *|...|*, which hurt me to implement, and particularly to document! @mikeerickson is right to say it gets easier to read when laid out with added whitespace, but even so, please let's change it!

So, would this be more appealing?

{{
events({
template: "- [ ] **<% START %>**: <% TITLE %>",
allday_template: "- **<% TITLE %>**"
})
}}

As you can see, I have had to mix the tags {{ and }} in the outer block, and used <% and %> on the inner tags, otherwise the render method would attempt to render everything in one pass, but in the case of this block, you have nested rendering occuring (assuming events will also have an array of items that need to be processed internally where START and TITLE are internal variables.

Alternately, it could be formatted as (again assuming START and TITLE will be looped variables.

<%
events({
template: "- [ ] **|START|**: |TITLE|",
allday_template: "- **|TITLE|**"
})
%>
If I am assuming incorrectly, please let me know and I will adjust accordingly.

[mikeerickson]

@jgclark@dwertheimer
Alright, I am going to get this project started and will get a POC version posted as soon as possible so that we can all start using it and find the holes, etc that need to be plugged up. I should have something to share in a few days, I don’t anticipate any big hurdles for POC version, we will work on edge cases, etc. after POC is cleared.

[jgclark]

Some excellent input here. (I do love the way that as we inhabit different time zones I can always expect some useful progress happening while I'm hard at work ... sleeping!)

I am 100% on board with mirroring Templater and using Eta. Seeing as we are basically shaping the future of NotePlan Templating, we already have a consensus on the direction.

Sounds like we have agreement that this is our Plan A, and that we will:

create a new project (maybe np.Templating so it has np moniker from the get go) and start with a clean canvas, as opposed to reworking nmn.Templates.

Indeed, I suggest when the new np.Templating is ready, we should slim down nmn.Templates to be back to be just about defining and using templates, not the whole templating language. (If possible that is; the coupling between the two might turn out to be necessary.) This will mean we continue to honour the excellent work of @nmn getting us started on this journey.

And I'm very grateful to you, @mikeerickson, for being willing to get this new development underway. I stand ready to test, and to think ahead to future harder use cases.

[mikeerickson]

@jgclark I feel the exact same about waking up in the morning (I usually get started around 5am) there will be meaningful notes, etc. from the other ends of timezones :-)

However we can leverage nmn.Templates is totally fine by me, he did a great job getting it off the ground and this new project was only manifested by what he started, and now we seek to bring to the next level based on requirements.

I am eager to get this into your hands as quickly as possible so we fan start hammering on it and discover what changes will be necessary to support all the existing plugins, and what others will create in the coming weeks, months, years.

And, I hope the code in this new project give inspiration to future plugin authors, as it will contain as much test case coverage as possible!

[mikeerickson]

@dwertheimer so, i found your answer about speed

Eta's is weighing in at only 2.4KB gzipped!!

So, if we have a speed issue, it is not the library size 😀

[dwertheimer]

yeah, but I don't think we gzip and if (most) every single plugin has eta bundled in, it that amount goes up geometrically. As you said, let's do some tests. @EduardMe can run some profiles on the Swift side to see how much time a plugin takes from load to finish. By the time we see it on our side, it's already loaded.

…

On Fri, Sep 17, 2021 at 3:06 PM, Mike Erickson ***@***.***> wrote: @dwertheimer <https://github.com/dwertheimer> so, i found your answer about speed Eta's is weighing in at only 2.4KB gzipped!! So, if we have a speed issue, it is not the library size [image: 😀] — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#89 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACEI6VA5Q6GXDVS2EIE32D3UCO3WVANCNFSM5EFVWNNQ> .

[mikeerickson]

Nice David, throwing some advanced knowledge there!. 💥😊

The good thing is, these template actions don’t run on a regular basis, thus not really concerned.

[EduardMe]

You mean for executing a plugin? I can add time stamps before and after, if it helps, which prints into the logs or console.

[mikeerickson]

@jgclark wanted to say thank you for sharing Templater, which in turn leads me to eta

This is a nice little gem, I can already say it will replace my use of handlebars moving forward.

[dwertheimer]

yes. would be great if Noteplan could log to the console the elapsed time of the plugin run --- from before you load it into memory, to when it returns). We need to be able to test the overhead of loading the templating library. We don't really need before/after if you give us elapsed time.

…

On Sat, Sep 18, 2021 at 7:31 AM, Eduard Metzger ***@***.***> wrote: You mean for executing a plugin? I can add time stamps before and after, if it helps, which prints into the logs or console. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#89 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACEI6VHMC7VBFB3TGO2KIK3UCSPD5ANCNFSM5EFVWNNQ> .

[mikeerickson]

If @EduardMe does time before and after plugin execution, we can do the math as well. I think it would be a “nice to have” for any plugin command.

[dwertheimer]

Of course. But we can't manipulate it if it's just output in the console, so you'd have to pull out your calculator. that's why I thought it's better if he just outputs the calculation (but it would be fine if he outputs before/after/elapsed) — though you'd probably never use the before/after. :) It will be interesting though to do a start/end/elapsed inside the JS/plugin itself and compare it to the Noteplan timing.

…

On Sat, Sep 18, 2021 at 7:40 AM, Mike Erickson ***@***.***> wrote: If @EduardMe <https://github.com/EduardMe> does time before and after plugin execution, we can do the math as well. I think it would be a “nice to have” for any plugin command. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#89 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACEI6VHX2PFAXIBWWRSS5M3UCSQGNANCNFSM5EFVWNNQ> .

[EduardMe]

Elapsed time is simple. I have already code to do that, it‘s just copy and paste. I need to find the right place though.

[mikeerickson]

np.Templating Status Update

• Implement eta library
• Support global and namespace (template objects begin with np)
• Support Variables
• Support Custom Methods
• Support standard and extended mode (extended allows using all array methods - .forEach, etc)
• All tests are passing
• All date utility functions accounted for (matching Templater)
• All note utility functions accounted for (matching Templater) [pending]
• Support custom tags (plan to support {{ and }} provide testing is favorable) [pending]
• Migrate nmn.Templates utility methods used in other NotePlan Plugins
  - applyNamedTemplate
  - insertNamedTemplate
  - getStructuredConfiguration
  - getOrMakeConfigurationSection
• Interface with NotePlan notes
• Custom Error Handler

Performance

• Speed is pretty awesome so far (see testing times, and this includes test runner overhead)

• @jgclark@EduardMe@dwertheimer

[EduardMe]

Wow, awesome!

[tastapod]

This is fantastic progress, @mikeerickson!

• Support custom tags (plan to support {{ and }} provide testing is favorable) [pending]

FWIW I tend to favour consistency over short-term convenience. In other words, I might not introduce special support for existing delimiters like {{ }} (and oh please not *| |*!) if those are not standard in eta. Instead have a (short) transition period and/or (semi-)automatic process to convert existing templates to use the new format. (I suspect the 99% case could be a handful of regexes.)

I think templates are still new/beta enough that people won't mind a one-time conversion to set everything off on a consistent footing. If my template breaks, I will convert it using the excellent README that I will no doubt find. 😁

[jgclark]

You echo my thoughts exactly, @tastapod.

[dwertheimer]

Mike you are amazing!

…

On Sat, Sep 18, 2021 at 4:19 PM, Mike Erickson ***@***.***> wrote: np.Templating Status Update - Implement eta library - Support global and namespace (template objects begin with np) - Support Variables - Support Custom Methods - Support standard and extended mode (extended allows using all array methods - .forEach, etc) - All tests are passing - All date utility functions accounted for (matching Templater) - All note utility functions accounted for (matching Templater) *[pending]* - Support custom tags (plan to support {{ and }} provide testing is favorable) *[pending]* - Interface with NotePlan notes - Migrate nmn.Templates utility methods used in other NotePlan Plugins - applyNamedTemplate - insertNamedTemplate - getStructuredConfiguration - getOrMakeConfigurationSection - Custom Error Handler Performance - Speed is pretty awesome so far (see testing times, and this includes test runner overhead) [image: CleanShot 2021-09-18 at 16 13 57] <https://user-images.githubusercontent.com/183153/133910834-fdef2400-1cc4-4b2e-a459-e7afd7289a7f.png> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#89 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACEI6VCOCRAVMPLVI2ASRTTUCUNABANCNFSM5EFVWNNQ> .

[jgclark]

For some Readwise improvements I wanted to make (getting a backup of all my highlights into Obsidian), I've needed to learn bits of the jinja2 templating system. It seems quite a close (python-based) parallel to eta. And in case it's that close, the one annoyance I've found is how it handles white space. It turned out to be much harder than expected to get spaces where I wanted them between multiple variables in output. It's just a little thing that we'll need to make sure we test ...

[tastapod]

I presume you mean Jinja2? What kind of problems are you seeing?

[jgclark]

Thanks for the correction. It was surprisingly difficult to get the equivalent of {{Title}} ({{Author}}) Highlights where author was optional, without it removing spaces between things.

[mikeerickson]

@jgclark Not sure how Jinja2 works as I have not used it, but in np.Templating (which uses Eta) you could do the following (using ternary operations as it is pure JavaScript)

<%= title.length > 0 ? ` ${title} ` : ‘’ %>

The conditional space you are looking for is within the JavaScript template literal within the tags. I am not sure how Jinja2 handles ternary, but you should able to do something like

<% Title.length > 0 ? ` ${Title} `:'' %><% Author.length > 0 ? ` (${Author}) `:'' %>

[tastapod]

The equivalent in Python is the "ternary if": {{ " " + author if author else "" }}

[mikeerickson]

FWIW I tend to favour consistency over short-term convenience. In other words, I might not introduce special support >
for existing delimiters like {{ }} (and oh please not | |!) if those are not standard in eta. Instead have a (short) > transition period and/or (semi-)automatic process to convert existing templates to use the new format. (I suspect the >
99% case could be a handful of regexes.)

I would agree that using the default tags is preferred, and the only reason this item is there as it is an option for Eta natively, not something I am doing "custom". Implementation took all of 15 minutes (including creating all the tests).

I think templates are still new/beta enough that people won't mind a one-time conversion to set everything off on a
consistent footing. If my template breaks, I will convert it using the excellent README that I will no doubt find. 😁

No pressure there :-)

Documenting this capability is something that may not even be exposed to public documentation, thus meaning that <% and %> will be the only publicly exposed tags.

More to come...

[mikeerickson]

@jgclark@dwertheimer@tastapod@EduardMe

I have nested templates working!

The following template produces

data:

constdata={displayBooks: (config={})=>{letresult=''config.books.forEach((book)=>{letrow=book?.TITLE?.length>0
? config.full.replace('|AUTHOR|',book.AUTHOR).replace('|TITLE|',book.TITLE)
: config.partial.replace('|AUTHOR|',book.AUTHOR)result+=row+'\n'})returnresult},books: [{TITLE: 'The Sobbing School: Poems',AUTHOR: 'Joshua Bennett'},{TITLE: `Ain't No Mo'`,AUTHOR: 'Jordan E. Cooper'},{TITLE: 'A Particular Kind of Black Man',AUTHOR: 'Tope Folarin'},{TITLE: 'Where We Stand',AUTHOR: 'Donnetta Lavinia Grays'},{TITLE: 'Invasive species',AUTHOR: 'Marwa Helal'},{TITLE: 'The Sirens of Mars',AUTHOR: 'Sarah Stewart Johnson'},{TITLE: null,AUTHOR: 'Mike Erickson'},],}

template:

<%~ displayBooks({
books,
full: "**|AUTHOR|**: |TITLE|",
partial: "**|AUTHOR|**"
})%>

output:

 **Joshua Bennett**: The Sobbing School: Poems
**Jordan E. Cooper**: Ain't No Mo'
**Tope Folarin**: A Particular Kind of Black Man
**Donnetta Lavinia Grays**: Where We Stand
**Marwa Helal**: Invasive species
**Sarah Stewart Johnson**: The Sirens of Mars
**Mike Erickson**

[jgclark]

Excellent. Quick to grasp and pretty clean.
A couple of suggestions, if I may?

Firstly, before we get too far with even examples, is it possible to change from |KEYWORD| to something else? While us devs are used to the pipe symbol, most mortals aren't. Would ::KEYWORD:: be easier to type and to read? It might have the advantage too of being rendered in some markdown-y places as a highlight, which would make it easier to tell if they've been specified correctly.

Second, I'm intrigued whether it might be possible already to move some of the logic from code to the template definition? For example something like (the basic and untested):

<%it.books.forEach(function(book){%>**<%=book.TITLE%>**: <%=book.AUTHOR%><%})%>

That avoids the delimiters entirely ;-)

What I don't know yet is how you pass the book data array to the template.

[mikeerickson]

Yes, I am sure I can make that work as well. My first approach (as documented above) was to implement the same approach you had already been doing (and related to @tastapod comment). As far as the delimiter question, you can provide whatever syntax you wish the initial example had the displayBooks method perform the .replace against your own delimiters.

I will work on testing the alternate syntax you have proposed.

Excellent. Quick to grasp and pretty clean.
A couple of suggestions, if I may?

Firstly, before we get too far with even examples, is it possible to change from |KEYWORD| to something else? While us devs are used to pipe symbol, most mortals aren't. Would ::KEYWORD:: be easier to type and read? It might have the advantage too of being rendered in some places as a highlight, which might help still demonstrate if they've been specified correctly.

Second, I'm intrigued whether it might be possible already to move some of the logic from code to the template definition? For example something like (the basic and untested):

<%it.books.forEach(function(book){%>**<%=book.TITLE%>**: <%=book.AUTHOR%><%})%>

What I don't know yet is how you pass the book data array to the template.

[jgclark]

Thanks. I'm not suggesting it as a priority to work on, but it's an interesting test case for the power of this more advanced templating system, allowing some things to move from code to config.

[mikeerickson]

@jgclark

OK, with some small adjustments to the template markup, I have gotten this working as well

modified template:

<% books.forEach(function(book){ %>
**<%~ book.TITLE %>**: <%= book.AUTHOR %><% }) %>

output:

**The Sobbing School: Poems**: Joshua Bennett
**Ain't No Mo'**: Jordan E. Cooper
**A Particular Kind of Black Man**: Tope Folarin
**Where We Stand**: Donnetta Lavinia Grays
**Invasive species**: Marwa Helal
**The Sirens of Mars**: Sarah Stewart Johnson
**The NotePlan Templating Guide**: Mike Erickson

On this line, the following adjustments have been made:

**<%~ book.TITLE %>**: <%= book.AUTHOR %><% }) %>

• I removed the it. which I am sure you leveraged from the Obsidian template (the Templater plugin namespaces with it) but np.Templating does not have any namespace requirements.

• I moved the 3rd line up to be part of second line, otherwise it produces unwanted line breaks (any character outside of the tags will be preserved accordingly). I know this breaks "style" when you would typically place the )} on the next line

• On this line, you need to use <%~ so that it will properly encode the result. You could also do this, just need to make sure the %> and <% are on the same line (see end of first line)

**<%~ book.TITLE %>**: <%= book.AUTHOR %><%
}) %>

But, other than these minor adjustments to the markup, the logic could be performed in the template, thus reducing need to call out to a magic method

If you have a full template which you are currently using to produce something similar in complete, I will create appropriate tests to make sure it works.

[jgclark]

That's great to see, and an excellent test of the principle, as well as the practice. I don't have other examples in mind at the moment. And I don't want to further distract you from integrating and testing it into NP itself. Thanks.

[mikeerickson]

@jgclark that will be the next major development push.

[tastapod]

This is looking really good. Great work @mikeerickson.

[dwertheimer]

So cool, Mike. Nice work!

…

On Tue, Sep 21, 2021 at 4:39 PM, Mike Erickson ***@***.***> wrote: @jgclark <https://github.com/jgclark> that will be the next major development push. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#89 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACEI6VDFVXADM5DBUSULTNTUDEJUFANCNFSM5EFVWNNQ> .

[mikeerickson]

Thanks bud, it is coming along nicely. Looking forward to cracking open the NotePlan integration soon!

When we are all said and done, I would like to share the key points as it relates to encapsulation and testing.

The template file has 100% function coverage, and the helpers is currently at 75% function coverage, and that is only because I have placeholder code for functions that have not been written yet. These will start filling up once I begin working with the NotePlan API and I see exactly what is needed as far as additional methods are concerned.

-------------|---------|----------|---------|---------|-------------------
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
-------------|---------|----------|---------|---------|-------------------
All files | 100 | 79.17 | 80 | 100 | helpers.js | 100 | 76.47 | 75 | 100 | 36-44 template.js | 100 | 85.71 | 100 | 100 | 26 -------------|---------|----------|---------|---------|-------------------
Ran 25 tests in 0.928 s
✔ 23 passing
- 2 pending

[jgclark]

I remembered what seems like a significant detail that we've not yet discussed at all so far: how many different ways should there to to trigger these templates?

In our architecture so far, the only way to trigger one of the plugin-defined function()s was to include it in a template like so:{{function(...)}}. This feels a limitation we should remove, and I'd be planning to add a more general /processTags command. This would allow a user to get any {{...}} processed in a note file, replacing the {{...}} definition.

I think adding this to our new framework would add flexibility and the ability to more easily use the power of the new framework.

[mikeerickson]

@jgclark would you mind providing a bit more context as you what you are wanting? The currently implementation is pretty flexible as it is, but if I need to make it even more flexible, let’s get the requirements on the table sooner rather than later 😊

[tastapod]

I’m not sure I’m a fan of this. How does that work? If I type {{…}} in a note does it immediately get evaluated? Does it re-evaluate each time I open the note, or is it a one-off, in which case it can be inserted as a /-expression (eg. /date)? This is different from eg. Hugo templates, where the template generates the static page so the page can contain partials and references to other templates, because NP doesn’t have a “build” as such; it’s just notes that you write. So NP “templates” are more like macros that you invoke on demand.

[mikeerickson]

@tastapod If this is indeed what @jgclark meant, this is outside the current scope of what this project is meant to provide, and is something that NotePlan would have to extend. We have discussed enabling plugins to respond to various NotePlan events, but again not in scope of this project.

I will await response from @jgclark to provide more context what functionality he requesting.

[jgclark]

Thanks @tastapod for pushing back.
(See my follow-up above as well.)

If I type {{…}} in a note does it immediately get evaluated?

I excluded immediate evaluation in my OP. That's already available via apply a Template.

Does it re-evaluate each time I open the note,

I had in mind a one-off, as I said it would the output would replace the code.

or is it a one-off, in which case it can be inserted as a /-expression (eg. /date)?

Yes, the simple cases can have their own /-commands (like /date), but I want to cover all cases. This would then allow non-plugin-authors to write even quite complex config and execute when and where they like.

So NP “templates” are more like macros that you invoke on demand.

I've written before about my frustration that we don't seem to have good language yet to describe what we're doing, particularly overloading the term 'template'. So I rather like your use of 'macros' ... that feels much closer to what we're doing right now, though it's now language I've seen in eta.