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

Allow for YAML metadata in templates #655

Merged

Conversation

movermeyer
Copy link
Collaborator

@movermeyer movermeyer commented May 24, 2021

What are you trying to accomplish?

As part of #563, we are adding a mechanism to provide metadata within a Frontmatter block within a Foam note template.

What approach did you choose and why?

As noted in this comment, it's nicer to be able to add the metadata to an existing YAML frontmatter block.
However, it is also very difficult to programmatically remove an entry from a YAML mapping without disrupting the rest of the YAML.

So in this PR, I allow for both. If you have an existing YAML frontmatter block, and you're willing to abide by fairly strict formatting, then you can add the metadata to the existing frontmatter block.

If for some reason, you cannot use the restricted syntax, you are still able to provide a second, Foam-specific YAML frontmatter block at the start of the template instead.

What should reviewers focus on?

Not quite there

This PR does not succeed at fully implementing the desired behaviour.
I had dreamed of being able to use any VS Code snippet variable in the filepath.

---
foam_template:
  filepath: `journal/${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}.md`
---

This would allow Foam: Open Daily Note to make use of templates easily.
However, this is not currently possible. VS Code does not currently offer an interface for resolving the snippet variables without opening the snippet in an editor for the user.

In the future, we might vendor the relevant bits snippet resolution code, or submit a patch to VS Code to expose their variable resolution functionality as part of the API.

The PR as it stands still offers value, since it allows you to define relative or absolute directories to store the files into, instead of the default Foam: Create New Note behaviour of opening the file in the same directory as the active file.

Example of using metadata to specify a directory relative to the current workspace

---
# This will create the note in the "journal" subdirectory of the current workspace, 
# regardless of which file is the active file. 
foam_template:
  filepath: `journal/$FOAM_TITLE.md` 
---

Next steps

@riccardoferretti
Copy link
Collaborator

The general approach looks good to me, a few comments:

  • I didn't realize there was such limitation on Snippet strings, that's unfortunate, we should look into getting an API to the text expansion
  • I am happy to not support JSON frontmatter
  • I am happy to only support a single YAML block if that simplifies your life, I don't mind supporting 2 YAML blocks if you prefer that way and it doesn't make the code awfully more complicated

@riccardoferretti riccardoferretti added the foam-vscode Foam for VSCode extension in packages/foam-vscode label May 25, 2021
@movermeyer movermeyer force-pushed the yaml_template_metadata branch 4 times, most recently from daf2a94 to 0b5bbec Compare May 30, 2021 16:47
@movermeyer movermeyer changed the title WIP: YAML template metadata Allow for YAML metadata in templates May 30, 2021
@movermeyer
Copy link
Collaborator Author

@riccardoferretti, I think this is ready for review.

Since you last looked, I've implemented the name and description template metadata attributes that @jevakallio suggested.

IMO, it looks pretty slick:

foam-template-picker


Replying to your previous comment.

I didn't realize there was such limitation on Snippet strings, that's unfortunate, we should look into getting an API to the text expansion

💯, that's the next step after this PR.

I am happy to not support JSON frontmatter

👍

I am happy to only support a single YAML block if that simplifies your life, I don't mind supporting 2 YAML blocks if you prefer that way and it doesn't make the code awfully more complicated

It wasn't very complicated to support both (with the caveat that users cannot use the full flexibility of the YAML syntax if they want to have the metadata within an existing Frontmatter bock)

@movermeyer movermeyer marked this pull request as ready for review May 30, 2021 16:59
Copy link
Collaborator

@riccardoferretti riccardoferretti left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the screenshots look pretty cool, thanks for this!
I have added a few comments, mostly minor, let me know your thoughts

packages/foam-vscode/src/features/create-from-template.ts Outdated Show resolved Hide resolved
packages/foam-vscode/src/features/create-from-template.ts Outdated Show resolved Hide resolved
packages/foam-vscode/src/features/create-from-template.ts Outdated Show resolved Hide resolved
@@ -218,15 +299,41 @@ function currentDirectoryFilepath(filename: string) {
return Uri.joinPath(currentDir, filename);
}

export function determineDefaultFilepath(
resolvedValues: Map<string, string>,
templateMetadata
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this an implicit any? in that case I am surprised it didn't raise a warning from the linter.

I also noticed in other places you are using object for metadata.. given that we have a specific shape for the template metadata, could it be helpful to map it onto a type/interface?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this an implicit any? in that case I am surprised it didn't raise a warning from the linter.

It is. I guess I just missed the warning:

image


I've switched it to Map<string, string>... if that helps?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am surprised it didn't show up as a warning in the PR, I thought the integration would do that (kinda like when there is an unused import/variable)... mm, to be looked into at some point.

Given the metadata has a specific type, I would just defined that, as it also provides a good in-code documentation for what info can be found (and is allowed) as template metadata, wdyt?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given the metadata has a specific type, I would just defined that, as it also provides a good in-code documentation for what info can be found (and is allowed) as template metadata, wdyt?

@riccardoferretti Sounds good to me. I won't have time to make this change until next week. If you're eager, we can ship this now, and I'll do that refactor as part of my next PR.

@movermeyer movermeyer force-pushed the yaml_template_metadata branch from 0b5bbec to e2e9e27 Compare May 30, 2021 20:12
@movermeyer movermeyer marked this pull request as draft May 30, 2021 20:25
@movermeyer movermeyer force-pushed the yaml_template_metadata branch 2 times, most recently from dadc700 to 7dac126 Compare May 30, 2021 20:37
@movermeyer movermeyer force-pushed the yaml_template_metadata branch from 7dac126 to 9731c80 Compare May 30, 2021 21:10
@movermeyer movermeyer marked this pull request as ready for review May 30, 2021 21:13
Copy link
Collaborator

@riccardoferretti riccardoferretti left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

happy to merge this in the meantime, will do a release later so the feature will already be available. thanks!

@riccardoferretti riccardoferretti merged commit d4623a2 into foambubble:master Jun 4, 2021
@chrisUsick
Copy link
Contributor

chrisUsick commented Jun 4, 2021

Just came across an issue that I couldn't find in the docs, started reading the code and found foam_template.filepath on master but couldn't figure out why it appeared template metadata wasn't working, then noticed that this if 5h old!
So thanks for implementing and can't wait for this to be released!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
foam-vscode Foam for VSCode extension in packages/foam-vscode
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants